{ "openapi": "3.1.0", "info": { "title": "Renaska External Integration API", "version": "1.0.0", "description": "**Server-to-server only** — API keys are secrets and must never be placed in a browser\n(they would be exposed in the bundle / DevTools). This API has no CORS support for\nbrowser cross-origin calls by design.\n\n## Authentication\nEvery request (except `GET /openapi.json`) requires:\n```\nAuthorization: Bearer rnk_live_\n```\nGenerate keys in your tenant dashboard under **Settings → API Keys**.\nEach key carries one or more scopes (e.g. `orders:read`, `clients:write`).\n\n## Side effects of write operations\n- **POST /orders** — deducts inventory stock, assigns workflow stage to every line item,\n and posts an accounting journal entry (same as creating an order in the dashboard).\n It does not send a customer notification and does not fire a Meta CAPI event.\n- **POST /quotations/:id/convert** — same side effects as POST /orders; the quotation keeps\n its `accepted` status (billing it is a separate operation this endpoint never performs).\n- **POST /shipments** — links the shipment to the order; does not auto-deduct stock.\n\n## Idempotency\nPOST endpoints accept an optional `Idempotency-Key` header (max 255 chars).\nOn retry with the same key the original response is replayed. Covers sequential retries;\nexact concurrent duplicate submissions are not guaranteed (documented limitation).\n\n## Rate limits\n- Read endpoints: 120 requests/min per key\n- Write endpoints: 30 requests/min per key\n\n## Pagination\nList endpoints return `{ data: [...], meta: { page, limit, total, totalPages } }`.\nDefault `limit` is 20; maximum is 100." }, "servers": [ { "url": "https://bk.renaska.com/api/external/v1", "description": "Production" } ], "security": [ { "bearerApiKey": [] } ], "tags": [ { "name": "Products", "description": "Read-only access to the product catalog" }, { "name": "Inventory", "description": "Read-only stock levels and low-stock alerts" }, { "name": "Clients", "description": "Create and manage customers" }, { "name": "Orders", "description": "Create and query orders (with inventory side effects)" }, { "name": "Quotations", "description": "Create, update, and convert quotations" }, { "name": "Payments", "description": "Payment links and configured payment methods" }, { "name": "Shipping", "description": "Shipments and carrier catalog" } ], "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "rnk_live_", "description": "API key generated in the tenant dashboard (Settings → API Keys). Example: `rnk_live_xxxxx`" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "example": "validation_error" }, "message": { "type": "string", "example": "clientId must be a valid UUID" }, "details": { "type": "array", "description": "Present on validation_error — field-level detail map", "items": { "type": "object", "properties": { "field": { "type": "string", "example": "clientId" }, "issue": { "type": "string", "example": "invalid UUID" } } } } } } } }, "PaginatedMeta": { "type": "object", "required": [ "page", "limit", "total", "totalPages" ], "properties": { "page": { "type": "integer", "example": 1 }, "limit": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 142 }, "totalPages": { "type": "integer", "example": 8 } } }, "LineItemInput": { "type": "object", "required": [ "quantity", "unitPrice" ], "anyOf": [ { "required": [ "description" ] }, { "required": [ "productId" ] } ], "properties": { "id": { "type": "string", "format": "uuid" }, "description": { "type": "string", "example": "Servicio de diseño" }, "productId": { "type": "string", "format": "uuid" }, "productOptionId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "exclusiveMinimum": 0, "example": 2 }, "unitPrice": { "type": "number", "minimum": 0, "example": 45000 }, "discountPct": { "type": "number", "minimum": 0, "maximum": 100 }, "taxRate": { "type": "number", "minimum": 0, "maximum": 100 }, "variableInputs": { "type": "object", "additionalProperties": true }, "note": { "type": "string" } } }, "Client": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-0000-0000-0000-000000000001" }, "code": { "type": [ "string", "null" ], "example": "CLI-0001" }, "type": { "type": [ "string", "null" ], "example": "company" }, "name": { "type": "string", "example": "Tienda El Sol" }, "legalName": { "type": [ "string", "null" ] }, "taxId": { "type": [ "string", "null" ], "example": "900123456-7" }, "email": { "type": [ "string", "null" ], "format": "email", "example": "contacto@tiendaelsol.co" }, "phone": { "type": [ "string", "null" ], "example": "+573001234567" }, "whatsappPhone": { "type": [ "string", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string" } }, "source": { "type": [ "string", "null" ], "example": "whatsapp" }, "language": { "type": [ "string", "null" ], "example": "es" }, "currency": { "type": [ "string", "null" ], "example": "COP" }, "assignedSellerId": { "type": [ "string", "null" ], "format": "uuid" }, "recontactAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "website": { "type": [ "string", "null" ] }, "address": { "type": [ "object", "null" ], "additionalProperties": true }, "discountTierId": { "type": [ "string", "null" ], "format": "uuid" }, "customFields": { "type": [ "object", "null" ], "additionalProperties": true } } }, "ClientInput": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 255, "example": "Tienda El Sol" }, "type": { "type": "string", "enum": [ "individual", "company" ], "example": "company" }, "legalName": { "type": "string" }, "taxId": { "type": "string", "example": "900123456-7" }, "email": { "type": "string", "format": "email", "example": "contacto@tiendaelsol.co" }, "phone": { "type": "string", "example": "+573001234567" }, "whatsappPhone": { "type": "string", "example": "+573001234567" }, "instagramUserId": { "type": "string" }, "instagramUsername": { "type": "string" }, "facebookUserId": { "type": "string" }, "website": { "type": "string" }, "address": { "type": "object", "additionalProperties": true }, "discountTierId": { "type": "string", "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true }, "notes": { "type": "string" }, "source": { "type": "string", "example": "whatsapp" }, "language": { "type": "string" }, "currency": { "type": "string" }, "assignedSellerId": { "type": "string", "format": "uuid" }, "recontactAt": { "type": "string", "format": "date-time" } } }, "ClientInput-Patch": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "example": "Tienda El Sol" }, "type": { "type": "string", "enum": [ "individual", "company" ], "example": "company" }, "legalName": { "type": "string" }, "taxId": { "type": "string", "example": "900123456-7" }, "email": { "type": "string", "format": "email", "example": "contacto@tiendaelsol.co" }, "phone": { "type": "string", "example": "+573001234567" }, "whatsappPhone": { "type": "string", "example": "+573001234567" }, "instagramUserId": { "type": "string" }, "instagramUsername": { "type": "string" }, "facebookUserId": { "type": "string" }, "website": { "type": "string" }, "address": { "type": "object", "additionalProperties": true }, "discountTierId": { "type": "string", "format": "uuid" }, "tags": { "type": "array", "items": { "type": "string" } }, "customFields": { "type": "object", "additionalProperties": true }, "notes": { "type": "string" }, "source": { "type": "string", "example": "whatsapp" }, "language": { "type": "string" }, "currency": { "type": "string" }, "assignedSellerId": { "type": "string", "format": "uuid" }, "recontactAt": { "type": "string", "format": "date-time" } } }, "Product": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "fixed", "fixed_with_options", "variable", "variable_with_options" ], "example": "fixed" }, "name": { "type": "string", "example": "Camiseta básica negra" }, "nameTranslations": { "type": [ "object", "null" ], "additionalProperties": true }, "shortNameTranslations": { "type": [ "object", "null" ], "additionalProperties": true }, "slug": { "type": [ "string", "null" ], "example": "camiseta-basica-negra" }, "optionLabelTranslations": { "type": [ "object", "null" ], "additionalProperties": true }, "brand": { "type": [ "string", "null" ] }, "categoryId": { "type": [ "string", "null" ], "format": "uuid" }, "colorHex": { "type": [ "string", "null" ], "example": "#000000" }, "descriptionTranslations": { "type": [ "object", "null" ], "additionalProperties": true }, "images": { "type": [ "array", "null" ], "items": { "type": "string" } }, "videos": { "type": [ "array", "null" ], "items": { "type": "string" } }, "minQuantity": { "type": [ "number", "null" ], "example": 1 }, "salePrice": { "type": [ "number", "null" ], "example": 45000 }, "compareAtPrice": { "type": [ "number", "null" ], "example": 55000 }, "weight": { "type": [ "number", "null" ], "example": 0.2 }, "weightUnit": { "type": [ "string", "null" ], "example": "kg" }, "includesTax": { "type": [ "boolean", "null" ] }, "taxRate": { "type": [ "number", "null" ], "example": 19 }, "serviceType": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "example": "published" }, "barcode": { "type": [ "string", "null" ] }, "isActive": { "type": [ "boolean", "null" ], "example": true }, "productionDays": { "type": [ "integer", "null" ] }, "bookingDurationMinutes": { "type": [ "integer", "null" ] }, "minOptionPrice": { "type": [ "number", "null" ] }, "maxOptionPrice": { "type": [ "number", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "CatalogItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Camiseta básica negra" }, "type": { "type": "string", "enum": [ "fixed", "fixed_with_options", "variable", "variable_with_options" ], "example": "fixed" }, "salePrice": { "type": [ "number", "null" ], "example": 45000 }, "compareAtPrice": { "type": [ "number", "null" ], "example": 55000 }, "taxRate": { "type": [ "number", "null" ], "example": 19 }, "weight": { "type": [ "number", "null" ], "example": 0.2 }, "optionsText": { "type": "string", "example": "S M L Negro Blanco" } } }, "StockEntry": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "itemType": { "type": [ "string", "null" ], "example": "product" }, "productId": { "type": [ "string", "null" ], "format": "uuid" }, "productOptionId": { "type": [ "string", "null" ], "format": "uuid" }, "warehouseId": { "type": [ "string", "null" ], "format": "uuid" }, "quantity": { "type": "number", "example": 38 }, "reservedQty": { "type": [ "number", "null" ], "example": 0 }, "minStock": { "type": [ "number", "null" ], "example": 5 }, "itemName": { "type": [ "string", "null" ], "example": "Camiseta básica negra" }, "inputUnit": { "type": [ "string", "null" ] }, "warehouseName": { "type": [ "string", "null" ] }, "lotNumber": { "type": [ "string", "null" ] }, "serialNumber": { "type": [ "string", "null" ] }, "expiryDate": { "type": [ "string", "null" ], "format": "date" }, "locationId": { "type": [ "string", "null" ], "format": "uuid" } } }, "Order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": [ "string", "null" ], "example": "PED-0042" }, "invoiceId": { "type": [ "string", "null" ], "format": "uuid" }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "clientName": { "type": [ "string", "null" ], "example": "Tienda El Sol" }, "workflowId": { "type": [ "string", "null" ], "format": "uuid" }, "workflowName": { "type": [ "string", "null" ] }, "currentStageId": { "type": [ "string", "null" ], "format": "uuid" }, "currentStageName": { "type": [ "string", "null" ] }, "currentStageColor": { "type": [ "string", "null" ] }, "currentStageProgress": { "type": [ "number", "null" ], "description": "Average stage progress (0-100) of the order's active items; 100 when the order is in its final workflow stage." }, "itemCount": { "type": [ "integer", "null" ] }, "unitCount": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "confirmed" }, "isUrgent": { "type": [ "boolean", "null" ], "readOnly": true }, "requiredByDate": { "type": [ "string", "null" ], "format": "date", "readOnly": true }, "notes": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "invoiceNumber": { "type": [ "string", "null" ], "example": "FE-0042" }, "invoiceTotal": { "type": [ "number", "null" ], "example": 135000 }, "externalPlatform": { "type": [ "string", "null" ], "example": "api" }, "externalOrderId": { "type": [ "string", "null" ] }, "externalOrderNumber": { "type": [ "string", "null" ] }, "quotationId": { "type": [ "string", "null" ], "format": "uuid" }, "shippingCost": { "type": [ "number", "null" ] }, "shippingCarrierId": { "type": [ "string", "null" ], "format": "uuid" }, "shippingCity": { "type": [ "string", "null" ] }, "shippingCountry": { "type": [ "string", "null" ] }, "shippingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "billingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "isCod": { "type": [ "boolean", "null" ] }, "codSettled": { "type": [ "boolean", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "productId": { "type": [ "string", "null" ], "format": "uuid" }, "productOptionId": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "unitPrice": { "type": [ "number", "null" ] } } } } } }, "OrderInput": { "type": "object", "required": [ "clientId", "items" ], "properties": { "clientId": { "type": "string", "format": "uuid" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LineItemInput" } }, "currency": { "type": "string", "enum": [ "COP", "USD", "EUR", "MXN", "PEN", "CLP", "BRL", "ARS", "BOB" ], "example": "COP" }, "notes": { "type": "string" }, "deliverySlotOverrides": { "type": "object", "additionalProperties": true } } }, "Quotation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": [ "string", "null" ], "example": "COT-0017" }, "name": { "type": [ "string", "null" ] }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "clientName": { "type": [ "string", "null" ] }, "status": { "type": "string", "example": "sent" }, "currency": { "type": [ "string", "null" ], "example": "COP" }, "exchangeRate": { "type": [ "number", "null" ] }, "subtotal": { "type": [ "number", "null" ] }, "taxAmount": { "type": [ "number", "null" ] }, "discountAmount": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ], "example": 90000 }, "notes": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "language": { "type": [ "string", "null" ], "example": "es" }, "orderId": { "type": [ "string", "null" ], "format": "uuid" }, "paymentLinkId": { "type": [ "string", "null" ], "format": "uuid" }, "paymentMethodId": { "type": [ "string", "null" ], "format": "uuid" }, "shippingCarrierId": { "type": [ "string", "null" ], "format": "uuid" }, "shippingCity": { "type": [ "string", "null" ] }, "shippingCountry": { "type": [ "string", "null" ] }, "shippingPostalCode": { "type": [ "string", "null" ] }, "shippingCost": { "type": [ "number", "null" ] }, "shippingCod": { "type": [ "boolean", "null" ] }, "shippingCodScope": { "type": [ "string", "null" ] }, "billingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "shippingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "quotationId": { "type": [ "string", "null" ], "format": "uuid" }, "productId": { "type": [ "string", "null" ], "format": "uuid" }, "productOptionId": { "type": [ "string", "null" ], "format": "uuid" }, "description": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] }, "unitPrice": { "type": [ "number", "null" ] }, "compareAtPrice": { "type": [ "number", "null" ] }, "discountPct": { "type": [ "number", "null" ] }, "taxRate": { "type": [ "number", "null" ] }, "taxType": { "type": [ "string", "null" ], "enum": [ "iva", "inc", "exempt", null ], "description": "Para exempt/inc el taxRate es irrelevante: el impuesto del header cascadea por tipo (exempt=0, inc=8/108)." }, "subtotal": { "type": [ "number", "null" ] }, "weight": { "type": [ "number", "null" ] }, "imageUrl": { "type": [ "string", "null" ] }, "serviceDescription": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "bookingDurationMinutes": { "type": [ "integer", "null" ] }, "productName": { "type": [ "string", "null" ] }, "optionName": { "type": [ "string", "null" ] } } } } } }, "QuotationInput": { "type": "object", "required": [ "clientId", "items" ], "properties": { "clientId": { "type": "string", "format": "uuid" }, "items": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/LineItemInput" } }, "name": { "type": "string" }, "currency": { "type": "string", "enum": [ "COP", "USD", "EUR", "MXN", "PEN", "CLP", "BRL", "ARS", "BOB" ], "example": "COP" }, "exchangeRate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "notes": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time" }, "shippingCost": { "type": "number", "minimum": 0 }, "shippingCarrierId": { "type": "string", "format": "uuid" }, "shippingCity": { "type": "string" }, "shippingCountry": { "type": "string" }, "shippingPostalCode": { "type": "string" }, "billingAddress": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddressId": { "type": "string", "format": "uuid" }, "shippingAddressId": { "type": "string", "format": "uuid" }, "paymentMethodId": { "type": "string", "format": "uuid" }, "language": { "type": "string", "enum": [ "es", "en" ], "example": "es" } } }, "UpdateQuotationInput": { "type": "object", "properties": { "clientId": { "type": "string", "format": "uuid" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/LineItemInput" } }, "name": { "type": "string" }, "currency": { "type": "string", "enum": [ "COP", "USD", "EUR", "MXN", "PEN", "CLP", "BRL", "ARS", "BOB" ], "example": "COP" }, "exchangeRate": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000 }, "notes": { "type": "string" }, "validUntil": { "type": "string", "format": "date-time" }, "shippingCost": { "type": "number", "minimum": 0 }, "shippingCarrierId": { "type": "string", "format": "uuid" }, "shippingCity": { "type": "string" }, "shippingCountry": { "type": "string" }, "shippingPostalCode": { "type": "string" }, "billingAddress": { "type": "object", "additionalProperties": true }, "shippingAddress": { "type": "object", "additionalProperties": true }, "billingAddressId": { "type": "string", "format": "uuid" }, "shippingAddressId": { "type": "string", "format": "uuid" }, "paymentMethodId": { "type": "string", "format": "uuid" }, "language": { "type": "string", "enum": [ "es", "en" ], "example": "es" } } }, "ConvertInput": { "type": "object", "properties": { "deliverySlotOverrides": { "type": "object", "additionalProperties": true } } }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": [ "string", "null" ] }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "clientName": { "type": [ "string", "null" ] }, "invoiceId": { "type": [ "string", "null" ], "format": "uuid" }, "invoiceNumber": { "type": [ "string", "null" ] }, "quotationId": { "type": [ "string", "null" ], "format": "uuid" }, "amount": { "type": "number", "example": 135000 }, "currency": { "type": [ "string", "null" ], "example": "COP" }, "description": { "type": [ "string", "null" ] }, "paymentProvider": { "type": [ "string", "null" ], "example": "wompi" }, "isManual": { "type": [ "boolean", "null" ] }, "paymentMethodId": { "type": [ "string", "null" ], "format": "uuid" }, "paymentMethodName": { "type": [ "string", "null" ] }, "providerLink": { "type": [ "string", "null" ], "format": "uri", "example": "https://link.wompi.co/xxxxx" }, "status": { "type": "string", "example": "pending" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "transactionId": { "type": [ "string", "null" ] }, "receiptUrl": { "type": [ "string", "null" ], "format": "uri" }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "PaymentLinkInput": { "type": "object", "required": [ "amount", "paymentProvider" ], "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000000, "example": 135000 }, "paymentProvider": { "type": "string", "enum": [ "stripe", "wompi", "paypal", "epayco", "manual", "bold", "addi" ], "example": "wompi" }, "clientId": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string", "format": "uuid" }, "quotationId": { "type": "string", "format": "uuid" }, "currency": { "type": "string", "enum": [ "COP", "USD", "EUR", "MXN", "PEN", "CLP", "BRL", "ARS", "BOB" ], "example": "COP" }, "description": { "type": "string" }, "paymentMethodId": { "type": "string", "format": "uuid" }, "expiresAt": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } } }, "PaymentMethod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Transferencia bancaria" }, "type": { "type": [ "string", "null" ], "example": "bank_transfer" }, "integrationSlug": { "type": [ "string", "null" ], "example": "wompi" }, "isActive": { "type": [ "boolean", "null" ], "example": true }, "displayOrder": { "type": [ "integer", "null" ], "example": 1 }, "supportedCurrencies": { "type": [ "array", "null" ], "items": { "type": "string" }, "example": [ "COP", "USD" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Shipment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "orderId": { "type": [ "string", "null" ], "format": "uuid" }, "orderNumber": { "type": [ "string", "null" ] }, "externalPlatform": { "type": [ "string", "null" ] }, "externalOrderNumber": { "type": [ "string", "null" ] }, "clientId": { "type": [ "string", "null" ], "format": "uuid" }, "clientName": { "type": [ "string", "null" ] }, "carrier": { "type": "string", "example": "servientrega" }, "carrierDisplayName": { "type": [ "string", "null" ], "example": "Servientrega" }, "carrierService": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ], "example": "SV123456789CO" }, "shippingAddress": { "type": [ "object", "null" ], "additionalProperties": true }, "weightKg": { "type": [ "number", "null" ] }, "dimensions": { "type": [ "object", "null" ], "additionalProperties": true }, "shippingCost": { "type": [ "number", "null" ] }, "status": { "type": "string", "example": "in_transit" }, "estimatedDelivery": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "eventCount": { "type": [ "integer", "null" ] }, "invoiceCount": { "type": [ "integer", "null" ] }, "publicTrackingUrl": { "type": [ "string", "null" ], "format": "uri" }, "events": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "example": "in_transit" }, "occurredAt": { "type": "string", "format": "date-time" }, "location": { "type": [ "string", "null" ], "example": "Bogotá" }, "description": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ], "example": "carrier" } } } } } }, "ShipmentInput": { "type": "object", "required": [ "carrier" ], "anyOf": [ { "required": [ "orderId" ] }, { "required": [ "invoiceIds" ] } ], "properties": { "carrier": { "type": "string", "maxLength": 100, "example": "servientrega" }, "orderId": { "type": "string", "format": "uuid" }, "invoiceIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "carrierService": { "type": "string" }, "trackingNumber": { "type": "string", "example": "SV123456789CO" }, "shippingAddress": { "type": "object", "additionalProperties": true }, "weightKg": { "type": "number", "minimum": 0 }, "dimensions": { "type": "object", "additionalProperties": true }, "shippingCost": { "type": "number", "minimum": 0 }, "estimatedDelivery": { "type": "string", "format": "date-time" }, "shipmentItems": { "type": "array", "items": { "type": "object", "required": [ "orderItemId", "quantity" ], "properties": { "orderItemId": { "type": "string", "format": "uuid" }, "quantity": { "type": "number", "exclusiveMinimum": 0 } } } } } }, "TrackingEventInput": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "pending", "picked_up", "in_transit", "out_for_delivery", "delivered", "returned", "failed" ], "example": "in_transit" }, "description": { "type": "string", "example": "En camino al destino" }, "location": { "type": "string", "example": "Bogotá" }, "source": { "type": "string", "enum": [ "manual", "carrier", "webhook" ], "example": "carrier" } } }, "Carrier": { "type": "object", "properties": { "slug": { "type": "string", "example": "servientrega" }, "name": { "type": "string", "example": "Servientrega" }, "scope": { "type": "string", "example": "national" }, "color": { "type": [ "string", "null" ], "example": "#E30613" }, "icon": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "publicTrackingUrl": { "type": [ "string", "null" ], "format": "uri" }, "hasAdapter": { "type": "boolean", "example": true } } } }, "responses": { "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stock insuficiente" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "paths": { "/products": { "get": { "operationId": "listProducts", "summary": "List products", "description": "Returns active and published products for the tenant. Scope required: `products:read`. Module gate: `products`.", "tags": [ "Products" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by words in any order — every word must appear in the product name, or in an active variant name or SKU suffix; also matches a barcode containing the phrase" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Product type filter" }, { "name": "categoryId", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "Category UUID filter" }, { "name": "barcode", "in": "query", "schema": { "type": "string" }, "description": "Exact barcode filter" } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "b2c3d4e5-0000-0000-0000-000000000002", "type": "fixed", "name": "Camiseta básica negra", "slug": "camiseta-basica-negra", "salePrice": 45000, "compareAtPrice": 55000, "weight": 0.2, "weightUnit": "kg", "taxRate": 19, "status": "published", "isActive": true, "images": [], "createdAt": "2026-01-10T09:00:00Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/products/{id}": { "get": { "operationId": "getProduct", "summary": "Get product by ID", "description": "Returns a single published product. Scope required: `products:read`. Module gate: `products`.", "tags": [ "Products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the product" } ], "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" } } }, "example": { "data": { "id": "b2c3d4e5-0000-0000-0000-000000000002", "type": "fixed", "name": "Camiseta básica negra", "slug": "camiseta-basica-negra", "salePrice": 45000, "compareAtPrice": 55000, "weight": 0.2, "weightUnit": "kg", "taxRate": 19, "status": "published", "isActive": true, "images": [], "createdAt": "2026-01-10T09:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/catalog": { "get": { "operationId": "getCatalog", "summary": "Get full product catalog", "description": "Returns the full versioned product catalog for the tenant. Useful for initial sync. Scope required: `products:read`. Module gate: `products`.", "tags": [ "Products" ], "responses": { "200": { "description": "Full catalog with version", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" }, "version": { "type": "string" } } } } }, "example": { "data": [ { "id": "b2c3d4e5-0000-0000-0000-000000000002", "name": "Camiseta básica negra", "type": "fixed", "salePrice": 45000, "compareAtPrice": 55000, "taxRate": 19, "weight": 0.2 } ], "meta": { "page": 1, "limit": 1, "total": 1, "totalPages": 1, "version": "v_20260629" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/inventory": { "get": { "operationId": "listInventory", "summary": "List stock entries", "description": "Returns paginated stock entries for all products. Scope required: `inventory:read`. Module gate: `inventory`.", "tags": [ "Inventory" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "warehouseId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "itemType", "in": "query", "schema": { "type": "string" } }, { "name": "productId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "locationId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "search", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockEntry" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "c3d4e5f6-0000-0000-0000-000000000003", "itemType": "product", "productId": "b2c3d4e5-0000-0000-0000-000000000002", "warehouseId": "a9b8c7d6-0000-0000-0000-000000000020", "quantity": 38, "reservedQty": 0, "minStock": 5, "itemName": "Camiseta básica negra", "warehouseName": "Bodega principal" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/inventory/low": { "get": { "operationId": "getLowStock", "summary": "Get low-stock items", "description": "Returns products at or below their `min_stock` threshold. Not paginated. Scope required: `inventory:read`. Module gate: `inventory`.", "tags": [ "Inventory" ], "parameters": [ { "name": "warehouseId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Low-stock items (plain array)", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StockEntry" } } } }, "example": { "data": [ { "id": "c3d4e5f6-0000-0000-0000-000000000003", "itemType": "product", "productId": "b2c3d4e5-0000-0000-0000-000000000002", "warehouseId": "a9b8c7d6-0000-0000-0000-000000000020", "quantity": 38, "reservedQty": 0, "minStock": 5, "itemName": "Camiseta básica negra", "warehouseName": "Bodega principal" } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/clients": { "get": { "operationId": "listClients", "summary": "List clients", "description": "Returns paginated clients for the tenant. Scope required: `clients:read`. Module gate: `clients`.", "tags": [ "Clients" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Client" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Tienda El Sol", "email": "contacto@tiendaelsol.co", "phone": "+573001234567", "type": "company", "source": "whatsapp", "taxId": null, "createdAt": "2026-01-15T10:00:00Z", "updatedAt": "2026-06-01T08:30:00Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "post": { "operationId": "createClient", "summary": "Create client", "description": "Creates a new client. Scope required: `clients:write`. Module gate: `clients`.", "tags": [ "Clients" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key — on retry the original response is replayed (sequential retry only)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput" }, "example": { "name": "Tienda El Sol", "email": "contacto@tiendaelsol.co", "phone": "+573001234567", "type": "company" } } } }, "responses": { "201": { "description": "Created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } }, "example": { "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Tienda El Sol", "email": "contacto@tiendaelsol.co", "phone": "+573001234567", "type": "company", "source": "whatsapp", "taxId": null, "createdAt": "2026-01-15T10:00:00Z", "updatedAt": "2026-06-01T08:30:00Z" } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stock insuficiente" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/clients/{id}": { "get": { "operationId": "getClient", "summary": "Get client by ID", "description": "Returns a single client. Scope required: `clients:read`. Module gate: `clients`.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the client" } ], "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } }, "example": { "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Tienda El Sol", "email": "contacto@tiendaelsol.co", "phone": "+573001234567", "type": "company", "source": "whatsapp", "taxId": null, "createdAt": "2026-01-15T10:00:00Z", "updatedAt": "2026-06-01T08:30:00Z" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "patch": { "operationId": "updateClient", "summary": "Update client", "description": "Partially updates a client. Only provided fields are changed. Scope required: `clients:write`. Module gate: `clients`.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the client" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientInput-Patch" }, "example": { "phone": "+573009876543" } } } }, "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Client" } } }, "example": { "data": { "id": "a1b2c3d4-0000-0000-0000-000000000001", "name": "Tienda El Sol", "email": "contacto@tiendaelsol.co", "phone": "+573001234567", "type": "company", "source": "whatsapp", "taxId": null, "createdAt": "2026-01-15T10:00:00Z", "updatedAt": "2026-06-01T08:30:00Z" } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/orders": { "get": { "operationId": "listOrders", "summary": "List orders", "description": "Returns paginated orders. Scope required: `orders:read`. Module gate: `orders`.", "tags": [ "Orders" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "clientId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "platform", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "d4e5f6a7-0000-0000-0000-000000000004", "number": "PED-0042", "invoiceId": null, "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "status": "confirmed", "itemCount": 1, "unitCount": 3, "invoiceNumber": "FE-0042", "invoiceTotal": 135000, "externalPlatform": "api", "createdAt": "2026-06-29T12:00:00Z", "items": [ { "id": "e1f2a3b4-0000-0000-0000-000000000030", "productId": "b2c3d4e5-0000-0000-0000-000000000002", "productOptionId": null, "description": "Camiseta básica negra", "quantity": 3, "unitPrice": 45000 } ] } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "post": { "operationId": "createOrder", "summary": "Create order", "description": "Creates an order with line items. **Side effects:** deducts inventory stock, creates journal entry for accounting. Uses the same service as the dashboard UI — all business rules (stage assignment, oversell guard) apply. Scope required: `orders:write`. Module gate: `orders`.", "tags": [ "Orders" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key — on retry the original response is replayed (sequential retry only)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInput" }, "example": { "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "items": [ { "productId": "b2c3d4e5-0000-0000-0000-000000000002", "quantity": 3, "unitPrice": 45000 } ] } } } }, "responses": { "201": { "description": "Created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } }, "example": { "data": { "id": "d4e5f6a7-0000-0000-0000-000000000004", "number": "PED-0042", "invoiceId": null, "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "status": "confirmed", "itemCount": 1, "unitCount": 3, "invoiceNumber": "FE-0042", "invoiceTotal": 135000, "externalPlatform": "api", "createdAt": "2026-06-29T12:00:00Z", "items": [ { "id": "e1f2a3b4-0000-0000-0000-000000000030", "productId": "b2c3d4e5-0000-0000-0000-000000000002", "productOptionId": null, "description": "Camiseta básica negra", "quantity": 3, "unitPrice": 45000 } ] } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "examples": { "conflict": { "summary": "Stock/kit conflict", "value": { "error": { "code": "conflict", "message": "Stock insuficiente" } } }, "resourceUnavailable": { "summary": "Kit resource unavailable", "value": { "error": { "code": "conflict", "message": "resource_unavailable: Cilindro 40cm", "resources": [ "Cilindro 40cm" ] } } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/orders/{id}": { "get": { "operationId": "getOrder", "summary": "Get order by ID", "description": "Returns a single order with its line items. Scope required: `orders:read`. Module gate: `orders`.", "tags": [ "Orders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the order" } ], "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } }, "example": { "data": { "id": "d4e5f6a7-0000-0000-0000-000000000004", "number": "PED-0042", "invoiceId": null, "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "status": "confirmed", "itemCount": 1, "unitCount": 3, "invoiceNumber": "FE-0042", "invoiceTotal": 135000, "externalPlatform": "api", "createdAt": "2026-06-29T12:00:00Z", "items": [ { "id": "e1f2a3b4-0000-0000-0000-000000000030", "productId": "b2c3d4e5-0000-0000-0000-000000000002", "productOptionId": null, "description": "Camiseta básica negra", "quantity": 3, "unitPrice": 45000 } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/quotations": { "get": { "operationId": "listQuotations", "summary": "List quotations", "description": "Returns paginated quotations. Scope required: `quotations:read`. Module gate: `orders`.", "tags": [ "Quotations" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "clientId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quotation" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "e5f6a7b8-0000-0000-0000-000000000005", "number": "COT-0017", "name": "Cotización camisetas", "status": "sent", "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "currency": "COP", "total": 90000, "validUntil": "2026-07-15T00:00:00Z", "createdAt": "2026-06-28T10:00:00Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "post": { "operationId": "createQuotation", "summary": "Create quotation", "description": "Creates a new quotation. Scope required: `quotations:write`. Module gate: `orders`.", "tags": [ "Quotations" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key — on retry the original response is replayed (sequential retry only)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotationInput" }, "example": { "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "items": [ { "productId": "b2c3d4e5-0000-0000-0000-000000000002", "productOptionId": "d1e2f3a4-0000-0000-0000-000000000010", "quantity": 2, "unitPrice": 45000 } ], "validUntil": "2026-07-15" } } } }, "responses": { "201": { "description": "Created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quotation" } } }, "example": { "data": { "id": "e5f6a7b8-0000-0000-0000-000000000005", "number": "COT-0017", "name": "Cotización camisetas", "status": "sent", "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "currency": "COP", "total": 90000, "validUntil": "2026-07-15T00:00:00Z", "createdAt": "2026-06-28T10:00:00Z" } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stock insuficiente" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/quotations/{id}": { "get": { "operationId": "getQuotation", "summary": "Get quotation by ID", "description": "Returns a single quotation with its line items. Scope required: `quotations:read`. Module gate: `orders`.", "tags": [ "Quotations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the quotation" } ], "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quotation" } } }, "example": { "data": { "id": "e5f6a7b8-0000-0000-0000-000000000005", "number": "COT-0017", "name": "Cotización camisetas", "status": "sent", "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "currency": "COP", "total": 90000, "validUntil": "2026-07-15T00:00:00Z", "createdAt": "2026-06-28T10:00:00Z" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "patch": { "operationId": "updateQuotation", "summary": "Update quotation", "description": "Partially updates a quotation. Scope required: `quotations:write`. Module gate: `orders`.", "tags": [ "Quotations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the quotation" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateQuotationInput" }, "example": { "notes": "Updated notes" } } } }, "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Quotation" } } }, "example": { "data": { "id": "e5f6a7b8-0000-0000-0000-000000000005", "number": "COT-0017", "name": "Cotización camisetas", "status": "sent", "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "currency": "COP", "total": 90000, "validUntil": "2026-07-15T00:00:00Z", "createdAt": "2026-06-28T10:00:00Z" } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/quotations/{id}/convert": { "post": { "operationId": "convertQuotationToOrder", "summary": "Convert quotation to order", "description": "Converts an approved quotation into a confirmed order. **Side effects:** deducts inventory, creates journal entry, sets all order item stages. Requires BOTH `quotations:read` AND `orders:write` scopes. Module gate: `orders`.", "tags": [ "Quotations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the quotation" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key — on retry the original response is replayed (sequential retry only)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConvertInput" }, "example": { "deliverySlotOverrides": { "f1f2f3f4-0000-0000-0000-000000000010": "a1a2a3a4-0000-0000-0000-000000000011" } } } } }, "responses": { "201": { "description": "Created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } }, "example": { "data": { "id": "d4e5f6a7-0000-0000-0000-000000000004", "number": "PED-0042", "invoiceId": null, "clientId": "a1b2c3d4-0000-0000-0000-000000000001", "clientName": "Tienda El Sol", "status": "confirmed", "itemCount": 1, "unitCount": 3, "invoiceNumber": "FE-0042", "invoiceTotal": 135000, "externalPlatform": "api", "createdAt": "2026-06-29T12:00:00Z", "items": [ { "id": "e1f2a3b4-0000-0000-0000-000000000030", "productId": "b2c3d4e5-0000-0000-0000-000000000002", "productOptionId": null, "description": "Camiseta básica negra", "quantity": 3, "unitPrice": 45000 } ] } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — quota full (delivery window) or out of stock", "content": { "application/json": { "examples": { "quotaFull": { "summary": "Delivery slot full", "value": { "error": { "code": "conflict", "message": "Cupo lleno para la fecha" }, "alternatives": [ { "id": "a1a2a3a4-0000-0000-0000-000000000020", "name": "Mañana", "startTime": "08:00", "endTime": "12:00", "remaining": 2 }, { "id": "a1a2a3a4-0000-0000-0000-000000000021", "name": "Tarde", "startTime": "14:00", "endTime": "17:00", "remaining": null } ], "fullSlotId": "a1a2a3a4-0000-0000-0000-000000000010", "deliveryDate": "2026-07-15" } }, "resourceUnavailable": { "summary": "Kit resource unavailable", "value": { "error": { "code": "conflict", "message": "resource_unavailable: Cilindro 40cm" }, "resources": [ "Cilindro 40cm" ] } } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/payment-links": { "get": { "operationId": "listPaymentLinks", "summary": "List payment links", "description": "Returns paginated payment links. Scope required: `payments:read`. Module gate: `payments`.", "tags": [ "Payments" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "clientId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "orderId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "paymentProvider", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "f6a7b8c9-0000-0000-0000-000000000006", "code": "PL-0006", "amount": 135000, "currency": "COP", "status": "pending", "paymentProvider": "wompi", "providerLink": "https://link.wompi.co/xxxxx", "expiresAt": null, "createdAt": "2026-06-29T12:05:00Z" } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "post": { "operationId": "createPaymentLink", "summary": "Create payment link", "description": "Creates a payment link via the configured payment provider. Scope required: `payments:write`. Module gate: `payments`.", "tags": [ "Payments" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key — on retry the original response is replayed (sequential retry only)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkInput" }, "example": { "amount": 135000, "currency": "COP", "paymentProvider": "wompi" } } } }, "responses": { "201": { "description": "Created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" } } }, "example": { "data": { "id": "f6a7b8c9-0000-0000-0000-000000000006", "code": "PL-0006", "amount": 135000, "currency": "COP", "status": "pending", "paymentProvider": "wompi", "providerLink": "https://link.wompi.co/xxxxx", "expiresAt": null, "createdAt": "2026-06-29T12:05:00Z" } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stock insuficiente" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/payment-links/{id}": { "get": { "operationId": "getPaymentLink", "summary": "Get payment link by ID", "description": "Returns a single payment link. Scope required: `payments:read`. Module gate: `payments`.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the payment link" } ], "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" } } }, "example": { "data": { "id": "f6a7b8c9-0000-0000-0000-000000000006", "code": "PL-0006", "amount": 135000, "currency": "COP", "status": "pending", "paymentProvider": "wompi", "providerLink": "https://link.wompi.co/xxxxx", "expiresAt": null, "createdAt": "2026-06-29T12:05:00Z" } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/payment-methods": { "get": { "operationId": "listPaymentMethods", "summary": "List payment methods", "description": "Returns the active payment methods configured for the tenant. Scope required: `payments:read`. Module gate: `payments`.", "tags": [ "Payments" ], "responses": { "200": { "description": "List of active payment methods", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "example": { "data": [ { "id": "a7b8c9d0-0000-0000-0000-000000000007", "name": "Transferencia bancaria", "type": "bank_transfer", "isActive": true } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/shipments": { "get": { "operationId": "listShipments", "summary": "List shipments", "description": "Returns paginated shipments. Scope required: `shipping:read`. Module gate: `shipping`.", "tags": [ "Shipping" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1, "minimum": 1 }, "description": "Page number (1-based)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 }, "description": "Items per page (max 100)" }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "carrier", "in": "query", "schema": { "type": "string" } }, { "name": "orderId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "invoiceId", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Paginated list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Shipment" } }, "meta": { "$ref": "#/components/schemas/PaginatedMeta" } } }, "example": { "data": [ { "id": "b8c9d0e1-0000-0000-0000-000000000008", "status": "in_transit", "carrier": "servientrega", "trackingNumber": "SV123456789CO", "orderId": "d4e5f6a7-0000-0000-0000-000000000004", "createdAt": "2026-06-29T13:00:00Z", "events": [ { "status": "picked_up", "description": "Recogido en origen", "location": "Medellín", "occurredAt": "2026-06-29T13:00:00Z" } ] } ], "meta": { "page": 1, "limit": 20, "total": 1, "totalPages": 1 } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } }, "post": { "operationId": "createShipment", "summary": "Create shipment", "description": "Creates a shipment record linked to an order. Scope required: `shipping:write`. Module gate: `shipping`.", "tags": [ "Shipping" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Optional idempotency key — on retry the original response is replayed (sequential retry only)" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentInput" }, "example": { "carrier": "servientrega", "orderId": "d4e5f6a7-0000-0000-0000-000000000004", "trackingNumber": "SV123456789CO" } } } }, "responses": { "201": { "description": "Created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Shipment" } } }, "example": { "data": { "id": "b8c9d0e1-0000-0000-0000-000000000008", "status": "in_transit", "carrier": "servientrega", "trackingNumber": "SV123456789CO", "orderId": "d4e5f6a7-0000-0000-0000-000000000004", "createdAt": "2026-06-29T13:00:00Z", "events": [ { "status": "picked_up", "description": "Recogido en origen", "location": "Medellín", "occurredAt": "2026-06-29T13:00:00Z" } ] } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stock insuficiente" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/shipments/{id}": { "get": { "operationId": "getShipment", "summary": "Get shipment by ID", "description": "Returns a single shipment with its tracking event history. Scope required: `shipping:read`. Module gate: `shipping`.", "tags": [ "Shipping" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the shipment" } ], "responses": { "200": { "description": "Single item", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Shipment" } } }, "example": { "data": { "id": "b8c9d0e1-0000-0000-0000-000000000008", "status": "in_transit", "carrier": "servientrega", "trackingNumber": "SV123456789CO", "orderId": "d4e5f6a7-0000-0000-0000-000000000004", "createdAt": "2026-06-29T13:00:00Z", "events": [ { "status": "picked_up", "description": "Recogido en origen", "location": "Medellín", "occurredAt": "2026-06-29T13:00:00Z" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/shipments/{id}/tracking": { "post": { "operationId": "addTrackingEvent", "summary": "Add tracking event", "description": "Appends a tracking event to an existing shipment (e.g. from a carrier webhook). Scope required: `shipping:write`. Module gate: `shipping`.", "tags": [ "Shipping" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "UUID of the shipment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrackingEventInput" }, "example": { "status": "in_transit", "description": "En camino al destino", "location": "Bogotá", "source": "carrier" } } } }, "responses": { "201": { "description": "Tracking event recorded", "content": { "application/json": { "example": { "data": { "id": "c0d1e2f3-0000-0000-0000-000000000009", "status": "in_transit", "description": "En camino al destino", "location": "Bogotá", "occurredAt": "2026-06-29T15:00:00Z" } } } } }, "400": { "description": "Validation error — missing or invalid field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation_error", "message": "clientId must be a valid UUID", "details": [ { "field": "clientId", "issue": "invalid UUID" } ] } } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "404": { "description": "Resource not found (or belongs to a different tenant)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Resource not found" } } } } }, "409": { "description": "Conflict — e.g. duplicate Idempotency-Key result or out-of-stock", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Stock insuficiente" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } }, "/carriers": { "get": { "operationId": "listCarriers", "summary": "List carriers", "description": "Returns the static carrier catalog (no DB query). Scope required: `shipping:read`. Module gate: `shipping`.", "tags": [ "Shipping" ], "responses": { "200": { "description": "Carrier catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Carrier" } } } }, "example": { "data": [ { "slug": "servientrega", "name": "Servientrega", "scope": "national", "publicTrackingUrl": "https://www.servientrega.com/wps/portal/Colombia/Servicios-en-Linea/rastrear-envios", "hasAdapter": true } ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_api_key", "message": "Unauthorized" } } } } }, "403": { "description": "Insufficient scope or module not enabled for this tenant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "insufficient_scope", "message": "Scope orders:write required" } } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Too Many Requests" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } } } } } }