{
  "openapi": "3.1.0",
  "info": {
    "title": "Nexlymate OMS REST API",
    "version": "1.0.0",
    "description": "Production REST API for Nexlymate Order Management System — The Operating System for the Republic of COD Business. Connect external storefronts (WooCommerce, Shopify, custom websites) to automate incoming order management, courier dispatch (Koombiyo, Domex, Royal Express), waybill tracking, and warehouse inventory sync.",
    "contact": {
      "name": "Nexlymate Developer Support",
      "url": "https://nexlymate.com/api-docs",
      "email": "support@nexlymate.com"
    }
  },
  "servers": [
    {
      "url": "https://app.nexlymate.com/api/v1",
      "description": "Production API Server"
    }
  ],
  "security": [
    { "BearerAuth": [] },
    { "ApiKeyHeader": [] }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "API Key obtained from Settings -> Developer Options (e.g., vs_live_...)"
      },
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "description": "Store API Key"
      },
      "ApiSecretHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-SECRET",
        "description": "Optional strict API Secret"
      }
    },
    "schemas": {
      "OrderItem": {
        "type": "object",
        "required": ["name", "qty", "price"],
        "properties": {
          "name": { "type": "string", "example": "Classic Heavyweight Tee - Black (L)" },
          "qty": { "type": "integer", "minimum": 1, "example": 2 },
          "price": { "type": "number", "minimum": 0, "example": 2450.00 }
        }
      },
      "CreateOrderRequest": {
        "type": "object",
        "required": ["customerName", "phone", "address", "city", "district", "items"],
        "properties": {
          "customerName": { "type": "string", "example": "Kasun Wickramasinghe" },
          "phone": { "type": "string", "example": "0771234567" },
          "address": { "type": "string", "example": "No 45/2 Galle Road, Bambalapitiya" },
          "city": { "type": "string", "example": "Colombo" },
          "district": { "type": "string", "example": "Colombo" },
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/OrderItem" }
          },
          "shippingFee": { "type": "number", "default": 0, "example": 350.00 },
          "paymentMethod": { "type": "string", "enum": ["COD", "Card", "Bank"], "default": "COD" },
          "notes": { "type": "string", "example": "Call customer before delivery" },
          "email": { "type": "string", "format": "email", "example": "kasun@example.com" }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "example": "ord_89f02a" },
          "orderId": { "type": "string", "example": "STO-10492" },
          "customerName": { "type": "string", "example": "Kasun Wickramasinghe" },
          "phone": { "type": "string", "example": "0771234567" },
          "address": { "type": "string", "example": "No 45/2 Galle Road, Bambalapitiya" },
          "city": { "type": "string", "example": "Colombo" },
          "district": { "type": "string", "example": "Colombo" },
          "totalPayable": { "type": "number", "example": 5250.00 },
          "paymentMethod": { "type": "string", "example": "COD" },
          "deliveryStatus": { "type": "string", "example": "Open" },
          "waybillNumber": { "type": "string", "example": "KMB-COL-8829104" },
          "courier": { "type": "string", "example": "koombiyo" },
          "syncStatus": { "type": "string", "example": "Synced" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "CourierDispatchRequest": {
        "type": "object",
        "required": ["courier"],
        "properties": {
          "courier": {
            "type": "string",
            "enum": ["koombiyo", "domex", "royal", "fardar", "trans_express"],
            "example": "koombiyo"
          },
          "packageWeight": { "type": "number", "default": 1.0, "example": 1.5 },
          "remarks": { "type": "string", "example": "Handle with care" }
        }
      },
      "StockAdjustmentRequest": {
        "type": "object",
        "required": ["adjustment"],
        "properties": {
          "adjustment": { "type": "integer", "example": -2, "description": "Delta to increment or decrement stock level" },
          "warehouseId": { "type": "string", "example": "wh_central" }
        }
      }
    }
  },
  "paths": {
    "/ping": {
      "get": {
        "summary": "Health check and authentication test",
        "description": "Verifies that your API credentials are valid and returns store details.",
        "responses": {
          "200": { "description": "API is online and credentials are valid" },
          "401": { "description": "Invalid or missing API Key" }
        }
      }
    },
    "/orders": {
      "post": {
        "summary": "Push new order into pipeline",
        "description": "Creates a new order in Nexlymate from an external checkout (WooCommerce, Shopify, custom site).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }
            }
          }
        },
        "responses": {
          "201": { "description": "Order created successfully" },
          "400": { "description": "Missing required fields or invalid phone format" },
          "401": { "description": "Unauthorized" }
        }
      },
      "get": {
        "summary": "List paginated orders",
        "description": "Fetch orders with pagination and filtering by delivery status or keyword.",
        "parameters": [
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } },
          { "name": "deliveryStatus", "in": "query", "schema": { "type": "string" } },
          { "name": "search", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "List of orders with pagination metadata" }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "summary": "Retrieve single order",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Order details found" },
          "404": { "description": "Order not found" }
        }
      },
      "patch": {
        "summary": "Edit existing order",
        "description": "Updates customer info, items, or notes. Blocked if order is already synced to a courier partner (409 Conflict).",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Order updated successfully" },
          "409": { "description": "ORDER_COURIER_SYNCED — Cannot edit order after waybill generation" }
        }
      },
      "delete": {
        "summary": "Soft-delete or cancel order",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Order deleted and stock released" },
          "409": { "description": "ORDER_COURIER_SYNCED — Cancel courier consignment first" }
        }
      }
    },
    "/orders/{id}/dispatch": {
      "post": {
        "summary": "Automated courier dispatch",
        "description": "Books a consignment with courier (Koombiyo, Domex, Royal Express) and issues an official waybill number.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CourierDispatchRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Order dispatched and waybill generated" },
          "409": { "description": "Order already dispatched" }
        }
      }
    },
    "/orders/{id}/unsync": {
      "post": {
        "summary": "Unsync courier waybill",
        "description": "Cancels courier booking and unlocks the order for editing.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Waybill unsynced successfully" }
        }
      }
    },
    "/products": {
      "get": {
        "summary": "List products and stock counts",
        "responses": {
          "200": { "description": "Product catalog with stock levels" }
        }
      }
    },
    "/products/{id}/stock": {
      "put": {
        "summary": "Adjust stock level",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/StockAdjustmentRequest" }
            }
          }
        },
        "responses": {
          "200": { "description": "Stock updated successfully" }
        }
      }
    }
  }
}