{ "openapi": "3.1.0", "info": { "title": "Wocart API", "version": "1.0.0", "description": "Complete reference for the Wocart REST API: merchant endpoints under `/api`, storefront endpoints under `/store`, plus images and webhooks.\n\n## Authentication\n\nMerchant endpoints accept `X-API-Key` or `Authorization: Bearer `. Public storefront endpoints use `X-Store-API-Key`. Operations that require a scheme list it.\n\nRead [Authentication](/authentication) for keys, scopes and failure modes, and [Errors](/errors) for the error envelope and retry guidance.\n\n## Responses\n\nJSON operations wrap their payload as `{ \"success\": true, \"data\": ... }`. List endpoints add a `count`; a few paginated lists use `total` instead. Image endpoints return binary data and webhook endpoints answer carrier-specific payloads. Each operation's response schema is authoritative." }, "servers": [ { "url": "https://api.wocart.store", "description": "Production" }, { "url": "http://localhost:8787", "description": "Local development" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key for authentication. Get your API key from the Developers section." }, "StoreAuth": { "type": "apiKey", "in": "header", "name": "X-Store-API-Key", "description": "Store API key for public storefront endpoints. Different from the dashboard API key." } }, "schemas": { "OrderCreatedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.created" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderUpdatedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.updated" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "changedFields": { "type": "array", "items": { "type": "string", "enum": [ "customerName", "customerPhone", "customerEmail", "destination", "notes" ] } } }, "required": [ "order", "changedFields" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderConfirmedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.confirmed" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderUnreachableEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.unreachable" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderPreparingEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.preparing" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderReadyEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.ready" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderCancelledEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.cancelled" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderLineReturnedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.line_returned" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "lineId": { "type": "string" }, "previousReturnedQuantity": { "type": "integer" } }, "required": [ "order", "lineId", "previousReturnedQuantity" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "OrderDeletedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.deleted" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentHandedOffEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.handed_off" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "shipment", "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentOutForDeliveryEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.out_for_delivery" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentDeliveryFailedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.delivery_failed" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] }, "attempt": { "type": "integer" } }, "required": [ "shipment", "order", "reason", "attempt" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentDeliveredEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.delivered" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentReturnStartedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.return_started" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentReturnedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.returned" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentCancelledEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.cancelled" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "ShipmentVoidedEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.voided" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "shipment", "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, "StoreConfig": { "type": "object", "properties": { "id": { "type": "string", "description": "Store UUID" }, "name": { "type": "string", "example": "متجري" }, "domain": { "type": [ "string", "null" ] }, "logo": { "$ref": "#/components/schemas/MediaImage" }, "lang": { "type": "string", "enum": [ "ar", "fr", "en" ], "description": "The store's primary language", "example": "ar" }, "locale": { "type": "string", "enum": [ "ar", "fr", "en" ], "description": "The language this config is served in: `?locale=` when the store publishes it, else `lang`", "example": "ar" }, "locales": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontLanguage" }, "description": "The published languages, primary first" }, "contentOverrides": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "string" } }, "fr": { "type": "object", "additionalProperties": { "type": "string" } }, "en": { "type": "object", "additionalProperties": { "type": "string" } } }, "description": "The requesting theme's text edits for the published languages; empty without `theme`", "example": { "ar": { "heroTitle": "توصيل مجاني لكل الولايات" }, "fr": { "heroTitle": "Livraison gratuite" } } }, "themeSettings": { "type": "object", "additionalProperties": {}, "description": "The merchant's values for the requesting theme's settings, as saved, by setting key; empty without `theme`. The theme reads them against its declaration (`resolveThemeSettings` in `@wocart/theme`), which falls back to its defaults.", "example": { "font": "Tajawal", "headerMenu": "main-menu" } }, "currency": { "type": "string", "example": "DZD" }, "currencySymbol": { "type": "string", "example": "دج" }, "metaTitle": { "type": [ "string", "null" ] }, "metaDescription": { "type": [ "string", "null" ] }, "ogImage": { "$ref": "#/components/schemas/MediaImage" }, "media": { "$ref": "#/components/schemas/MediaDelivery" }, "reviewsEnabled": { "type": "boolean", "description": "When false, the reviews section is hidden on the storefront", "example": true }, "cartEnabled": { "type": "boolean", "description": "When true the storefront renders the shopping cart alongside the direct order form. False (the default) leaves the storefront exactly as it was.", "example": false }, "freeShippingThreshold": { "type": [ "integer", "null" ], "description": "Order subtotal (DZD) at or above which delivery is free. null = no threshold. Exposed so the storefront can show the promise and how far the shopper is from it.", "example": 10000 }, "otpEnabled": { "type": "boolean", "description": "When true, storefront checkout requires WhatsApp phone verification (dzverify). True only when a store_otp_config row exists AND is enabled.", "example": false }, "turnstileEnabled": { "type": "boolean", "description": "When true, storefront checkout requires a Cloudflare Turnstile token that the server verifies against siteverify. True only when a store_turnstile_config row exists AND is enabled.", "example": false }, "turnstileSiteKey": { "type": [ "string", "null" ], "description": "Public Turnstile widget site key for rendering the checkout widget. null when Turnstile is disabled. The siteverify secret key is never exposed.", "example": "0x4AAAAAAAxxxxxxxxxxxx" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "terms", "privacy", "refund", "shipping", "custom" ] }, "slug": { "type": "string", "example": "refund-policy" }, "title": { "type": "string", "example": "سياسة الإرجاع والاسترجاع" }, "position": { "type": "integer" } }, "required": [ "id", "kind", "slug", "title", "position" ] }, "description": "Published pages that opt into the footer, titled in the store's own language (stores.lang), ordered for display. The checkout consent line resolves Terms/Refund from here by `kind`, never by a hardcoded slug — a merchant may rename any page's slug freely." }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ], "example": "0551234567" }, "email": { "type": [ "string", "null" ], "example": "contact@example.dz" }, "address": { "type": [ "string", "null" ], "example": "12 rue Didouche Mourad, Alger" } }, "required": [ "phone", "email", "address" ], "description": "How a shopper reaches the store, from its legal profile (Settings → Store Pages); each null until the merchant writes it. RC, NIF and the legal name are never exposed here, only inside the documents themselves. The WhatsApp number is `whatsapp.href`." }, "checkoutForm": { "type": "object", "properties": { "address": { "type": "string", "enum": [ "required", "optional" ] }, "notes": { "type": "string", "enum": [ "optional", "hidden" ] }, "email": { "type": "string", "enum": [ "required", "optional", "hidden" ] }, "deliveryOptions": { "type": "object", "properties": { "home": { "type": "boolean" }, "stopDesk": { "type": "boolean" } }, "required": [ "home", "stopDesk" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cf_a1b2c3d4" }, "label": { "type": "string", "example": "Preferred delivery time" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "type", "required" ] } } }, "required": [ "address", "notes", "email", "deliveryOptions", "customFields" ], "description": "The merchant's order-form configuration, already resolved: a store that never customised it gets the defaults, which describe the form exactly as it behaved before this feature existed. The theme renders this and holds no form rules of its own — cod-server enforces every one of them on POST /store/orders, so a hidden field posted from an edge-cached page is dropped and a required one refuses the order. The raw stored column is never exposed." }, "whatsapp": { "$ref": "#/components/schemas/StoreWhatsAppWidget" } }, "required": [ "id", "name", "domain", "logo", "lang", "locale", "locales", "contentOverrides", "themeSettings", "currency", "currencySymbol", "metaTitle", "metaDescription", "ogImage", "media", "reviewsEnabled", "cartEnabled", "freeShippingThreshold", "otpEnabled", "turnstileEnabled", "turnstileSiteKey", "pages", "contact", "checkoutForm", "whatsapp" ] }, "MediaImage": { "type": [ "object", "null" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "url": { "type": "string", "format": "uri", "description": "Where browsers fetch it, from the store's Media Delivery", "example": "https://ik.imagekit.io/wocart/stores/maysa/products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "width": { "type": [ "integer", "null" ], "description": "Pixels, when known", "example": 1200 }, "height": { "type": [ "integer", "null" ], "description": "Pixels, when known", "example": 900 } }, "required": [ "key", "url", "width", "height" ] }, "StorefrontLanguage": { "type": "object", "properties": { "code": { "type": "string", "description": "BCP 47 language tag", "example": "ar" }, "nativeName": { "type": "string", "description": "The language's name in itself", "example": "العربية" }, "direction": { "type": "string", "enum": [ "rtl", "ltr" ] } }, "required": [ "code", "nativeName", "direction" ] }, "MediaDelivery": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "imagekit", "cloudflare", "direct" ], "description": "How images are resized: `imagekit` (`?tr=`), `cloudflare` (`/cdn-cgi/image/`), or `direct` (not resized)" }, "origin": { "type": "string", "format": "uri", "description": "A key's URL is this origin, a slash and the key", "example": "https://ik.imagekit.io/wocart/stores/maysa" } }, "required": [ "kind", "origin" ], "description": "How the storefront fetches and resizes every image key (ADR 0021)" }, "StoreWhatsAppWidget": { "type": [ "object", "null" ], "properties": { "href": { "type": "string", "description": "The wa.me link, ready to use. Digits only — a '+' in the path makes WhatsApp answer with an invalid-number page.", "example": "https://wa.me/213551234567" }, "agentName": { "type": [ "string", "null" ], "description": "Who the shopper is talking to. Null means the theme uses the store name.", "example": "أمين" }, "caption": { "type": [ "string", "null" ], "description": "The line under the name, e.g. how fast the merchant answers.", "example": "نرد خلال دقائق" }, "avatarUrl": { "type": [ "string", "null" ], "description": "The avatar's URL, from the store's Media Delivery. Null means the theme falls back to the store logo." }, "welcomeMessage": { "type": [ "string", "null" ], "description": "The bubble in the panel, before the shopper opens WhatsApp." }, "launcherLabel": { "type": [ "string", "null" ], "description": "Text on the floating launcher." }, "ctaLabel": { "type": [ "string", "null" ], "description": "The panel's button that opens WhatsApp." }, "prefillGeneral": { "type": [ "string", "null" ], "description": "The message WhatsApp opens with on a page that has no product. May contain {url}, {order} and {store}, which the theme resolves from the page." }, "prefillProduct": { "type": [ "string", "null" ], "description": "Same, for a product or landing page. May also contain {product}.", "example": "سلام، بغيت نسقسي على {product}" }, "thankYouButtonLabel": { "type": [ "string", "null" ], "description": "The WhatsApp button on the order confirmation." }, "prefillThankYou": { "type": [ "string", "null" ], "description": "The message that button opens WhatsApp with. May contain {order}.", "example": "سلام، درت الطلب {order}" }, "accent": { "type": "string", "enum": [ "whatsapp", "primary" ], "description": "Brand green, or the store's own primary colour." }, "position": { "type": "string", "enum": [ "right", "left" ], "description": "Which physical side the launcher sits on, in both LTR and RTL." }, "attention": { "type": "boolean", "description": "One attention pulse per session, suppressed under prefers-reduced-motion." }, "surfaces": { "type": "object", "properties": { "home": { "type": "boolean" }, "catalog": { "type": "boolean" }, "product": { "type": "boolean" }, "pages": { "type": "boolean" }, "thankYou": { "type": "boolean" }, "checkout": { "type": "boolean" }, "landing": { "type": "boolean" } }, "required": [ "home", "catalog", "product", "pages", "thankYou", "checkout", "landing" ], "description": "Which kinds of page the launcher appears on. `checkout` and `landing` are off by default: both already carry their own sticky order CTA, and a second floating control competing for the same thumb costs the order." } }, "required": [ "href", "agentName", "caption", "avatarUrl", "welcomeMessage", "launcherLabel", "ctaLabel", "prefillGeneral", "prefillProduct", "thankYouButtonLabel", "prefillThankYou", "accent", "position", "attention", "surfaces" ], "description": "The WhatsApp contact widget, already resolved — or null, which is what a store gets when the widget is off, has no number, or holds a number that no longer normalises. A theme's entire gate is this being non-null and the current surface being on in `surfaces`. The raw stored column is never exposed." }, "StorefrontMenu": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "example": "main-menu" }, "title": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/StorefrontMenuItem" }, "description": "Only items a shopper can follow: one whose destination is deleted or not public is left out, with its children" } }, "required": [ "handle", "title", "items" ] }, "StorefrontMenuItem": { "type": "object", "properties": { "label": { "type": "string", "description": "In the requested language when the store translated it" }, "href": { "type": "string", "description": "A path of the store without a language prefix (`/products/robe`), or the URL the merchant entered", "example": "/category/robes" }, "type": { "type": "string", "enum": [ "home", "catalog", "search", "trackOrder", "contact", "category", "collection", "product", "page", "landing", "url" ] }, "children": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "In the requested language when the store translated it" }, "href": { "type": "string", "description": "A path of the store without a language prefix (`/products/robe`), or the URL the merchant entered", "example": "/category/robes" }, "type": { "type": "string", "enum": [ "home", "catalog", "search", "trackOrder", "contact", "category", "collection", "product", "page", "landing", "url" ] }, "children": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "In the requested language when the store translated it" }, "href": { "type": "string", "description": "A path of the store without a language prefix (`/products/robe`), or the URL the merchant entered", "example": "/category/robes" }, "type": { "type": "string", "enum": [ "home", "catalog", "search", "trackOrder", "contact", "category", "collection", "product", "page", "landing", "url" ] }, "children": { "type": "array", "items": {}, "maxItems": 0, "description": "Always empty: a third-level item has no children" } }, "required": [ "label", "href", "type", "children" ] } } }, "required": [ "label", "href", "type", "children" ] } } }, "required": [ "label", "href", "type", "children" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "example": "Resource not found" }, "code": { "type": "string", "example": "RESOURCE_NOT_FOUND" }, "category": { "type": "string", "enum": [ "VALIDATION", "AUTHENTICATION", "BUSINESS_LOGIC", "SYSTEM" ], "example": "BUSINESS_LOGIC" }, "context": { "type": "object", "additionalProperties": {}, "description": "Additional context about the error (optional)" } }, "required": [ "error", "code", "category" ], "description": "Standard error envelope returned by all non-2xx responses." }, "StorefrontCollection": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "example": "best-sellers" }, "title": { "type": "string", "description": "In the requested language when the store translated it" }, "description": { "type": [ "string", "null" ] }, "productCount": { "type": "integer", "minimum": 0, "description": "How many products a shopper sees in it" }, "image": { "$ref": "#/components/schemas/StoreProductImage" } }, "required": [ "handle", "title", "description", "productCount", "image" ] }, "StoreProductImage": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "altText": { "type": [ "string", "null" ], "description": "Alt text for accessibility" }, "position": { "type": "integer", "minimum": 1, "description": "Display order (1 = first)" } }, "required": [ "id", "altText", "position" ] } ], "description": "The first photo of the first product it lists, in the merchant's order, that has one; null when none does" }, "StoreProductList": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "Samsung Galaxy A54" }, "description": { "type": [ "string", "null" ] }, "descriptionFormat": { "type": "string", "enum": [ "text", "html" ], "description": "How `description` is stored. `text` renders as literal text (legacy rows and products created without a format); `html` is sanitised rich text — render only via a strict HTML sink." }, "descriptionPlain": { "type": [ "string", "null" ], "description": "Tag-free rendering of `description` for and JSON-LD. Identical to `description` for `text` rows; null when `description` is null." }, "handle": { "type": "string", "example": "samsung-galaxy-a54" }, "currency": { "type": "string", "example": "DZD" }, "price": { "type": "number", "example": 45000 }, "compareAtPrice": { "type": [ "number", "null" ] }, "type": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ] }, "hasVariants": { "type": "boolean" }, "sku": { "type": [ "string", "null" ] }, "inventory": { "type": "integer" }, "trackInventory": { "type": "boolean" }, "lowStockThreshold": { "type": "integer", "description": "Threshold for low stock warnings" }, "categoryId": { "type": [ "string", "null" ] }, "metaTitle": { "type": [ "string", "null" ], "description": "The title search engines and shared links show, in the requested language when translated; null: use the product's name." }, "metaDescription": { "type": [ "string", "null" ], "description": "The description search engines and shared links show, in the requested language when translated; null: use `descriptionPlain`, shortened." }, "variantOptions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Color" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "Red" }, "hexColor": { "type": [ "string", "null" ], "example": "#FF0000" } }, "required": [ "value", "hexColor" ] } } }, "required": [ "name", "values" ] }, "description": "Parsed variant option axes. null for simple products." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Parsed tag list", "example": [ "sale", "new" ] }, "coverImage": { "allOf": [ { "$ref": "#/components/schemas/StoreProductImage" }, { "description": "First image by position, or null if no images" } ] }, "reviewStats": { "type": [ "object", "null" ], "properties": { "avgRating": { "type": "number", "description": "Average rating (1.0–5.0, rounded to 1 decimal)", "example": 4.5 }, "reviewCount": { "type": "integer", "description": "Number of approved reviews", "example": 12 } }, "required": [ "avgRating", "reviewCount" ], "description": "Aggregate review stats (approved reviews only). null if no approved reviews exist for this product." } }, "required": [ "id", "name", "description", "descriptionFormat", "descriptionPlain", "handle", "currency", "price", "compareAtPrice", "type", "hasVariants", "sku", "inventory", "trackInventory", "lowStockThreshold", "categoryId", "metaTitle", "metaDescription", "variantOptions", "tags", "coverImage", "reviewStats" ] }, "StoreProductDetail": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string", "example": "Samsung Galaxy A54" }, "description": { "type": [ "string", "null" ] }, "descriptionFormat": { "type": "string", "enum": [ "text", "html" ], "description": "How `description` is stored. `text` renders as literal text (legacy rows and products created without a format); `html` is sanitised rich text — render only via a strict HTML sink." }, "descriptionPlain": { "type": [ "string", "null" ], "description": "Tag-free rendering of `description` for and JSON-LD. Identical to `description` for `text` rows; null when `description` is null." }, "handle": { "type": "string", "example": "samsung-galaxy-a54" }, "currency": { "type": "string", "example": "DZD" }, "price": { "type": "number", "example": 45000 }, "compareAtPrice": { "type": [ "number", "null" ] }, "type": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ] }, "hasVariants": { "type": "boolean" }, "sku": { "type": [ "string", "null" ] }, "inventory": { "type": "integer" }, "trackInventory": { "type": "boolean" }, "lowStockThreshold": { "type": "integer", "description": "Threshold for low stock warnings" }, "categoryId": { "type": [ "string", "null" ] }, "metaTitle": { "type": [ "string", "null" ], "description": "The title search engines and shared links show, in the requested language when translated; null: use the product's name." }, "metaDescription": { "type": [ "string", "null" ], "description": "The description search engines and shared links show, in the requested language when translated; null: use `descriptionPlain`, shortened." }, "variantOptions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Color" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "Red" }, "hexColor": { "type": [ "string", "null" ], "example": "#FF0000" } }, "required": [ "value", "hexColor" ] } } }, "required": [ "name", "values" ] }, "description": "Parsed variant option axes. null for simple products." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Parsed tag list", "example": [ "sale", "new" ] }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "cat_123" }, "name": { "type": "string", "example": "Electronics" }, "slug": { "type": "string", "example": "electronics", "description": "Lowercase letters, numbers and hyphens; auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ], "example": "Electronic products" }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID for nested hierarchies; null for top-level groups", "example": null }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The group's image, from its Media Key" } ] }, "metaTitle": { "type": [ "string", "null" ], "description": "SEO page title (max 60 chars)", "example": "Electronics | Wocart" }, "metaDescription": { "type": [ "string", "null" ], "description": "SEO description (max 160 chars)", "example": "Phones, laptops and accessories" }, "metaKeywords": { "type": [ "string", "null" ], "description": "Comma-separated SEO keywords", "example": "electronics, gadgets" }, "position": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order; lower values come first" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "parentId", "image", "metaTitle", "metaDescription", "metaKeywords", "position", "createdAt", "updatedAt" ], "description": "Joined category, or null if no category assigned." }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "variations": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Option name → value, in the requested language", "example": { "Color": "Red", "Size": "M" } }, "price": { "type": "number", "example": 45000 }, "compareAtPrice": { "type": [ "number", "null" ] }, "sku": { "type": [ "string", "null" ] }, "inventory": { "type": "integer" }, "lowStockThreshold": { "type": "integer" }, "imageId": { "type": [ "string", "null" ], "description": "The product image this variant shows" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "variations", "price", "compareAtPrice", "sku", "inventory", "lowStockThreshold", "imageId", "isDefault" ] }, "description": "Active variants ordered by position. Empty array for simple products." }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProductImage" }, "description": "All product images ordered by position." }, "reviewStats": { "type": [ "object", "null" ], "properties": { "avgRating": { "type": "number", "description": "Average rating (1.0–5.0, rounded to 1 decimal)", "example": 4.5 }, "reviewCount": { "type": "integer", "description": "Number of approved reviews", "example": 12 } }, "required": [ "avgRating", "reviewCount" ], "description": "Aggregate review stats (approved reviews only). null if no approved reviews exist for this product." }, "quantityPricing": { "$ref": "#/components/schemas/StoreQuantityPricing" }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Offer UUID" }, "name": { "type": "string", "description": "Merchant-facing offer name — display as the offer banner title.", "example": "اشتري 2 واحصل على 1 مجاناً" }, "discountType": { "type": "string", "enum": [ "free", "free_shipping" ], "description": "`free` = Buy X Get Y (reward product added at $0). `free_shipping` = delivery fee waived for this order." }, "triggerQuantity": { "type": "integer", "description": "Minimum quantity the customer must order to trigger the offer.", "example": 2 }, "triggerVariantId": { "type": [ "string", "null" ], "description": "Trigger variant restriction. null = offer applies to any variant. When non-null, the offer only activates if the customer selects this specific variant." }, "rewardQuantity": { "type": "integer", "description": "Number of free units of the reward product added to the order.", "example": 1 }, "rewardProductId": { "type": [ "string", "null" ], "description": "UUID of the product given for free. null for `free_shipping` offers (no reward product)." }, "rewardProductName": { "type": "string", "description": "Display name of the reward product. Empty string for `free_shipping` offers.", "example": "Samsung Galaxy A54" }, "rewardVariantId": { "type": [ "string", "null" ], "description": "UUID of the specific reward variant. null = server resolves automatically (same variant as ordered when same product, or first active variant when different product)." }, "rewardVariantLabel": { "type": [ "string", "null" ], "description": "Human-readable reward variant label (e.g. 'أزرق / 128 GB'). null when no specific variant is fixed." }, "rewardUnitPrice": { "type": [ "number", "null" ], "description": "What one gift unit is worth at list price: the reward variant's price, or the reward product's when there is no variant. The storefront states savings at this value." } }, "required": [ "id", "name", "discountType", "triggerQuantity", "triggerVariantId", "rewardQuantity", "rewardProductId", "rewardProductName", "rewardVariantId", "rewardVariantLabel", "rewardUnitPrice" ] }, "description": "Live Buy X Get Y and free-delivery offers for this product (quantity pricing is `quantityPricing`). Only includes offers where `status=active` and the current time is within the optional schedule window. The storefront uses this list to display offer banners and to show the free reward row in the order summary when the customer selects a matching variant and quantity." } }, "required": [ "id", "name", "description", "descriptionFormat", "descriptionPlain", "handle", "currency", "price", "compareAtPrice", "type", "hasVariants", "sku", "inventory", "trackInventory", "lowStockThreshold", "categoryId", "metaTitle", "metaDescription", "variantOptions", "tags", "category", "variants", "images", "reviewStats", "quantityPricing", "offers" ] }, "StoreQuantityPricing": { "type": [ "object", "null" ], "properties": { "offerId": { "type": "string" }, "name": { "type": "string", "description": "The offer's name, in the requested language", "example": "عروض الكمية" }, "triggerVariantId": { "type": [ "string", "null" ], "description": "When set, only this variant's units count and are priced by the tiers" }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "example": 2 }, "price": { "type": "integer", "description": "What that many units cost, in DZD", "example": 3500 }, "freeShipping": { "type": "boolean", "description": "Delivery is free from this tier, for a basket of this product alone" } }, "required": [ "quantity", "price", "freeShipping" ] }, "description": "In increasing quantity" } }, "required": [ "offerId", "name", "triggerVariantId", "tiers" ], "description": "The product's live quantity pricing — price tiers by quantity — or null. A separate field from `offers` (whose kinds published SDKs validate): the highest tier the quantity reaches prices every unit at its per-unit price; the cart quote and the order charge exactly that." }, "StoreLandingPage": { "type": "object", "properties": { "id": { "type": "string", "example": "lp_abc123" }, "slug": { "type": "string", "example": "lp-9f3a2b1c" }, "name": { "type": "string", "example": "Zinc v3 — carousel ad" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ], "example": "published" }, "imageGap": { "type": "integer", "description": "Pixels between stacked images", "example": 0 }, "metaTitle": { "type": [ "string", "null" ], "example": "Samsung A55 — عرض خاص" }, "metaDescription": { "type": [ "string", "null" ], "example": "اطلب الآن — الدفع عند الاستلام" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "images": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "type": "object", "properties": { "id": { "type": "string", "example": "lpimg_abc123" }, "altText": { "type": [ "string", "null" ], "example": "عرض خاص" }, "position": { "type": "integer", "example": 1 } }, "required": [ "id", "altText", "position" ] } ] }, "description": "The image stack, ordered by position (1 = top)" }, "product": { "allOf": [ { "$ref": "#/components/schemas/StoreProductDetail" }, { "type": [ "object", "null" ], "description": "The product in its full store-product shape — the landing page renders the same data the product page does, so the order form works unmodified. Null when the product is no longer publicly visible." } ] }, "document": { "$ref": "#/components/schemas/PageDocument" }, "tracking": { "$ref": "#/components/schemas/StorePublicTracking" } }, "required": [ "id", "slug", "name", "status", "imageGap", "metaTitle", "metaDescription", "publishedAt", "images", "product", "document", "tracking" ] }, "PageDocument": { "type": [ "object", "null" ], "properties": { "version": { "type": "integer" }, "surface": { "type": "string" }, "sections": { "type": "array", "items": {} } }, "required": [ "version", "surface", "sections" ], "additionalProperties": {}, "description": "This page's own composition (its `lp:` page document) for the requesting `theme`, written by Wocart Cloud's editor; null when it has none or no `theme` is named — the theme then renders its `landing` default." }, "StorePublicTracking": { "type": "object", "properties": { "pixelId": { "type": [ "string", "null" ], "description": "The Meta Pixel to load, or null when no pixel should load at all. Public by definition — it appears in the page source. The Conversions API token is never included.", "example": "1234567890123456" }, "conversionEvent": { "type": "string", "enum": [ "Lead", "Purchase", "Purchase_Confirmed", "Purchase_Delivered" ], "description": "Which moment counts as a conversion here. Inert while pixelId is null.", "example": "Purchase" } }, "required": [ "pixelId", "conversionEvent" ], "description": "Which Meta pixel THIS page loads and fires at, already resolved server-side: the page's own pixel when it has one in force, otherwise the store's. The browser never works this out for itself, so it cannot disagree with the Conversions API mirror." }, "StorePagePublic": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "terms", "privacy", "refund", "shipping", "custom" ] }, "slug": { "type": "string", "example": "refund-policy" }, "locale": { "type": "string", "enum": [ "ar", "fr", "en" ], "description": "The locale actually served — the store's own language, or the fallback locale when that translation doesn't exist (see legal/render.ts's resolution order)." }, "title": { "type": "string" }, "bodyHtml": { "type": "string", "description": "Sanitised HTML. Render with set:html and never re-sanitise." }, "metaTitle": { "type": [ "string", "null" ] }, "metaDescription": { "type": [ "string", "null" ] } }, "required": [ "id", "kind", "slug", "locale", "title", "bodyHtml", "metaTitle", "metaDescription" ] }, "StoreOrderTracking": { "type": "object", "properties": { "pixelId": { "type": [ "string", "null" ], "description": "The Meta pixel this order belongs to, or null when tracking is off.", "example": "1234567890123456" }, "event": { "type": [ "string", "null" ], "enum": [ "Purchase", "Lead", null ], "description": "The browser event the thank-you page should fire, or null when none should — tracking is off, or the merchant's conversion fires further down the funnel from the server only.", "example": "Purchase" } }, "required": [ "pixelId", "event" ] }, "ShopperOrderStatus": { "type": "object", "properties": { "orderNumber": { "type": "string" }, "placedAt": { "type": "string", "description": "When the order was placed (ISO 8601)" }, "stage": { "type": "string", "enum": [ "placed", "confirmed", "preparing", "shipped", "out_for_delivery", "delivered", "returned", "cancelled" ], "description": "Where the order is, in the shopper's words: `placed` (not confirmed yet), `confirmed`, `preparing`, `shipped`, `out_for_delivery`, `delivered`, `returned` (refused at the door) or `cancelled`." }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "As it was sold, in the catalog's language" }, "variantLabel": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" } }, "required": [ "name", "variantLabel", "quantity" ] } }, "total": { "type": "number", "description": "What the shopper pays on delivery" }, "tracking": { "type": [ "object", "null" ], "properties": { "number": { "type": "string" }, "carrier": { "type": [ "string", "null" ] } }, "required": [ "number", "carrier" ], "description": "The carrier's tracking number once the parcel is with it; null before, or with the store's own driver" } }, "required": [ "orderNumber", "placedAt", "stage", "deliveryType", "lines", "total", "tracking" ] }, "UploadTicket": { "type": "object", "properties": { "mediaId": { "type": "string", "description": "Complete the upload with this id" }, "key": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "expiresAt": { "type": "string", "format": "date-time" }, "send": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "form" ] }, "method": { "type": "string", "enum": [ "POST" ] }, "url": { "type": "string", "format": "uri" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "fileField": { "type": "string" } }, "required": [ "kind", "method", "url", "fields", "fileField" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "put" ] }, "method": { "type": "string", "enum": [ "PUT" ] }, "url": { "type": "string", "format": "uri" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "kind", "method", "url", "headers" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "relay" ] }, "method": { "type": "string", "enum": [ "PUT" ] }, "url": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "kind", "method", "url", "headers" ] } ], "description": "How to send the file: `form` — POST multipart `fields` plus the file as `fileField` to `url`; `put` — PUT the bytes to `url` with exactly `headers`; `relay` — PUT the bytes to this server's `url` (a path) with `headers`." } }, "required": [ "mediaId", "key", "expiresAt", "send" ] }, "ActivityLog": { "type": "object", "properties": { "id": { "type": "string" }, "actorId": { "type": "string" }, "actorName": { "type": "string", "example": "Ahmed Benali" }, "actorRole": { "type": "string", "enum": [ "admin", "staff" ] }, "action": { "type": "string", "description": "Dot-notation action identifier. Valid values: `order.created`, `order.status_changed`, `order.driver_assigned`, `order.dispatched`, `order.deleted`, `shipment.voided`, `shipment.released`, `customer.created`, `customer.updated`, `customer.deleted`, `customer_group.created`, `customer_group.updated`, `customer_group.deleted`, `customer_group.member_added`, `customer_group.member_removed`, `customer_tag.created`, `customer_tag.updated`, `customer_tag.deleted`, `customer_tag.assigned`, `customer_tag.unassigned`, `driver.created`, `driver.updated`, `driver.status_changed`, `driver.deleted`, `product.created`, `product.updated`, `product.status_changed`, `product.deleted`, `review.approved`, `review.rejected`, `review.deleted`, `user.created`, `user.updated`, `user.role_changed`, `user.scope_granted`, `user.scope_revoked`, `user.api_key_generated`, `user.api_key_revoked`", "example": "order.created" }, "entityType": { "type": "string", "description": "Entity category the action applies to. Valid values: `order`, `customer`, `customer_group`, `customer_tag`, `driver`, `product`, `review`, `user`", "example": "order" }, "entityId": { "type": "string" }, "entityLabel": { "type": [ "string", "null" ], "example": "ORD-0042", "description": "Human-readable label at the time of action (order number, customer name, etc.)" }, "metadata": { "type": [ "string", "null" ], "description": "JSON-encoded extra context. Shape varies by action: `{ from, to }` for `order.status_changed`, `{ amount }` for payments, `{ scope }` for permission changes, `{ role }` for role changes, `{ rating, orderNumber }` for review actions" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "actorId", "actorName", "actorRole", "action", "entityType", "entityId", "entityLabel", "metadata", "createdAt" ] }, "BusinessEvent": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.created" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.updated" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "changedFields": { "type": "array", "items": { "type": "string", "enum": [ "customerName", "customerPhone", "customerEmail", "destination", "notes" ] } } }, "required": [ "order", "changedFields" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.confirmed" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.unreachable" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.preparing" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.ready" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.cancelled" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "previousStatus": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "order", "previousStatus" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.line_returned" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "lineId": { "type": "string" }, "previousReturnedQuantity": { "type": "integer" } }, "required": [ "order", "lineId", "previousReturnedQuantity" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.deleted" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.handed_off" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "shipment", "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.out_for_delivery" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.delivery_failed" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] }, "attempt": { "type": "integer" } }, "required": [ "shipment", "order", "reason", "attempt" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.delivered" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.return_started" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.returned" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.cancelled" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] }, "reason": { "type": [ "string", "null" ] } }, "required": [ "shipment", "order", "reason" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "shipment.voided" ] }, "version": { "type": "integer" }, "subject": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "shipment" ] }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "actor": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "staff", "agent", "carrier" ] }, "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "kind", "id", "name" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "shopper", "system" ] }, "id": { "type": "null" }, "name": { "type": "null" } }, "required": [ "kind", "id", "name" ] } ] }, "origin": { "type": "string", "enum": [ "dashboard", "api", "agent", "storefront", "carrier_webhook", "carrier_sync", "schedule" ] }, "data": { "type": "object", "properties": { "shipment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "carrier": { "type": [ "object", "null" ], "properties": { "companyId": { "type": "string" }, "name": { "type": "string" }, "provider": { "type": [ "string", "null" ] } }, "required": [ "companyId", "name", "provider" ] }, "driver": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "providerStatus": { "type": [ "object", "null" ], "properties": { "value": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "value", "label" ] }, "handedOffAt": { "type": "string", "format": "date-time" }, "outForDeliveryAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "returnedAt": { "type": [ "string", "null" ], "format": "date-time" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "deliveryAttempts": { "type": "integer" } }, "required": [ "id", "kind", "carrier", "driver", "trackingNumber", "deliveryType", "stationCode", "codAmount", "providerStatus", "handedOffAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts" ] }, "order": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "type": { "type": "string", "enum": [ "online", "offline" ] }, "placedAt": { "type": "string", "format": "date-time" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "customer": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "phone", "email" ] }, "destination": { "type": "object", "properties": { "wilaya": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "id", "name", "nameAr" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] } }, "required": [ "wilaya", "commune", "city", "address", "deliveryType", "stationCode" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" }, "unitPrice": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "gift": { "type": "boolean" }, "offer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "returnedQuantity": { "type": "integer" } }, "required": [ "id", "productId", "variantId", "name", "variantLabel", "sku", "quantity", "unitPrice", "discount", "total", "gift", "offer", "returnedQuantity" ] } }, "subtotal": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "deliveryFee": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "total": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] }, "coupon": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "discount": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$" }, "currency": { "type": "string", "enum": [ "DZD" ] } }, "required": [ "amount", "currency" ] } }, "required": [ "code", "discount" ] }, "freeDeliveryOffer": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ] }, "notes": { "type": [ "string", "null" ] }, "customFields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "value": { "type": "string" } }, "required": [ "id", "label", "type", "value" ] } } }, "required": [ "id", "number", "status", "type", "placedAt", "locale", "customer", "destination", "lines", "subtotal", "deliveryFee", "total", "coupon", "freeDeliveryOffer", "notes", "customFields" ] } }, "required": [ "shipment", "order" ] } }, "required": [ "id", "sequence", "type", "version", "subject", "orderId", "occurredAt", "recordedAt", "actor", "origin", "data" ] } ], "description": "A Business Event as it is published: its envelope — id (the same on every delivery), Sequence, type and version, subject, order, when it happened and was recorded, who caused it and through what — and the data its type and version promise. Fields are only ever added." }, "EventConsumer": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "description": "How it is reached: `webhook` (an endpoint of the merchant's own) or `meta_capi` (Meta conversions)", "example": "webhook" }, "name": { "type": "string" }, "enabled": { "type": "boolean" }, "builtIn": { "type": "boolean", "description": "Kept by its App (Meta conversions, by the Meta App): it can be started and stopped, not edited or deleted" }, "subscription": { "type": "array", "items": { "type": "string" }, "description": "The Event Types it receives, each named exactly, by subject (`order.*`), or `*`", "example": [ "order.created", "shipment.delivered" ] }, "catalogueVersion": { "type": "integer", "description": "The catalogue version its Deliveries are written in" }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "failing", "merchant", "gone", "bot_blocked", "not_connected", null ], "description": "Why it stopped receiving, while disabled: `failing` (every Attempt failed for 3 days), `merchant`, `gone` (its endpoint answered HTTP 410 Gone), `bot_blocked` (its Telegram chat blocked the bot), or `not_connected` (no Telegram chat connected yet)" }, "failingSince": { "type": [ "string", "null" ], "description": "Since when every Attempt has failed; null once one succeeds" }, "deliveries": { "type": "object", "properties": { "due": { "type": "integer", "description": "Deliveries on their way" }, "dead": { "type": "integer", "description": "Deliveries given up on, waiting for a Replay" } }, "required": [ "due", "dead" ] }, "webhook": { "type": [ "object", "null" ], "properties": { "url": { "type": "string" }, "signingSecret": { "type": "string", "description": "The Signing Secret, masked: shown in full only when it is made", "example": "••••Xw4=", "x-credential": "masked" }, "secretRotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "previousSecretSignsUntil": { "type": [ "string", "null" ], "format": "date-time", "description": "After a rotation, until when Deliveries are also signed with the previous secret" } }, "required": [ "url", "signingSecret", "secretRotatedAt", "previousSecretSignsUntil" ], "description": "A webhook Consumer's endpoint; null for any other kind" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "kind", "name", "enabled", "builtIn", "subscription", "catalogueVersion", "disabledReason", "failingSince", "deliveries", "webhook", "createdAt", "updatedAt" ] }, "WebhookCreated": { "type": "object", "properties": { "consumer": { "$ref": "#/components/schemas/EventConsumer" }, "signingSecret": { "type": "string", "description": "The Signing Secret, in full: shown this once. Verify Deliveries with it (Standard Webhooks)", "example": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw", "x-credential": "issued" } }, "required": [ "consumer", "signingSecret" ] }, "MessageResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string" } }, "required": [ "success", "message" ] }, "SigningSecret": { "type": "object", "properties": { "signingSecret": { "type": "string", "description": "The Signing Secret, in full: shown this once. Verify Deliveries with it (Standard Webhooks)", "example": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw", "x-credential": "issued" }, "previousSecretSignsUntil": { "type": "string", "format": "date-time", "description": "Until when Deliveries are also signed with the secret this one replaces" } }, "required": [ "signingSecret", "previousSecretSignsUntil" ] }, "WebhookTest": { "type": "object", "properties": { "event": { "type": "object", "properties": { "id": { "type": "string", "example": "test_0b7e4c1a-2f7d-4a52-9d1e-1f3c5a9b7e21" }, "type": { "type": "string", "enum": [ "order.created", "order.updated", "order.confirmed", "order.unreachable", "order.preparing", "order.ready", "order.cancelled", "order.line_returned", "order.deleted", "shipment.handed_off", "shipment.out_for_delivery", "shipment.delivery_failed", "shipment.delivered", "shipment.return_started", "shipment.returned", "shipment.cancelled", "shipment.voided" ] } }, "required": [ "id", "type" ] }, "outcome": { "type": "string", "enum": [ "delivered", "retry", "reject" ], "description": "What a Delivery's Attempt would have come to" }, "httpStatus": { "type": [ "integer", "null" ] }, "durationMs": { "type": "integer" }, "response": { "type": [ "string", "null" ], "description": "The start of what the endpoint answered" }, "error": { "type": [ "string", "null" ] } }, "required": [ "event", "outcome", "httpStatus", "durationMs", "response", "error" ] }, "Redelivery": { "type": "object", "properties": { "reopened": { "type": "integer", "description": "Settled Deliveries made due again" }, "created": { "type": "integer", "description": "Deliveries made for events the Consumer never had one for" } }, "required": [ "reopened", "created" ] }, "EventDelivery": { "type": "object", "properties": { "id": { "type": "string" }, "consumerId": { "type": "string" }, "state": { "type": "string", "enum": [ "due", "delivered", "skipped", "dead" ], "description": "`due` (on its way), `delivered`, `skipped` (declined on purpose) or `dead` (given up on)" }, "attempts": { "type": "integer", "description": "Attempts since it was last made due; a retry or Replay starts them over" }, "nextAttemptAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "settledAt": { "type": [ "string", "null" ] }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.created", "order.updated", "order.confirmed", "order.unreachable", "order.preparing", "order.ready", "order.cancelled", "order.line_returned", "order.deleted", "shipment.handed_off", "shipment.out_for_delivery", "shipment.delivery_failed", "shipment.delivered", "shipment.return_started", "shipment.returned", "shipment.cancelled", "shipment.voided" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string" } }, "required": [ "id", "sequence", "type", "orderId", "occurredAt" ] } }, "required": [ "id", "consumerId", "state", "attempts", "nextAttemptAt", "lastError", "createdAt", "settledAt", "event" ] }, "EventDeliveryDetail": { "type": "object", "properties": { "id": { "type": "string" }, "consumerId": { "type": "string" }, "state": { "type": "string", "enum": [ "due", "delivered", "skipped", "dead" ], "description": "`due` (on its way), `delivered`, `skipped` (declined on purpose) or `dead` (given up on)" }, "attempts": { "type": "integer", "description": "Attempts since it was last made due; a retry or Replay starts them over" }, "nextAttemptAt": { "type": [ "string", "null" ] }, "lastError": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "settledAt": { "type": [ "string", "null" ] }, "event": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "integer" }, "type": { "type": "string", "enum": [ "order.created", "order.updated", "order.confirmed", "order.unreachable", "order.preparing", "order.ready", "order.cancelled", "order.line_returned", "order.deleted", "shipment.handed_off", "shipment.out_for_delivery", "shipment.delivery_failed", "shipment.delivered", "shipment.return_started", "shipment.returned", "shipment.cancelled", "shipment.voided" ] }, "orderId": { "type": "string" }, "occurredAt": { "type": "string" } }, "required": [ "id", "sequence", "type", "orderId", "occurredAt" ] }, "attemptLog": { "type": "array", "items": { "$ref": "#/components/schemas/EventDeliveryAttempt" }, "description": "Every Attempt, oldest first — those before a retry or Replay too" } }, "required": [ "id", "consumerId", "state", "attempts", "nextAttemptAt", "lastError", "createdAt", "settledAt", "event", "attemptLog" ] }, "EventDeliveryAttempt": { "type": "object", "properties": { "attempt": { "type": "integer" }, "attemptedAt": { "type": "string" }, "durationMs": { "type": "integer" }, "outcome": { "type": "string", "enum": [ "delivered", "skipped", "retry", "reject" ] }, "httpStatus": { "type": [ "integer", "null" ] }, "responseExcerpt": { "type": [ "string", "null" ], "description": "The first kilobyte of what the Consumer answered" }, "error": { "type": [ "string", "null" ] } }, "required": [ "attempt", "attemptedAt", "durationMs", "outcome", "httpStatus", "responseExcerpt", "error" ] }, "OrderListItem": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "orderNumber": { "type": "string", "example": "ORD-20260327-0042" }, "customerId": { "type": "string" }, "customerName": { "type": "string", "example": "Ahmed Benali" }, "phone": { "type": "string", "example": "0551234567" }, "wilayaId": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 58, "example": 16 }, "wilaya": { "type": [ "string", "null" ], "description": "Wilaya Arabic name, joined from reference table", "example": "الجزائر" }, "communeId": { "type": [ "string", "null" ] }, "commune": { "type": [ "string", "null" ], "description": "Commune Arabic name, joined from reference table", "example": "بئر مراد رايس" }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "Product subtotal (excluding delivery fee)", "example": 9000 }, "deliveryFee": { "type": "number", "example": 400 }, "codAmount": { "type": [ "number", "null" ], "description": "What the customer owes on delivery: price + deliveryFee", "example": 9400 }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ], "description": "The order's processing; its delivery is its shipment's (see `stage`)" }, "orderType": { "type": "string", "enum": [ "online", "offline" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "description": "What the customer asked for; the shipment may ship otherwise" }, "stationCode": { "type": [ "string", "null" ] }, "driverName": { "type": [ "string", "null" ], "description": "The name of the store's driver delivering it, when its shipment is a driver's" }, "notes": { "type": [ "string", "null" ] }, "landingPageId": { "type": [ "string", "null" ], "description": "The landing page the order was placed on, if any" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "customerEmail": { "type": [ "string", "null" ], "description": "Email supplied at order time" }, "customFieldsJson": { "type": [ "string", "null" ], "description": "Custom checkout fields snapshot JSON" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the finished order was archived: it is left out of the working lists and their counts, and still counts in sales and the customer's history. Null while not archived." }, "deliveryOfferId": { "type": [ "string", "null" ], "description": "The offer that made delivery free (a free-shipping offer, or a quantity tier that includes it); null when none did" }, "deliveryOfferName": { "type": [ "string", "null" ], "description": "That offer's name when the order was placed — kept when the offer is renamed or deleted" }, "couponId": { "type": [ "string", "null" ], "description": "The coupon the order was placed with; null when none, or once the coupon is deleted" }, "couponCode": { "type": [ "string", "null" ], "description": "The code the order used, kept when the coupon is deleted" }, "couponDiscount": { "type": "integer", "description": "What the coupon took off; `price` is already net of it" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ], "description": "The language the order was placed in — the shopper's storefront language, the store's primary for a dashboard or agent order — and the one its customer messages are written in; null for an order placed before it was recorded", "example": "fr" }, "hasReview": { "type": "integer", "description": "1 if a customer review exists for this order, 0 otherwise. Included in list responses only (GET /api/orders)." }, "lastUpdatedBy": { "type": [ "string", "null" ], "description": "User ID of the last status-change actor. Included in list responses only (GET /api/orders)." }, "shipmentId": { "type": [ "string", "null" ], "description": "The order's shipment, or null before handoff. List responses only." }, "shipmentKind": { "type": [ "string", "null" ], "enum": [ "carrier", "driver", null ], "description": "Handed to a carrier, or to the store's driver; null before handoff. List responses only." }, "carrierName": { "type": [ "string", "null" ], "description": "The delivery company carrying it, for a carrier shipment. List responses only." }, "trackingNumber": { "type": [ "string", "null" ], "description": "The parcel's tracking number at the carrier. List responses only." }, "stage": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready_to_ship", "handoff_pending", "in_transit", "out_for_delivery", "delivered", "returning", "returned", "delivery_cancelled", "cancelled" ], "description": "Where the order stands overall — its processing, then its shipment's delivery. List responses only." }, "needsAttention": { "type": "boolean", "description": "Whether the order's delivery needs the merchant. List responses only." } }, "required": [ "id", "orderNumber", "customerId", "customerName", "phone", "wilayaId", "wilaya", "communeId", "commune", "city", "address", "price", "deliveryFee", "codAmount", "status", "orderType", "deliveryType", "stationCode", "driverName", "notes", "landingPageId", "createdAt", "updatedAt", "archivedAt", "deliveryOfferId", "deliveryOfferName", "couponId", "couponCode", "couponDiscount", "locale" ], "description": "Order summary for list view - includes joins but not nested arrays" }, "Order": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "orderNumber": { "type": "string", "example": "ORD-20260327-0042" }, "customerId": { "type": "string" }, "customerName": { "type": "string", "example": "Ahmed Benali" }, "phone": { "type": "string", "example": "0551234567" }, "wilayaId": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 58, "example": 16 }, "wilaya": { "type": [ "string", "null" ], "description": "Wilaya Arabic name, joined from reference table", "example": "الجزائر" }, "communeId": { "type": [ "string", "null" ] }, "commune": { "type": [ "string", "null" ], "description": "Commune Arabic name, joined from reference table", "example": "بئر مراد رايس" }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "price": { "type": "number", "description": "Product subtotal (excluding delivery fee)", "example": 9000 }, "deliveryFee": { "type": "number", "example": 400 }, "codAmount": { "type": [ "number", "null" ], "description": "What the customer owes on delivery: price + deliveryFee", "example": 9400 }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ], "description": "The order's processing; its delivery is its shipment's (see `stage`)" }, "orderType": { "type": "string", "enum": [ "online", "offline" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "description": "What the customer asked for; the shipment may ship otherwise" }, "stationCode": { "type": [ "string", "null" ] }, "driverName": { "type": [ "string", "null" ], "description": "The name of the store's driver delivering it, when its shipment is a driver's" }, "notes": { "type": [ "string", "null" ] }, "landingPageId": { "type": [ "string", "null" ], "description": "The landing page the order was placed on, if any" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "customerEmail": { "type": [ "string", "null" ], "description": "Email supplied at order time" }, "customFieldsJson": { "type": [ "string", "null" ], "description": "Custom checkout fields snapshot JSON" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the finished order was archived: it is left out of the working lists and their counts, and still counts in sales and the customer's history. Null while not archived." }, "deliveryOfferId": { "type": [ "string", "null" ], "description": "The offer that made delivery free (a free-shipping offer, or a quantity tier that includes it); null when none did" }, "deliveryOfferName": { "type": [ "string", "null" ], "description": "That offer's name when the order was placed — kept when the offer is renamed or deleted" }, "couponId": { "type": [ "string", "null" ], "description": "The coupon the order was placed with; null when none, or once the coupon is deleted" }, "couponCode": { "type": [ "string", "null" ], "description": "The code the order used, kept when the coupon is deleted" }, "couponDiscount": { "type": "integer", "description": "What the coupon took off; `price` is already net of it" }, "locale": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ], "description": "The language the order was placed in — the shopper's storefront language, the store's primary for a dashboard or agent order — and the one its customer messages are written in; null for an order placed before it was recorded", "example": "fr" }, "products": { "type": "array", "items": { "$ref": "#/components/schemas/OrderProduct" }, "description": "Order line items. Included in GET /api/orders/{id} (detail view only)." }, "statusHistory": { "type": "array", "items": { "$ref": "#/components/schemas/StatusHistoryItem" }, "description": "Full status change log. Included in GET /api/orders/{id} (detail view only)." }, "shipment": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "companyId": { "type": [ "string", "null" ] }, "carrierName": { "type": [ "string", "null" ], "description": "The delivery company carrying it; null for the store's driver" }, "driverId": { "type": [ "string", "null" ] }, "handoffState": { "type": "string", "enum": [ "submitting", "accepted", "unknown" ], "description": "submitting: the carrier is being called · accepted: the carrier has the parcel · unknown: the outcome must be resolved" }, "carrierParcelId": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "number", "description": "Cash the courier collects (price + delivery fee)" }, "driverFee": { "type": "number" }, "weight": { "type": [ "number", "null" ] }, "isFragile": { "type": [ "boolean", "null" ] }, "providerStatus": { "type": [ "string", "null" ], "description": "The carrier's latest status, as reported" }, "providerStatusLabel": { "type": [ "string", "null" ] }, "providerStatusKind": { "type": [ "string", "null" ], "enum": [ "milestone", "failed_attempt", "exception", "collection", "progress", "unknown", null ] }, "providerStatusAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "validatedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "outForDeliveryAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "deliveredAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "returnStartedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "returnedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "cancelledAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "deliveryAttempts": { "type": "integer" }, "attentionSince": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "lastSyncedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "validate", "update", "void", "resolve", "lookup", "addRemark", "listRemarks", "label", "askReturn", "requestNewAttempt", "confirmReturn", "sync", "report" ] }, "description": "What can be done to this shipment now" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentEvent" } } }, "required": [ "id", "orderId", "kind", "companyId", "carrierName", "driverId", "handoffState", "carrierParcelId", "trackingNumber", "deliveryType", "stationCode", "codAmount", "driverFee", "weight", "isFragile", "providerStatus", "providerStatusLabel", "providerStatusKind", "providerStatusAt", "validatedAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts", "attentionSince", "lastSyncedAt", "createdBy", "createdAt", "updatedAt", "actions" ], "description": "The order's delivery, with its history and the actions available now; null before handoff. Detail view only." }, "stage": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready_to_ship", "handoff_pending", "in_transit", "out_for_delivery", "delivered", "returning", "returned", "delivery_cancelled", "cancelled" ], "description": "Where the order stands overall — its processing, then its shipment's delivery." }, "needsAttention": { "type": "boolean", "description": "The merchant must act on the delivery: the carrier flagged it, the handoff outcome is unknown, or the carrier cancelled it" } }, "required": [ "id", "orderNumber", "customerId", "customerName", "phone", "wilayaId", "wilaya", "communeId", "commune", "city", "address", "price", "deliveryFee", "codAmount", "status", "orderType", "deliveryType", "stationCode", "driverName", "notes", "landingPageId", "createdAt", "updatedAt", "archivedAt", "deliveryOfferId", "deliveryOfferName", "couponId", "couponCode", "couponDiscount", "locale" ], "description": "Complete order record with products and status history" }, "OrderProduct": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "productId": { "type": [ "string", "null" ], "description": "Null once the product was removed: the line keeps what was sold" }, "productName": { "type": "string" }, "variantId": { "type": [ "string", "null" ], "description": "Null for a product without variants, or once the variant was removed" }, "variantLabel": { "type": [ "string", "null" ] }, "sku": { "type": [ "string", "null" ], "description": "Denormalized SKU at time of order" }, "quantity": { "type": "integer", "example": 2 }, "pricePerUnit": { "type": "number", "example": 4500 }, "lineTotal": { "type": "number", "example": 9000 }, "status": { "type": "string", "enum": [ "fulfilled", "partially_returned", "returned" ], "description": "Per-line fulfilment outcome — updated via PATCH /orders/{id}/products/{productLineId}/return" }, "returnedQuantity": { "type": "integer", "description": "Units the customer refused at the door. Always 0 when status=fulfilled, = quantity when status=returned." }, "createdAt": { "type": "string", "format": "date-time" }, "offerId": { "type": [ "string", "null" ], "description": "The offer that shaped the line: the quantity-pricing offer that set its price, or the gift offer that gave it. Null at the catalog price." }, "offerName": { "type": [ "string", "null" ], "description": "The offer's name when the order was placed — kept when the offer is renamed or deleted. Null without an offer.", "example": "اشترِ 2 والثالثة مجاناً" }, "reward": { "type": "boolean", "description": "A gift, given by `offerId` at no charge" }, "discount": { "type": "integer", "description": "The line's share of the order's coupon discount; `lineTotal` is already net of it" } }, "required": [ "id", "orderId", "productId", "productName", "variantId", "variantLabel", "sku", "quantity", "pricePerUnit", "lineTotal", "status", "returnedQuantity", "createdAt", "offerId", "offerName", "reward", "discount" ] }, "StatusHistoryItem": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "When the status change happened" }, "by": { "type": [ "string", "null" ], "description": "User ID who triggered the status change" }, "byName": { "type": [ "string", "null" ], "description": "User display name" } }, "required": [ "id", "orderId", "status", "timestamp", "by", "byName" ] }, "ShipmentEvent": { "type": "object", "properties": { "id": { "type": "string" }, "source": { "type": "string", "enum": [ "webhook", "pull", "handoff", "merchant", "system", "legacy" ] }, "vocabulary": { "type": [ "string", "null" ], "description": "Whose words the status is in (the carrier's field, or `codflow`)" }, "providerStatus": { "type": [ "string", "null" ], "description": "The status exactly as reported" }, "providerStatusLabel": { "type": [ "string", "null" ] }, "interpretation": { "type": [ "string", "null" ], "enum": [ "milestone", "failed_attempt", "exception", "collection", "progress", "unknown", null ] }, "milestone": { "type": [ "string", "null" ], "enum": [ "out_for_delivery", "delivered", "return_started", "returned", "cancelled", null ] }, "attention": { "type": "boolean" }, "anomaly": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ], "description": "Why, when the carrier says (a refusal, no answer…)" }, "occurredAt": { "type": "string" }, "recordedAt": { "type": "string" }, "actorId": { "type": [ "string", "null" ] } }, "required": [ "id", "source", "vocabulary", "providerStatus", "providerStatusLabel", "interpretation", "milestone", "attention", "anomaly", "reason", "occurredAt", "recordedAt", "actorId" ] }, "OrderCreatedData": { "type": "object", "properties": { "id": { "type": "string", "description": "Newly created order ID" }, "orderNumber": { "type": "string", "example": "ORD-20260327-0042" }, "deliveryFee": { "type": "number", "description": "Calculated delivery fee (from shipping profile or admin override)", "example": 600 }, "price": { "type": "number", "description": "Product subtotal (excluding delivery fee)", "example": 2500 }, "codAmount": { "type": "number", "description": "Total amount to collect (price + deliveryFee)", "example": 3100 }, "customerId": { "type": "string" }, "customerName": { "type": "string" }, "phone": { "type": "string" }, "wilayaId": { "type": "integer" }, "communeId": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "orderType": { "type": "string", "enum": [ "online", "offline" ] }, "status": { "type": "string", "description": "Initial order status", "example": "new" } }, "required": [ "id", "orderNumber", "deliveryFee", "price", "codAmount", "customerId", "customerName", "phone", "wilayaId", "communeId", "deliveryType", "orderType", "status" ] }, "OrderRemoval": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string", "example": "ORD-20261016-0042" }, "shipment": { "type": "string", "enum": [ "none", "open", "closed" ], "description": "No shipment yet, one on its way, or one that ended (delivered, returned, cancelled)" }, "deletable": { "type": "boolean", "description": "Only an order never handed to delivery" }, "archivable": { "type": "boolean", "description": "A finished order (cancelled, or its shipment ended) not archived yet" }, "archivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "lines": { "type": "integer", "description": "Its order lines, removed with it" }, "restockUnits": { "type": "integer", "description": "Units deleting it puts back in stock" }, "reviews": { "type": "integer", "description": "Its reviews, removed with it" } }, "required": [ "id", "orderNumber", "shipment", "deletable", "archivable", "archivedAt", "lines", "restockUnits", "reviews" ] }, "ReturnProductData": { "type": "object", "properties": { "returnedQuantity": { "type": "integer" }, "status": { "type": "string", "enum": [ "fulfilled", "partially_returned", "returned" ] } }, "required": [ "returnedQuantity", "status" ] }, "HandoffResult": { "type": "object", "properties": { "orderId": { "type": "string" }, "orderNumber": { "type": [ "string", "null" ] }, "outcome": { "type": "string", "enum": [ "accepted", "unknown", "refused" ], "description": "accepted: the carrier has the parcel, or the driver has the order · unknown: the carrier may or may not have it — resolve it, never re-send · refused: nothing was created; the order is unchanged" }, "shipment": { "$ref": "#/components/schemas/Shipment" }, "validationError": { "type": [ "string", "null" ], "description": "Created, but the carrier refused to validate it" }, "message": { "type": "string" }, "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ORDER_NOT_READY_FOR_HANDOFF" }, "message": { "type": "string" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "code", "message" ] } }, "required": [ "orderId", "orderNumber", "outcome" ] }, "Shipment": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "kind": { "type": "string", "enum": [ "carrier", "driver" ] }, "companyId": { "type": [ "string", "null" ] }, "carrierName": { "type": [ "string", "null" ], "description": "The delivery company carrying it; null for the store's driver" }, "driverId": { "type": [ "string", "null" ] }, "handoffState": { "type": "string", "enum": [ "submitting", "accepted", "unknown" ], "description": "submitting: the carrier is being called · accepted: the carrier has the parcel · unknown: the outcome must be resolved" }, "carrierParcelId": { "type": [ "string", "null" ] }, "trackingNumber": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "stationCode": { "type": [ "string", "null" ] }, "codAmount": { "type": "number", "description": "Cash the courier collects (price + delivery fee)" }, "driverFee": { "type": "number" }, "weight": { "type": [ "number", "null" ] }, "isFragile": { "type": [ "boolean", "null" ] }, "providerStatus": { "type": [ "string", "null" ], "description": "The carrier's latest status, as reported" }, "providerStatusLabel": { "type": [ "string", "null" ] }, "providerStatusKind": { "type": [ "string", "null" ], "enum": [ "milestone", "failed_attempt", "exception", "collection", "progress", "unknown", null ] }, "providerStatusAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "validatedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "outForDeliveryAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "deliveredAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "returnStartedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "returnedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "cancelledAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "deliveryAttempts": { "type": "integer" }, "attentionSince": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "lastSyncedAt": { "type": [ "string", "null" ], "description": "UTC ISO-8601, or null", "example": "2026-10-14T09:30:00.000Z" }, "createdBy": { "type": [ "string", "null" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "validate", "update", "void", "resolve", "lookup", "addRemark", "listRemarks", "label", "askReturn", "requestNewAttempt", "confirmReturn", "sync", "report" ] }, "description": "What can be done to this shipment now" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentEvent" } } }, "required": [ "id", "orderId", "kind", "companyId", "carrierName", "driverId", "handoffState", "carrierParcelId", "trackingNumber", "deliveryType", "stationCode", "codAmount", "driverFee", "weight", "isFragile", "providerStatus", "providerStatusLabel", "providerStatusKind", "providerStatusAt", "validatedAt", "outForDeliveryAt", "deliveredAt", "returnStartedAt", "returnedAt", "cancelledAt", "deliveryAttempts", "attentionSince", "lastSyncedAt", "createdBy", "createdAt", "updatedAt", "actions" ] }, "BulkHandoffData": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/HandoffResult" } }, "summary": { "type": "object", "properties": { "accepted": { "type": "integer" }, "unknown": { "type": "integer" }, "refused": { "type": "integer" } }, "required": [ "accepted", "unknown", "refused" ] } }, "required": [ "results", "summary" ] }, "HandoffResolution": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "accepted", "unknown", "not_found", "released" ] }, "shipment": { "$ref": "#/components/schemas/Shipment" }, "message": { "type": "string" } }, "required": [ "outcome" ] }, "ShipmentOperationResult": { "type": "object", "properties": { "shipment": { "$ref": "#/components/schemas/Shipment" }, "recorded": { "type": "integer", "description": "Events new to the shipment" }, "duplicates": { "type": "integer", "description": "Events it already had" }, "reached": { "type": "array", "items": { "type": "string", "enum": [ "out_for_delivery", "delivered", "return_started", "returned", "cancelled" ] }, "description": "Milestones reached for the first time" }, "anomalies": { "type": "array", "items": { "type": "string" } } }, "required": [ "shipment" ] }, "CarrierRemark": { "type": "object", "properties": { "content": { "type": "string" }, "createdAt": { "type": [ "string", "null" ] } }, "required": [ "content", "createdAt" ] }, "User": { "type": "object", "properties": { "id": { "type": "string", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "name": { "type": "string", "example": "Ahmed Benali" }, "email": { "type": "string", "format": "email", "example": "staff@example.com" }, "emailVerified": { "type": "boolean", "example": true }, "image": { "type": [ "string", "null" ], "description": "Avatar image URL", "example": null }, "role": { "type": "string", "enum": [ "admin", "staff" ], "example": "staff" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "example": "active" }, "language": { "type": "string", "description": "UI language preference for emails: \"ar\" | \"en\"", "example": "en" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Permission scopes for this user. Always `[\"*\"]` for admins. The `apiKey` field is never included in these responses — use POST /{id}/api-key/rotate for a one-time key reveal.", "example": [ "orders:read", "customers:read" ] } }, "required": [ "id", "name", "email", "emailVerified", "image", "role", "status", "language", "createdAt", "updatedAt", "scopes" ], "description": "Team member record with permission scopes" }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "name": { "type": "string", "example": "Ahmed Benali" }, "phone": { "type": "string", "example": "0551234567", "description": "Algerian mobile number starting with 05, 06, or 07" }, "phone2": { "type": [ "string", "null" ], "description": "Secondary phone number", "example": null }, "email": { "type": [ "string", "null" ], "description": "Email, lower-cased: typed by the merchant, or taken from the first order that brought one", "example": "amina@example.com" }, "wilayaId": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 58, "description": "Official wilaya number (1–58)", "example": 16 }, "communeId": { "type": [ "string", "null" ], "description": "Commune UUID from reference table", "example": "550e8400-e29b-41d4-a716-446655440000" }, "wilaya": { "type": "string", "description": "Wilaya Arabic name — denormalized display value, derived from wilayaId", "example": "الجزائر" }, "commune": { "type": [ "string", "null" ], "description": "Commune Arabic name — denormalized display value, derived from communeId", "example": "بئر مراد رايس" }, "address": { "type": [ "string", "null" ] }, "totalOrders": { "type": "integer", "example": 5, "description": "Denormalized count, incremented on each order created" }, "totalSpent": { "type": "number", "example": 25000 }, "createdAt": { "type": "string", "format": "date-time" }, "lastOrderAt": { "type": [ "string", "null" ], "format": "date-time" }, "recentOrders": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "Up to 10 most recent full order records (same shape as the Orders API), newest first. Included only in GET /api/customers/{id}; not present in list responses." } }, "required": [ "id", "name", "phone", "phone2", "email", "wilayaId", "communeId", "wilaya", "commune", "address", "totalOrders", "totalSpent", "createdAt", "lastOrderAt" ], "description": "Customer profile with denormalized purchase statistics" }, "CustomerOrderSummary": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string", "example": "ORD-20260327-0042" }, "status": { "type": "string", "example": "new" }, "price": { "type": "number", "example": 9000 }, "createdAt": { "type": "string", "format": "date-time" }, "wilayaId": { "type": [ "integer", "null" ] }, "communeId": { "type": [ "string", "null" ] }, "wilaya": { "type": [ "string", "null" ], "description": "Wilaya Arabic name, joined from reference table", "example": "الجزائر" }, "commune": { "type": [ "string", "null" ], "description": "Commune Arabic name, joined from reference table", "example": "بئر مراد رايس" }, "stage": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready_to_ship", "handoff_pending", "in_transit", "out_for_delivery", "delivered", "returning", "returned", "delivery_cancelled", "cancelled" ], "description": "Where the order stands overall — delivered, returned… (the same stage as GET /api/orders)" }, "statusHistory": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderStatus" } } }, "required": [ "id", "orderNumber", "status", "price", "createdAt", "wilayaId", "communeId", "wilaya", "commune", "stage", "statusHistory" ], "description": "Order summary returned by GET /api/customers/{id}/orders, each with its full statusHistory" }, "CustomerOrderStatus": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "status": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "by": { "type": [ "string", "null" ] } }, "required": [ "id", "orderId", "status", "timestamp", "by" ] }, "CustomerGroupMembership": { "type": "object", "properties": { "id": { "type": "string", "example": "grp_123" }, "name": { "type": "string", "example": "Wholesale Customers" }, "color": { "type": "string", "example": "#6366f1" }, "description": { "type": [ "string", "null" ] }, "memberCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "assignedAt": { "type": "string", "format": "date-time", "description": "When the customer was added to this group" } }, "required": [ "id", "name", "color", "description", "memberCount", "createdAt", "updatedAt", "assignedAt" ] }, "CustomerTagMembership": { "type": "object", "properties": { "id": { "type": "string", "example": "tag_123" }, "name": { "type": "string", "example": "VIP" }, "color": { "type": "string", "example": "#64748b" }, "assignmentCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "assignedAt": { "type": "string", "format": "date-time", "description": "When the tag was assigned to this customer" } }, "required": [ "id", "name", "color", "assignmentCount", "createdAt", "updatedAt", "assignedAt" ] }, "CustomerGroup": { "type": "object", "properties": { "id": { "type": "string", "example": "grp_123" }, "name": { "type": "string", "example": "Wholesale Customers" }, "description": { "type": [ "string", "null" ], "example": "High volume buyers" }, "color": { "type": "string", "example": "#6366f1" }, "memberCount": { "type": "integer", "example": 12, "description": "Denormalized count, kept in sync on add/remove member" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerGroupMember" }, "description": "Included only when `?members=true` is passed to GET /api/customer-groups/{id}." } }, "required": [ "id", "name", "description", "color", "memberCount", "createdAt", "updatedAt" ], "description": "Group for segmenting customers" }, "CustomerGroupMember": { "type": "object", "properties": { "id": { "type": "string", "example": "cust_123" }, "name": { "type": "string", "example": "Ahmed Benali" }, "phone": { "type": "string", "example": "0555123456" }, "wilaya": { "type": [ "string", "null" ], "example": "Alger" }, "totalOrders": { "type": "integer", "example": 5 }, "totalSpent": { "type": "number", "example": 15000 }, "assignedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "phone", "wilaya", "totalOrders", "totalSpent", "assignedAt" ] }, "CustomerTag": { "type": "object", "properties": { "id": { "type": "string", "example": "tag_123" }, "name": { "type": "string", "example": "VIP" }, "color": { "type": "string", "example": "#64748b" }, "assignmentCount": { "type": "integer", "example": 8, "description": "Denormalized count, kept in sync on assign/unassign" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "customers": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerTagCustomer" }, "description": "Included only when `?customers=true` is passed to GET /api/customer-tags/{id}." } }, "required": [ "id", "name", "color", "assignmentCount", "createdAt", "updatedAt" ], "description": "Label for tagging customers" }, "CustomerTagCustomer": { "type": "object", "properties": { "id": { "type": "string", "example": "cust_123" }, "name": { "type": "string", "example": "Ahmed Benali" }, "phone": { "type": "string", "example": "0555123456" }, "wilaya": { "type": [ "string", "null" ], "example": "Alger" }, "totalOrders": { "type": "integer", "example": 5 }, "totalSpent": { "type": "number", "example": 15000 }, "assignedAt": { "type": "string", "format": "date-time", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "name", "phone", "wilaya", "totalOrders", "totalSpent", "assignedAt" ] }, "Driver": { "type": "object", "properties": { "id": { "type": "string", "example": "drv_123" }, "firstName": { "type": "string", "example": "Mohamed" }, "lastName": { "type": "string", "example": "Amiri" }, "phone": { "type": "string", "description": "Algerian mobile number starting with 05, 06, or 07", "example": "0551234567" }, "phone2": { "type": [ "string", "null" ], "description": "Optional secondary phone", "example": null }, "vehicleType": { "type": [ "string", "null" ], "enum": [ "motorcycle", "car", "van", null ], "description": "Type of vehicle; null if unknown", "example": "van" }, "status": { "type": "string", "enum": [ "available", "busy", "inactive" ], "example": "available" }, "totalDelivered": { "type": "integer", "description": "Cumulative deliveries completed (incremented on status → delivered)", "example": 50 }, "totalEarnings": { "type": "number", "description": "Cumulative delivery fees earned (incremented on status → delivered)", "example": 25000 }, "pendingCash": { "type": "number", "description": "COD cash collected by driver but not yet remitted to the business", "example": 5000 }, "totalPaid": { "type": "number", "description": "Total COD cash remitted to the business", "example": 20000 }, "notes": { "type": [ "string", "null" ], "description": "Internal notes about the driver (not visible to customers)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "compensationWilayaCount": { "type": "integer", "description": "Number of wilayas with a configured per-delivery fee for this driver", "example": 12 }, "recentShipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orderId": { "type": "string" }, "orderNumber": { "type": "string" }, "customerName": { "type": "string" }, "wilayaId": { "type": [ "integer", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "codAmount": { "type": "number" }, "driverFee": { "type": "number" }, "providerStatus": { "type": [ "string", "null" ], "description": "The last progress reported: out_for_delivery, failed_attempt, delivered or returned" }, "outForDeliveryAt": { "type": [ "string", "null" ] }, "deliveredAt": { "type": [ "string", "null" ] }, "returnedAt": { "type": [ "string", "null" ] }, "deliveryAttempts": { "type": "integer" }, "stage": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready_to_ship", "handoff_pending", "in_transit", "out_for_delivery", "delivered", "returning", "returned", "delivery_cancelled", "cancelled" ], "description": "Where its order stands overall (out_for_delivery, delivered, returned…)" }, "createdAt": { "type": "string" } }, "required": [ "id", "orderId", "orderNumber", "customerName", "wilayaId", "deliveryType", "codAmount", "driverFee", "providerStatus", "outForDeliveryAt", "deliveredAt", "returnedAt", "deliveryAttempts", "stage", "createdAt" ] }, "description": "The 10 most recent orders given to this driver, newest first. Detail, create and update responses only." }, "openShipmentCount": { "type": "integer", "description": "Orders the driver still has out (not delivered, returned or cancelled)." }, "cashReconciliation": { "type": "object", "properties": { "pendingCash": { "type": "number" }, "pendingOrdersTotal": { "type": "number", "description": "Cash of delivered shipments not yet handed over" }, "pendingOrdersCount": { "type": "integer" }, "drift": { "type": "number", "description": "pendingCash − pendingOrdersTotal; non-zero means the counter needs attention" } }, "required": [ "pendingCash", "pendingOrdersTotal", "pendingOrdersCount", "drift" ] } }, "required": [ "id", "firstName", "lastName", "phone", "phone2", "vehicleType", "status", "totalDelivered", "totalEarnings", "pendingCash", "totalPaid", "notes", "createdAt", "updatedAt", "compensationWilayaCount" ], "description": "Delivery driver profile with denormalized earnings statistics" }, "DriverCompensationRow": { "type": "object", "properties": { "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58, "example": 16 }, "wilayaName": { "type": "string", "example": "Alger" }, "wilayaNameAr": { "type": "string", "example": "الجزائر" }, "feePerDelivery": { "type": [ "number", "null" ], "description": "DZD per delivery; `null` when not configured.", "example": 350 } }, "required": [ "wilayaId", "wilayaName", "wilayaNameAr", "feePerDelivery" ], "description": "Per-wilaya compensation entry. GET /{id}/compensations always returns all 58 wilayas; a null fee means no row is configured." }, "DeliveryCompany": { "type": "object", "properties": { "id": { "type": "string", "example": "comp_abc123" }, "name": { "type": "string", "example": "Yalidine" }, "nameAr": { "type": "string", "example": "ياليدين" }, "code": { "type": "string", "example": "yalidine" }, "website": { "type": [ "string", "null" ], "format": "uri", "example": "https://www.yalidine.com" }, "active": { "type": "boolean", "example": true }, "apiEndpoint": { "type": [ "string", "null" ], "format": "uri", "example": "https://api.yalidine.app/v1" }, "isConnected": { "type": "boolean", "description": "True when API credentials are stored. Credentials themselves are never returned.", "example": true }, "supportsHomeDelivery": { "type": "boolean", "example": true }, "supportsStopDesk": { "type": "boolean", "example": true }, "autoValidate": { "type": [ "boolean", "null" ], "description": "When true, the server calls `validateShipment` immediately after `createShipment` on dispatch. The order is locked at the carrier (no edits/deletes). When false, the order stays editable and the team must manually confirm it. If omitted/null, a provider-specific default is used.", "example": true }, "notes": { "type": [ "string", "null" ], "example": "Primary carrier for Algiers region" }, "provider": { "type": [ "string", "null" ], "enum": [ "yalidine", "zr_express", "noest", "ecotrack", null ], "description": "The carrier adapter serving this company; null = it cannot take parcels." }, "providerConfig": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "The adapter's settings; secrets masked (•••• + last 4)." }, "webhookSecretSet": { "type": "boolean", "description": "True when the webhook signing secret is stored. The secret itself is never returned." }, "capabilities": { "$ref": "#/components/schemas/CarrierCapabilities" }, "webhookEndpointId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "nameAr", "code", "website", "active", "apiEndpoint", "isConnected", "supportsHomeDelivery", "supportsStopDesk", "autoValidate", "notes", "provider", "providerConfig", "webhookSecretSet", "capabilities", "webhookEndpointId", "createdAt", "updatedAt" ], "description": "Third-party delivery company integration" }, "CarrierCapabilities": { "type": [ "object", "null" ], "properties": { "homeDelivery": { "type": "boolean" }, "stopDesk": { "type": "boolean" }, "separateValidation": { "type": "boolean", "description": "A created parcel waits for a separate validation before the carrier handles it" }, "bulkCreate": { "type": "integer", "description": "Most parcels one bulk handoff sends at once; 0 = one at a time" }, "parcelFields": { "type": "object", "properties": { "weight": { "type": "boolean" }, "fragile": { "type": "boolean" }, "remarks": { "type": "boolean" } }, "required": [ "weight", "fragile", "remarks" ], "description": "Parcel fields the carrier takes at creation" }, "limits": { "type": "object", "properties": { "maxAmount": { "type": [ "number", "null" ] }, "maxDescription": { "type": [ "integer", "null" ] } }, "required": [ "maxAmount", "maxDescription" ], "description": "The carrier's own ceilings, checked before calling it" }, "update": { "type": "boolean" }, "cancel": { "type": "boolean" }, "remarks": { "type": "object", "properties": { "add": { "type": "boolean" }, "list": { "type": "boolean" } }, "required": [ "add", "list" ] }, "history": { "type": "boolean", "description": "Its status history can be read (sync)" }, "historyBatch": { "type": "integer" }, "findByReference": { "type": "boolean", "description": "A parcel can be found by the order number — resolves an unknown handoff" }, "updates": { "type": "string", "enum": [ "webhook", "pull" ], "description": "How its updates reach Wocart: pushed by webhook, or pulled every few minutes" }, "label": { "type": "boolean" }, "askReturn": { "type": "boolean" }, "requestNewAttempt": { "type": "boolean" }, "confirmReturn": { "type": "boolean" }, "stopDeskList": { "type": "boolean" }, "geoNames": { "type": "boolean" }, "verifyConnection": { "type": "boolean" } }, "required": [ "homeDelivery", "stopDesk", "separateValidation", "bulkCreate", "parcelFields", "limits", "update", "cancel", "remarks", "history", "historyBatch", "findByReference", "updates", "label", "askReturn", "requestNewAttempt", "confirmReturn", "stopDeskList", "geoNames", "verifyConnection" ], "description": "What its carrier can do; null when it has no provider" }, "StopDesk": { "type": "object", "properties": { "id": { "type": "string", "example": "desk_xyz789" }, "companyId": { "type": "string", "example": "comp_abc123" }, "code": { "type": "string", "example": "16A", "description": "Station code to use as `stationCode` when dispatching a stop-desk order. Format differs by provider: Noest = alphanumeric code (e.g. \"16A\"); Yalidine = numeric center_id (e.g. \"160101\"); ZR Express = territory UUID; EcoTrack = postal code string." }, "name": { "type": "string", "example": "Agence Alger Centre" }, "commune": { "type": [ "string", "null" ], "example": "Bir Mourad Raïs" }, "wilayaId": { "type": [ "integer", "null" ], "example": 16 }, "address": { "type": [ "string", "null" ], "example": "5 Rue Didouche Mourad, Alger" }, "phones": { "type": "array", "items": { "type": "string" }, "example": [ "0555123456" ], "description": "Contact phone numbers for the stop-desk station." }, "active": { "type": "boolean", "example": true, "description": "Admin toggle. When false, this stop desk is hidden from merchant UI. Survives re-sync." }, "syncedAt": { "type": "string", "format": "date-time", "description": "Last time this row was fetched from the carrier API (via POST .../sync-stop-desks)." } }, "required": [ "id", "companyId", "code", "name", "commune", "wilayaId", "address", "phones", "active", "syncedAt" ] }, "Product": { "type": "object", "properties": { "id": { "type": "string", "example": "prod_abc123" }, "name": { "type": "string", "example": "Samsung Galaxy A54" }, "description": { "type": [ "string", "null" ], "example": "6.4-inch display, 5000mAh battery" }, "descriptionFormat": { "type": "string", "enum": [ "text", "html" ], "description": "How `description` is stored. `text` renders as literal text (legacy rows and products created without a format); `html` was sanitised at write against the rich-text allow-list.", "example": "text" }, "descriptionPlain": { "type": [ "string", "null" ], "description": "Tag-free rendering of `description` for meta/JSON-LD (tags stripped, images dropped, entities decoded, whitespace collapsed). Identical to `description` for `text` rows; null when `description` is null.", "example": "6.4-inch display, 5000mAh battery" }, "handle": { "type": "string", "description": "URL slug — auto-generated from name if not provided", "example": "samsung-galaxy-a54-1a2b3c4d" }, "currency": { "type": "string", "example": "DZD" }, "price": { "type": "integer", "minimum": 0, "description": "Price in DZD (smallest unit)", "example": 45000 }, "compareAtPrice": { "type": [ "integer", "null" ], "minimum": 0, "example": null }, "costPrice": { "type": [ "integer", "null" ], "minimum": 0, "example": null }, "type": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ], "example": "PHYSICAL" }, "hasVariants": { "type": "boolean", "example": true }, "variantOptions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "example": "Color" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "example": "Red" }, "hexColor": { "type": [ "string", "null" ], "example": "#FF0000" } }, "required": [ "value" ] }, "minItems": 1 } }, "required": [ "name", "values" ] }, "description": "Variant option axes. Parsed from JSON storage — null when the product has no options." }, "sku": { "type": [ "string", "null" ], "description": "Only used by simple products (hasVariants=false); variant products carry SKU on each variant.", "example": null }, "inventory": { "type": "integer", "minimum": 0, "description": "Stock for simple products; ignored for variant products.", "example": 0 }, "lowStockThreshold": { "type": "integer", "minimum": 0, "description": "Alert when stock drops to this level. Ignored for variant products (threshold is per-variant).", "example": 5 }, "trackInventory": { "type": "boolean", "example": true }, "categoryId": { "type": [ "string", "null" ], "example": "cat_123" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Parsed from JSON storage.", "example": [ "samsung", "smartphone" ] }, "visibility": { "type": "boolean", "example": true }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "example": "ACTIVE" }, "showInStore": { "type": "boolean", "example": true }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Auto-set when status changes to ACTIVE", "example": "2026-01-15T09:30:00.000Z" }, "shippingProfileId": { "type": [ "string", "null" ], "description": "Shipping profile ID for this product. Null = store default profile is used.", "example": null }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "metaTitle": { "type": [ "string", "null" ], "description": "Search-engine title (60 characters at most); null: the product's name", "example": null }, "metaDescription": { "type": [ "string", "null" ], "description": "Search-engine description (160 characters at most); null: the product's description, shortened", "example": null }, "variantsCount": { "type": "integer", "description": "Number of variants attached to this product", "example": 3 }, "totalInventory": { "type": "integer", "description": "Sum of variant inventory for variant products; product.inventory for simple products", "example": 75 }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" }, "description": "Variants ordered by position; variations are parsed into objects" }, "primaryImage": { "type": [ "object", "null" ], "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "url": { "type": "string", "format": "uri", "description": "Where browsers fetch it, from the store's Media Delivery", "example": "https://ik.imagekit.io/wocart/stores/maysa/products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "width": { "type": [ "integer", "null" ], "description": "Pixels, when known", "example": 1200 }, "height": { "type": [ "integer", "null" ], "description": "Pixels, when known", "example": 900 } }, "required": [ "key", "url", "width", "height" ], "description": "The gallery's first image. Included in list responses only." }, "reviewCount": { "type": "integer", "description": "Approved review count. Included in list responses only.", "example": 12 }, "avgRating": { "type": [ "number", "null" ], "description": "Average approved rating (1 decimal), null when unreviewed. Included in list responses only.", "example": 4.5 }, "category": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "cat_123" }, "name": { "type": "string", "example": "Electronics" }, "slug": { "type": "string", "example": "electronics", "description": "Lowercase letters, numbers and hyphens; auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ], "example": "Electronic products" }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID for nested hierarchies; null for top-level groups", "example": null }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The group's image, from its Media Key" } ] }, "metaTitle": { "type": [ "string", "null" ], "description": "SEO page title (max 60 chars)", "example": "Electronics | Wocart" }, "metaDescription": { "type": [ "string", "null" ], "description": "SEO description (max 160 chars)", "example": "Phones, laptops and accessories" }, "metaKeywords": { "type": [ "string", "null" ], "description": "Comma-separated SEO keywords", "example": "electronics, gadgets" }, "position": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order; lower values come first" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "parentId", "image", "metaTitle", "metaDescription", "metaKeywords", "position", "createdAt", "updatedAt" ], "description": "Full category record. Included only in GET /{id} detail responses." }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" }, "description": "Images ordered by position. Included only in GET /{id} detail and mutation responses." } }, "required": [ "id", "name", "description", "descriptionFormat", "descriptionPlain", "handle", "currency", "price", "compareAtPrice", "costPrice", "type", "hasVariants", "variantOptions", "sku", "inventory", "lowStockThreshold", "trackInventory", "categoryId", "tags", "visibility", "status", "showInStore", "publishedAt", "shippingProfileId", "createdAt", "updatedAt", "metaTitle", "metaDescription", "variantsCount", "totalInventory", "variants" ] }, "ProductVariant": { "type": "object", "properties": { "id": { "type": "string", "example": "var_abc123" }, "productId": { "type": "string", "example": "prod_abc123" }, "variations": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Key-value map matching the product's variantOptions axes", "example": { "Color": "Red", "Size": "M" } }, "currency": { "type": "string", "example": "DZD" }, "price": { "type": "integer", "minimum": 0, "description": "Price in DZD", "example": 45000 }, "compareAtPrice": { "type": [ "integer", "null" ], "minimum": 0, "example": null }, "sku": { "type": "string", "description": "Unique stock-keeping unit identifier. Used for order tracking and inventory management.", "example": "GALAXY-A54-RED-M" }, "barcode": { "type": [ "string", "null" ], "example": null }, "inventory": { "type": "integer", "minimum": 0, "example": 25 }, "lowStockThreshold": { "type": "integer", "minimum": 0, "description": "Alert when this variant's stock drops to this level.", "example": 5 }, "weightKg": { "type": [ "number", "null" ], "minimum": 0, "example": null }, "imageId": { "type": [ "string", "null" ], "description": "Product image ID associated with this variant", "example": null }, "isDefault": { "type": "boolean", "example": false }, "active": { "type": "boolean", "example": true }, "position": { "type": "integer", "minimum": 1, "example": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "productId", "variations", "currency", "price", "compareAtPrice", "sku", "barcode", "inventory", "lowStockThreshold", "weightKg", "imageId", "isDefault", "active", "position", "createdAt", "updatedAt" ] }, "ProductImage": { "type": "object", "properties": { "id": { "type": "string", "example": "img_abc123" }, "productId": { "type": "string", "example": "prod_abc123" }, "key": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "url": { "type": "string", "format": "uri", "description": "Where browsers fetch it, from the store's Media Delivery", "example": "https://ik.imagekit.io/wocart/stores/maysa/products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "width": { "type": [ "integer", "null" ], "example": 1200 }, "height": { "type": [ "integer", "null" ], "example": 900 }, "altText": { "type": [ "string", "null" ], "description": "Alt text for accessibility", "example": "Galaxy A54 front view" }, "position": { "type": "integer", "minimum": 1, "description": "Display order (1 = first)", "example": 1 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "productId", "key", "url", "width", "height", "altText", "position", "createdAt", "updatedAt" ] }, "ProductDetail": { "allOf": [ { "$ref": "#/components/schemas/Product" }, { "type": "object", "properties": { "collectionIds": { "type": "array", "items": { "type": "string" }, "description": "The collections the product is in (curated lists such as `featured` or `best-sellers`)", "example": [ "store-1:collection:best-sellers" ] } }, "required": [ "collectionIds" ] } ] }, "ProductRemoval": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "variants": { "type": "integer" }, "images": { "type": "integer" }, "reviews": { "type": "integer" }, "offers": { "type": "integer", "description": "Offers it triggers or rewards: removed with it" }, "landingPages": { "type": "integer", "description": "Its landing pages, with their images and pixel settings: removed with it" }, "landingPageOrders": { "type": "integer", "description": "Orders those landing pages brought: kept, without the landing page link" }, "orderLines": { "type": "integer", "description": "Order lines that sold it: kept as sold, without the product link" }, "ordersToShip": { "type": "integer", "description": "Orders holding it not handed to delivery yet: they keep the line, which is never put back in stock" } }, "required": [ "id", "name", "variants", "images", "reviews", "offers", "landingPages", "landingPageOrders", "orderLines", "ordersToShip" ] }, "ProductCategory": { "type": "object", "properties": { "id": { "type": "string", "example": "cat_123" }, "name": { "type": "string", "example": "Electronics" }, "slug": { "type": "string", "example": "electronics", "description": "Lowercase letters, numbers and hyphens; auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ], "example": "Electronic products" }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID for nested hierarchies; null for top-level groups", "example": null }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The group's image, from its Media Key" } ] }, "metaTitle": { "type": [ "string", "null" ], "description": "SEO page title (max 60 chars)", "example": "Electronics | Wocart" }, "metaDescription": { "type": [ "string", "null" ], "description": "SEO description (max 160 chars)", "example": "Phones, laptops and accessories" }, "metaKeywords": { "type": [ "string", "null" ], "description": "Comma-separated SEO keywords", "example": "electronics, gadgets" }, "position": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order; lower values come first" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "productsCount": { "type": "integer", "example": 5, "description": "Number of active (non-deleted) products assigned to this group" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cat_123" }, "name": { "type": "string", "example": "Electronics" }, "slug": { "type": "string", "example": "electronics", "description": "Lowercase letters, numbers and hyphens; auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ], "example": "Electronic products" }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID for nested hierarchies; null for top-level groups", "example": null }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The group's image, from its Media Key" } ] }, "metaTitle": { "type": [ "string", "null" ], "description": "SEO page title (max 60 chars)", "example": "Electronics | Wocart" }, "metaDescription": { "type": [ "string", "null" ], "description": "SEO description (max 160 chars)", "example": "Phones, laptops and accessories" }, "metaKeywords": { "type": [ "string", "null" ], "description": "Comma-separated SEO keywords", "example": "electronics, gadgets" }, "position": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order; lower values come first" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "parentId", "image", "metaTitle", "metaDescription", "metaKeywords", "position", "createdAt", "updatedAt" ] }, "description": "Immediate sub-categories. Included only in GET /api/product-groups/{id}." } }, "required": [ "id", "name", "slug", "description", "parentId", "image", "metaTitle", "metaDescription", "metaKeywords", "position", "createdAt", "updatedAt", "productsCount" ], "description": "Product category/collection group in the catalog hierarchy" }, "LandingPageListItem": { "type": "object", "properties": { "id": { "type": "string", "example": "lp_abc123" }, "slug": { "type": "string", "example": "lp-9f3a2b1c" }, "name": { "type": "string", "example": "Zinc v3 — carousel ad" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "productId": { "type": "string", "example": "prod_abc123" }, "productName": { "type": [ "string", "null" ], "example": "Samsung Galaxy A55" }, "productHandle": { "type": [ "string", "null" ], "example": "samsung-galaxy-a55" }, "imageCount": { "type": "integer", "minimum": 0, "example": 7 }, "views": { "type": "integer", "minimum": 0, "example": 1240 }, "orders": { "type": "integer", "minimum": 0, "example": 36 }, "revenue": { "type": "number", "minimum": 0, "example": 180000 }, "publicUrl": { "type": "string", "description": "The shareable storefront URL for this page", "example": "https://demo.wocart.store/lp/lp-9f3a2b1c" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "tracking": { "type": [ "object", "null" ], "properties": { "pixelId": { "type": "string", "example": "1234567890123456" }, "conversionEvent": { "type": "string", "enum": [ "Lead", "Purchase", "Purchase_Confirmed", "Purchase_Delivered" ] }, "enabled": { "type": "boolean" }, "testMode": { "type": "boolean" } }, "required": [ "pixelId", "conversionEvent", "enabled", "testMode" ], "description": "This page's own pixel, or null when it inherits the store's. Enough to badge a list row; the access token is never included. Whether it is actually in force also depends on the store's per-page tracking switch." } }, "required": [ "id", "slug", "name", "status", "productId", "productName", "productHandle", "imageCount", "views", "orders", "revenue", "publicUrl", "publishedAt", "createdAt", "updatedAt", "tracking" ] }, "LandingPage": { "type": "object", "properties": { "id": { "type": "string", "example": "lp_abc123" }, "slug": { "type": "string", "description": "Public URL identifier — /lp/", "example": "lp-9f3a2b1c" }, "name": { "type": "string", "description": "Internal label, never rendered publicly", "example": "Zinc v3 — carousel ad" }, "productId": { "type": "string", "example": "prod_abc123" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ], "description": "draft → published → archived. Only published pages resolve publicly.", "example": "published" }, "imageGap": { "type": "integer", "minimum": 0, "maximum": 200, "description": "Pixels between stacked images — the only spacing setting", "example": 0 }, "metaTitle": { "type": [ "string", "null" ], "example": "Samsung A55 — عرض خاص" }, "metaDescription": { "type": [ "string", "null" ], "example": "اطلب الآن — الدفع عند الاستلام" }, "views": { "type": "integer", "minimum": 0, "example": 1240 }, "publicUrl": { "type": "string", "description": "The shareable storefront URL (from the store's domain, or the deployment's storefront fallback; relative /lp/ when neither is set)", "example": "https://demo.wocart.store/lp/lp-9f3a2b1c" }, "publishedAt": { "type": [ "string", "null" ], "format": "date-time", "example": null }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageImage" }, "description": "The image stack, ordered by position (1 = top)" }, "product": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "prod_abc123" }, "name": { "type": "string", "example": "Samsung Galaxy A55" }, "handle": { "type": "string", "example": "samsung-galaxy-a55" }, "price": { "type": "number", "description": "Catalog price in DZD — the price the LP charges (no override)", "example": 65000 } }, "required": [ "id", "name", "handle", "price" ], "description": "The single product this page sells" }, "stats": { "$ref": "#/components/schemas/LandingPageStats" } }, "required": [ "id", "slug", "name", "productId", "status", "imageGap", "metaTitle", "metaDescription", "views", "publicUrl", "publishedAt", "createdAt", "updatedAt", "images", "product", "stats" ] }, "LandingPageImage": { "type": "object", "properties": { "id": { "type": "string", "example": "lpimg_abc123" }, "landingPageId": { "type": "string", "example": "lp_abc123" }, "key": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "url": { "type": "string", "format": "uri", "description": "Where browsers fetch it, from the store's Media Delivery" }, "altText": { "type": [ "string", "null" ], "description": "Alt text for accessibility", "example": "Samsung A55 — عرض خاص" }, "source": { "type": "string", "enum": [ "upload", "ai" ], "description": "How the image entered the stack (AI generation is a future phase)", "example": "upload" }, "position": { "type": "integer", "minimum": 1, "description": "Stack order (1 = top of the page)", "example": 1 }, "width": { "type": [ "integer", "null" ], "description": "Intrinsic pixel width — the storefront reserves this space to prevent layout shift; null on legacy rows", "example": 1080 }, "height": { "type": [ "integer", "null" ], "description": "Intrinsic pixel height — the storefront reserves this space to prevent layout shift; null on legacy rows", "example": 1350 }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "landingPageId", "key", "url", "altText", "source", "position", "width", "height", "createdAt" ] }, "LandingPageStats": { "type": "object", "properties": { "views": { "type": "integer", "minimum": 0, "example": 1240 }, "orders": { "type": "integer", "minimum": 0, "example": 36 }, "revenue": { "type": "number", "minimum": 0, "description": "Sum of attributed order prices in DZD", "example": 180000 } }, "required": [ "views", "orders", "revenue" ] }, "LandingPageTrackingState": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/LandingPageTracking" }, "lastEvent": { "$ref": "#/components/schemas/LandingPageTrackingActivity" } }, "required": [ "config", "lastEvent" ] }, "LandingPageTracking": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "example": "lppc_abc123" }, "landingPageId": { "type": "string", "example": "lp_abc123" }, "pixelId": { "type": "string", "description": "The Meta Pixel this page reports to. Public by definition — it appears in the page source.", "example": "1234567890123456" }, "adAccountName": { "type": [ "string", "null" ], "description": "The merchant's own label for the ad account. Reference only, never sent to Meta.", "example": "Zinc — scaling" }, "accessTokenMasked": { "type": "string", "description": "Last four characters of the stored Conversions API token. The token itself never leaves the server.", "example": "••••x9Kq" }, "testEventCode": { "type": [ "string", "null" ], "example": "TEST12345" }, "conversionEvent": { "type": "string", "enum": [ "Lead", "Purchase", "Purchase_Confirmed", "Purchase_Delivered" ], "description": "Which moment counts as a conversion for THIS page's campaigns — independent of the store's choice.", "example": "Purchase" }, "testMode": { "type": "boolean", "example": false }, "enabled": { "type": "boolean", "description": "Switched off returns the page to the store pixel without losing what was configured.", "example": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "landingPageId", "pixelId", "adAccountName", "accessTokenMasked", "testEventCode", "conversionEvent", "testMode", "enabled", "createdAt", "updatedAt" ], "description": "The page's own pixel, or null when it inherits the store's." }, "LandingPageTrackingActivity": { "type": [ "object", "null" ], "properties": { "eventName": { "type": "string", "example": "Purchase" }, "stage": { "type": "string", "description": "Which business moment produced it: checkout, confirmed, or delivered.", "example": "delivered" }, "status": { "type": "string", "description": "sent | failed | skipped | claimed", "example": "sent" }, "pixelId": { "type": [ "string", "null" ], "description": "Which pixel it went to. Null only for rows written before this was recorded.", "example": "1234567890123456" }, "error": { "type": [ "string", "null" ], "description": "Meta's own message when the attempt failed.", "example": null }, "sentAt": { "type": "string", "example": "2026-09-19T18:42:39.682Z" } }, "required": [ "eventName", "stage", "status", "pixelId", "error", "sentAt" ], "description": "The last Conversions API attempt for this page, or null when there has been none." }, "StorePageSummary": { "type": "object", "properties": { "id": { "type": "string", "example": "sp_abc123" }, "kind": { "type": "string", "enum": [ "terms", "privacy", "refund", "shipping", "custom" ] }, "slug": { "type": "string", "description": "Public URL segment — /pages/", "example": "refund-policy" }, "status": { "type": "string", "enum": [ "published", "draft" ] }, "showInFooter": { "type": "boolean" }, "position": { "type": "integer" }, "templateVersion": { "type": [ "integer", "null" ], "description": "Which template revision this page's prose was last seeded/reset from. Null for custom pages." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "translations": { "type": "array", "items": { "$ref": "#/components/schemas/StorePageTranslationSummary" } } }, "required": [ "id", "kind", "slug", "status", "showInFooter", "position", "templateVersion", "createdAt", "updatedAt", "translations" ] }, "StorePageTranslationSummary": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "title": { "type": "string", "example": "سياسة الإرجاع والاسترجاع" }, "source": { "type": "string", "enum": [ "template", "merchant" ], "description": "'template' = still the seeded text, never reviewed. 'merchant' = edited at least once.", "example": "template" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "locale", "title", "source", "updatedAt" ] }, "StoreLegalProfile": { "type": [ "object", "null" ], "properties": { "storeId": { "type": "string" }, "legalName": { "type": [ "string", "null" ] }, "rcNumber": { "type": [ "string", "null" ], "description": "Registre de Commerce number" }, "nif": { "type": [ "string", "null" ], "description": "Numéro d'Identification Fiscale" }, "address": { "type": [ "string", "null" ] }, "contactEmail": { "type": [ "string", "null" ] }, "contactPhone": { "type": [ "string", "null" ] }, "returnWindowDays": { "type": "integer", "minimum": 0, "description": "0 = no post-delivery return window offered; the refund page's return clause is dropped." }, "deliveryMinDays": { "type": "integer", "minimum": 0 }, "deliveryMaxDays": { "type": "integer", "minimum": 0 }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "storeId", "legalName", "rcNumber", "nif", "address", "contactEmail", "contactPhone", "returnWindowDays", "deliveryMinDays", "deliveryMaxDays", "updatedAt" ] }, "StorePageDetail": { "allOf": [ { "$ref": "#/components/schemas/StorePageSummary" }, { "type": "object", "properties": { "bodies": { "type": "object", "properties": { "ar": { "$ref": "#/components/schemas/StorePageTranslationBody" }, "en": { "$ref": "#/components/schemas/StorePageTranslationBody" }, "fr": { "$ref": "#/components/schemas/StorePageTranslationBody" } }, "description": "Full body per locale. A locale never saved is absent, not null." } }, "required": [ "bodies" ] } ] }, "StorePageTranslationBody": { "type": "object", "properties": { "pageId": { "type": "string" }, "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "title": { "type": "string" }, "bodyHtml": { "type": "string", "description": "Sanitised HTML — h2/p/strong/ul/li/etc. Render with set:html, never re-sanitise." }, "bodyPlain": { "type": "string" }, "metaTitle": { "type": [ "string", "null" ] }, "metaDescription": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "template", "merchant" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "pageId", "locale", "title", "bodyHtml", "bodyPlain", "metaTitle", "metaDescription", "source", "updatedAt" ] }, "MenuSummary": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "example": "main-menu" }, "title": { "type": "string" }, "itemCount": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "handle", "title", "itemCount", "updatedAt" ] }, "MenuDestinationOption": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "path": { "type": "string", "description": "Its public path", "example": "/products/robe" }, "visible": { "type": "boolean", "description": "False when shoppers cannot see it now: an item pointing at it is left out of the menu" } }, "required": [ "id", "label", "path", "visible" ] }, "MenuDetail": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "example": "main-menu" }, "title": { "type": "string" }, "updatedAt": { "type": "string" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/MenuItem" } } }, "required": [ "id", "handle", "title", "updatedAt", "items" ] }, "MenuItem": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "destination": { "$ref": "#/components/schemas/MenuDestination" }, "destinationStatus": { "type": "string", "enum": [ "ok", "missing", "hidden" ], "description": "`missing`: the destination was deleted. `hidden`: it exists but shoppers cannot see it (a draft page, an inactive product). Either way the storefront leaves the item out." }, "destinationLabel": { "type": [ "string", "null" ], "description": "The destination's name (a product's or category's name, a page's slug)" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "destination": { "$ref": "#/components/schemas/MenuDestination" }, "destinationStatus": { "type": "string", "enum": [ "ok", "missing", "hidden" ], "description": "`missing`: the destination was deleted. `hidden`: it exists but shoppers cannot see it (a draft page, an inactive product). Either way the storefront leaves the item out." }, "destinationLabel": { "type": [ "string", "null" ], "description": "The destination's name (a product's or category's name, a page's slug)" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "destination": { "$ref": "#/components/schemas/MenuDestination" }, "destinationStatus": { "type": "string", "enum": [ "ok", "missing", "hidden" ], "description": "`missing`: the destination was deleted. `hidden`: it exists but shoppers cannot see it (a draft page, an inactive product). Either way the storefront leaves the item out." }, "destinationLabel": { "type": [ "string", "null" ], "description": "The destination's name (a product's or category's name, a page's slug)" }, "children": { "type": "array", "items": {}, "maxItems": 0, "description": "Always empty: a third-level item has no children" } }, "required": [ "id", "label", "destination", "destinationStatus", "destinationLabel", "children" ] } } }, "required": [ "id", "label", "destination", "destinationStatus", "destinationLabel", "children" ] } } }, "required": [ "id", "label", "destination", "destinationStatus", "destinationLabel", "children" ] }, "MenuDestination": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "home", "catalog", "search", "trackOrder", "contact" ], "description": "A page of the store: the home, every product, search, order tracking or contact" } }, "required": [ "type" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "category", "collection", "product", "page", "landing" ] }, "ref": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The category, collection, product, store page or landing page id" } }, "required": [ "type", "ref" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ] }, "url": { "type": "string", "example": "/pages/faq" } }, "required": [ "type", "url" ] } ] }, "MenuItemInput": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "An existing item's id, to keep it (and its translations)" }, "label": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Robes" }, "destination": { "$ref": "#/components/schemas/MenuDestination" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "An existing item's id, to keep it (and its translations)" }, "label": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Robes" }, "destination": { "$ref": "#/components/schemas/MenuDestination" }, "children": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 100, "description": "An existing item's id, to keep it (and its translations)" }, "label": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Robes" }, "destination": { "$ref": "#/components/schemas/MenuDestination" } }, "required": [ "label", "destination" ], "additionalProperties": false } } }, "required": [ "label", "destination" ], "additionalProperties": false } } }, "required": [ "label", "destination" ], "additionalProperties": false }, "CollectionSummary": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "example": "best-sellers" }, "title": { "type": "string" }, "productCount": { "type": "integer" }, "updatedAt": { "type": "string" } }, "required": [ "id", "handle", "title", "productCount", "updatedAt" ] }, "CollectionDetail": { "type": "object", "properties": { "id": { "type": "string" }, "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "example": "best-sellers" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "updatedAt": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "Its gallery's first image" } ] }, "visible": { "type": "boolean", "description": "Whether shoppers see it now (active, visible, listed in the store); a hidden product is left out of the storefront list" } }, "required": [ "id", "name", "handle", "image", "visible" ] } } }, "required": [ "id", "handle", "title", "description", "updatedAt", "products" ] }, "CheckoutFormPolicy": { "type": "object", "properties": { "address": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "Home delivery only. Hidden is allowed; the dispatch guard ensures a home parcel has an address before leaving." }, "notes": { "type": "string", "enum": [ "optional", "hidden" ] }, "email": { "type": "string", "enum": [ "required", "optional", "hidden" ], "description": "Defaults to hidden, which is the storefront's behaviour before this feature. Stored on the order (`orders.customer_email`) when the shopper supplies one." }, "deliveryOptions": { "type": "object", "properties": { "home": { "type": "boolean" }, "stopDesk": { "type": "boolean" } }, "required": [ "home", "stopDesk" ], "description": "At least one must stay on — a form with neither cannot be submitted." }, "customFields": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutFormCustomField" }, "maxItems": 5 } }, "required": [ "address", "notes", "email", "deliveryOptions", "customFields" ] }, "CheckoutFormCustomField": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^cf_[a-z0-9]{8}$", "description": "Server-minted id. Omit it to create a field; send it to edit the field it names. An id the store does not already have is rejected — ids key the answer snapshots on existing orders.", "example": "cf_a1b2c3d4" }, "label": { "type": "string", "minLength": 1, "maxLength": 60, "example": "Preferred delivery time" }, "type": { "type": "string", "enum": [ "text", "textarea", "number", "select" ] }, "required": { "type": "boolean", "example": false }, "options": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "minItems": 1, "maxItems": 20, "description": "Dropdown choices — `select` only, and required for it." } }, "required": [ "label", "type" ] }, "CheckoutFormPolicyInput": { "type": "object", "additionalProperties": {}, "description": "A policy document. Same shape as CheckoutFormPolicy, with `customFields[].id` optional (omit it to create a field). Validated server-side by the policy module: unknown keys, an empty delivery-option pair, an unknown field id and every authoring limit are refused, with each problem listed in `context.issues`.", "example": { "address": "required", "notes": "hidden", "email": "required", "deliveryOptions": { "home": true, "stopDesk": false }, "customFields": [ { "label": "Preferred delivery time", "type": "select", "required": true, "options": [ "Morning", "Evening" ] } ] } }, "App": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "meta", "dzverify", "turnstile", "sendili", "whatsapp-button", "telegram", "reviews" ], "description": "The App Key: its name in URLs, the API and permissions" }, "category": { "type": "string", "enum": [ "marketing", "checkout_protection", "messaging", "storefront" ] }, "status": { "type": "string", "enum": [ "not_set_up", "on", "off", "needs_attention" ], "description": "not_set_up | on | off | needs_attention (on, but what it sends is failing, or it cannot do what it is on for)" } }, "required": [ "key", "category", "status" ] }, "StorePixelConfig": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "storeId": { "type": "string" }, "pixelId": { "type": "string", "example": "1234567890123456" }, "adAccountName": { "type": [ "string", "null" ], "description": "Merchant's own label for the Meta ad account — reference only, never sent to Meta." }, "accessTokenMasked": { "type": "string", "description": "Masked hint of the stored Meta access token — the token itself is write-only.", "example": "••••a9f2" }, "testEventCode": { "type": [ "string", "null" ], "description": "Meta test event code — used only while Test Mode is on. Set to null in production." }, "conversionEvent": { "type": "string", "enum": [ "Purchase", "Purchase_Confirmed", "Purchase_Delivered", "Lead" ], "description": "Merchant-chosen conversion event: 'Purchase' fires immediately at checkout, 'Purchase_Confirmed' fires on order confirmation, 'Purchase_Delivered' fires on confirmed delivery, and 'Lead' fires at checkout." }, "testMode": { "type": "boolean", "description": "When true, Conversions API events carry test_event_code to Meta's test stream." }, "enabled": { "type": "boolean", "example": true }, "perPageTrackingEnabled": { "type": "boolean", "description": "Master switch for per-landing-page pixels. While false (the default), every landing page reports to this pixel no matter what is configured against it — which is also this feature's rollback.", "example": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "storeId", "pixelId", "adAccountName", "accessTokenMasked", "testEventCode", "conversionEvent", "testMode", "enabled", "perPageTrackingEnabled", "createdAt", "updatedAt" ], "description": "Meta pixel tracking configuration for server-side conversion events" }, "WhatsAppButtonConfig": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "phone": { "type": [ "string", "null" ], "description": "Stored in E.164, however the merchant typed it.", "example": "+213551234567" }, "agentName": { "type": [ "string", "null" ] }, "caption": { "type": [ "string", "null" ] }, "avatarKey": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "The agent's photo, from a completed upload; null shows the store's logo.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "welcomeMessage": { "type": [ "string", "null" ] }, "launcherLabel": { "type": [ "string", "null" ] }, "ctaLabel": { "type": [ "string", "null" ] }, "prefillGeneral": { "type": [ "string", "null" ] }, "prefillProduct": { "type": [ "string", "null" ] }, "thankYouButtonLabel": { "type": [ "string", "null" ] }, "prefillThankYou": { "type": [ "string", "null" ] }, "accent": { "type": "string", "enum": [ "whatsapp", "primary" ] }, "position": { "type": "string", "enum": [ "right", "left" ] }, "attention": { "type": "boolean" }, "surfaces": { "$ref": "#/components/schemas/WhatsAppButtonSurfaces" } }, "required": [ "enabled", "phone", "agentName", "caption", "avatarKey", "welcomeMessage", "launcherLabel", "ctaLabel", "prefillGeneral", "prefillProduct", "thankYouButtonLabel", "prefillThankYou", "accent", "position", "attention", "surfaces" ] }, "WhatsAppButtonSurfaces": { "type": "object", "properties": { "home": { "type": "boolean" }, "catalog": { "type": "boolean" }, "product": { "type": "boolean" }, "pages": { "type": "boolean" }, "thankYou": { "type": "boolean" }, "checkout": { "type": "boolean" }, "landing": { "type": "boolean" } }, "required": [ "home", "catalog", "product", "pages", "thankYou", "checkout", "landing" ], "description": "Which kinds of storefront page the launcher appears on. A fixed registry rather than URL patterns, and every surface off is a valid paused state." }, "WhatsAppButtonConfigInput": { "type": "object", "additionalProperties": {}, "description": "The button's setup. Same shape as WhatsAppButtonConfig, with every key optional — an omitted key takes its default. `phone` is accepted in any form the merchant knows (0551234567, 00213…, +213…, spaced) and stored normalised. Unknown keys, an unreachable number, an avatar that is not an uploaded image's Media Key and every text cap are refused, with each problem listed in `context.issues`.", "example": { "enabled": true, "phone": "0551234567", "agentName": "أمين", "caption": "نرد خلال دقائق", "welcomeMessage": "مرحبا 👋 كيفاش نعاونك؟", "prefillProduct": "سلام، بغيت نسقسي على {product} — {url}", "accent": "whatsapp", "position": "right", "surfaces": { "home": true, "catalog": true, "product": true, "pages": true, "thankYou": true, "checkout": false, "landing": false } } }, "TelegramApp": { "type": [ "object", "null" ], "properties": { "consumerId": { "type": "string", "description": "The Telegram Consumer the bot sends through: its deliveries are under /api/event-deliveries" }, "enabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "enum": [ "failing", "merchant", "gone", "bot_blocked", "not_connected", null ], "description": "Why it is off: `not_connected` (no chat yet), `bot_blocked` (the chat blocked the bot), `merchant`, `failing`; null while on" }, "failingSince": { "type": [ "string", "null" ], "description": "Since when every message has failed; null once one is delivered" }, "bot": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "username": { "type": "string", "example": "acme_orders_bot" }, "tokenMasked": { "type": "string", "description": "The bot token, masked: it is never sent back", "example": "••••x9Qa", "x-credential": "masked" } }, "required": [ "id", "username", "tokenMasked" ], "description": "The saved bot; null once it was disconnected" }, "chat": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "example": "Amina Benali" }, "connectedAt": { "type": "string" } }, "required": [ "name", "connectedAt" ], "description": "The connected chat; null until someone presses Start on a pairing link" }, "pairingExpiresAt": { "type": [ "string", "null" ], "description": "Until when the latest pairing link works; null when none is open" }, "events": { "type": "array", "items": { "type": "string" }, "example": [ "order.created", "shipment.delivered", "shipment.delivery_failed" ] }, "language": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ] }, "writesIn": { "type": "string", "enum": [ "ar", "fr", "en" ], "description": "The language messages are written in now" } }, "required": [ "consumerId", "enabled", "disabledReason", "failingSince", "bot", "chat", "pairingExpiresAt", "events", "language", "writesIn" ] }, "TelegramChange": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "string", "enum": [ "order.created", "order.updated", "order.confirmed", "order.unreachable", "order.preparing", "order.ready", "order.cancelled", "order.line_returned", "order.deleted", "shipment.handed_off", "shipment.out_for_delivery", "shipment.delivery_failed", "shipment.delivered", "shipment.return_started", "shipment.returned", "shipment.cancelled", "shipment.voided" ] }, "minItems": 1, "description": "The Event Types the bot tells, one or more", "example": [ "order.created", "shipment.delivered" ] }, "language": { "type": [ "string", "null" ], "enum": [ "ar", "fr", "en", null ], "description": "The language messages are written in; null for the store's primary language" }, "enabled": { "type": "boolean", "description": "On or off. Turning it on needs a connected chat." } } }, "ReviewRules": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "When false, reviews are hidden on the storefront and shoppers cannot send one", "example": true }, "maxPhotos": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Photos a shopper may add to a review, 0 (none) to 6", "example": 3 }, "voiceMaxSeconds": { "anyOf": [ { "type": "number", "enum": [ 30 ] }, { "type": "number", "enum": [ 60 ] }, { "type": "number", "enum": [ 90 ] }, { "type": "number", "enum": [ 120 ] }, { "type": "null" } ], "description": "Longest voice note a shopper may add, in seconds (30, 60, 90, 120); null = no voice notes", "example": 60 }, "autoPublish": { "type": "string", "enum": [ "off", "text_only", "all" ], "description": "Which shopper reviews publish without checking: none (off), text-only ones (text_only: anything with a photo or voice note waits), or all", "example": "text_only" } }, "required": [ "enabled", "maxPhotos", "voiceMaxSeconds", "autoPublish" ] }, "ShippingLabelConfig": { "type": "object", "properties": { "size": { "type": "string", "enum": [ "100x150" ], "description": "The physical label: 100×150 mm, the 4×6 inch roll of thermal printers" }, "language": { "type": "string", "enum": [ "fr", "ar" ], "description": "The language of the label's own words; the order's details print as written" }, "showLogo": { "type": "boolean" }, "senderPhone": { "type": [ "string", "null" ], "description": "Printed for the sender; null prints the legal profile's contact phone" }, "showItems": { "type": "boolean", "description": "What is in the parcel: quantity, name and variant of each line" }, "showNotes": { "type": "boolean", "description": "The order's notes, for the driver" }, "openParcel": { "type": "string", "enum": [ "unset", "allowed", "forbidden" ], "description": "Whether the customer may open the parcel before paying; `unset` prints nothing" }, "footer": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "size", "language", "showLogo", "senderPhone", "showItems", "showNotes", "openParcel", "footer" ] }, "ShippingLabelSender": { "type": "object", "properties": { "name": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "name", "logoUrl", "phone", "address" ], "description": "The store as its labels print it: its name and logo, and the phone and address of its legal profile" }, "ShippingLabelConfigInput": { "type": "object", "additionalProperties": {}, "description": "A ShippingLabelConfig with every key optional" }, "ShippingLabelParcel": { "type": "object", "properties": { "shipmentId": { "type": "string" }, "orderNumber": { "type": "string" }, "handedAt": { "type": "string", "description": "When the order was given to the driver" }, "amount": { "type": "number", "description": "The cash to collect, frozen on the shipment" }, "recipient": { "type": "object", "properties": { "name": { "type": "string" }, "phone": { "type": "string" }, "wilaya": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "name", "nameAr" ] }, "commune": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "nameAr": { "type": "string" } }, "required": [ "name", "nameAr" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "name", "phone", "wilaya", "commune", "address" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "variant": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" } }, "required": [ "name", "variant", "quantity" ] } }, "notes": { "type": [ "string", "null" ] }, "driver": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] } }, "required": [ "name", "phone" ] } }, "required": [ "shipmentId", "orderNumber", "handedAt", "amount", "recipient", "items", "notes", "driver" ] }, "ShippingProfile": { "type": "object", "properties": { "id": { "type": "string", "example": "profile_123" }, "name": { "type": "string", "example": "Standard Rates" }, "isDefault": { "type": "boolean", "description": "Exactly one profile is always the default; its rates auto-apply on order creation", "example": false }, "notes": { "type": [ "string", "null" ], "example": null }, "productCount": { "type": "integer", "description": "How many products are assigned to this profile", "example": 3 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "ruleCount": { "type": "integer", "description": "Number of wilaya rules in this profile", "example": 58 } }, "required": [ "id", "name", "isDefault", "notes", "productCount", "createdAt", "updatedAt", "ruleCount" ], "description": "Shipping rate profile. List responses include ruleCount; detail responses include the rules array instead." }, "ShippingProfileWithRules": { "type": "object", "properties": { "id": { "type": "string", "example": "profile_123" }, "name": { "type": "string", "example": "Standard Rates" }, "isDefault": { "type": "boolean", "description": "Exactly one profile is always the default; its rates auto-apply on order creation", "example": false }, "notes": { "type": [ "string", "null" ], "example": null }, "productCount": { "type": "integer", "description": "How many products are assigned to this profile", "example": 3 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingRule" } } }, "required": [ "id", "name", "isDefault", "notes", "productCount", "createdAt", "updatedAt", "rules" ], "description": "Shipping profile with its full list of wilaya rules" }, "ShippingRule": { "type": "object", "properties": { "id": { "type": "string", "example": "rule_abc123" }, "profileId": { "type": "string", "example": "profile_123" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58, "example": 16 }, "wilayaName": { "type": "string", "description": "Wilaya French/name — joined from reference table", "example": "Alger" }, "wilayaNameAr": { "type": "string", "example": "الجزائر" }, "homePrice": { "type": "number", "example": 400 }, "stopDeskPrice": { "type": "number", "example": 250 }, "homeEnabled": { "type": "boolean", "example": true }, "stopDeskEnabled": { "type": "boolean", "example": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "profileId", "wilayaId", "wilayaName", "wilayaNameAr", "homePrice", "stopDeskPrice", "homeEnabled", "stopDeskEnabled", "createdAt" ], "description": "Per-wilaya customer delivery rate within a shipping profile" }, "CommuneOverride": { "type": "object", "properties": { "communeId": { "type": "string", "example": "550e8400-e29b-41d4-a716-446655440000" }, "communeName": { "type": "string", "example": "Bab Ezzouar" }, "communeNameAr": { "type": "string", "example": "باب الزوار" }, "postalCode": { "type": [ "string", "null" ] }, "homeEnabled": { "type": [ "boolean", "null" ], "description": "null = inherited from wilaya rule" }, "stopDeskEnabled": { "type": [ "boolean", "null" ], "description": "null = inherited from wilaya rule" }, "homePrice": { "type": [ "number", "null" ], "description": "null = inherited from wilaya rule" }, "stopDeskPrice": { "type": [ "number", "null" ], "description": "null = inherited from wilaya rule" }, "effectiveHomeEnabled": { "type": "boolean" }, "effectiveStopDeskEnabled": { "type": "boolean" }, "effectiveHomePrice": { "type": "number" }, "effectiveStopDeskPrice": { "type": "number" }, "hasOverride": { "type": "boolean" } }, "required": [ "communeId", "communeName", "communeNameAr", "postalCode", "homeEnabled", "stopDeskEnabled", "homePrice", "stopDeskPrice", "effectiveHomeEnabled", "effectiveStopDeskEnabled", "effectiveHomePrice", "effectiveStopDeskPrice", "hasOverride" ], "description": "A commune within a wilaya rule, showing both the raw override fields (null = inherited) and the effective values used at fee-resolution time." }, "DriverPayment": { "type": "object", "properties": { "id": { "type": "string", "example": "pay_abc123" }, "driverId": { "type": "string", "description": "UUID of the driver this payment is for" }, "type": { "type": "string", "enum": [ "cod_remittance", "fee_payment", "net_settlement" ], "description": "`cod_remittance`: driver hands COD cash to business. `fee_payment`: business pays driver fees. `net_settlement`: both at once (driver hands COD − fees net amount).", "example": "cod_remittance" }, "amount": { "type": "number", "description": "Settled amount, computed server-side from the shipments' frozen values: cash total (`cod_remittance`), fee total (`fee_payment`), or cash − fees (`net_settlement`).", "example": 95000 }, "orderCount": { "type": "integer", "description": "Number of shipments (one per order) this payment settles.", "example": 3 }, "notes": { "type": [ "string", "null" ], "description": "Optional internal note about this payment record.", "example": null }, "createdBy": { "type": "string", "description": "User ID of the team member who recorded this payment." }, "createdByName": { "type": "string", "description": "Denormalised display name for audit trail.", "example": "Ahmed Benali" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "driverId", "type", "amount", "orderCount", "notes", "createdBy", "createdByName", "createdAt" ] }, "PendingSettlement": { "type": "object", "properties": { "shipmentId": { "type": "string" }, "orderId": { "type": "string" }, "orderNumber": { "type": "string" }, "customerName": { "type": "string" }, "codAmount": { "type": "number", "description": "Cash the driver collected (DZD)" }, "driverFee": { "type": "number", "description": "The driver's frozen fee (DZD)" }, "deliveredAt": { "type": "string", "format": "date-time" }, "codPaymentId": { "type": [ "string", "null" ], "description": "The payment that settled the cash; null while the driver still holds it" }, "feePaymentId": { "type": [ "string", "null" ], "description": "The payment that settled the fee; null while it is owed" } }, "required": [ "shipmentId", "orderId", "orderNumber", "customerName", "codAmount", "driverFee", "deliveredAt", "codPaymentId", "feePaymentId" ], "description": "A delivered driver shipment with a part still to settle" }, "Store": { "type": "object", "properties": { "id": { "type": "string", "example": "store_01" }, "name": { "type": "string", "example": "My Shop" }, "domain": { "type": [ "string", "null" ], "description": "Custom storefront domain", "example": null }, "logo": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The store's logo" } ] }, "themeId": { "type": "string", "description": "The storefront theme's slug, e.g. \"theme-00\"", "example": "theme-00" }, "lang": { "type": "string", "enum": [ "ar", "fr", "en" ], "description": "The store's primary language: its storefront language and first fallback", "example": "ar" }, "currency": { "type": "string", "example": "DZD" }, "currencySymbol": { "type": "string", "example": "دج" }, "metaTitle": { "type": [ "string", "null" ], "example": "My Shop — Best Products" }, "metaDescription": { "type": [ "string", "null" ], "example": "Find the best products at My Shop." }, "ogImage": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The image links to the store show when shared" } ] }, "cartEnabled": { "type": "boolean", "description": "When true the storefront renders the shopping cart alongside the direct order form", "example": false }, "freeShippingThreshold": { "type": [ "integer", "null" ], "description": "Order subtotal (DZD) at or above which delivery is free. null = off", "example": null }, "cartShippingMode": { "type": "string", "enum": [ "highest", "default_profile" ], "description": "Which rate a basket spanning several shipping profiles pays", "example": "highest" }, "storeApiKey": { "type": [ "string", "null" ], "description": "Plaintext storefront API key — visible to the merchant in Store Settings. Not the dashboard API key." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/StoreLanguage" }, "description": "Every language the store has added, primary first, published or not." } }, "required": [ "id", "name", "domain", "logo", "themeId", "lang", "currency", "currencySymbol", "metaTitle", "metaDescription", "ogImage", "cartEnabled", "freeShippingThreshold", "cartShippingMode", "storeApiKey", "createdAt", "updatedAt", "languages" ], "description": "Single-tenant store configuration: branding, theme, localization, SEO, and feature flags" }, "StoreLanguage": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean", "description": "Shown to shoppers. Always true for the primary." }, "primary": { "type": "boolean" } }, "required": [ "locale", "published", "primary" ] }, "Review": { "type": "object", "properties": { "id": { "type": "string", "example": "6f0c9b8e-3d2a-4e5f-8a7b-9c1d2e3f4a5b" }, "productId": { "type": "string" }, "productName": { "type": [ "string", "null" ] }, "orderId": { "type": [ "string", "null" ], "description": "The order it rests on; null for a store review without one" }, "orderNumber": { "type": [ "string", "null" ], "example": "ORD-20261016-0042" }, "customerId": { "type": [ "string", "null" ] }, "customerName": { "type": "string", "example": "أحمد بن علي" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "example": 5 }, "title": { "type": [ "string", "null" ], "example": "منتج ممتاز" }, "body": { "type": "string", "example": "جودة عالية وسعر مناسب" }, "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "example": "pending" }, "source": { "type": "string", "enum": [ "storefront", "merchant" ], "description": "Sent by a shopper (storefront) or entered by the store (merchant)" }, "verified": { "type": "boolean", "description": "Rests on a delivered order: the storefront shows it as a verified purchase" }, "mediaDropped": { "type": "integer", "description": "Photos or voice notes received but not kept (unreadable, too long)" }, "createdBy": { "type": [ "string", "null" ], "description": "The staff member who entered a store review" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "media": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewMedia" } } }, "required": [ "id", "productId", "productName", "orderId", "orderNumber", "customerId", "customerName", "rating", "title", "body", "status", "source", "verified", "mediaDropped", "createdBy", "createdAt", "updatedAt", "media" ], "description": "A product review, as the merchant moderates it" }, "ReviewMedia": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "audio" ] }, "url": { "type": "string", "format": "uri", "description": "A photo at 1600 px at most (WebP), or the voice note as recorded" }, "thumbUrl": { "type": [ "string", "null" ], "format": "uri", "description": "A photo's 480 px version for lists" }, "contentType": { "type": "string" }, "bytes": { "type": "integer" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ], "description": "A voice note's length" } }, "required": [ "id", "kind", "url", "thumbUrl", "contentType", "bytes", "width", "height", "durationMs" ], "description": "A photo or the voice note of a review" }, "Offer": { "type": "object", "properties": { "id": { "type": "string", "description": "Offer UUID", "example": "off_abc123" }, "name": { "type": "string", "description": "Merchant-facing display name.", "example": "اشتري 2 واحصل على 1 مجاناً" }, "triggerProduct": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Product UUID" }, "name": { "type": "string", "example": "Samsung Galaxy A54" }, "handle": { "type": "string", "description": "URL-friendly product handle", "example": "samsung-galaxy-a54" } }, "required": [ "id", "name", "handle" ], "description": "The product the customer must purchase to trigger this offer. Null when the trigger product no longer exists." }, "triggerVariant": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Variant UUID" }, "label": { "type": "string", "description": "Human-readable label built from variation values.", "example": "أزرق / 128 GB" } }, "required": [ "id", "label" ], "description": "Specific variant required to trigger the offer. null = any variant of the trigger product." }, "triggerQuantity": { "type": "integer", "minimum": 1, "description": "Minimum quantity of the trigger product the customer must order.", "example": 2 }, "rewardProduct": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Product UUID" }, "name": { "type": "string", "example": "Samsung Galaxy Buds" }, "handle": { "type": "string", "description": "URL-friendly product handle", "example": "samsung-galaxy-buds" } }, "required": [ "id", "name", "handle" ], "description": "The product the customer receives for free when the offer triggers. null for `free_shipping` offers." }, "rewardVariant": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Variant UUID" }, "label": { "type": "string", "description": "Human-readable label built from variation values.", "example": "أبيض" } }, "required": [ "id", "label" ], "description": "Specific variant given as the reward. null = same variant as the ordered item (when same product) or the first active variant (when different product). Always null for `free_shipping` offers." }, "rewardQuantity": { "type": "integer", "minimum": 0, "description": "Number of free reward units added to the order. 0 for `free_shipping` offers.", "example": 1 }, "discountType": { "type": "string", "enum": [ "free", "free_shipping" ], "description": "`free` = reward product added at price 0. `free_shipping` = delivery fee waived (no reward product)." }, "startsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC ISO-8601 datetime when the offer becomes active. null = no start restriction.", "example": null }, "endsAt": { "type": [ "string", "null" ], "format": "date-time", "description": "UTC ISO-8601 datetime when the offer expires. null = no end restriction.", "example": null }, "status": { "type": "string", "enum": [ "active", "inactive" ], "description": "Only `active` offers within the schedule window are auto-applied to store orders.", "example": "active" }, "state": { "type": "string", "enum": [ "inactive", "scheduled", "expired", "live" ], "description": "Where the offer stands now: switched off, not started, ended, or live — the only state shoppers see it in.", "example": "live" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "triggerProduct", "triggerVariant", "triggerQuantity", "rewardProduct", "rewardVariant", "rewardQuantity", "discountType", "startsAt", "endsAt", "status", "state", "createdAt", "updatedAt" ] }, "CouponSummary": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string", "example": "RAMADAN10" }, "kind": { "type": "string", "enum": [ "percentage", "fixed_amount", "free_shipping" ] }, "value": { "type": "integer" }, "maxDiscount": { "type": [ "integer", "null" ] }, "minSubtotal": { "type": [ "integer", "null" ] }, "minQuantity": { "type": [ "integer", "null" ] }, "scope": { "type": "string", "enum": [ "store", "products", "collections" ] }, "audience": { "type": "string", "enum": [ "everyone", "selected" ] }, "usageLimit": { "type": [ "integer", "null" ] }, "oncePerCustomer": { "type": "boolean" }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "state": { "type": "string", "enum": [ "inactive", "scheduled", "expired", "used_up", "live" ], "description": "Where the coupon stands now." }, "uses": { "type": "integer", "description": "Orders that used it and are not cancelled." }, "discountGiven": { "type": "integer", "description": "What those orders were given off, in dinars." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "counts": { "type": "object", "properties": { "products": { "type": "integer" }, "collections": { "type": "integer" }, "customers": { "type": "integer" }, "groups": { "type": "integer" } }, "required": [ "products", "collections", "customers", "groups" ] } }, "required": [ "id", "code", "kind", "value", "maxDiscount", "minSubtotal", "minQuantity", "scope", "audience", "usageLimit", "oncePerCustomer", "startsAt", "endsAt", "status", "state", "uses", "discountGiven", "createdAt", "updatedAt", "counts" ] }, "Coupon": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string", "example": "RAMADAN10" }, "kind": { "type": "string", "enum": [ "percentage", "fixed_amount", "free_shipping" ] }, "value": { "type": "integer" }, "maxDiscount": { "type": [ "integer", "null" ] }, "minSubtotal": { "type": [ "integer", "null" ] }, "minQuantity": { "type": [ "integer", "null" ] }, "scope": { "type": "string", "enum": [ "store", "products", "collections" ] }, "audience": { "type": "string", "enum": [ "everyone", "selected" ] }, "usageLimit": { "type": [ "integer", "null" ] }, "oncePerCustomer": { "type": "boolean" }, "startsAt": { "type": [ "string", "null" ] }, "endsAt": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "state": { "type": "string", "enum": [ "inactive", "scheduled", "expired", "used_up", "live" ], "description": "Where the coupon stands now." }, "uses": { "type": "integer", "description": "Orders that used it and are not cancelled." }, "discountGiven": { "type": "integer", "description": "What those orders were given off, in dinars." }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "handle": { "type": "string" } }, "required": [ "id", "name", "handle" ] } }, "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "handle": { "type": "string" } }, "required": [ "id", "title", "handle" ] } }, "customers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] } }, "groups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "code", "kind", "value", "maxDiscount", "minSubtotal", "minQuantity", "scope", "audience", "usageLimit", "oncePerCustomer", "startsAt", "endsAt", "status", "state", "uses", "discountGiven", "createdAt", "updatedAt", "products", "collections", "customers", "groups" ] }, "StockOverview": { "type": "object", "properties": { "totalSkus": { "type": "integer", "description": "Total number of tracked SKUs (simple + variants).", "example": 42 }, "outOfStockCount": { "type": "integer", "example": 3 }, "lowStockCount": { "type": "integer", "example": 7 }, "totalInventoryValue": { "type": "integer", "description": "Sum of (inventory × price) across all tracked SKUs, in DZD.", "example": 1250000 }, "currency": { "type": "string", "example": "DZD" }, "outOfStockItems": { "type": "array", "items": { "$ref": "#/components/schemas/StockAlertItem" } }, "lowStockItems": { "type": "array", "items": { "$ref": "#/components/schemas/StockAlertItem" }, "description": "Items at or below their low stock threshold (but still in stock)." }, "allItems": { "type": "array", "items": { "$ref": "#/components/schemas/StockAlertItem" }, "description": "Every tracked SKU. Sorted: out-of-stock first, then by inventory ascending. Used by the inventory table." } }, "required": [ "totalSkus", "outOfStockCount", "lowStockCount", "totalInventoryValue", "currency", "outOfStockItems", "lowStockItems", "allItems" ] }, "StockAlertItem": { "type": "object", "properties": { "productId": { "type": "string", "example": "prod_abc123" }, "variantId": { "type": [ "string", "null" ], "example": null }, "productName": { "type": "string", "example": "Samsung Galaxy A54" }, "variantLabel": { "type": [ "string", "null" ], "description": "Concatenated variant option values, e.g. 'Red / M'. Null for simple products.", "example": "أحمر / M" }, "sku": { "type": [ "string", "null" ], "description": "SKU code of the tracked row. Null when a simple product has none.", "example": "TSHIRT-RED-M" }, "inventory": { "type": "integer", "example": 2 }, "lowStockThreshold": { "type": "integer", "example": 5 }, "isOutOfStock": { "type": "boolean", "example": false }, "updatedAt": { "type": "string", "description": "Last write to the SKU row — every stock adjustment updates it.", "example": "2025-01-15T10:30:00.000Z" } }, "required": [ "productId", "variantId", "productName", "variantLabel", "sku", "inventory", "lowStockThreshold", "isOutOfStock", "updatedAt" ] }, "StockMovement": { "type": "object", "properties": { "id": { "type": "string", "example": "mov_abc123" }, "productId": { "type": "string", "example": "prod_abc123" }, "variantId": { "type": [ "string", "null" ], "description": "Variant ID for variant-level movements; null for simple products", "example": null }, "type": { "type": "string", "enum": [ "PURCHASE", "ADJUSTMENT_ADD", "ADJUSTMENT_REMOVE", "ORDER_DEDUCTED", "ORDER_CANCELLED", "ORDER_RETURNED", "OFFLINE_SALE" ] }, "delta": { "type": "integer", "description": "Positive = stock in, negative = stock out. Never zero.", "example": 10 }, "qtyBefore": { "type": "integer", "example": 5 }, "qtyAfter": { "type": "integer", "example": 15 }, "reason": { "type": [ "string", "null" ], "description": "User-supplied note. Required by the API for ADJUSTMENT_ADD, ADJUSTMENT_REMOVE and OFFLINE_SALE.", "example": "Restocked from supplier" }, "reference": { "type": [ "string", "null" ], "description": "orderId for ORDER_* movement types; null otherwise.", "example": null }, "createdBy": { "type": "string" }, "createdByName": { "type": "string", "example": "Ahmed Benali" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "productId", "variantId", "type", "delta", "qtyBefore", "qtyAfter", "reason", "reference", "createdBy", "createdByName", "createdAt" ] }, "AbandonedOrder": { "type": "object", "properties": { "id": { "type": "string", "example": "ab_abc123" }, "sessionId": { "type": "string", "description": "Storefront session ID — unique per abandoned checkout" }, "customerName": { "type": "string", "example": "Ahmed Benali" }, "phone": { "type": "string", "example": "0551234567" }, "wilayaId": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 58, "example": 16 }, "communeId": { "type": [ "string", "null" ] }, "wilayaName": { "type": [ "string", "null" ], "example": "الجزائر" }, "communeName": { "type": [ "string", "null" ] }, "productId": { "type": [ "string", "null" ] }, "productName": { "type": [ "string", "null" ], "description": "The only product, or the FIRST line of the basket. Always populated, so this column reads the same for both shapes.", "example": "Samsung Galaxy A54" }, "variantId": { "type": [ "string", "null" ] }, "variantLabel": { "type": [ "string", "null" ], "example": "أحمر / XL" }, "price": { "type": [ "number", "null" ], "description": "Cart value at abandonment — the basket subtotal, or one unit's price", "example": 9000 }, "items": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/AbandonedOrderItem" }, "description": "The whole basket, when the shopper abandoned a cart checkout. Null for a single-product checkout, where the flat product fields above are the record." }, "itemCount": { "type": [ "integer", "null" ], "description": "Distinct lines in the basket. Null for a single-product checkout.", "example": 3 }, "deliveryType": { "type": [ "string", "null" ], "enum": [ "home", "stop_desk", null ] }, "fbc": { "type": [ "string", "null" ], "description": "_fbc cookie captured at input — links recovery back to the ad click" }, "fbp": { "type": [ "string", "null" ], "description": "_fbp browser identity cookie" }, "ipAddress": { "type": [ "string", "null" ] }, "userAgent": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "abandoned", "contacted", "converted" ] }, "convertedOrderId": { "type": [ "string", "null" ], "description": "Set when the customer completes an order after contact" }, "convertedOrderNumber": { "type": [ "string", "null" ] }, "recoveryAttempts": { "type": "integer", "example": 0 }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "sessionId", "customerName", "phone", "wilayaId", "communeId", "wilayaName", "communeName", "productId", "productName", "variantId", "variantLabel", "price", "items", "itemCount", "deliveryType", "fbc", "fbp", "ipAddress", "userAgent", "status", "convertedOrderId", "convertedOrderNumber", "recoveryAttempts", "createdAt", "updatedAt" ] }, "AbandonedOrderItem": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string", "example": "Hoodie Classic" }, "variantId": { "type": [ "string", "null" ] }, "variantLabel": { "type": [ "string", "null" ], "example": "Noir / L" }, "quantity": { "type": "integer", "example": 2 }, "unitPrice": { "type": "number", "description": "Price shown to the shopper at abandonment. Display only.", "example": 2400 } }, "required": [ "productId", "productName", "quantity", "unitPrice" ] }, "AbandonedOrderStats": { "type": "object", "properties": { "totalAbandoned": { "type": "integer", "description": "Orders currently in `abandoned` status", "example": 34 }, "totalConverted": { "type": "integer", "example": 12 }, "conversionRate": { "type": "integer", "description": "Recovered percentage: converted / (abandoned + converted), rounded", "example": 26 }, "estimatedLostRevenue": { "type": "number", "description": "Sum of cart values still sitting in `abandoned` status, in DZD", "example": 306000 } }, "required": [ "totalAbandoned", "totalConverted", "conversionRate", "estimatedLostRevenue" ] } }, "parameters": {} }, "paths": { "/media/{key}": { "get": { "tags": [ "Media" ], "summary": "Serve a media file", "description": "A file of the store's media, for a store whose server serves its media itself (`direct` delivery — local development). Public, cached as immutable. On a store whose host delivers its own files, every key answers 404: use the URL the API gives.", "operationId": "serveMedia", "security": [], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "A Media Key, e.g. `products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp`" } ], "responses": { "200": { "description": "The file, with its Content-Type" }, "404": { "description": "Not a key this server serves", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "MEDIA_NOT_FOUND" } } } } } } } } }, "/webhooks/yalidine": { "get": { "tags": [ "Webhooks" ], "summary": "Yalidine CRC challenge", "description": "Yalidine sends a GET request with ?subscribe=…&crc_token= to validate the endpoint at creation, edit, and periodically. The endpoint echoes the crc_token as plain text. If this fails, Yalidine disables the webhook automatically.", "operationId": "yalidineChallenge", "parameters": [ { "schema": { "type": "string", "description": "Sent by Yalidine to initiate the CRC challenge" }, "required": false, "description": "Sent by Yalidine to initiate the CRC challenge", "name": "subscribe", "in": "query" }, { "schema": { "type": "string", "description": "Token echoed back in the (plain-text) response body" }, "required": false, "description": "Token echoed back in the (plain-text) response body", "name": "crc_token", "in": "query" } ], "responses": { "200": { "description": "CRC token echoed as plain text", "content": { "text/plain": { "schema": { "type": "string", "example": "abc123token" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Yalidine event delivery", "description": "Receives webhook event batches from Yalidine (one event type per delivery, several events per batch; each `event_id` is its own idempotency key). The events are stored in the inbox and the request is answered at once — processing follows, so Yalidine's 10-second limit is always met — and an event that fails processing is retried with backoff.\n\n**Which company:** the one whose webhook secret verifies `X-Yalidine-Signature` (HMAC-SHA256 of the raw body, hex), so several Yalidine companies never mix. A delivery no secret verifies is refused with **401** — unless the store has a single Yalidine company and it has no secret set (accepted, with a warning).\n\n**Payload:** `{ type: \"parcel_created\" | \"parcel_edited\" | \"parcel_deleted\" | \"parcel_status_updated\" | \"parcel_payment_updated\", events: [{ event_id, occurred_at, data }] }`. Status updates and deletions move the shipment; payment updates are kept for settlement; the rest is ignored. An unreadable body is refused with **400**.", "operationId": "yalidineWebhook", "parameters": [ { "schema": { "type": "string", "description": "HMAC-SHA256 of the raw request body, keyed with the webhook secret (hex). Required when a secret is stored." }, "required": false, "description": "HMAC-SHA256 of the raw request body, keyed with the webhook secret (hex). Required when a secret is stored.", "name": "X-Yalidine-Signature", "in": "header" } ], "responses": { "200": { "description": "Stored in the inbox; processed after this answer (a duplicate delivery is stored once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "example": true } }, "required": [ "received" ] } } } }, "400": { "description": "An unreadable delivery (INVALID_WEBHOOK_PAYLOAD)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_WEBHOOK_PAYLOAD" }, "category": { "type": "string", "example": "VALIDATION" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "error", "code", "category" ] } } } }, "401": { "description": "The signature matches no company (INVALID_WEBHOOK_PAYLOAD)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_WEBHOOK_PAYLOAD" }, "category": { "type": "string", "example": "VALIDATION" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "error", "code", "category" ] } } } } } } }, "/webhooks/zr_express": { "post": { "tags": [ "Webhooks" ], "summary": "ZR Express event delivery", "description": "Receives webhook events from ZR Express via Svix; `svix-id` is the idempotency key. The event is stored in the inbox and the request answered at once; processing follows, with retries.\n\n**Which company:** the one whose `whsec_` secret verifies the Svix signature over the raw bytes; none verifying is a **401** — unless the store has a single ZR company and it has no secret set.\n\n**Payload:** `{ eventType: \"parcel.state.updated\" | \"parcel.state.situation.created\" | \"parcel.isReturn.updated\", occurredAt, data: ParcelWebhookDto }`.", "operationId": "zrExpressWebhook", "parameters": [ { "schema": { "type": "string", "description": "Svix idempotency key" }, "required": true, "description": "Svix idempotency key", "name": "svix-id", "in": "header" }, { "schema": { "type": "string", "description": "Svix signed timestamp" }, "required": true, "description": "Svix signed timestamp", "name": "svix-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Svix HMAC-SHA256 signature" }, "required": true, "description": "Svix HMAC-SHA256 signature", "name": "svix-signature", "in": "header" } ], "responses": { "200": { "description": "Stored in the inbox; processed after this answer (a duplicate delivery is stored once)", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean", "example": true } }, "required": [ "received" ] } } } }, "400": { "description": "An unreadable delivery (INVALID_WEBHOOK_PAYLOAD)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_WEBHOOK_PAYLOAD" }, "category": { "type": "string", "example": "VALIDATION" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "error", "code", "category" ] } } } }, "401": { "description": "The signature matches no company (INVALID_WEBHOOK_PAYLOAD)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_WEBHOOK_PAYLOAD" }, "category": { "type": "string", "example": "VALIDATION" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "error", "code", "category" ] } } } } } } }, "/webhooks/telegram/{consumerId}": { "post": { "tags": [ "Webhooks" ], "summary": "Telegram bot update", "description": "Receives the updates of the merchant's own Telegram bot (the Telegram App), sent by Telegram to the URL the store gave it with `setWebhook`, for messages and chat membership only.\n\n**Which bot:** the Telegram Consumer named in the path, whose secret must be in `X-Telegram-Bot-Api-Secret-Token` — checked before the body is read. Without it the update is refused with **401** and changes nothing.\n\n**What it does:** `/start ` in a private chat connects that chat when the code is the bot's open pairing code, unexpired and unused, and the answer asks Telegram to send the bot's reply (`{ method: \"sendMessage\", chat_id, text }`); the connected chat blocking the bot stops its Consumer (`bot_blocked`), unblocking it starts it again. Anything else is acknowledged and ignored. A body that is not JSON is refused with **400**.", "operationId": "telegramUpdate", "parameters": [ { "schema": { "type": "string", "description": "The Telegram Consumer the bot sends through" }, "required": true, "description": "The Telegram Consumer the bot sends through", "name": "consumerId", "in": "path" }, { "schema": { "type": "string", "description": "The secret the store gave Telegram for this bot" }, "required": false, "description": "The secret the store gave Telegram for this bot", "name": "X-Telegram-Bot-Api-Secret-Token", "in": "header" } ], "responses": { "200": { "description": "Acknowledged; for a /start, the bot's reply for Telegram to send", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "received": { "type": "boolean", "example": true } }, "required": [ "received" ] }, { "type": "object", "properties": { "method": { "type": "string", "enum": [ "sendMessage" ] }, "chat_id": { "type": "integer" }, "text": { "type": "string" } }, "required": [ "method", "chat_id", "text" ] } ] } } } }, "400": { "description": "Not JSON (INVALID_WEBHOOK_PAYLOAD)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_WEBHOOK_PAYLOAD" }, "category": { "type": "string", "example": "VALIDATION" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "error", "code", "category" ] } } } }, "401": { "description": "No secret, or not this bot's (INVALID_WEBHOOK_PAYLOAD)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "example": "INVALID_WEBHOOK_PAYLOAD" }, "category": { "type": "string", "example": "VALIDATION" }, "context": { "type": "object", "additionalProperties": {} } }, "required": [ "error", "code", "category" ] } } } } } } }, "/store/config": { "get": { "tags": [ "Store API" ], "summary": "Get store configuration", "description": "Get store settings used by the storefront (theme, locale, branding).", "operationId": "getStoreConfig", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" }, { "schema": { "type": "string", "pattern": "^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$", "description": "The requesting theme's key (`defineTheme({ key })`). Its text edits ride along as `contentOverrides`; without it there are none.", "example": "theme-00" }, "required": false, "description": "The requesting theme's key (`defineTheme({ key })`). Its text edits ride along as `contentOverrides`; without it there are none.", "name": "theme", "in": "query" } ], "responses": { "200": { "description": "Store configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreConfig" } }, "required": [ "success", "data" ] } } } } } } }, "/store/menus/{handle}": { "get": { "tags": [ "Store API" ], "summary": "Get a menu", "description": "A navigation menu by handle, as a shopper sees it: labels in the requested language (`?locale=`, else the store's primary), each item's `href` a path of the store without a language prefix (or the merchant's URL). An item whose destination is deleted or not public is left out with its children. An unknown handle is a 404: the theme then renders its own fallback.", "operationId": "getStoreMenu", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "example": "main-menu" }, "required": true, "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "name": "handle", "in": "path" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "The menu", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorefrontMenu" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "The store has no menu with this handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/collections/{handle}": { "get": { "tags": [ "Store API" ], "summary": "Get a collection", "description": "A collection's title and description for its page (`/collections/:handle`), in the requested language (`?locale=`, else the store's primary). Its products come from `/store/products?collection=`. An unknown handle is a 404: the theme answers a real 404 page.", "operationId": "getStoreCollection", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "example": "best-sellers" }, "required": true, "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "name": "handle", "in": "path" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "The collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorefrontCollection" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "The store has no collection with this handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/products": { "get": { "tags": [ "Store API" ], "summary": "List store products", "description": "Get the public product catalog for the storefront. Only returns products where `status=ACTIVE`, `showInStore=true` and `visibility=true`.", "operationId": "listStoreProducts", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Only this collection's products (by handle), in the merchant's order. An unknown handle lists nothing.", "example": "best-sellers" }, "required": false, "description": "Only this collection's products (by handle), in the merchant's order. An unknown handle lists nothing.", "name": "collection", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When true, only products priced below their compare-at price." }, "required": false, "description": "When true, only products priced below their compare-at price.", "name": "onSale", "in": "query" }, { "schema": { "type": "string", "description": "Filter by category ID." }, "required": false, "description": "Filter by category ID.", "name": "categoryId", "in": "query" }, { "schema": { "type": "string", "enum": [ "newest", "price-ascending", "price-descending" ], "description": "The order: `newest`, `price-ascending` or `price-descending`. Absent: a collection's own order, a search's best match first, else newest." }, "required": false, "description": "The order: `newest`, `price-ascending` or `price-descending`. Absent: a collection's own order, a search's best match first, else newest.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24, "description": "Maximum number of products to return. Server cap: 100." }, "required": false, "description": "Maximum number of products to return. Server cap: 100.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Products to skip, for paging through the whole catalog (e.g. a sitemap)." }, "required": false, "description": "Products to skip, for paging through the whole catalog (e.g. a sitemap).", "name": "offset", "in": "query" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProductList" } }, "count": { "type": "integer", "description": "Number of items in `data`" }, "total": { "type": "integer", "description": "Number of products in the whole listing, across its pages" } }, "required": [ "success", "data", "count", "total" ] } } } } } } }, "/store/search": { "get": { "tags": [ "Store API" ], "summary": "Search store products", "description": "The products a shopper's words find, with the list endpoint's gates, filters, paging and sort; without a `sort`, products whose name holds every word come first. Its own path, so a server without search answers 404 rather than the whole catalog.", "operationId": "searchStoreProducts", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Only this collection's products (by handle), in the merchant's order. An unknown handle lists nothing.", "example": "best-sellers" }, "required": false, "description": "Only this collection's products (by handle), in the merchant's order. An unknown handle lists nothing.", "name": "collection", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "When true, only products priced below their compare-at price." }, "required": false, "description": "When true, only products priced below their compare-at price.", "name": "onSale", "in": "query" }, { "schema": { "type": "string", "description": "Filter by category ID." }, "required": false, "description": "Filter by category ID.", "name": "categoryId", "in": "query" }, { "schema": { "type": "string", "enum": [ "newest", "price-ascending", "price-descending" ], "description": "The order: `newest`, `price-ascending` or `price-descending`. Absent: a collection's own order, a search's best match first, else newest." }, "required": false, "description": "The order: `newest`, `price-ascending` or `price-descending`. Absent: a collection's own order, a search's best match first, else newest.", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24, "description": "Maximum number of products to return. Server cap: 100." }, "required": false, "description": "Maximum number of products to return. Server cap: 100.", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Products to skip, for paging through the whole catalog (e.g. a sitemap)." }, "required": false, "description": "Products to skip, for paging through the whole catalog (e.g. a sitemap).", "name": "offset", "in": "query" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "What the shopper typed. Every word must be in the product's name — the catalog's or the requested language's — or its tags; case is ignored for Latin letters.", "example": "robe coton" }, "required": true, "description": "What the shopper typed. Every word must be in the product's name — the catalog's or the requested language's — or its tags; case is ignored for Latin letters.", "name": "q", "in": "query" } ], "responses": { "200": { "description": "The products found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoreProductList" } }, "count": { "type": "integer", "description": "Number of items in `data`" }, "total": { "type": "integer", "description": "Number of products in the whole listing, across its pages" } }, "required": [ "success", "data", "count", "total" ] } } } } } } }, "/store/products/{handle}": { "get": { "tags": [ "Store API" ], "summary": "Get store product", "description": "Get a single product by its URL handle. Same visibility filters as the list endpoint. Returns parsed `variantOptions`, `tags`, joined `category`, active `variants`, all `images`, and `offers` — the active Buy X Get Y promotions currently applicable to this product.", "operationId": "getStoreProduct", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "samsung-galaxy-a54" }, "required": true, "name": "handle", "in": "path" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "Product details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreProductDetail" } }, "required": [ "success", "data" ] } } } } } } }, "/store/landing-pages/{slug}": { "get": { "tags": [ "Store API" ], "summary": "Get published landing page", "description": "Get a published landing page by its public slug: the ordered image stack, spacing settings, the linked product in its full store-product shape (variants, offers, inventory) in the requested language (`?locale=`), so the storefront order form works unmodified, and the page's own document for the requesting `?theme=`. Store-hidden products (`showInStore=false`) still render here — the landing page is their sales channel; the catalog list and the product's own page stay hidden. Draft/archived/unknown slugs return 404; with `?preview=1` a draft answers too. Each successful GET increments the page's view counter (non-unique in v1), except a preview.", "operationId": "getStoreLandingPage", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "lp-9f3a2b1c" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" }, { "schema": { "type": "string", "pattern": "^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$", "description": "The requesting theme's key (`defineTheme({ key })`): the page's own document for that theme comes with it.", "example": "theme-00" }, "required": false, "description": "The requesting theme's key (`defineTheme({ key })`): the page's own document for that theme comes with it.", "name": "theme", "in": "query" }, { "schema": { "type": "string", "enum": [ "1" ], "description": "`1` for an editor's preview: a draft page answers too, and no visit is counted. Never sent for a shopper's page.", "example": "1" }, "required": false, "description": "`1` for an editor's preview: a draft page answers too, and no visit is counted. Never sent for a shopper's page.", "name": "preview", "in": "query" } ], "responses": { "200": { "description": "Published landing page with its product", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreLandingPage" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Landing page not found, draft, or archived", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/pages/{slug}": { "get": { "tags": [ "Store API" ], "summary": "Get a published store page", "description": "Get a Terms/Privacy/Refund/Shipping/custom page by its public slug, in the requested language (`?locale=`, else the store's primary). Falls back to the primary, then to whichever locale exists, only when the requested language has no translation for this page; the actual locale served is in the response's `locale` field. Draft or unknown slugs return 404 — never a soft 200 with empty content.", "operationId": "getStorePage", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "example": "refund-policy" }, "required": true, "name": "slug", "in": "path" }, { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "The resolved page, already-sanitised HTML — render with set:html, never re-sanitise", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePagePublic" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Page not found, or exists only as a draft", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/page-documents/{surface}": { "get": { "tags": [ "Store API" ], "summary": "Get the store's saved page document", "description": "The store's saved composition for one theme and surface (a page such as `home` or `product`, an area such as `area:header`, or one landing page's `lp:`), written by Wocart Cloud's editor and read verbatim. `data` is `null` when the store has never saved one, or when the saved row is not a document for this surface: the theme then renders its own default. A store that has none is a normal answer, so it is a 200, not a 404.", "operationId": "getStorePageDocument", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._:-]{0,63}$", "example": "home" }, "required": true, "name": "surface", "in": "path" }, { "schema": { "type": "string", "pattern": "^(?=.{1,64}$)[a-z][a-z0-9]*(-[a-z0-9]+)*$", "description": "The requesting theme's key (`defineTheme({ key })`): its document for the surface. Without it, the most recently saved document for the surface, whichever theme wrote it.", "example": "theme-00" }, "required": false, "description": "The requesting theme's key (`defineTheme({ key })`): its document for the surface. Without it, the most recently saved document for the surface, whichever theme wrote it.", "name": "theme", "in": "query" } ], "responses": { "200": { "description": "The saved document, or null when there is none", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/PageDocument" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "The surface name is not a valid surface key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/orders/{id}/tracking": { "get": { "tags": [ "Store API" ], "summary": "Get an order's tracking destination", "description": "Which Meta pixel this order belongs to, and which browser event the thank-you page should fire for it.\n\nThe thank-you page cannot work this out for itself: it knows the order id and nothing about which landing page the shopper came from, and landing-page attribution is best-effort — an unknown, draft or archived slug leaves the order unattributed. A browser deciding independently would fire at a pixel the Conversions API never mirrors to, and Meta deduplicates per pixel, so that produces two conversions in two ad accounts instead of one.\n\nReturns the decision, not the configuration. `event` is null when no browser event should fire — either tracking is off, or the merchant's conversion fires further down the funnel (phone confirmation, delivery) from the server only.\n\nDeliberately narrow: nothing about the order itself is returned, and never an access token.", "operationId": "getStoreOrderTracking", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Order UUID", "example": "ord_abc123" }, "required": true, "description": "Order UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The order's tracking destination", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreOrderTracking" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/orders/status": { "post": { "tags": [ "Store API" ], "summary": "Find where a shopper's order is", "description": "The order's number and the phone it was placed with prove it is the shopper's, as for a review; a wrong number and a wrong phone both answer 404 ORDER_NOT_FOUND. Attempts are limited per order and per shopper (ORDER_LOOKUP_RATE_LIMITED, with `windowSeconds`). The answer is what a shopper may know — the step it is at, its lines and total, and the carrier's tracking number once shipped — never the address, the notes or the merchant's own statuses. A POST, so the phone never sits in a URL or a log.", "operationId": "getShopperOrderStatus", "security": [ { "StoreAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderNumber": { "type": "string", "pattern": "^ORD-\\d{8}-\\d+$/i", "description": "The customer-facing order number, as on the thank-you page and the SMS", "example": "ORD-20261016-1234" }, "phone": { "type": "string", "minLength": 6, "maxLength": 32, "description": "The phone the order was placed with, however it is typed", "example": "0551 23 45 67" } }, "required": [ "orderNumber", "phone" ] } } } }, "responses": { "200": { "description": "The order's status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShopperOrderStatus" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No order has this number and phone", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/categories": { "get": { "tags": [ "Store API" ], "summary": "List store categories", "description": "Get product categories ordered by position.", "operationId": "listStoreCategories", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "responses": { "200": { "description": "List of categories", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "cat_123" }, "name": { "type": "string", "example": "Electronics" }, "slug": { "type": "string", "example": "electronics", "description": "Lowercase letters, numbers and hyphens; auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ], "example": "Electronic products" }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID for nested hierarchies; null for top-level groups", "example": null }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The group's image, from its Media Key" } ] }, "metaTitle": { "type": [ "string", "null" ], "description": "SEO page title (max 60 chars)", "example": "Electronics | Wocart" }, "metaDescription": { "type": [ "string", "null" ], "description": "SEO description (max 160 chars)", "example": "Phones, laptops and accessories" }, "metaKeywords": { "type": [ "string", "null" ], "description": "Comma-separated SEO keywords", "example": "electronics, gadgets" }, "position": { "type": "integer", "minimum": 0, "example": 0, "description": "Display order; lower values come first" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "parentId", "image", "metaTitle", "metaDescription", "metaKeywords", "position", "createdAt", "updatedAt" ] } }, "count": { "type": "integer", "description": "Number of items in `data`" } }, "required": [ "success", "data", "count" ] } } } } } } }, "/store/shipping-rates": { "get": { "tags": [ "Store API" ], "summary": "Get shipping rates", "description": "Per-wilaya shipping rates for the order form. Returns wilayas that have a rule in the default shipping profile; absent wilayas should be treated as unknown/unsupported.", "operationId": "getShippingRates", "security": [ { "StoreAuth": [] } ], "responses": { "200": { "description": "Shipping rates keyed by wilaya ID (as string)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "home": { "type": "number", "description": "Home delivery price (DZD)", "example": 400 }, "stopDesk": { "type": "number", "description": "Stop-desk / post-office pickup price (DZD)", "example": 350 } }, "required": [ "home", "stopDesk" ] } } }, "required": [ "success", "data" ] } } } } } } }, "/store/communes/{wilayaId}": { "get": { "tags": [ "Store API" ], "summary": "List communes for a wilaya", "description": "Get all communes for a given wilaya. Use the returned `id` as `communeId` when submitting an order.", "operationId": "listStoreCommunes", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Wilaya number (1–58).", "example": 16 }, "required": true, "description": "Wilaya number (1–58).", "name": "wilayaId", "in": "path" } ], "responses": { "200": { "description": "List of communes for the wilaya", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Commune ID — use as `communeId` in POST /store/orders. Format is not UUID.", "example": "c-16-001" }, "name": { "type": "string", "example": "Bab El Oued" }, "nameAr": { "type": "string", "example": "باب الوادي" } }, "required": [ "id", "name", "nameAr" ] } }, "count": { "type": "integer", "description": "Number of items in `data`" } }, "required": [ "success", "data", "count" ] } } } }, "400": { "description": "Invalid wilaya ID — must be 1–58 (VALUE_OUT_OF_RANGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/orders": { "post": { "tags": [ "Store API" ], "summary": "Create store order", "description": "Submit a customer order from the public storefront. Finds or creates the customer by phone number.\n\n**Basket (`items`):** send `items` to order several products in one go — up to 20 distinct lines, each up to 100 units. Lines with the same product AND variant are merged and their quantities summed. When `items` is absent the flat `productId`/`quantity` fields are used, so existing integrations are unaffected.\n\n**Pricing is server-authoritative.** `pricePerUnit` is accepted for UI continuity and never trusted; every line is priced from the catalog row.\n\n**All or nothing.** If any line cannot be satisfied — insufficient stock, missing SKU — the whole order is refused and nothing is written.\n\n**Delivery fee** is resolved per basket: a product's own shipping profile overrides the store default, a commune-level override beats the wilaya rule, and a basket spanning two profiles pays the highest applicable rate. Delivery is refused (not silently free) when any product cannot be shipped to the destination.\n\n**Offer selection:** send `offerId` to explicitly select the tier the customer chose. It is honoured only if it independently qualifies — reached, and able to give its benefit; otherwise the server picks the highest threshold that qualifies. Trigger quantity counts a product across all its lines, so two variants of one shirt are two shirts.\n\n**Buy X Get Y (`discountType: \"free\"`):** the reward product is appended as a `$0` line item. A reward the stock cannot cover makes its offer not qualify: the product falls to its next offer and the order still succeeds. Reward lines never trigger further offers.\n\n**Coupon (`couponCode`):** applied after offers, to the paid lines in its scope that no offer applied to; its discount is shared across those lines, so `price` is net of it, and a free-delivery coupon makes `deliveryFee` 0. A code that does not apply refuses the whole order with COUPON_NOT_APPLICABLE (`reason`, with `shortBy` or `startsAt` when there is one) — the order is never placed without it. Its uses are counted by the database as the order is inserted, so two orders cannot take the last one.\n\n**Free Shipping (`discountType: \"free_shipping\"`):** the delivery fee is overridden to 0 — reflected in both `deliveryFee` and `total`. This applies only when the basket holds a **single distinct product**; in a multi-product basket free delivery is earned by the store's basket threshold instead, so one cheap promotional item cannot ship an expensive basket for free.\n\n**One checkout, one order (`checkoutKey`):** a UUID the shopper's browser stamps on the checkout attempt. Sent again — a double click, a resubmitted form, a retried request — it answers with the order already placed, as it answered the first time, without placing another; for another phone it is refused with CHECKOUT_KEY_IN_USE. Without it, every request places an order.\n\n**Multi-unit variant orders:** when different variants are selected per unit, send `variantSelections` — one entry per unit. Identical variants are grouped into a single line and inventory deducts per-variant.", "operationId": "createStoreOrder", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 35, "description": "The language the shopper checked out in (BCP 47, e.g. `fr`): recorded on the order, and the language its customer messages are written in, when the store publishes it; the primary language otherwise. The `Content-Language` response header names the one recorded.", "example": "fr" }, "required": false, "description": "The language the shopper checked out in (BCP 47, e.g. `fr`): recorded on the order, and the language its customer messages are written in, when the store publishes it; the primary language otherwise. The `Content-Language` response header names the one recorded.", "name": "locale", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "productName": { "type": "string", "minLength": 1, "maxLength": 200 }, "variantId": { "type": "string", "minLength": 1 }, "variantLabel": { "type": "string", "maxLength": 100 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "offerId": { "type": [ "string", "null" ] }, "variantSelections": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1 }, "variantLabel": { "type": "string" } }, "required": [ "variantId" ] }, "maxItems": 100 }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "productName": { "type": "string", "minLength": 1, "maxLength": 200 }, "variantId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "variantLabel": { "type": [ "string", "null" ], "maxLength": 100 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "pricePerUnit": { "type": "number", "minimum": 0 }, "offerId": { "type": [ "string", "null" ] } }, "required": [ "productId", "productName", "quantity" ] }, "minItems": 1, "maxItems": 20 }, "customerName": { "type": "string", "minLength": 2, "maxLength": 100 }, "phone": { "type": "string", "pattern": "^0[567]\\d{8}$" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": "string", "minLength": 1 }, "address": { "type": "string", "maxLength": 300 }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "default": "home" }, "pricePerUnit": { "type": "number", "minimum": 0 }, "notes": { "type": "string", "maxLength": 500 }, "email": { "type": [ "string", "null" ], "maxLength": 254 }, "customFieldResponses": { "anyOf": [ { "type": "string" }, { "type": "array", "items": {} }, { "type": "null" } ] }, "fbc": { "type": "string" }, "fbp": { "type": "string" }, "otpToken": { "type": [ "string", "null" ], "minLength": 10, "maxLength": 1024 }, "turnstileToken": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048 }, "landingPageSlug": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "couponCode": { "type": [ "string", "null" ], "maxLength": 64 }, "checkoutKey": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "customerName", "phone", "wilayaId", "communeId" ] } } } }, "responses": { "201": { "description": "Order created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "orderId": { "type": "string" }, "orderNumber": { "type": "string", "example": "ORD-20260327-0042" }, "price": { "type": "number" }, "deliveryFee": { "type": "number" }, "total": { "type": "number", "description": "price + deliveryFee, offers and coupon applied" }, "couponDiscount": { "type": "integer", "description": "What the coupon took off; 0 without one" } }, "required": [ "orderId", "orderNumber", "price", "deliveryFee", "total", "couponDiscount" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Referenced SKU/product record missing (REQUIRED_FIELD_MISSING)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The checkout key already placed an order for another phone (CHECKOUT_KEY_IN_USE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Insufficient stock (INSUFFICIENT_STOCK), missing SKU before accepting orders, or a coupon that does not apply (COUPON_NOT_APPLICABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/cart/validate": { "post": { "tags": [ "Store API" ], "summary": "Re-price and check a basket — the quote of an order", "description": "Read-only. Returns what the catalog says about a basket right now, so the cart can show the truth before the shopper commits. Nothing is written and no stock is reserved.\n\nThe body names what is being ordered in the order's own fields: a basket (`items[]`), or one product — `productId`, `productName`, `quantity`, optionally `variantId`, a variant per unit (`variantSelections`) and an offer tier (`offerId`). A product page asks with exactly what its form will post, and the lines are built the same way the order builds them.\n\nEvery line comes back with its CURRENT catalog price, the units still available (`maxQuantity`, null when the product is not stock-tracked), and a `blocker` when it cannot be ordered as requested:\n\n- `missing`: the product no longer exists\n- `unlisted`: it is no longer on sale (draft, hidden or removed)\n- `out_of_stock`: fewer units are available than requested\n\nBlocked lines are excluded from `subtotal`, from offer evaluation and from the free-delivery calculation, so the basket never promises something checkout would refuse.\n\n`freeDelivery` is subtotal-based and therefore answerable before the shopper types an address: use `remaining` for a \"spend X more\" prompt.\n\nSend `destination` (`wilayaId`, optional `communeId`, `deliveryType`) and the answer carries `delivery`: the fee and the total the order would charge there, from the same quote the order itself uses — product shipping profiles, commune overrides, the free-delivery threshold and free-shipping offers included. `available: false` (fee and total null) means the store does not deliver there, and an order to it is refused with DELIVERY_NOT_AVAILABLE. Without `destination`, there is no `delivery` field.\n\nSend `couponCode` and the answer carries `coupon`: applied (with the `discount` taken off the lines, each line's share in its `discount`, and whether it makes delivery free) or refused with the `reason` the order would be refused for. Send `phone` once the shopper has typed it, so a coupon for selected customers, or one use per customer, is judged before the order. Without `couponCode`, `coupon` is null.\n\nProduct names and variant labels come from the catalog, in the language `?locale=` asks for (the store's primary when it does not publish that language), announced in `Content-Language`. The order itself records the catalog's names in the store's primary language.", "operationId": "validateStoreCart", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 35, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "example": "fr" }, "required": false, "description": "The language to serve merchant text in (BCP 47, e.g. `fr`). Served when the store publishes it, the primary language otherwise; the `Content-Language` response header names the one served. Untranslated fields fall back to the primary one by one.", "name": "locale", "in": "query" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "productName": { "type": "string", "minLength": 1, "maxLength": 200 }, "variantId": { "type": "string", "minLength": 1 }, "variantLabel": { "type": "string", "maxLength": 100 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "offerId": { "type": [ "string", "null" ] }, "variantSelections": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "variantId": { "type": "string", "minLength": 1 }, "variantLabel": { "type": "string" } }, "required": [ "variantId" ] }, "maxItems": 100 }, "items": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "productName": { "type": "string", "minLength": 1, "maxLength": 200 }, "variantId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "variantLabel": { "type": [ "string", "null" ], "maxLength": 100 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "pricePerUnit": { "type": "number", "minimum": 0 }, "offerId": { "type": [ "string", "null" ] } }, "required": [ "productId", "productName", "quantity" ] }, "minItems": 1, "maxItems": 20 }, "pricePerUnit": { "type": "number", "minimum": 0 }, "destination": { "type": "object", "properties": { "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": "string", "minLength": 1, "maxLength": 200 }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "default": "home" } }, "required": [ "wilayaId" ] }, "couponCode": { "type": [ "string", "null" ], "maxLength": 64 }, "phone": { "type": "string", "maxLength": 32 } } } } } }, "responses": { "200": { "description": "Basket priced and checked against the live catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "variantId": { "type": [ "string", "null" ] }, "variantLabel": { "type": [ "string", "null" ] }, "productName": { "type": "string" }, "quantity": { "type": "integer" }, "unitPrice": { "type": "number", "description": "The catalog's unit price" }, "lineTotal": { "type": "number", "description": "What the line costs, offers and coupon applied" }, "offerId": { "type": [ "string", "null" ], "description": "The offer applied to the line; null when none" }, "offerName": { "type": [ "string", "null" ], "description": "That offer's name, in the shopper's language" }, "discount": { "type": "integer", "description": "The line's share of the coupon's discount, already out of `lineTotal`" }, "maxQuantity": { "type": [ "integer", "null" ] }, "blocker": { "type": [ "string", "null" ], "enum": [ "missing", "unlisted", "out_of_stock", null ] } }, "required": [ "productId", "variantId", "variantLabel", "productName", "quantity", "unitPrice", "lineTotal", "offerId", "offerName", "discount", "maxQuantity", "blocker" ] } }, "subtotal": { "type": "number" }, "rewards": { "type": "array", "items": { "type": "object", "properties": { "offerId": { "type": "string" }, "offerName": { "type": [ "string", "null" ], "description": "The offer's name, in the shopper's language" }, "productId": { "type": [ "string", "null" ] }, "productName": { "type": [ "string", "null" ] }, "variantId": { "type": [ "string", "null" ], "description": "The variant given, when the product has variants" }, "variantLabel": { "type": [ "string", "null" ] }, "quantity": { "type": "integer" } }, "required": [ "offerId", "offerName", "productId", "productName", "variantId", "variantLabel", "quantity" ], "description": "A gift the basket earns, as it will be given: its product and variant, free" } }, "freeDelivery": { "type": "object", "properties": { "fromOffer": { "type": "boolean" }, "threshold": { "type": [ "integer", "null" ], "description": "The store's free-delivery amount; null when it has none" }, "qualified": { "type": "boolean", "description": "Delivery is free for this basket, wherever it goes: by an offer, the coupon or the store's amount" }, "remaining": { "type": "number", "description": "How much more to spend for the store's free delivery; 0 once delivery is free, or with no amount" }, "by": { "type": [ "string", "null" ], "enum": [ "offer", "coupon", "threshold", null ], "description": "Why delivery is free; null when it is not" } }, "required": [ "fromOffer", "threshold", "qualified", "remaining", "by" ] }, "coupon": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "applied": { "type": "boolean", "enum": [ true ] }, "discount": { "type": "integer" }, "freeShipping": { "type": "boolean" } }, "required": [ "code", "applied", "discount", "freeShipping" ] }, { "type": "object", "properties": { "code": { "type": "string" }, "applied": { "type": "boolean", "enum": [ false ] }, "reason": { "type": "string", "enum": [ "not_found", "not_started", "expired", "used_up", "identify_first", "not_eligible", "already_used", "no_eligible_products", "offer_applied", "below_minimum_subtotal", "below_minimum_quantity", "delivery_already_free" ] }, "shortBy": { "type": "integer", "description": "Dinars, or items, the covered lines still lack" }, "startsAt": { "type": "string" } }, "required": [ "code", "applied", "reason" ] }, { "type": "null" } ], "description": "The code's outcome; null without `couponCode`." }, "delivery": { "type": "object", "properties": { "available": { "type": "boolean" }, "fee": { "type": [ "number", "null" ] }, "total": { "type": [ "number", "null" ] } }, "required": [ "available", "fee", "total" ], "description": "Present only when the request names a destination." } }, "required": [ "lines", "subtotal", "rewards", "freeDelivery", "coupon" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Basket exceeds its bounds (VALUE_OUT_OF_RANGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/reviews": { "get": { "tags": [ "Store API" ], "summary": "List a product's approved reviews", "description": "A product's approved reviews, newest first, with their photos and voice note. Empty when the store turned reviews off.", "operationId": "listStoreReviews", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Product ID to fetch reviews for." }, "required": true, "description": "Product ID to fetch reviews for.", "name": "productId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "One page of approved reviews", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "customerName": { "type": "string" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": [ "string", "null" ] }, "body": { "type": "string" }, "createdAt": { "type": "string" }, "verified": { "type": "boolean", "description": "Rests on an order that reached its customer (a verified purchase)" }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "audio" ] }, "url": { "type": "string", "format": "uri", "description": "A photo at 1600 px at most, or the voice note as recorded" }, "thumbUrl": { "type": [ "string", "null" ], "format": "uri", "description": "A photo's small version for lists" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "durationMs": { "type": [ "integer", "null" ], "description": "A voice note's length" } }, "required": [ "id", "kind", "url", "thumbUrl", "width", "height", "durationMs" ] } } }, "required": [ "id", "customerName", "rating", "title", "body", "createdAt", "verified", "media" ] } }, "count": { "type": "integer" }, "total": { "type": "integer", "description": "Approved reviews of this product" } }, "required": [ "success", "data", "count", "total" ] } } } } } }, "post": { "tags": [ "Store API" ], "summary": "Submit a review", "description": "Proves the purchase again, records the review and answers at once. Its photos and voice note are prepared afterwards (resized, location data removed); `visibility` says whether it is public now or after the store checks it — the store's choice.\n\nOne review per product of an order (**409 ORDER_ALREADY_REVIEWED**). Without `phone` (storefronts on `@wocart/storefront` 1.5) a review is text only, still for a delivered order — deprecated.", "operationId": "submitStoreReview", "security": [ { "StoreAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderNumber": { "type": "string", "pattern": "^ORD-\\d{8}-\\d+$/i", "description": "The customer-facing order number, as on the thank-you page and the SMS", "example": "ORD-20261016-1234" }, "phone": { "type": [ "string", "null" ], "minLength": 6, "maxLength": 32, "description": "The phone the order was placed with. Storefronts on @wocart/storefront 1.5 send none: their reviews are text only, still for a delivered order. Deprecated without it.", "example": "0551 23 45 67" }, "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": [ "string", "null" ], "maxLength": 150 }, "body": { "type": "string", "maxLength": 2000, "default": "", "description": "At least 10 characters, unless a voice note says it" }, "grant": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "The upload grant from /store/reviews/eligibility, when files are sent" }, "uploads": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "maxItems": 8, "description": "Upload IDs from /store/reviews/uploads" } }, "required": [ "orderNumber", "productId", "rating" ] } } } }, "responses": { "201": { "description": "Review received", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "visibility": { "type": "string", "enum": [ "published", "after_review" ] } }, "required": [ "id", "visibility" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No order with this number and phone (ORDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "This product was already reviewed from this order (ORDER_ALREADY_REVIEWED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Not delivered yet, not a product of the order, reviews off, too many attempts, or a file problem (REVIEW_* / PRODUCT_NOT_IN_ORDER)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/reviews/eligibility": { "post": { "tags": [ "Store API" ], "summary": "Find an order to review", "description": "Proves the purchase with the order number **and the phone it was placed with**, and answers what can be reviewed: the order's products the shopper kept (each once), and — when the store takes photos or a voice note — what may be attached and an **upload grant** for `PUT /store/reviews/uploads` (30 minutes).\n\nA wrong number and a wrong phone both answer **404 ORDER_NOT_FOUND**. An order not delivered yet answers **422 REVIEW_ORDER_NOT_DELIVERED**. Attempts are limited per order number (**422 REVIEW_RATE_LIMITED**). Turnstile is not asked here: it guards checkout.", "operationId": "checkStoreReviewEligibility", "security": [ { "StoreAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderNumber": { "type": "string", "pattern": "^ORD-\\d{8}-\\d+$/i", "description": "The customer-facing order number, as on the thank-you page and the SMS", "example": "ORD-20261016-1234" }, "phone": { "type": "string", "minLength": 6, "maxLength": 32, "description": "The phone the order was placed with, however it is typed", "example": "0551 23 45 67" }, "turnstileToken": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "Ignored: Turnstile guards checkout, not reviews — the order number and phone are the proof, and attempts are limited per order" } }, "required": [ "orderNumber", "phone" ] } } } }, "responses": { "200": { "description": "The order can be reviewed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "orderNumber": { "type": "string" }, "customerName": { "type": "string" }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "name": { "type": "string" }, "image": { "allOf": [ { "$ref": "#/components/schemas/MediaImage" }, { "description": "The product's first image" } ] }, "imageSrc": { "type": [ "string", "null" ], "description": "The same image's URL, for storefront SDKs that read it (@wocart/storefront ≤ 2.0)" }, "reviewed": { "type": "boolean", "description": "Already reviewed from this order" } }, "required": [ "productId", "name", "image", "imageSrc", "reviewed" ] } }, "media": { "type": [ "object", "null" ], "properties": { "maxPhotos": { "type": "integer", "minimum": 0 }, "voiceMaxSeconds": { "type": [ "integer", "null" ], "description": "The longest voice note, in seconds (30, 60, 90, 120); null: no voice note" }, "grant": { "type": "string", "description": "Send as the X-Review-Grant header of each upload, and as `grant` on submit" }, "expiresAt": { "type": "integer", "description": "Unix seconds" } }, "required": [ "maxPhotos", "voiceMaxSeconds", "grant", "expiresAt" ], "description": "null: text only" } }, "required": [ "orderNumber", "customerName", "products", "media" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No order with this number and phone (ORDER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Not delivered yet, reviews off, or too many attempts (REVIEW_ORDER_NOT_DELIVERED / REVIEWS_DISABLED / REVIEW_RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/reviews/uploads": { "put": { "tags": [ "Store API" ], "summary": "Send a review photo or voice note", "description": "The file itself as the request body, with the grant from `/store/reviews/eligibility` in the **X-Review-Grant** header (and, for a voice note, its length as the recorder reported it in **X-Media-Duration-Ms** — shown only when the file does not say). Send each file as soon as it is picked; submit the review with the returned `uploadId`s.\n\nIts kind is read from the file's bytes: a photo (JPEG, PNG, WebP, GIF — shrink it in the browser first, 8 MB at most) or a voice note (WebM, Ogg, M4A, MP3 — as long as the store allows).", "operationId": "uploadStoreReviewMedia", "security": [ { "StoreAuth": [] } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Received; kept until the review is submitted (a day at most)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "uploadId": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "audio" ] }, "bytes": { "type": "integer" } }, "required": [ "uploadId", "kind", "bytes" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No file, an empty one, too large, or not a photo or voice note (REQUIRED_FIELD_MISSING / FILE_TOO_LARGE / INVALID_FILE_TYPE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Grant missing or expired, or a kind or number of files the store does not take (REVIEW_UPLOAD_GRANT_INVALID / REVIEW_MEDIA_LIMIT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/abandoned": { "post": { "tags": [ "Storefront" ], "summary": "Track an abandoned checkout", "description": "Called silently by the storefront as the customer types contact details. Upserts the abandoned-checkout record keyed by sessionId and captures Meta attribution (_fbc/_fbp) plus client IP/User-Agent for CAPI recovery events.", "operationId": "upsertAbandonedOrder", "security": [ { "StoreAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "sessionId": { "type": "string", "format": "uuid" }, "customerName": { "type": "string", "minLength": 2, "maxLength": 100 }, "phone": { "type": "string", "minLength": 9, "maxLength": 20, "pattern": "^[0-9+\\s-]+$" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": "string" }, "wilayaName": { "type": "string", "maxLength": 100 }, "communeName": { "type": "string", "maxLength": 100 }, "productId": { "type": "string", "maxLength": 200 }, "productName": { "type": "string", "maxLength": 200 }, "variantId": { "type": "string", "maxLength": 200 }, "variantLabel": { "type": "string", "maxLength": 200 }, "price": { "type": "number", "exclusiveMinimum": 0 }, "items": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1, "maxLength": 200 }, "productName": { "type": "string", "minLength": 1, "maxLength": 200 }, "variantId": { "type": [ "string", "null" ], "maxLength": 200 }, "variantLabel": { "type": [ "string", "null" ], "maxLength": 200 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 100 }, "unitPrice": { "type": "number", "minimum": 0 } }, "required": [ "productId", "productName", "quantity", "unitPrice" ] }, "minItems": 1, "maxItems": 20 }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "fbc": { "type": "string", "maxLength": 500 }, "fbp": { "type": "string", "maxLength": 500 } }, "required": [ "sessionId", "customerName", "phone" ] } } } }, "responses": { "200": { "description": "Record stored (new or updated)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "id": { "type": "string", "description": "Abandoned order record ID" } }, "required": [ "success", "id" ] } } } } } } }, "/store/abandoned/{sessionId}/convert": { "patch": { "tags": [ "Storefront" ], "summary": "Mark abandoned checkout as converted", "description": "Links a completed order back to the original abandoned session (recovery attribution). Intentionally returns 200 even if the session is unknown — conversion tracking is fire-and-forget and must never break checkout.", "operationId": "markAbandonedOrderConverted", "security": [ { "StoreAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Storefront session ID from the upsert call" }, "required": true, "description": "Storefront session ID from the upsert call", "name": "sessionId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1 }, "orderNumber": { "type": "string", "minLength": 1 } }, "required": [ "orderId", "orderNumber" ] } } } }, "responses": { "200": { "description": "Conversion recorded (fire-and-forget)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/store/otp/send": { "post": { "tags": [ "Storefront" ], "summary": "Send a WhatsApp OTP to the customer's phone", "description": "Sends a 6-digit code over WhatsApp via dzverify. Requires the store's OTP verification to be enabled. When dzverify cannot serve the send (balance exhausted, provider down), returns status 'unavailable' with a server-signed bypassToken — checkout proceeds unverified (fail-open; orders are never blocked by quota). Rate limits return 429 with the wait window.", "operationId": "sendStoreOtp", "security": [ { "StoreAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 6, "maxLength": 20, "example": "0551234567", "description": "Algerian mobile; normalized server-side to E.164" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "OTP sent (or unavailable with a bypass token)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sent" ] }, "requestId": { "type": "string" }, "expiresAt": { "type": "number", "description": "Unix milliseconds" }, "maxAttempts": { "type": "number" } }, "required": [ "status", "requestId", "expiresAt", "maxAttempts" ] }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unavailable" ] }, "reason": { "type": "string" }, "bypassToken": { "type": "string" } }, "required": [ "status", "reason", "bypassToken" ] } ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Phone cannot be normalized to E.164 (INVALID_PHONE_FORMAT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "OTP verification not enabled for this store (OTP_NOT_ENABLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited — retry after context.windowSeconds (OTP_RATE_LIMITED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "dzverify rejected the request for a non-fail-open reason", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/store/otp/verify": { "post": { "tags": [ "Storefront" ], "summary": "Verify the WhatsApp OTP code", "description": "Verifies the code the customer typed. On success returns a signed otpToken (15-min TTL, bound to the phone) that the storefront submits with the order. Wrong-but-retryable codes return 422 with attemptsRemaining. Terminal states (expired, attempts exhausted, already verified) return 409 — send a new OTP.", "operationId": "verifyStoreOtp", "security": [ { "StoreAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 6, "maxLength": 20 }, "requestId": { "type": "string", "minLength": 1, "maxLength": 64 }, "code": { "type": "string", "pattern": "^\\d{6}$" } }, "required": [ "phone", "requestId", "code" ] } } } }, "responses": { "200": { "description": "Verified — otpToken returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified" ] }, "otpToken": { "type": "string" } }, "required": [ "status", "otpToken" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Phone cannot be normalized to E.164 (INVALID_PHONE_FORMAT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Unknown requestId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Terminal: expired / failed / already verified — send a new OTP", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Wrong code, retryable — context.attemptsRemaining", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "dzverify transport failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/media/uploads": { "post": { "tags": [ "Media" ], "summary": "Ticket an image upload", "description": "Records a pending upload and answers how the browser sends the file (`send`). Then call POST /api/media/uploads/{id}/complete; the image's `key` is attachable once complete.", "operationId": "requestMediaUpload", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "folder": { "type": "string", "enum": [ "products", "landing" ], "description": "`products` (gallery, categories, the logo, rich text, apps) or `landing` (landing-page stacks)", "example": "products" }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif" ], "example": "image/webp" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 10485760, "description": "The file's exact size", "example": 245760 } }, "required": [ "folder", "contentType", "bytes" ] } } } }, "responses": { "201": { "description": "The ticket", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/UploadTicket" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "A folder, type or size not allowed (VALIDATION_FAILED / INVALID_FILE_TYPE / FILE_TOO_LARGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The store's media is not configured, or its host is unavailable (MEDIA_NOT_CONFIGURED / MEDIA_HOST_UNAVAILABLE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/media/uploads/{id}/content": { "put": { "tags": [ "Media" ], "summary": "Send a relayed upload's bytes", "description": "For a `relay` ticket only: the file's bytes, no larger than the ticket's size, of its type. Then complete the upload.", "operationId": "receiveMediaUpload", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The ticket's `mediaId`" }, "required": true, "description": "The ticket's `mediaId`", "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "204": { "description": "Stored; complete the upload" }, "400": { "description": "Larger than the ticket, or not its type (FILE_TOO_LARGE / INVALID_FILE_TYPE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such upload, or its ticket expired (MEDIA_UPLOAD_UNKNOWN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/media/uploads/{id}/complete": { "post": { "tags": [ "Media" ], "summary": "Complete an image upload", "description": "Confirms the file with the store's host. Completing twice answers the same image.", "operationId": "completeMediaUpload", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "The ticket's `mediaId`" }, "required": true, "description": "The ticket's `mediaId`", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "hostRef": { "type": [ "string", "null" ], "description": "For a `form` ticket: the `fileId` the host answered" }, "width": { "type": [ "integer", "null" ], "minimum": 1, "description": "The image's width as the browser measured it" }, "height": { "type": [ "integer", "null" ], "minimum": 1, "description": "The image's height as the browser measured it" } } } } } }, "responses": { "200": { "description": "The image, ready", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MediaImage" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such upload (MEDIA_UPLOAD_UNKNOWN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The host does not hold the file yet (MEDIA_UPLOAD_MISSING)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The host holds another file than the ticket's; it was deleted, start again (MEDIA_UPLOAD_MISMATCH)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/activity-logs": { "get": { "tags": [ "Activity Logs" ], "summary": "List activity logs", "description": "Get audit trail of all system actions (admin only)", "operationId": "listActivityLogs", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter by actor (user) ID" }, "required": false, "description": "Filter by actor (user) ID", "name": "actorId", "in": "query" }, { "schema": { "type": "string", "description": "Filter by entity type. Valid values: `order`, `customer`, `customer_group`, `customer_tag`, `driver`, `product`, `stock`, `user`, `review`" }, "required": false, "description": "Filter by entity type. Valid values: `order`, `customer`, `customer_group`, `customer_tag`, `driver`, `product`, `stock`, `user`, `review`", "name": "entityType", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50, "description": "Maximum number of logs to return" }, "required": false, "description": "Maximum number of logs to return", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Number of logs to skip" }, "required": false, "description": "Number of logs to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of activity logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityLog" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } }, "403": { "description": "Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/activity-logs/users/{userId}": { "get": { "tags": [ "Activity Logs" ], "summary": "Get user activity logs", "description": "Get activity logs for a specific user (admin only)", "operationId": "getUserActivityLogs", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID to filter logs for" }, "required": true, "description": "User ID to filter logs for", "name": "userId", "in": "path" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 30, "description": "Maximum number of logs to return" }, "required": false, "description": "Maximum number of logs to return", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Number of logs to skip" }, "required": false, "description": "Number of logs to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "User activity logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ActivityLog" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } }, "403": { "description": "Admin access required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/events": { "get": { "tags": [ "Events" ], "summary": "Read the Event Log", "description": "The store's Business Events. With `after`, oldest first from that Sequence: follow the log by passing each page's `nextCursor` as the next `after`. Otherwise newest first, paged back with `before`.", "operationId": "listEvents", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": [ "integer", "null" ], "minimum": 0, "description": "Read forward, oldest first, from after this Sequence — how an integration follows the log (`after=0` reads from the start)." }, "required": false, "description": "Read forward, oldest first, from after this Sequence — how an integration follows the log (`after=0` reads from the start).", "name": "after", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "description": "Read back, newest first, from before this Sequence." }, "required": false, "description": "Read back, newest first, from before this Sequence.", "name": "before", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "At most this many events (1–100)" }, "required": false, "description": "At most this many events (1–100)", "name": "limit", "in": "query" }, { "schema": { "type": "string", "description": "Only these Event Types, comma-separated, each named exactly (`order.confirmed`), by subject (`order.*`), or `*`.", "example": "order.created,shipment.*" }, "required": false, "description": "Only these Event Types, comma-separated, each named exactly (`order.confirmed`), by subject (`order.*`), or `*`.", "name": "type", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Only the events of this order" }, "required": false, "description": "Only the events of this order", "name": "orderId", "in": "query" } ], "responses": { "200": { "description": "A page of the Event Log", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessEvent" } }, "count": { "type": "integer", "description": "Number of items returned" }, "nextCursor": { "type": [ "integer", "null" ], "description": "The Sequence to pass as `after` (or `before`, the way this page was read) for the next page; null on the last page" } }, "required": [ "success", "data", "count", "nextCursor" ] } } } }, "400": { "description": "A type that is not an Event Type or pattern, or `after` and `before` together (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/events/{id}": { "get": { "tags": [ "Events" ], "summary": "Get a Business Event", "operationId": "getEvent", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The Business Event", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BusinessEvent" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No Business Event with this id (BUSINESS_EVENT_NOT_FOUND); events are kept 90 days", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-consumers": { "get": { "tags": [ "Events" ], "summary": "List Consumers", "description": "Who receives the store's Business Events, with how many Deliveries are on their way and how many were given up on.", "operationId": "listEventConsumers", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Every Consumer, oldest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventConsumer" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Events" ], "summary": "Add a webhook", "description": "A webhook Consumer: an endpoint of the merchant's own that receives the Business Events it subscribes to, recorded from now on, each POSTed as JSON and signed per the Standard Webhooks specification. Its Signing Secret is in this answer and never shown in full again.", "operationId": "createEventConsumer", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "webhook" ], "description": "The kind of Consumer: `webhook`, an endpoint of the merchant's own" }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What the merchant calls it", "example": "Order system" }, "url": { "type": "string", "description": "Where Deliveries are POSTed: a public https URL", "example": "https://erp.example.dz/hooks/wocart" }, "subscription": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "The Event Types it receives, each named exactly, by subject (`order.*`), or `*`", "example": [ "order.created", "shipment.*" ] } }, "required": [ "kind", "name", "url", "subscription" ] } } } }, "responses": { "201": { "description": "The webhook, and its Signing Secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookCreated" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Not a webhook this store can send to: a public https URL, a name, one or more Event Types (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The store already has 10 webhooks (EVENT_CONSUMER_LIMIT_REACHED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-consumers/{id}": { "get": { "tags": [ "Events" ], "summary": "Get a Consumer", "operationId": "getEventConsumer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The Consumer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EventConsumer" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No Consumer with this id (EVENT_CONSUMER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Events" ], "summary": "Change a Consumer", "description": "Start or stop any Consumer; rename a webhook, point it at another URL or change what it subscribes to. Stopped, a Consumer receives nothing: its waiting Deliveries are skipped and new events are not delivered to it. Started again, it receives what is recorded from then on and its failing streak is cleared; replay what it missed. A new Subscription applies to what is recorded from then on; a new URL starts without a failing streak.", "operationId": "updateEventConsumer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Start (true) or stop (false) delivering to it" }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "What the merchant calls it", "example": "Order system" }, "url": { "type": "string", "description": "Where Deliveries are POSTed: a public https URL", "example": "https://erp.example.dz/hooks/wocart" }, "subscription": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "description": "The Event Types it receives, each named exactly, by subject (`order.*`), or `*`", "example": [ "order.created", "shipment.*" ] } } } } } }, "responses": { "200": { "description": "The Consumer as it now stands", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EventConsumer" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Not a change this API makes (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No Consumer with this id (EVENT_CONSUMER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A built-in Consumer is kept by its App: only start or stop it (EVENT_CONSUMER_BUILT_IN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Events" ], "summary": "Delete a webhook", "description": "The webhook goes with its Deliveries and their Attempts. The Business Events stay in the Event Log.", "operationId": "deleteEventConsumer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "404": { "description": "No Consumer with this id (EVENT_CONSUMER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "A built-in Consumer is kept by its App: stop it instead (EVENT_CONSUMER_BUILT_IN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-consumers/{id}/rotate-secret": { "post": { "tags": [ "Events" ], "summary": "Rotate a webhook's Signing Secret", "description": "A new Signing Secret, in this answer and never shown in full again. For a day, Deliveries carry a signature by each secret, so the endpoint switches to the new one without refusing any; after that, only the new one signs.", "operationId": "rotateEventConsumerSecret", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The new Signing Secret", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/SigningSecret" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No Consumer with this id (EVENT_CONSUMER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Only a webhook has a Signing Secret (EVENT_CONSUMER_BUILT_IN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-consumers/{id}/test": { "post": { "tags": [ "Events" ], "summary": "Send a Test Event to a webhook", "description": "POSTs an example of an Event Type to the webhook now, signed like any Delivery, and answers what the endpoint did. A Test Event has Sequence 0 and an id starting `test_`; it is recorded in no Event Log and has no Delivery. It is sent to a stopped webhook too.", "operationId": "testEventConsumer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "order.created", "order.updated", "order.confirmed", "order.unreachable", "order.preparing", "order.ready", "order.cancelled", "order.line_returned", "order.deleted", "shipment.handed_off", "shipment.out_for_delivery", "shipment.delivery_failed", "shipment.delivered", "shipment.return_started", "shipment.returned", "shipment.cancelled", "shipment.voided" ], "description": "Which Event Type's example to send; `order.created` when not said" } } } } } }, "responses": { "200": { "description": "What the endpoint did with it", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/WebhookTest" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Not an Event Type (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No Consumer with this id (EVENT_CONSUMER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Only a webhook is sent Test Events (EVENT_CONSUMER_BUILT_IN)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-consumers/{id}/replay": { "post": { "tags": [ "Events" ], "summary": "Replay Business Events to a Consumer", "description": "Deliver the Business Events of a Sequence range again to this Consumer — those it subscribes to now. Settled Deliveries become due with their Attempts started over (their history is kept); events it never received, recorded while it was stopped or before it existed, get a Delivery. One already on its way is left alone. No Business Event is recorded again.", "operationId": "replayEventConsumer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "fromSequence": { "type": "integer", "minimum": 1, "description": "The first Business Event to deliver again, by Sequence" }, "toSequence": { "type": "integer", "minimum": 1, "description": "The last one; at most 1000 Sequences after the first" } }, "required": [ "fromSequence", "toSequence" ] } } } }, "responses": { "202": { "description": "Accepted: the Deliveries are due and the store delivers them", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Redelivery" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Not a range of 1 to 1000 Sequences (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No Consumer with this id (EVENT_CONSUMER_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The Consumer is stopped; start it first (EVENT_CONSUMER_DISABLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-deliveries": { "get": { "tags": [ "Events" ], "summary": "List Deliveries", "description": "A Consumer's Deliveries, newest event first and paged with `before`, or every Delivery of one Business Event. `state=dead` lists those given up on.", "operationId": "listEventDeliveries", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "A Consumer's Deliveries, newest event first" }, "required": false, "description": "A Consumer's Deliveries, newest event first", "name": "consumerId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "description": "Every Delivery of one Business Event" }, "required": false, "description": "Every Delivery of one Business Event", "name": "eventId", "in": "query" }, { "schema": { "type": "string", "enum": [ "due", "delivered", "skipped", "dead" ], "description": "Only Deliveries in this state — `dead` for those given up on" }, "required": false, "description": "Only Deliveries in this state — `dead` for those given up on", "name": "state", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "description": "Read on from before this event Sequence: the previous page's `nextCursor`" }, "required": false, "description": "Read on from before this event Sequence: the previous page's `nextCursor`", "name": "before", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "description": "At most this many (1–100)" }, "required": false, "description": "At most this many (1–100)", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "A page of Deliveries", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventDelivery" } }, "count": { "type": "integer", "description": "Number of items returned" }, "nextCursor": { "type": [ "integer", "null" ], "description": "Pass as `before` for the next page; null on the last page" } }, "required": [ "success", "data", "count", "nextCursor" ] } } } }, "400": { "description": "Neither a Consumer nor a Business Event named, or both (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-deliveries/{id}": { "get": { "tags": [ "Events" ], "summary": "Get a Delivery", "description": "The Delivery with every Attempt it took and what the Consumer answered.", "operationId": "getEventDelivery", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The Delivery", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/EventDeliveryDetail" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No Delivery with this id (EVENT_DELIVERY_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/event-deliveries/{id}/retry": { "post": { "tags": [ "Events" ], "summary": "Retry a Delivery", "description": "Make a settled Delivery — dead, skipped or delivered — due again now, its Attempts started over; its history is kept.", "operationId": "retryEventDelivery", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "202": { "description": "Accepted: the Delivery is due and the store delivers it", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Redelivery" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No Delivery with this id (EVENT_DELIVERY_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Already on its way (EVENT_DELIVERY_ALREADY_DUE), or its Consumer is stopped (EVENT_CONSUMER_DISABLED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orders": { "get": { "tags": [ "Orders" ], "summary": "List orders", "operationId": "listOrders", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Where the order stands overall — its processing, then its shipment's delivery: one stage, or several separated by commas (new,unreachable)" }, "required": false, "description": "Where the order stands overall — its processing, then its shipment's delivery: one stage, or several separated by commas (new,unreachable)", "name": "stage", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "true: only orders whose delivery needs the merchant (an unknown handoff, a parcel the carrier cancelled or flagged); false: only the others" }, "required": false, "description": "true: only orders whose delivery needs the merchant (an unknown handoff, a parcel the carrier cancelled or flagged); false: only the others", "name": "attention", "in": "query" }, { "schema": { "type": "string", "enum": [ "carrier", "driver" ], "description": "Only orders handed to a carrier, or to the store's driver" }, "required": false, "description": "Only orders handed to a carrier, or to the store's driver", "name": "kind", "in": "query" }, { "schema": { "type": "string", "enum": [ "exclude", "only", "include" ], "default": "exclude", "description": "Archived orders: left out (default), the only ones listed, or listed with the rest" }, "required": false, "description": "Archived orders: left out (default), the only ones listed, or listed with the rest", "name": "archived", "in": "query" }, { "schema": { "type": "string", "enum": [ "online", "offline" ] }, "required": false, "name": "orderType", "in": "query" }, { "schema": { "type": [ "integer", "null" ] }, "required": false, "name": "wilayaId", "in": "query" }, { "schema": { "type": "string", "description": "Order number, customer name, phone, or the parcel's tracking number" }, "required": false, "description": "Order number, customer name, phone, or the parcel's tracking number", "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 300, "description": "Keyset pagination cursor (takes precedence over offset). Pass the (createdAt, id) cursor of the last row of the current page to fetch the next page; deep pages stay index-served unlike offset." }, "required": false, "description": "Keyset pagination cursor (takes precedence over offset). Pass the (createdAt, id) cursor of the last row of the current page to fetch the next page; deep pages stay index-served unlike offset.", "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Orders, newest first (archived ones left out unless `archived` says otherwise), with their delivery at a glance: the shipment's kind, carrier or driver and tracking number, the stage and whether it needs the merchant. `nextCursor` fetches the next page (null on the last one).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItem" } }, "count": { "type": "integer", "description": "Number of items returned" }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass as `cursor` for the next page; null on the last page" } }, "required": [ "success", "data", "count", "nextCursor" ] } } } } } }, "post": { "tags": [ "Orders" ], "summary": "Create order", "description": "Creates a new order.\n\n**Auto-customer creation:** If `customerId` is not found in the customers table (e.g. walk-in / manual entry), the customer is automatically created using `customerName`, `phone`, `wilayaId`, and `address`. Pass a client-generated UUID (e.g. `crypto.randomUUID()`) as `customerId` in this case.\n\n**Inventory:** Products with `trackInventory` enabled will have their stock decremented automatically.\n\n**Delivery fee:** decided as the storefront checkout decides it (`POST /orders/delivery-quote` shows it): every product's shipping profile, the dearest winning; a commune's own price; free at the store's free-delivery amount; free by an offer for a basket of its product alone, which the order records (`deliveryOfferId`). An offline order may pass an explicit `deliveryFee`, which is then kept as typed. Where the store does not deliver, an online order is refused (422 DELIVERY_NOT_AVAILABLE).\n\n**Delivery** is chosen later, when the ready order is handed to a carrier or a driver (`POST /orders/{id}/shipment`).", "operationId": "createOrder", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "pattern": "^0[5-7]\\d{8}$" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": "string", "minLength": 1 }, "city": { "type": [ "string", "null" ] }, "customerEmail": { "type": [ "string", "null" ], "maxLength": 254, "format": "email" }, "address": { "type": [ "string", "null" ] }, "price": { "type": "number", "exclusiveMinimum": 0 }, "notes": { "type": [ "string", "null" ] }, "orderType": { "type": "string", "enum": [ "online", "offline" ], "default": "online" }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "default": "home" }, "deliveryFee": { "type": "number", "minimum": 0 }, "products": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "productName": { "type": "string" }, "variantId": { "type": [ "string", "null" ], "minLength": 1 }, "variantLabel": { "type": [ "string", "null" ] }, "quantity": { "type": "integer", "exclusiveMinimum": 0 }, "pricePerUnit": { "type": "number", "exclusiveMinimum": 0 }, "lineTotal": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "productId", "productName", "quantity", "pricePerUnit", "lineTotal" ] }, "minItems": 1 } }, "required": [ "customerId", "customerName", "phone", "wilayaId", "communeId", "price", "products" ] } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/OrderCreatedData" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/api/orders/delivery-quote": { "post": { "tags": [ "Orders" ], "summary": "Quote an order's delivery", "description": "What delivery would cost on an order being entered, decided as the storefront checkout decides it — the fee `POST /orders` charges when no fee is typed — and why it is free when it is: `{ by: \"threshold\", threshold }` (the store's free-delivery amount) or `{ by: \"offer\", offerId, offerName }`. `{ available: false }` where the store does not deliver. A read: nothing is written.", "operationId": "quoteOrderDelivery", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "variantId": { "type": [ "string", "null" ], "minLength": 1 }, "quantity": { "type": "integer", "exclusiveMinimum": 0 } }, "required": [ "productId", "quantity" ] }, "minItems": 1, "maxItems": 100 }, "subtotal": { "type": "number", "minimum": 0 }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": [ "string", "null" ], "minLength": 1 }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] } }, "required": [ "lines", "subtotal", "wilayaId", "deliveryType" ] } } } }, "responses": { "200": { "description": "The quote", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "anyOf": [ { "type": "object", "properties": { "available": { "type": "boolean", "enum": [ false ] } }, "required": [ "available" ] }, { "type": "object", "properties": { "available": { "type": "boolean", "enum": [ true ] }, "rate": { "type": "number", "description": "The store's rate there, before anything makes it free" }, "fee": { "type": "number", "description": "What the order charges for delivery" }, "free": { "anyOf": [ { "type": "object", "properties": { "by": { "type": "string", "enum": [ "threshold" ] }, "threshold": { "type": "number" } }, "required": [ "by", "threshold" ] }, { "type": "object", "properties": { "by": { "type": "string", "enum": [ "offer" ] }, "offerId": { "type": "string" }, "offerName": { "type": [ "string", "null" ] } }, "required": [ "by", "offerId", "offerName" ] }, { "type": "null" } ] } }, "required": [ "available", "rate", "fee", "free" ] } ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/orders/{id}": { "get": { "tags": [ "Orders" ], "summary": "Get order", "description": "Returns full order detail including products and status history.", "operationId": "getOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Order details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Order" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Orders" ], "summary": "Update order", "description": "Partially edits an order's customer and destination fields: `customerName`, `phone`, `customerEmail`, `wilayaId`, `communeId`, `city`, `address`, `deliveryType`, `notes`. All fields optional — omitted fields stay untouched.\n\nThis is how a merchant records an address collected over the phone when the checkout hid the address field.\n\nThe linked customer record is updated in the same operation with the fields this request changes (name, phone, wilaya/commune, address) — an order and its customer never disagree on contact details. If the corrected phone already belongs to a different customer record, the order is re-pointed to that record instead of overwriting its phone. `customerEmail` is stored on the order only.\n\n`customerEmail` / `address`: an empty (or whitespace) value clears the field; a value is stored trimmed (email also lower-cased), matching POST /orders.\n\n**Rejected with 409 ORDER_HAS_SHIPMENT** when the order has a shipment and the edit touches what the parcel carries (name, phone, wilaya, commune, city, address, delivery type) — change those through PATCH /shipments/{id}; the email and notes still change. **Rejected with 422** for a legacy order that already has a tracking number, or one in a terminal state (returned/cancelled). **Rejected with 400 MISSING_ADDRESS** when the edit would leave a home delivery without a street address. Wilaya/commune are checked against the reference tables (400 MISSING_WILAYA_COMMUNE).", "operationId": "updateOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerName": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "pattern": "^0[5-7]\\d{8}$" }, "customerEmail": { "type": [ "string", "null" ], "maxLength": 254, "format": "email" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": "string", "minLength": 1 }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ] }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Order updated — returns the refreshed order detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Order" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "400": { "description": "Validation error — bad phone/email, home delivery left without an address (MISSING_ADDRESS), or unknown wilaya/commune (MISSING_WILAYA_COMMUNE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The order has a shipment and the edit touches what the parcel carries (ORDER_HAS_SHIPMENT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The order is cancelled (INVALID_STATUS_TRANSITION)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Orders" ], "summary": "Delete order", "description": "Permanently deletes an order never handed to delivery, in any status: the goods still out of stock go back, the customer's order count and spend are undone, and its lines, history, reviews and logs go with it. **409 ORDER_HAS_SHIPMENT** once it has a shipment — its parcel, the driver's cash and the carrier's records rest on it; archive it when its delivery has ended (`POST /orders/{id}/archive`), or void the shipment first. The database refuses it too.", "operationId": "deleteOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Order deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "409": { "description": "The order has a shipment (ORDER_HAS_SHIPMENT), or it changed meanwhile (ORDER_CHANGED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orders/{id}/removal": { "get": { "tags": [ "Orders" ], "summary": "What clearing an order away does", "description": "Whether the order can be deleted (never handed to delivery) or archived (finished: cancelled, or its shipment delivered, returned or cancelled), and what deleting it would undo — read before asking the merchant to confirm.", "operationId": "getOrderRemoval", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The order's removal options", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/OrderRemoval" } }, "required": [ "success", "data" ] } } } } } } }, "/api/orders/{id}/archive": { "post": { "tags": [ "Orders" ], "summary": "Archive order", "description": "Takes a finished order — cancelled, or its shipment delivered, returned or cancelled — out of the working lists and their counts. It still counts in sales and the customer's history, and can be restored. Archiving it again keeps the first date. **409 ORDER_NOT_FINISHED** before then.", "operationId": "archiveOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "archivedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "archivedAt" ] } }, "required": [ "success", "data" ] } } } }, "409": { "description": "The order is not finished yet (ORDER_NOT_FINISHED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orders/{id}/unarchive": { "post": { "tags": [ "Orders" ], "summary": "Restore an archived order", "description": "Brings an archived order back to the working lists.", "operationId": "unarchiveOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Restored", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "archivedAt": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "archivedAt" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/orders/{id}/status": { "patch": { "tags": [ "Orders" ], "summary": "Update order status", "description": "Moves the order's processing and appends a record to its status history (`cod-shared/orders/lifecycle.ts`):\n\n- `new` → `confirmed` | `unreachable` | `cancelled`\n- `confirmed` → `preparing` | `ready` | `unreachable` | `cancelled`\n- `unreachable` → `confirmed` | `cancelled` (the customer did not answer; call again)\n- `preparing` → `ready` | `cancelled`\n- `ready` → `cancelled`; a ready order is handed off with `POST /orders/{id}/shipment`\n- `cancelled` is final\n\nAny other move returns `400 INVALID_STATUS_TRANSITION` with the allowed next statuses.\n\n**Side effects:** `confirmed` starts the Meta CAPI confirmed stage (when the store tracks it); `cancelled` restores inventory for products with `trackInventory` and rolls back the customer's spend. Delivery and return are the shipment's milestones, with their own effects.\n\nEach effect applies exactly once, even when the same change is sent twice at once. **An order with a shipment has no status change** (409 ORDER_HAS_SHIPMENT): its delivery is the shipment's, and cancelling it means voiding the shipment first.", "operationId": "updateOrderStatus", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready", "cancelled" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "400": { "description": "Unknown status value (VALIDATION_FAILED) or transition not allowed by the flow guard (INVALID_STATUS_TRANSITION with currentStatus/targetStatus/allowedTransitions context)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The order has a shipment (ORDER_HAS_SHIPMENT), or it changed meanwhile (ORDER_CHANGED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orders/{id}/products/{productLineId}/return": { "patch": { "tags": [ "Orders" ], "summary": "Record a product line return", "description": "Records how many units on a single order line the customer refused at the door. Used for the Algerian \"open the box at delivery\" workflow where a customer may accept part of an order and return the rest.\n\nThe server computes the line status (\"fulfilled\" | \"partially_returned\" | \"returned\") from returnedQuantity vs. the line quantity, restocks the delta (repeated calls are idempotent), and logs an ORDER_RETURNED stock movement.\n\nOnly on a **delivered** order: the customer opened the parcel at the door and kept part of it. Before delivery nothing has been refused (422 ORDER_NOT_DELIVERED) — a parcel refused whole comes back as a return, and its stock with it.\n\nRefused (422) once the order is cancelled or its parcel came back — every remaining unit is already back in stock. Both are checked in the same write, so neither can happen in between.", "operationId": "returnOrderProduct", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Order product line ID" }, "required": true, "description": "Order product line ID", "name": "productLineId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "returnedQuantity": { "type": "integer", "minimum": 0 } }, "required": [ "returnedQuantity" ] } } } }, "responses": { "200": { "description": "Return recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ReturnProductData" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "400": { "description": "Validation error (VALIDATION_FAILED / VALUE_OUT_OF_RANGE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order or order line not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The line changed meanwhile (ORDER_CHANGED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The order is cancelled or its parcel came back (INVALID_STATUS_TRANSITION)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/orders/{id}/shipment": { "post": { "tags": [ "Shipments" ], "summary": "Hand an order to a carrier or to a driver", "description": "`kind: \"carrier\"` hands the order to a delivery company (needs delivery:dispatch); `kind: \"driver\"` gives it to the store's driver (needs orders:assign).\n\n**Carrier.** Only a **ready** order with no shipment can be handed off. The shipment is reserved before the carrier is called, so a second dispatch of the same order is refused (409 ORDER_HAS_SHIPMENT) and never reaches the carrier.\n\nWhat the carrier's answer proves decides the outcome:\n- **accepted** — the carrier created the parcel. When the company auto-validates and the carrier needs a separate validation, it is validated too; a refused validation is reported in `validationError` and kept in the shipment's history.\n- **refused** — the carrier refused it, the credentials failed, it was throttled, or it could not be reached: nothing was created and the order is ready again.\n- **unknown** — the carrier may have created it (a timeout, a server error). It is never sent again automatically: resolve it with `POST /shipments/{id}/resolve`.\n\n**Driver.** The store's own driver has no carrier to call: the shipment is accepted at once, and the driver's fee for the order's wilaya (0 where none is set) is frozen on it. The driver is not a carrier and has no stop desks: the shipment is always home delivery to the order's street address — an order whose customer chose a stop desk keeps that choice and its price, and the driver brings it to the door (`deliveryType: \"stop_desk\"` is refused). Only a **ready** order with no shipment and a street address (400 MISSING_ADDRESS), and a driver who is not inactive. The driver's progress is then reported with `POST /shipments/{id}/events`.", "operationId": "handOffOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "carrier" ] }, "companyId": { "type": "string", "minLength": 1, "description": "The delivery company to hand the order to" }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "description": "Ship as home or stop-desk delivery instead of what the customer asked for — for a carrier with no desk in the wilaya, or the reverse. The cash to collect does not change." }, "stationCode": { "type": "string", "minLength": 1, "description": "The stop desk, when shipping to one" }, "weight": { "type": "number", "exclusiveMinimum": 0, "description": "Parcel weight in kg; otherwise the sum of its variants' weights" }, "fragile": { "type": "boolean" }, "remarks": { "type": "string", "maxLength": 500, "description": "For the courier; otherwise the order's notes" } }, "required": [ "kind", "companyId" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "driver" ] }, "driverId": { "type": "string", "minLength": 1, "description": "The store's driver to give the order to" }, "deliveryType": { "type": "string", "enum": [ "home" ], "description": "Always home: the store's own driver brings the parcel to the customer's street address, even when the customer chose a stop desk (the order keeps that choice and its price). A stop desk is refused." } }, "required": [ "kind", "driverId" ] } ] } } } }, "responses": { "201": { "description": "The carrier has the parcel, or the driver has the order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/HandoffResult" } }, "required": [ "success", "data" ] } } } }, "202": { "description": "The carrier's outcome is unknown; resolve it", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/HandoffResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "The order's address, wilaya/commune or desk is incomplete, or the company is not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Missing the permission this kind of handoff needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Order, delivery company or driver not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The order already has a shipment, or the company's carrier settings are incomplete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The order is not ready, the driver is inactive, the company does not offer the delivery type, the value is over the carrier's ceiling, or the carrier refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling; nothing was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached; nothing was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/bulk": { "post": { "tags": [ "Shipments" ], "summary": "Hand many orders to a carrier", "description": "The same handoff as `POST /orders/{id}/shipment`, for up to 100 orders and one company, with one result per order. The carrier's bulk creation is used when it has one.\n\nOnly a **ready** order with no shipment can be handed off. The shipment is reserved before the carrier is called, so a second dispatch of the same order is refused (409 ORDER_HAS_SHIPMENT) and never reaches the carrier.\n\nWhat the carrier's answer proves decides the outcome:\n- **accepted** — the carrier created the parcel. When the company auto-validates and the carrier needs a separate validation, it is validated too; a refused validation is reported in `validationError` and kept in the shipment's history.\n- **refused** — the carrier refused it, the credentials failed, it was throttled, or it could not be reached: nothing was created and the order is ready again.\n- **unknown** — the carrier may have created it (a timeout, a server error). It is never sent again automatically: resolve it with `POST /shipments/{id}/resolve`.", "operationId": "handOffOrders", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "companyId": { "type": "string", "minLength": 1 }, "orderIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 }, "deliveryType": { "type": "string", "enum": [ "home", "stop_desk" ], "description": "Ship as home or stop-desk delivery instead of what the customer asked for — for a carrier with no desk in the wilaya, or the reverse. The cash to collect does not change." } }, "required": [ "companyId", "orderIds" ] } } } }, "responses": { "200": { "description": "One result per order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BulkHandoffData" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Delivery company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/driver-bulk": { "post": { "tags": [ "Shipments" ], "summary": "Give many orders to a driver", "description": "The same handoff as `POST /orders/{id}/shipment` with `kind: \"driver\"`, for up to 100 orders and one driver, with one result per order: `accepted` or `refused` (never `unknown`).\n\nThe store's own driver has no carrier to call: the shipment is accepted at once, and the driver's fee for the order's wilaya (0 where none is set) is frozen on it. The driver is not a carrier and has no stop desks: the shipment is always home delivery to the order's street address — an order whose customer chose a stop desk keeps that choice and its price, and the driver brings it to the door (`deliveryType: \"stop_desk\"` is refused). Only a **ready** order with no shipment and a street address (400 MISSING_ADDRESS), and a driver who is not inactive. The driver's progress is then reported with `POST /shipments/{id}/events`.", "operationId": "handOffOrdersToDriver", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "driverId": { "type": "string", "minLength": 1 }, "orderIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 }, "deliveryType": { "type": "string", "enum": [ "home" ], "description": "Always home: the store's own driver brings the parcel to the customer's street address, even when the customer chose a stop desk (the order keeps that choice and its price). A stop desk is refused." } }, "required": [ "driverId", "orderIds" ] } } } }, "responses": { "200": { "description": "One result per order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/BulkHandoffData" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Driver not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The driver is inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}": { "get": { "tags": [ "Shipments" ], "summary": "Get a shipment", "description": "The shipment with its full history (carrier statuses as reported, and what Wocart concluded from them) and the actions available now.", "operationId": "getShipment", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The shipment", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Shipment" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Shipments" ], "summary": "Edit a parcel at the carrier", "description": "Changes the customer's details, the destination, the cash to collect, the weight or fragility — at the carrier first, then in Wocart: the order's contact and destination (with its customer, like an order edit) and the shipment's cash, weight and fragility. Only before the parcel leaves (and, at a carrier that validates separately, before validation). A new destination needs both `wilayaId` and `communeId`.", "operationId": "updateShipment", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerName": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 9 }, "address": { "type": "string" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "communeId": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "minimum": 0, "description": "The cash to collect" }, "weight": { "type": "number", "exclusiveMinimum": 0 }, "fragile": { "type": "boolean" }, "remarks": { "type": "string", "maxLength": 500 } } } } } }, "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Nothing to change, an incomplete destination, or a home delivery left without an address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/resolve": { "post": { "tags": [ "Shipments" ], "summary": "Resolve a handoff whose outcome is unknown", "description": "- `lookup` — ask the carrier for a parcel with this order's number (carriers that support it). `not_found` leaves the shipment unresolved.\n- `attach` — the parcel was found at the carrier: record its tracking number.\n- `release` — the carrier has no parcel: the shipment is removed and the order is ready to hand off again.", "operationId": "resolveShipmentHandoff", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "lookup" ] } }, "required": [ "action" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "attach" ] }, "trackingNumber": { "type": "string", "minLength": 1 }, "carrierParcelId": { "type": "string", "minLength": 1, "description": "The carrier's own parcel id, when it differs from the tracking number (ZR Express)" } }, "required": [ "action", "trackingNumber" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "release" ] } }, "required": [ "action" ] } ] } } } }, "responses": { "200": { "description": "How it was resolved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/HandoffResolution" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The handoff is not unknown, or the parcel already belongs to another shipment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier cannot look parcels up by order number", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/validate": { "post": { "tags": [ "Shipments" ], "summary": "Validate a parcel at the carrier", "description": "For carriers that hold a created parcel until it is validated (EcoTrack, NOEST). After validation it can no longer be edited or cancelled.", "operationId": "validateShipment", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "requestPickup": { "type": "boolean", "description": "Ask the carrier to collect the parcel (EcoTrack)" } } } } } }, "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/void": { "post": { "tags": [ "Shipments" ], "summary": "Void a shipment", "description": "Undo a shipment that never reached the customer, so the order can be handed off again: a carrier parcel is cancelled at the carrier first (unless the carrier already cancelled it); a driver's order is taken back from the driver. Refused once it is out for delivery. A carrier shipment needs delivery:dispatch, a driver's orders:assign.", "operationId": "voidShipment", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Voided; the order is ready to hand off again", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "orderId": { "type": "string" } }, "required": [ "orderId" ] } }, "required": [ "success", "data" ] } } } }, "403": { "description": "Missing the permission this shipment's kind needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/remarks": { "get": { "tags": [ "Shipments" ], "summary": "Read the parcel's remarks at the carrier", "operationId": "listShipmentRemarks", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Remarks from the merchant and the courier", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CarrierRemark" } } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "post": { "tags": [ "Shipments" ], "summary": "Add a remark for the courier", "operationId": "addShipmentRemark", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 500, "example": "Appeler le client 30 minutes avant" } }, "required": [ "content" ] } } } }, "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/label": { "get": { "tags": [ "Shipments" ], "summary": "The parcel's label", "description": "Fetched from the carrier for the merchant: carrier labels sit behind the company's credentials or an expiring link.", "operationId": "getShipmentLabel", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The label", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/ask-return": { "post": { "tags": [ "Shipments" ], "summary": "Ask the carrier to return the parcel", "description": "A request the courier may decline; it is noted in the history and changes nothing until the carrier reports the return.", "operationId": "askShipmentReturn", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/request-new-attempt": { "post": { "tags": [ "Shipments" ], "summary": "Ask the carrier to try delivering again", "description": "After a failed attempt (NOEST). Noted in the history.", "operationId": "requestShipmentNewAttempt", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/confirm-return": { "post": { "tags": [ "Shipments" ], "summary": "Confirm at the carrier that the return reached you", "description": "EcoTrack's return confirmation, then the return is recorded: the goods go back in stock and the customer's spend is rolled back.", "operationId": "confirmShipmentReturn", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/sync": { "post": { "tags": [ "Shipments" ], "summary": "Read the carrier's history now", "description": "Records every status the carrier reports that the shipment does not have yet; a status already recorded (by webhook or an earlier sync) is not recorded twice.", "operationId": "syncShipment", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipments/{id}/events": { "post": { "tags": [ "Shipments" ], "summary": "Report what happened", "description": "What the merchant saw. On a driver's shipment: the driver's progress (`out_for_delivery`, `failed_attempt`, `delivered`, `returned`) — needs orders:assign. On a carrier shipment only `returned`: the goods are back with the merchant (the carrier alone can say a parcel was delivered) — needs delivery:dispatch.", "operationId": "reportShipmentEvent", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "out_for_delivery", "failed_attempt", "delivered", "returned" ], "description": "A driver's progress; on a carrier shipment only `returned` (the goods are back with the merchant)" }, "reason": { "type": "string", "maxLength": 500, "description": "Why — a refusal, no answer…" }, "occurredAt": { "type": "string", "format": "date-time", "description": "When it happened, if not now" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "The shipment after the operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShipmentOperationResult" } }, "required": [ "success", "data" ] } } } }, "403": { "description": "Missing the permission this shipment's kind needs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Shipment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Not now: the parcel is not accepted yet, already validated, on its way, or closed (the shipment's `actions` say what is possible)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier does not support this, or refused it", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached, or did not make its answer clear", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/users": { "get": { "tags": [ "Users" ], "summary": "List users", "description": "Returns a paginated list of team members. Each user includes their `scopes` array (`[\"*\"]` for admins).", "operationId": "listUsers", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "admin", "staff" ] }, "required": false, "name": "role", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "inactive" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Search by name or email" }, "required": false, "description": "Search by name or email", "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Users" ], "summary": "Create user", "description": "Creates a new team member. **Admin only.**\n\n**What happens:**\n1. A user account is created in the database with a secure temporary password\n2. The password is hashed using scrypt (same algorithm as better-auth)\n3. An API key is generated for programmatic access\n4. Initial permission scopes are assigned (if role is staff)\n5. A best-effort invite email is sent via Sendili when the store's email config exists and is enabled — the outcome is reported in `emailSent`/`emailError`, and creation never fails because of the email\n\n**Authentication:**\n- The new user receives a temporary password (returned once in this response, and included in the invite email when it sends)\n- They can sign in using email + temporary password\n- They should change their password on first login for security\n\n**Note:** `scopes` are ignored for `admin` users — admins always have `[\"*\"]`. The API key is never emailed.", "operationId": "createUser", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "staff@example.com" }, "name": { "type": "string", "minLength": 1, "example": "Ahmed Benali" }, "role": { "type": "string", "enum": [ "admin", "staff" ], "default": "staff", "description": "Defaults to `staff`." }, "scopes": { "type": "array", "items": { "type": "string" }, "default": [], "description": "Initial permission scopes. Ignored if role is `admin`.", "example": [ "orders:read", "customers:read" ] }, "language": { "type": "string", "enum": [ "ar", "en" ], "description": "Language for the invite email. Defaults to `en`.", "example": "ar" } }, "required": [ "email", "name" ] } } } }, "responses": { "201": { "description": "User created. **The `apiKey` and `tempPassword` fields are returned only in this response — store them immediately.**", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" }, "apiKey": { "type": "string", "description": "The raw API key for the new user — returned once at creation. Use POST /{id}/api-key/rotate to issue a new key.", "example": "cod_a1b2c3d4e5f6..." }, "tempPassword": { "type": "string", "description": "Temporary password for the new user — returned once at creation. Share this with the user securely. They should change it on first login.", "example": "a1b2c3d4e5f6g7h8i9j0" }, "emailSent": { "type": "boolean", "description": "Whether the invite email was handed to Sendili. False when email sending is not configured or the send failed — check `emailError`.", "example": true }, "emailError": { "type": [ "string", "null" ], "description": "Stable failure code when the invite email could not be sent: out_of_credits | invalid_key | forbidden | rate_limited | validation | transient. Null when sent or simply not configured.", "example": null }, "message": { "type": "string", "example": "User created. Share the tempPassword with the user — it will not be shown again." } }, "required": [ "success", "data", "apiKey", "tempPassword", "emailSent", "emailError", "message" ] } } } }, "409": { "description": "A user with this email already exists (code: DUPLICATE_EMAIL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/users/{id}": { "get": { "tags": [ "Users" ], "summary": "Get user", "description": "Returns full user record including their `scopes` array.", "operationId": "getUser", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "User detail with scopes", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Users" ], "summary": "Update user", "description": "Partial update — only include fields you want to change. To change scopes, use `POST /{id}/scopes` and `DELETE /{id}/scopes/{scope}`. To change role only, prefer `PATCH /{id}/role`.", "operationId": "updateUser", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "admin", "staff" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } } } } }, "responses": { "200": { "description": "User updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/api/users/{id}/role": { "patch": { "tags": [ "Users" ], "summary": "Update user role", "description": "Dedicated endpoint for role-only changes. Changing to `admin` effectively grants `[\"*\"]` scope.", "operationId": "updateUserRole", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "staff" ] } }, "required": [ "role" ] } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/api/users/{id}/scopes": { "post": { "tags": [ "Users" ], "summary": "Grant scope to user", "description": "Grants a single permission scope to the user. Returns the full updated user record.", "operationId": "grantScope", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "minLength": 1, "example": "customers:read" } }, "required": [ "scope" ] } } } }, "responses": { "200": { "description": "Scope granted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Scope already granted to user (code: DUPLICATE_ENTITY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/users/{id}/scopes/{scope}": { "delete": { "tags": [ "Users" ], "summary": "Revoke scope from user", "description": "Removes a permission scope from the user. If the scope was not granted, the operation succeeds silently.", "operationId": "revokeScope", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "required": true, "description": "User ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "The scope to revoke", "example": "customers:read" }, "required": true, "description": "The scope to revoke", "name": "scope", "in": "path" } ], "responses": { "200": { "description": "Scope revoked. Returns full updated user record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/User" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/api/users/{id}/api-key/rotate": { "post": { "tags": [ "Users" ], "summary": "Rotate API key", "description": "Generates a new API key for the user, invalidating the previous one. **Admin only. The raw key is returned only once** — store it securely.", "operationId": "rotateApiKey", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "User ID", "example": "a1b2c3d4e5f6a7b8a1b2c3d4e5f6a7b8" }, "required": true, "description": "User ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "New API key issued. The raw key is shown only in this response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "The new raw API key — store it immediately, it cannot be retrieved again", "example": "cod_a1b2c3d4e5f6..." } }, "required": [ "apiKey" ] }, "message": { "type": "string", "example": "API key rotated successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/api/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": "Returns a paginated list of customers. Use `groupId` or `tagId` to filter by segment. Use `wilayaId` to filter by wilaya.", "operationId": "listCustomers", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Filter by wilaya ID (1–58)" }, "required": false, "description": "Filter by wilaya ID (1–58)", "name": "wilayaId", "in": "query" }, { "schema": { "type": "string", "description": "Search by customer name, phone or email" }, "required": false, "description": "Search by customer name, phone or email", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Filter to customers in a specific customer group" }, "required": false, "description": "Filter to customers in a specific customer group", "name": "groupId", "in": "query" }, { "schema": { "type": "string", "description": "Filter to customers with a specific tag" }, "required": false, "description": "Filter to customers with a specific tag", "name": "tagId", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50, "description": "Maximum number of results to return" }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Number of results to skip for pagination" }, "required": false, "description": "Number of results to skip for pagination", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of customers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "description": "Register a new customer profile. Resolves wilayaId/communeId to their Arabic display names automatically.", "operationId": "createCustomer", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Ahmed Benali" }, "phone": { "type": "string", "pattern": "^0[5-7]\\d{8}$", "description": "Algerian mobile number starting with 05, 06, or 07", "example": "0551234567" }, "phone2": { "type": [ "string", "null" ], "pattern": "^0[5-7]\\d{8}$", "description": "Secondary phone number (optional)" }, "email": { "type": [ "string", "null" ], "maxLength": 254, "format": "email", "description": "Email address (optional); stored lower-cased", "example": "amina@example.com" }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Official wilaya number (1–58)", "example": 16 }, "communeId": { "type": "string", "minLength": 1, "description": "Commune UUID from /api/wilayas/{id}/communes", "example": "550e8400-e29b-41d4-a716-446655440000" }, "address": { "type": "string", "example": "12 Rue Didouche Mourad" } }, "required": [ "name", "phone", "wilayaId", "communeId" ] } } } }, "responses": { "201": { "description": "Customer created. Response includes the full customer record with recentOrders (empty array for new customers).", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Customer" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Duplicate phone number - a customer with this phone already exists (code: DUPLICATE_PHONE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "description": "Returns the full customer record plus `recentOrders` (up to 10 most recent orders).", "operationId": "getCustomer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "Customer ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Customer detail including recentOrders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Customer" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Customers" ], "summary": "Update customer", "description": "Partial update — only include fields you want to change. Set `phone2`, `communeId`, or `address` to null to clear them.", "operationId": "updateCustomer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "Customer ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Ahmed Benali" }, "phone": { "type": "string", "pattern": "^0[5-7]\\d{8}$", "description": "Algerian mobile number starting with 05, 06, or 07", "example": "0551234567" }, "phone2": { "type": [ "string", "null" ], "pattern": "^0[5-7]\\d{8}$", "description": "Secondary phone. Set to null to clear it." }, "email": { "type": [ "string", "null" ], "maxLength": 254, "format": "email", "description": "Email address. Set to null or empty to clear it." }, "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Official wilaya number (1–58)", "example": 16 }, "communeId": { "type": [ "string", "null" ], "minLength": 1, "description": "Commune UUID. Set to null to clear." }, "address": { "type": [ "string", "null" ], "description": "Street address. Set to null to clear it." } } } } } }, "responses": { "200": { "description": "Customer updated. Returns the full updated customer record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Customer" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Duplicate phone number - a customer with this phone already exists (code: DUPLICATE_PHONE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer", "description": "Permanently deletes the customer. **Blocked with 422 if the customer has any orders** — remove or reassign the orders first.", "operationId": "deleteCustomer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "Customer ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Customer permanently deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Cannot delete customer with existing orders (code: CUSTOMER_HAS_ORDERS). The context includes orderCount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/customers/{id}/orders": { "get": { "tags": [ "Customers" ], "summary": "Get customer orders", "description": "Returns all orders for a customer in reverse chronological order, each with `statusHistory` included.", "operationId": "getCustomerOrders", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "Customer ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of customer orders (each includes statusHistory)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOrderSummary" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } } }, "/api/customers/{id}/groups": { "get": { "tags": [ "Customers" ], "summary": "Get customer groups", "description": "Returns all customer groups the customer belongs to, including the `assignedAt` timestamp for each membership.", "operationId": "getCustomerGroups", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "Customer ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of groups the customer belongs to", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerGroupMembership" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/customers/{id}/tags": { "get": { "tags": [ "Customers" ], "summary": "Get customer tags", "description": "Returns all tags assigned to the customer, including the `assignedAt` timestamp for each assignment.", "operationId": "getCustomerTags", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Customer ID", "example": "550e8400-e29b-41d4-a716-446655440000" }, "required": true, "description": "Customer ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of tags assigned to the customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerTagMembership" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/customer-groups": { "get": { "tags": [ "Customer Groups" ], "summary": "List customer groups", "description": "Get all customer groups with optional search filter and pagination", "operationId": "listCustomerGroups", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Search by name" }, "required": false, "description": "Search by name", "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50, "description": "Maximum number of groups to return", "example": 50 }, "required": false, "description": "Maximum number of groups to return", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Number of groups to skip", "example": 0 }, "required": false, "description": "Number of groups to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of customer groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerGroup" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Customer Groups" ], "summary": "Create customer group", "description": "Create a new customer segment group", "operationId": "createCustomerGroup", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Wholesale Customers" }, "description": { "type": [ "string", "null" ], "maxLength": 500, "example": "High volume buyers" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#6366f1", "example": "#3B82F6" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Group created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerGroup" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Duplicate group name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/customer-groups/{id}": { "get": { "tags": [ "Customer Groups" ], "summary": "Get customer group", "description": "Returns the group. Pass `?members=true` to include the full member list (each with `assignedAt` timestamp).", "operationId": "getCustomerGroup", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Set to `true` to include the `members` array in the response" }, "required": false, "description": "Set to `true` to include the `members` array in the response", "name": "members", "in": "query" } ], "responses": { "200": { "description": "Group detail. When `?members=true`, includes a `members` array of customer summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerGroup" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Customer Groups" ], "summary": "Update customer group", "description": "Partial update — only include fields you want to change. Set `description` to `null` to clear it.", "operationId": "updateCustomerGroup", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "example": "VIP Customers" }, "description": { "type": [ "string", "null" ], "maxLength": 500, "example": "Updated description" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#10B981" } } } } } }, "responses": { "200": { "description": "Group updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerGroup" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Duplicate group name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Customer Groups" ], "summary": "Delete customer group", "description": "Deletes the group and all its member associations. Customers themselves are not affected.", "operationId": "deleteCustomerGroup", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Group deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Group has members - cannot delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/customer-groups/{id}/members": { "post": { "tags": [ "Customer Groups" ], "summary": "Add member to group", "description": "Adds a customer to the group. Idempotent — silently succeeds if already a member. Increments `memberCount`.", "operationId": "addMember", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "example": "cust_123" } }, "required": [ "customerId" ] } } } }, "responses": { "200": { "description": "Member added", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/customer-groups/{id}/members/{customerId}": { "delete": { "tags": [ "Customer Groups" ], "summary": "Remove member from group", "description": "Removes a customer from the group. Idempotent — succeeds silently if not a member. Decrements `memberCount`.", "operationId": "removeMember", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Customer ID", "example": "cust_123" }, "required": true, "description": "Customer ID", "name": "customerId", "in": "path" } ], "responses": { "200": { "description": "Member removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/customer-tags": { "get": { "tags": [ "Customer Tags" ], "summary": "List customer tags", "description": "Get all customer tags with optional search filter and pagination", "operationId": "listCustomerTags", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Search by name" }, "required": false, "description": "Search by name", "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50, "description": "Maximum number of tags to return", "example": 50 }, "required": false, "description": "Maximum number of tags to return", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Number of tags to skip", "example": 0 }, "required": false, "description": "Number of tags to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of customer tags", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerTag" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Customer Tags" ], "summary": "Create customer tag", "description": "Create a new customer tag", "operationId": "createCustomerTag", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "VIP" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "default": "#64748b", "example": "#FF5733" } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Tag created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerTag" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Duplicate tag name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/customer-tags/{id}": { "get": { "tags": [ "Customer Tags" ], "summary": "Get customer tag", "description": "Returns the tag. Pass `?customers=true` to include the full list of assigned customers (each with `assignedAt` timestamp).", "operationId": "getCustomerTag", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Set to `true` to include the `customers` array in the response" }, "required": false, "description": "Set to `true` to include the `customers` array in the response", "name": "customers", "in": "query" } ], "responses": { "200": { "description": "Tag detail. When `?customers=true`, includes a `customers` array of customer summaries.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerTag" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Customer Tags" ], "summary": "Update customer tag", "description": "Partial update — only include fields you want to change.", "operationId": "updateCustomerTag", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50, "example": "VIP" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#FF5733" } } } } } }, "responses": { "200": { "description": "Tag updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CustomerTag" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Duplicate tag name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Customer Tags" ], "summary": "Delete customer tag", "description": "Deletes the tag and all its customer assignments. Customers themselves are not affected.", "operationId": "deleteCustomerTag", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Tag deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } }, "422": { "description": "Tag has assignments - cannot delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/customer-tags/{id}/assignments": { "post": { "tags": [ "Customer Tags" ], "summary": "Assign tag to customer", "description": "Assigns the tag to a customer. Idempotent — silently succeeds if already assigned. Increments `assignmentCount`.", "operationId": "assignTag", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "minLength": 1, "example": "cust_123" } }, "required": [ "customerId" ] } } } }, "responses": { "200": { "description": "Tag assigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/customer-tags/{id}/assignments/{customerId}": { "delete": { "tags": [ "Customer Tags" ], "summary": "Unassign tag from customer", "description": "Removes the tag from a customer. Idempotent — succeeds silently if not assigned. Decrements `assignmentCount`.", "operationId": "unassignTag", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Resource ID" }, "required": true, "description": "Resource ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Customer ID", "example": "cust_123" }, "required": true, "description": "Customer ID", "name": "customerId", "in": "path" } ], "responses": { "200": { "description": "Tag unassigned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } } }, "/api/drivers": { "get": { "tags": [ "Drivers" ], "summary": "List drivers", "description": "Returns a paginated list of drivers. Each item includes `compensationWilayaCount` — the number of wilayas with a configured per-delivery fee for this driver.", "operationId": "listDrivers", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Filter to drivers with a configured compensation row for this wilaya (1–58)" }, "required": false, "description": "Filter to drivers with a configured compensation row for this wilaya (1–58)", "name": "wilayaId", "in": "query" }, { "schema": { "type": "string", "enum": [ "available", "busy", "inactive" ], "description": "Filter by availability status" }, "required": false, "description": "Filter by availability status", "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "motorcycle", "car", "van" ], "description": "Filter by vehicle type" }, "required": false, "description": "Filter by vehicle type", "name": "vehicleType", "in": "query" }, { "schema": { "type": "string", "description": "Search by first name, last name, or phone" }, "required": false, "description": "Search by first name, last name, or phone", "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50, "description": "Maximum number of results to return" }, "required": false, "description": "Maximum number of results to return", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Number of results to skip for pagination" }, "required": false, "description": "Number of results to skip for pagination", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of drivers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Driver" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Drivers" ], "summary": "Create driver", "description": "Register a new delivery driver.", "operationId": "createDriver", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1, "example": "Mohamed" }, "lastName": { "type": "string", "minLength": 1, "example": "Amiri" }, "phone": { "type": "string", "pattern": "^0[5-7]\\d{8}$", "description": "Algerian mobile number starting with 05, 06, or 07", "example": "0551234567" }, "phone2": { "type": [ "string", "null" ], "pattern": "^0[5-7]\\d{8}$", "description": "Optional secondary phone number" }, "vehicleType": { "type": [ "string", "null" ], "enum": [ "motorcycle", "car", "van", null ], "description": "Type of vehicle. Omit or null if unknown." }, "status": { "type": "string", "enum": [ "available", "busy", "inactive" ], "default": "available", "description": "Availability status. Defaults to `available`." }, "notes": { "type": [ "string", "null" ], "description": "Internal notes about the driver (not visible to customers)" } }, "required": [ "firstName", "lastName", "phone" ] } } } }, "responses": { "201": { "description": "Driver created. Returns full driver record including `compensationWilayaCount` and `recentShipments`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Driver" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Duplicate phone number - a driver with this phone already exists (code: DUPLICATE_PHONE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/drivers/{id}": { "get": { "tags": [ "Drivers" ], "summary": "Get driver", "description": "Returns full driver detail: `compensationWilayaCount`, `recentShipments` (the 10 most recent orders given to this driver, newest first), `openShipmentCount` (orders still out) and `cashReconciliation` (the cash counter against the delivered shipments not yet handed over). Use `GET /{id}/compensations` for the per-wilaya pay grid.", "operationId": "getDriver", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Driver detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Driver" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Drivers" ], "summary": "Update driver", "description": "Partial update — only include fields you want to change. Use `PATCH /{id}/status` to change availability status. Set `phone2`, `vehicleType`, or `notes` to null to clear them.", "operationId": "updateDriver", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "firstName": { "type": "string", "minLength": 1 }, "lastName": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "pattern": "^0[5-7]\\d{8}$", "description": "Algerian mobile number starting with 05, 06, or 07", "example": "0551234567" }, "phone2": { "type": [ "string", "null" ], "pattern": "^0[5-7]\\d{8}$", "description": "Updated secondary phone. Send `null` to clear it." }, "vehicleType": { "type": [ "string", "null" ], "enum": [ "motorcycle", "car", "van", null ], "description": "Updated vehicle type. Send `null` to clear it." }, "notes": { "type": [ "string", "null" ], "description": "Updated internal notes. Send `null` to clear." } } } } } }, "responses": { "200": { "description": "Driver updated. Returns full updated driver record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Driver" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "409": { "description": "Duplicate phone number - a driver with this phone already exists (code: DUPLICATE_PHONE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Drivers" ], "summary": "Delete driver", "description": "Permanently deletes a driver who never had an order. **409** while the driver has orders out (`DRIVER_HAS_ACTIVE_ORDERS` — finish or take them back first) or has past deliveries (`DRIVER_HAS_SHIPMENTS` — set the driver inactive instead).", "operationId": "deleteDriver", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Driver deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Driver deleted successfully" } }, "required": [ "success", "message" ] } } } }, "409": { "description": "The driver still has orders out (DRIVER_HAS_ACTIVE_ORDERS — finish or void them), or has past deliveries (DRIVER_HAS_SHIPMENTS — set the driver inactive instead)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/drivers/{id}/status": { "patch": { "tags": [ "Drivers" ], "summary": "Update driver status", "description": "Updates driver availability status. Returns the full updated driver record.", "operationId": "updateDriverStatus", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "busy", "inactive" ], "description": "New availability status for the driver" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Driver" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } } } } }, "/api/drivers/{id}/compensations": { "get": { "tags": [ "Drivers" ], "summary": "List driver compensations", "description": "Returns all 58 wilayas with the driver's configured per-delivery fee. `feePerDelivery` is `null` when no row has been configured for that wilaya (in which case the assigned order's driver fee defaults to 0).", "operationId": "listDriverCompensations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Per-wilaya compensation grid for this driver.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriverCompensationRow" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/drivers/{id}/compensations/{wilayaId}": { "put": { "tags": [ "Drivers" ], "summary": "Upsert driver compensation for one wilaya", "description": "Sets (or updates) the per-delivery fee this driver is paid for the given wilaya. Idempotent.", "operationId": "setDriverCompensation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Wilaya ID (1–58)", "example": 16 }, "required": true, "description": "Wilaya ID (1–58)", "name": "wilayaId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "feePerDelivery": { "type": "number", "minimum": 0, "description": "DZD per delivery in this wilaya.", "example": 350 } }, "required": [ "feePerDelivery" ] } } } }, "responses": { "200": { "description": "Compensation saved.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "driverId": { "type": "string" }, "wilayaId": { "type": "integer" }, "feePerDelivery": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "driverId", "wilayaId", "feePerDelivery", "createdAt", "updatedAt" ] }, "message": { "type": "string", "example": "Compensation saved" } }, "required": [ "success", "data", "message" ] } } } } } }, "delete": { "tags": [ "Drivers" ], "summary": "Remove driver compensation for one wilaya", "description": "Removes the per-delivery fee row for this driver/wilaya pair. Future assignments in that wilaya will compute driverFee = 0 until a new row is set.", "operationId": "deleteDriverCompensation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Driver ID", "example": "drv_123" }, "required": true, "description": "Driver ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Wilaya ID (1–58)", "example": 16 }, "required": true, "description": "Wilaya ID (1–58)", "name": "wilayaId", "in": "path" } ], "responses": { "200": { "description": "Compensation removed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Compensation removed" } }, "required": [ "success", "message" ] } } } }, "404": { "description": "Driver not found (`DRIVER_NOT_FOUND`) **or** no compensation row exists for this (driver, wilaya) pair (`DRIVER_COMPENSATION_NOT_FOUND`). Distinguish via the `code` field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/wilayas": { "get": { "tags": [ "Wilayas" ], "summary": "List wilayas", "description": "Get all Algerian wilayas (provinces)", "operationId": "listWilayas", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Search by name (Arabic or Latin)" }, "required": false, "description": "Search by name (Arabic or Latin)", "name": "search", "in": "query" } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/wilayas/{id}/communes": { "get": { "tags": [ "Wilayas" ], "summary": "List communes", "description": "Get all communes for a specific wilaya", "operationId": "listCommunes", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 58 }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success" }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies": { "get": { "tags": [ "Delivery Companies" ], "summary": "List delivery companies", "description": "List all delivery companies with optional filters", "operationId": "listDeliveryCompanies", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Filter by active status", "example": "true" }, "required": false, "description": "Filter by active status", "name": "active", "in": "query" }, { "schema": { "type": "string", "description": "Search in company name (EN/AR) and code" }, "required": false, "description": "Search in company name (EN/AR) and code", "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50, "description": "Maximum number of results", "example": 50 }, "required": false, "description": "Maximum number of results", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Pagination offset", "example": 0 }, "required": false, "description": "Pagination offset", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of delivery companies", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryCompany" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Delivery Companies" ], "summary": "Create delivery company", "description": "Create a new delivery company integration", "operationId": "createDeliveryCompany", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Yalidine" }, "nameAr": { "type": "string", "minLength": 1, "example": "ياليدين" }, "code": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$", "example": "yalidine", "description": "Lowercase alphanumeric with underscores" }, "website": { "type": [ "string", "null" ], "format": "uri", "example": "https://www.yalidine.com" }, "active": { "type": "boolean", "default": true, "example": true }, "apiEndpoint": { "type": [ "string", "null" ], "format": "uri", "example": "https://api.yalidine.app/v1" }, "apiToken": { "type": [ "string", "null" ], "description": "API authentication token" }, "apiUserGuid": { "type": [ "string", "null" ], "description": "Tenant/user GUID for ZR Express" }, "supportsHomeDelivery": { "type": "boolean", "default": true }, "supportsStopDesk": { "type": "boolean", "default": true }, "autoValidate": { "type": "boolean", "description": "When true, orders are auto-validated on dispatch (locked at carrier). When false, orders stay editable. If omitted, a safe default is derived per provider." }, "notes": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "yalidine", "zr_express", "noest", "ecotrack", null ], "description": "Which carrier adapter serves this company. When omitted it is derived from the code." }, "providerConfig": { "type": "object", "additionalProperties": {}, "description": "The adapter's own settings (e.g. Yalidine: platform, fromWilayaName, proxyBaseUrl, proxySecret). Merged onto the stored settings; a secret sent back masked keeps the stored one; null removes a key." } }, "required": [ "name", "nameAr", "code" ] } } } }, "responses": { "201": { "description": "Delivery company created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DeliveryCompany" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Duplicate company code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}": { "get": { "tags": [ "Delivery Companies" ], "summary": "Get delivery company", "description": "Get a single delivery company by ID", "operationId": "getDeliveryCompany", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delivery company details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DeliveryCompany" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Delivery Companies" ], "summary": "Update delivery company", "description": "Update an existing delivery company", "operationId": "updateDeliveryCompany", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "nameAr": { "type": "string", "minLength": 1 }, "code": { "type": "string", "minLength": 1, "pattern": "^[a-z0-9_]+$" }, "website": { "type": [ "string", "null" ], "format": "uri" }, "active": { "type": "boolean" }, "apiEndpoint": { "type": [ "string", "null" ], "format": "uri" }, "apiToken": { "type": [ "string", "null" ] }, "apiUserGuid": { "type": [ "string", "null" ] }, "supportsHomeDelivery": { "type": "boolean" }, "supportsStopDesk": { "type": "boolean" }, "autoValidate": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "provider": { "type": [ "string", "null" ], "enum": [ "yalidine", "zr_express", "noest", "ecotrack", null ], "description": "Which carrier adapter serves this company. When omitted it is derived from the code." }, "providerConfig": { "type": "object", "additionalProperties": {}, "description": "The adapter's own settings (e.g. Yalidine: platform, fromWilayaName, proxyBaseUrl, proxySecret). Merged onto the stored settings; a secret sent back masked keeps the stored one; null removes a key." } } } } } }, "responses": { "200": { "description": "Delivery company updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DeliveryCompany" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Duplicate company code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Delivery Companies" ], "summary": "Delete delivery company", "description": "Delete a delivery company that never carried a parcel, with its API log and webhook inbox. A company that has carried parcels keeps their history: deactivate it instead.", "operationId": "deleteDeliveryCompany", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Delivery company deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "404": { "description": "Delivery company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Parcels are still on their way (COMPANY_HAS_ACTIVE_SHIPMENTS), or the company has carried parcels (COMPANY_HAS_SHIPMENTS — deactivate it instead)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}/stop-desks": { "get": { "tags": [ "Delivery Companies" ], "summary": "Get company stop desks", "description": "Read stop desks from DB (no live API call). Admin must sync first via POST .../sync-stop-desks", "operationId": "fetchCompanyStopDesks", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "description": "Filter by wilaya ID", "example": 16 }, "required": false, "description": "Filter by wilaya ID", "name": "wilayaId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true", "description": "Filter by active flag (default true)", "example": "true" }, "required": false, "description": "Filter by active flag (default true)", "name": "activeOnly", "in": "query" } ], "responses": { "200": { "description": "Stop desks list", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "stopDesks": { "type": "array", "items": { "$ref": "#/components/schemas/StopDesk" } }, "total": { "type": "integer" }, "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" } }, "required": [ "id", "name", "code" ] } }, "required": [ "stopDesks", "total", "company" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/delivery-companies/{id}/sync-stop-desks": { "post": { "tags": [ "Delivery Companies" ], "summary": "Sync stop desks", "description": "Fetch stop desks from carrier API and upsert into DB. Active flag is preserved.", "operationId": "syncCompanyStopDesks", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Stop desks synced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "total": { "type": "integer", "description": "Total desks upserted", "example": 1359 }, "removed": { "type": "integer", "description": "Stale desks removed", "example": 3 }, "syncedAt": { "type": "string", "format": "date-time" } }, "required": [ "total", "removed", "syncedAt" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Company not connected or provider does not support stop desks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "External API failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}/sync-geo": { "post": { "tags": [ "Delivery Companies" ], "summary": "Sync carrier geo names", "description": "Fetch the carrier's own wilaya/commune name lists and build the per-carrier name map (exact strings the carrier matches parcel addresses against). Yalidine-only for now — carriers that match by name. Response reports matched and unmapped reference rows. Dispatch resolves our wilaya/commune IDs through this map before calling the carrier.", "operationId": "syncGeoNames", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Geo names synced", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "wilayasMatched": { "type": "integer", "description": "Wilayas with a carrier string stored", "example": 58 }, "wilayasUnmapped": { "type": "integer" }, "communesMatched": { "type": "integer", "description": "Communes with a carrier string stored", "example": 1497 }, "communesUnmapped": { "type": "integer" }, "unmappedCommunes": { "type": "array", "items": { "type": "object", "properties": { "communeId": { "type": "string" }, "ourName": { "type": "string", "example": "Aghabal" } }, "required": [ "communeId", "ourName" ] } }, "unmappedWilayas": { "type": "array", "items": { "type": "object", "properties": { "wilayaId": { "type": "integer" }, "ourName": { "type": "string" } }, "required": [ "wilayaId", "ourName" ] } }, "syncedAt": { "type": "string", "format": "date-time" } }, "required": [ "wilayasMatched", "wilayasUnmapped", "communesMatched", "communesUnmapped", "unmappedCommunes", "unmappedWilayas", "syncedAt" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Company not yalidine-style name-matching or not connected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "External API failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}/test-connection": { "post": { "tags": [ "Delivery Companies" ], "summary": "Test carrier connection", "description": "Verifies the company's stored credentials against its carrier API. A negative outcome (invalid token, API access disabled) returns 200 with ok:false — the check itself succeeded. Provider support: ecotrack (all 82 companies) ✅ | others ❌ OPERATION_NOT_SUPPORTED.", "operationId": "testCompanyConnection", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Connection check executed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "companyId": { "type": "string" }, "companyName": { "type": "string" }, "companyCode": { "type": "string" }, "ok": { "type": "boolean", "description": "Whether the credentials are usable" }, "code": { "type": "string", "description": "Outcome code: valid | invalid_token | not_allowed", "example": "valid" }, "message": { "type": "string", "example": "Token is valid" }, "details": { "type": "object", "additionalProperties": {}, "description": "Provider enrichment — EcoTrack includes servedWilayaIds + servedWilayaCount when reachable." } }, "required": [ "companyId", "companyName", "companyCode", "ok", "code", "message" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Company not connected — no API token stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Provider does not support connection testing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "External API failure (carrier unreachable)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}/sync-shipments": { "post": { "tags": [ "Delivery Companies" ], "summary": "Sync this company's open shipments now", "description": "Reads the carrier's history of the company's open shipments — up to 50 per request, the longest unsynced first — and records every status not recorded yet (a status already received by webhook or an earlier sync is not recorded twice). Pull-only carriers (EcoTrack platform, NOEST, Guepex) are also synced on a schedule every few minutes; this is the merchant's \"now\", for any carrier whose history can be read. Replaces reconcile-orders.", "operationId": "syncCompanyShipments", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "What the sync found", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "synced": { "type": "integer", "description": "Shipments read" }, "recorded": { "type": "integer", "description": "Statuses new to Wocart" }, "reached": { "type": "integer", "description": "Milestones reached for the first time" }, "moreRemain": { "type": "boolean", "description": "More open shipments wait for the next sync" } }, "required": [ "synced", "recorded", "reached", "moreRemain" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Company not connected — no API token stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The carrier's history cannot be read", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "The carrier is throttling", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "The carrier could not be reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}/stop-desks/{code}/toggle": { "patch": { "tags": [ "Delivery Companies" ], "summary": "Toggle stop desk active flag", "description": "Toggle the active flag on a single stop desk. Admin can deactivate stop desks that can't be serviced.", "operationId": "toggleCompanyStopDesk", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Stop desk code", "example": "16A" }, "required": true, "description": "Stop desk code", "name": "code", "in": "path" } ], "responses": { "200": { "description": "Stop desk toggled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "code": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "code", "active" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/delivery-companies/{id}/webhook/register": { "post": { "tags": [ "Delivery Companies" ], "summary": "Register ZR Express webhook", "description": "Registers a webhook endpoint with ZR Express via their API. Stores the endpointId and signing secret.", "operationId": "registerZrWebhook", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook registered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "webhookUrl": { "type": "string", "format": "uri", "example": "https://your-worker.workers.dev/webhooks/zr_express" }, "endpointId": { "type": "string", "example": "ep_1234567890" } }, "required": [ "success", "webhookUrl", "endpointId" ] } } } } } }, "delete": { "tags": [ "Delivery Companies" ], "summary": "Unregister ZR Express webhook", "description": "Deletes the registered webhook endpoint from ZR Express and clears the DB fields.", "operationId": "unregisterZrWebhook", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Webhook unregistered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/api/delivery-companies/{id}/webhook/secret": { "patch": { "tags": [ "Delivery Companies" ], "summary": "Save Yalidine webhook secret", "description": "Stores the Yalidine webhook secret key (entered manually after setting up webhook in Yalidine dashboard).", "operationId": "saveYalidineSecret", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "type": "string", "minLength": 1, "description": "Webhook secret key from Yalidine dashboard" } }, "required": [ "secret" ] } } } }, "responses": { "200": { "description": "Secret saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } } } } }, "/api/delivery-companies/{id}/webhook/events": { "get": { "tags": [ "Delivery Companies" ], "summary": "List inbound webhook events", "description": "The company's webhook inbox, newest first: every event its carrier pushed, with what processing made of it — ok, ignored, unmatched (no shipment has that parcel), unknown_status (recorded, but a status Wocart does not interpret), deferred_settlement (a money event), error (to be retried at nextAttemptAt) or dead (tries spent). Each row names the shipment it was recorded on and its order. rawPayload is left out: the log's value is the outcome.", "operationId": "listWebhookEvents", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "Page size (1-100)", "example": 25 }, "required": false, "description": "Page size (1-100)", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0, "description": "Offset for keyset-free pagination", "example": 0 }, "required": false, "description": "Offset for keyset-free pagination", "name": "offset", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "ok", "ignored", "unmatched", "unknown_status", "deferred_settlement", "error", "dead", "unmapped" ], "description": "Filter by processing result — the operational lens: error and dead need attention, unmatched and unknown_status may need a parcel attached or a status mapped" }, "required": false, "description": "Filter by processing result — the operational lens: error and dead need attention, unmatched and unknown_status may need a parcel attached or a status mapped", "name": "result", "in": "query" } ], "responses": { "200": { "description": "Webhook events page", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "b537eb81-e24d-4df5-be7a-b3bf3293a524" }, "provider": { "type": "string", "enum": [ "zr_express", "yalidine" ], "example": "yalidine" }, "eventId": { "type": "string", "description": "Idempotency key (event_id / svix-id)" }, "tracking": { "type": [ "string", "null" ] }, "eventType": { "type": "string", "example": "parcel_status_updated" }, "result": { "type": "string", "enum": [ "pending", "ok", "ignored", "unmatched", "unknown_status", "deferred_settlement", "error", "dead", "unmapped" ] }, "reason": { "type": [ "string", "null" ], "description": "Carrier reason / status string (Tentative échouée's reason, unmapped status)" }, "errorMsg": { "type": [ "string", "null" ] }, "shipmentId": { "type": [ "string", "null" ], "description": "The shipment the event was recorded on" }, "orderId": { "type": [ "string", "null" ] }, "orderNumber": { "type": [ "string", "null" ], "description": "Joined from orders for display" }, "attempts": { "type": "integer", "description": "Times processing was tried" }, "nextAttemptAt": { "type": [ "string", "null" ], "description": "When processing is tried again (error only)" }, "processedAt": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "provider", "eventId", "tracking", "eventType", "result", "reason", "errorMsg", "shipmentId", "orderId", "orderNumber", "attempts", "nextAttemptAt", "processedAt", "createdAt" ] } }, "total": { "type": "integer", "description": "Total rows matching the filter (for pagination)" } }, "required": [ "events", "total" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Company not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/delivery-companies/{id}/webhook/events/{eventId}/retry": { "post": { "tags": [ "Delivery Companies" ], "summary": "Process an inbox event again", "description": "Processes an event that ended in error, dead, unmatched or unknown_status again, now — after fixing the company's settings, attaching its parcel, or mapping its status. Its tries start over.", "operationId": "retryWebhookEvent", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Delivery company ID", "example": "comp_abc123" }, "required": true, "description": "Delivery company ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Inbox event id" }, "required": true, "description": "Inbox event id", "name": "eventId", "in": "path" } ], "responses": { "200": { "description": "What processing made of it this time", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "result": { "type": "string" }, "errorMsg": { "type": [ "string", "null" ] }, "shipmentId": { "type": [ "string", "null" ] } }, "required": [ "result", "errorMsg", "shipmentId" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such event for this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The event is not in a state that is processed again (ok, ignored, pending, deferred_settlement)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products": { "get": { "tags": [ "Products" ], "summary": "List products", "description": "Returns a paginated list of products. Soft-deleted products are never returned. Each item includes `variantsCount`, `totalInventory`, `primaryImage` (its gallery's first image), and `variants` array.", "operationId": "listProducts", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": false, "name": "categoryId", "in": "query" }, { "schema": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "visibility", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of products", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Products" ], "summary": "Create product", "description": "Creates a product. SKU rules: simple products (`hasVariants=false`, the default) must include `sku`. Variant products (`hasVariants=true`) must omit `sku` here — set it on each variant instead. Returns the full product record including empty `variants` and `images` arrays.", "operationId": "createProduct", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 100000 }, "descriptionFormat": { "type": "string", "enum": [ "text", "html" ] }, "handle": { "type": "string" }, "price": { "type": "integer", "minimum": 0 }, "compareAtPrice": { "type": "integer", "minimum": 0 }, "costPrice": { "type": "integer", "minimum": 0 }, "type": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ], "default": "PHYSICAL" }, "hasVariants": { "type": "boolean", "default": false }, "variantOptions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "hexColor": { "type": [ "string", "null" ] } }, "required": [ "value" ] }, "minItems": 1 } }, "required": [ "name", "values" ] } }, "sku": { "type": "string", "minLength": 1 }, "inventory": { "type": "integer", "minimum": 0, "default": 0 }, "lowStockThreshold": { "type": "integer", "minimum": 0, "default": 5 }, "trackInventory": { "type": "boolean", "default": true }, "categoryId": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "type": "boolean", "default": true }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ], "default": "ACTIVE" }, "showInStore": { "type": "boolean", "default": true }, "collectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 100 }, "shippingProfileId": { "type": [ "string", "null" ] }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 60 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 160 } }, "required": [ "name", "price" ] } } } }, "responses": { "201": { "description": "Product created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductDetail" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Duplicate SKU (DUPLICATE_SKU)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products/{id}/images": { "get": { "tags": [ "Products" ], "summary": "List product images", "description": "Returns all images for a product ordered by position.", "operationId": "listProductImages", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "List of product images ordered by position", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } } }, "required": [ "success", "data" ] } } } } } }, "post": { "tags": [ "Products" ], "summary": "Save product image", "description": "Attaches an uploaded image to a product by its Media Key. Upload it first: POST /api/media/uploads, send the file as the ticket says, then POST /api/media/uploads/{id}/complete.", "operationId": "attachProductImage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaKey": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "altText": { "type": [ "string", "null" ], "description": "Alt text for accessibility" }, "position": { "type": "integer", "minimum": 1, "description": "Where it goes, 1 = first; the images from there move down one. Omitted or past the end: last" } }, "required": [ "mediaKey" ] } } } }, "responses": { "201": { "description": "Image record created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductImage" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No product with this ID (PRODUCT_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "The key's upload is not complete (MEDIA_NOT_READY)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products/{id}/images/reorder": { "patch": { "tags": [ "Products" ], "summary": "Reorder product images", "description": "Sets the display order of a product's images. Send the complete ordered array of image IDs — every existing image ID must be included exactly once. The server assigns position 1, 2, 3… based on the array order. Returns the full reordered image list.", "operationId": "reorderProductImages", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "imageIds": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Complete ordered list of all image IDs for this product. All existing image IDs must be included — no duplicates, no omissions.", "example": [ "uuid-b", "uuid-a", "uuid-c" ] } }, "required": [ "imageIds" ] } } } }, "responses": { "200": { "description": "Images reordered successfully. Returns updated image list in new order.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImage" } } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Duplicate IDs, image IDs that don't belong to this product, or incomplete set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products/{id}/images/{imageId}": { "delete": { "tags": [ "Products" ], "summary": "Delete product image", "description": "Removes the image from the product; its file is deleted once nothing else shows it. Variants that showed the image are left without one.", "operationId": "deleteProductImage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Image ID", "example": "img_abc123" }, "required": true, "description": "Image ID", "name": "imageId", "in": "path" } ], "responses": { "200": { "description": "Image deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/products/{id}/status": { "patch": { "tags": [ "Products" ], "summary": "Update product status", "description": "Dedicated endpoint for status-only updates. Setting `ACTIVE` auto-sets `publishedAt`.", "operationId": "updateProductStatus", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Status updated. Returns full updated product record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Product" } }, "required": [ "success", "data" ] } } } } } } }, "/api/products/{id}": { "get": { "tags": [ "Products" ], "summary": "Get product", "description": "Returns full product detail including `category`, `variants`, and `images`.", "operationId": "getProduct", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Product detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductDetail" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Products" ], "summary": "Update product", "description": "Partial update — only include fields you want to change. Setting `status` to `ACTIVE` auto-sets `publishedAt`. Send `variantOptions: null` to clear all variant options when converting a variant product to simple.", "operationId": "updateProduct", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 100000 }, "descriptionFormat": { "type": "string", "enum": [ "text", "html" ] }, "handle": { "type": "string" }, "price": { "type": "integer", "minimum": 0 }, "compareAtPrice": { "type": [ "integer", "null" ], "minimum": 0 }, "costPrice": { "type": [ "integer", "null" ], "minimum": 0 }, "type": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL" ] }, "hasVariants": { "type": "boolean" }, "variantOptions": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "minLength": 1, "maxLength": 255 }, "hexColor": { "type": [ "string", "null" ] } }, "required": [ "value" ] }, "minItems": 1 } }, "required": [ "name", "values" ] } }, "sku": { "type": "string", "minLength": 1 }, "inventory": { "type": "integer", "minimum": 0 }, "lowStockThreshold": { "type": "integer", "minimum": 0 }, "trackInventory": { "type": "boolean" }, "categoryId": { "type": [ "string", "null" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "visibility": { "type": "boolean" }, "status": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] }, "showInStore": { "type": "boolean" }, "collectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 100 }, "shippingProfileId": { "type": [ "string", "null" ] }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 60 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 160 } } } } } }, "responses": { "200": { "description": "Product updated. Returns full updated product record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductDetail" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Products" ], "summary": "Delete product", "description": "Removes the product for good — even one that orders hold — and frees its handle and SKU. Its variants, images, reviews, stock history, offers and landing pages go with it, and its image files once nothing else shows them. Order lines that sold it keep what was sold (name, variant label, SKU, price) and lose only the link; orders a landing page of it brought lose only that attribution. `GET /products/{id}/removal` says all of it beforehand.", "operationId": "deleteProduct", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Product deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Product deleted" } }, "required": [ "success", "message" ] } } } } } } }, "/api/products/{id}/removal": { "get": { "tags": [ "Products" ], "summary": "What removing a product does", "description": "What `DELETE /products/{id}` would take with it and what stays — read before asking the merchant to confirm.", "operationId": "getProductRemoval", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The product's removal", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductRemoval" } }, "required": [ "success", "data" ] } } } } } } }, "/api/products/{productId}/variants": { "get": { "tags": [ "Products" ], "summary": "List product variants", "description": "Returns variants ordered by position, with parsed `variations` objects.", "operationId": "listVariants", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" } ], "responses": { "200": { "description": "List of variants ordered by position", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariant" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Products" ], "summary": "Create product variant", "operationId": "createVariant", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "variations": { "type": "object", "additionalProperties": { "type": "string" } }, "price": { "type": "integer", "minimum": 0 }, "compareAtPrice": { "type": [ "integer", "null" ], "minimum": 0 }, "sku": { "type": "string", "minLength": 1 }, "barcode": { "type": [ "string", "null" ] }, "inventory": { "type": "integer", "minimum": 0, "default": 0 }, "lowStockThreshold": { "type": "integer", "minimum": 0, "default": 5 }, "weightKg": { "type": [ "number", "null" ], "minimum": 0 }, "imageId": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean", "default": false }, "active": { "type": "boolean", "default": true }, "position": { "type": "integer", "minimum": 1, "default": 1 } }, "required": [ "variations", "price", "sku" ] } } } }, "responses": { "201": { "description": "Variant created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductVariant" } }, "required": [ "success", "data" ] } } } } } } }, "/api/products/{productId}/variants/{variantId}": { "get": { "tags": [ "Products" ], "summary": "Get product variant", "operationId": "getVariant", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" }, { "schema": { "type": "string", "description": "Variant ID", "example": "var_abc123" }, "required": true, "description": "Variant ID", "name": "variantId", "in": "path" } ], "responses": { "200": { "description": "Variant detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductVariant" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Products" ], "summary": "Update product variant", "description": "Partial update — only include fields you want to change.", "operationId": "updateVariant", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" }, { "schema": { "type": "string", "description": "Variant ID", "example": "var_abc123" }, "required": true, "description": "Variant ID", "name": "variantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "variations": { "type": "object", "additionalProperties": { "type": "string" } }, "price": { "type": "integer", "minimum": 0 }, "compareAtPrice": { "type": [ "integer", "null" ], "minimum": 0 }, "sku": { "type": "string", "minLength": 1 }, "barcode": { "type": [ "string", "null" ] }, "inventory": { "type": "integer", "minimum": 0 }, "lowStockThreshold": { "type": "integer", "minimum": 0 }, "weightKg": { "type": [ "number", "null" ], "minimum": 0 }, "imageId": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "active": { "type": "boolean" }, "position": { "type": "integer", "minimum": 1 } } } } } }, "responses": { "200": { "description": "Variant updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductVariant" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Products" ], "summary": "Delete product variant", "description": "Permanently deletes the variant. Any order line items referencing this variant will have their `variantId` set to null — order history is fully preserved.", "operationId": "deleteVariant", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" }, { "schema": { "type": "string", "description": "Variant ID", "example": "var_abc123" }, "required": true, "description": "Variant ID", "name": "variantId", "in": "path" } ], "responses": { "200": { "description": "Variant deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "422": { "description": "Cannot delete variant referenced by existing orders (VARIANT_HAS_ORDERS)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products/{id}/translations": { "get": { "tags": [ "Products" ], "summary": "Get a product's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getProductTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Products" ], "summary": "Translate a product into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchProductTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100000 }, "metaTitle": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "metaDescription": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 160 } }, "additionalProperties": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 } } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/product-groups": { "get": { "tags": [ "Product Groups" ], "summary": "List product groups", "description": "Get all product categories/groups, ordered by position. Each item includes productsCount (active, non-deleted products).", "operationId": "listProductGroups", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Search by name" }, "required": false, "description": "Search by name", "name": "search", "in": "query" }, { "schema": { "type": "string", "description": "Filter to direct sub-categories of this parent group ID" }, "required": false, "description": "Filter to direct sub-categories of this parent group ID", "name": "parentId", "in": "query" } ], "responses": { "200": { "description": "List of product groups", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Product Groups" ], "summary": "Create product group", "description": "Create a new product category/group. Provide parentId to create a sub-category; slug is auto-generated from name when omitted.", "operationId": "createProductGroup", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Electronics" }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "example": "electronics", "description": "Auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID to nest under; null/omitted for top-level" }, "imageKey": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "The image's Media Key, from a completed upload (POST /api/media/uploads)", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 60 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 160 }, "metaKeywords": { "type": [ "string", "null" ] }, "position": { "type": "integer", "minimum": 0, "default": 0 } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Group created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductCategory" } }, "required": [ "success", "data" ] } } } } } } }, "/api/product-groups/{id}": { "get": { "tags": [ "Product Groups" ], "summary": "Get product group", "description": "Returns the group with its immediate children (sub-categories) and productsCount.", "operationId": "getProductGroup", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product group ID", "example": "cat_123" }, "required": true, "description": "Product group ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Group details with children and product count", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductCategory" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Product Groups" ], "summary": "Update product group", "description": "Partial update — only include fields you want to change. Set parentId to null to move a group to the top level; set SEO fields to null to clear them.", "operationId": "updateProductGroup", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product group ID", "example": "cat_123" }, "required": true, "description": "Product group ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Electronics" }, "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "example": "electronics", "description": "Auto-generated from name with a unique suffix when omitted" }, "description": { "type": [ "string", "null" ] }, "parentId": { "type": [ "string", "null" ], "description": "Parent group ID to nest under; null/omitted for top-level" }, "imageKey": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "The image's Media Key, from a completed upload (POST /api/media/uploads)", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 60 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 160 }, "metaKeywords": { "type": [ "string", "null" ] }, "position": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Group updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ProductCategory" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Product Groups" ], "summary": "Delete product group", "description": "Permanently deletes a product group. Blocked while the group still has active products — reassign or remove those products first.", "operationId": "deleteProductGroup", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product group ID", "example": "cat_123" }, "required": true, "description": "Product group ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Group deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "422": { "description": "Product group has existing products - cannot delete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/product-groups/{id}/translations": { "get": { "tags": [ "Product Groups" ], "summary": "Get a category's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getCategoryTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Product Groups" ], "summary": "Translate a category into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchCategoryTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 255 }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 5000 }, "metaTitle": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "metaDescription": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 160 } }, "additionalProperties": false } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/landing-pages": { "get": { "tags": [ "Landing Pages" ], "summary": "List landing pages", "description": "List landing pages (newest first) with per-page stats: views, attributed orders, revenue — orders count as placed regardless of status (cancelled/returned included). Filter by product or status. limit/offset are opt-in pagination; omitting them returns the full list.", "operationId": "listLandingPages", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Filter by product UUID" }, "required": false, "description": "Filter by product UUID", "name": "productId", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "published", "archived" ], "description": "Filter by lifecycle status" }, "required": false, "description": "Filter by lifecycle status", "name": "status", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Opt-in page size (1-200). Omitted → the full list (the dashboard fetches everything; LLM-facing clients should set a limit).", "example": 50 }, "required": false, "description": "Opt-in page size (1-200). Omitted → the full list (the dashboard fetches everything; LLM-facing clients should set a limit).", "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "description": "Opt-in page offset — pair with limit. Rows are newest-first.", "example": 0 }, "required": false, "description": "Opt-in page offset — pair with limit. Rows are newest-first.", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "List of landing pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageListItem" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Landing Pages" ], "summary": "Create landing page", "description": "Create a draft landing page for a product. The slug defaults to `lp-<8 chars>` and is editable later. The page charges the product's catalog price — there is no price override (the price story lives in the images).\n\n**Validation:** the product must exist; a taken slug returns 409.", "operationId": "createLandingPage", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]{3,60}$" }, "productId": { "type": "string", "minLength": 1 }, "imageGap": { "type": "integer", "minimum": 0, "maximum": 200, "default": 0 }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 200 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 300 } }, "required": [ "name", "productId" ] } } } }, "responses": { "201": { "description": "Landing page created (draft)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPage" } }, "required": [ "success", "data" ] } } } } } } }, "/api/landing-pages/compare": { "get": { "tags": [ "Landing Pages" ], "summary": "Compare landing pages of one product", "description": "The A/B view: every landing page of one product side by side with views, orders, revenue — orders count as placed regardless of status (cancelled/returned included). Conversion rate = orders / views (undefined on zero views — compute client-side).", "operationId": "compareLandingPages", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product UUID to compare pages for" }, "required": true, "description": "Product UUID to compare pages for", "name": "productId", "in": "query" } ], "responses": { "200": { "description": "Landing pages of the product with stats", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageListItem" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } } }, "/api/landing-pages/{id}": { "get": { "tags": [ "Landing Pages" ], "summary": "Get landing page", "description": "Full landing page detail: settings, the ordered image stack, the linked product, and stats.", "operationId": "getLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Landing page details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPage" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Landing Pages" ], "summary": "Update landing page", "description": "Partial update — send only the fields you want to change (name, slug, spacing settings, SEO meta). A taken slug returns 409.", "operationId": "updateLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "slug": { "type": "string", "pattern": "^[a-z0-9-]{3,60}$" }, "imageGap": { "type": "integer", "minimum": 0, "maximum": 200, "default": 0 }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 200 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 300 } } } } } }, "responses": { "200": { "description": "Landing page updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPage" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Landing Pages" ], "summary": "Delete landing page", "description": "Permanently delete a landing page with NO attributed orders. Refused with LANDING_PAGE_HAS_ORDERS otherwise — archive instead so history stays intact. Images cascade.", "operationId": "deleteLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Landing page deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "422": { "description": "Landing page has attributed orders (LANDING_PAGE_HAS_ORDERS) — archive instead", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/landing-pages/{id}/duplicate": { "post": { "tags": [ "Landing Pages" ], "summary": "Duplicate landing page", "description": "Create a quick copy: a fresh DRAFT with a new slug, the same product, spacing, SEO meta, and image stack (images share the original immutable R2 objects — deleting an image elsewhere only removes the storage object when the last reference goes). Views, orders, revenue, and published state are never copied — a duplicate is a fresh creative test.", "operationId": "duplicateLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "201": { "description": "Landing page duplicated (draft)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPage" } }, "required": [ "success", "data" ] } } } } } } }, "/api/landing-pages/{id}/publish": { "post": { "tags": [ "Landing Pages" ], "summary": "Publish landing page", "description": "Make the page live at /lp/ and start counting views.", "operationId": "publishLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Landing page published", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPage" } }, "required": [ "success", "data" ] } } } } } } }, "/api/landing-pages/{id}/unpublish": { "post": { "tags": [ "Landing Pages" ], "summary": "Unpublish landing page", "description": "Return the page to draft — the link stops resolving (404) but history stays.", "operationId": "unpublishLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Landing page unpublished", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPage" } }, "required": [ "success", "data" ] } } } } } } }, "/api/landing-pages/{id}/archive": { "post": { "tags": [ "Landing Pages" ], "summary": "Archive landing page", "description": "Retire the page while keeping its order history intact. The link stops resolving.", "operationId": "archiveLandingPage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Landing page archived", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/landing-pages/{id}/images": { "get": { "tags": [ "Landing Pages" ], "summary": "List landing page images", "description": "The image stack ordered by position (1 = top of the page).", "operationId": "listLandingPageImages", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Image stack", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageImage" } } }, "required": [ "success", "data" ] } } } } } }, "post": { "tags": [ "Landing Pages" ], "summary": "Save landing page image", "description": "Appends an uploaded image to the stack by its Media Key. Upload it first (POST /api/media/uploads with folder `landing`, send the file, complete the upload); its size comes from the upload.", "operationId": "saveLandingPageImage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "mediaKey": { "type": "string", "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "altText": { "type": [ "string", "null" ], "description": "Alt text for accessibility" }, "position": { "type": "integer", "minimum": 1, "description": "Where it goes, 1 = top of the page; the images from there move down one. Omitted or past the end: last" } }, "required": [ "mediaKey" ] } } } }, "responses": { "201": { "description": "Image added — returns the full reordered stack", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageImage" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/landing-pages/{id}/images/reorder": { "patch": { "tags": [ "Landing Pages" ], "summary": "Reorder landing page images", "description": "Set the stack order. Send the complete ordered array of image IDs — every existing image ID exactly once.", "operationId": "reorderLandingPageImages", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "imageIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "description": "Complete ordered list of all image IDs for this landing page — no duplicates, no omissions.", "example": [ "uuid-b", "uuid-a", "uuid-c" ] } }, "required": [ "imageIds" ] } } } }, "responses": { "200": { "description": "Images reordered — returns the stack in new order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageImage" } } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Duplicate IDs, foreign IDs, or incomplete set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/landing-pages/{id}/images/{imageId}": { "delete": { "tags": [ "Landing Pages" ], "summary": "Delete landing page image", "description": "Remove an image from the stack. The R2 object is deleted first — a storage failure aborts so no DB row points at a missing object.", "operationId": "deleteLandingPageImage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Landing Page Image UUID", "example": "lpimg_abc123" }, "required": true, "description": "Landing Page Image UUID", "name": "imageId", "in": "path" } ], "responses": { "200": { "description": "Image deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/landing-pages/{id}/tracking": { "get": { "tags": [ "Landing Pages" ], "summary": "Get landing page tracking", "description": "This page's tracking: `config` is its own Meta Pixel + Conversions API configuration (null when it inherits the store's, which is the default for every page), and `lastEvent` is the most recent Conversions API attempt for an order this page produced — proof that a campaign is reporting, including Meta's own message when one failed. The access token is never returned, only a masked hint.", "operationId": "getLandingPageTracking", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The page's tracking configuration and its most recent Conversions API attempt", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPageTrackingState" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Landing page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "put": { "tags": [ "Landing Pages" ], "summary": "Save landing page tracking", "description": "Give this page its own pixel, REPLACING the store's for its visitors and for the orders attributed to it — never adding to it. Takes effect only while the Meta App's per-page tracking switch is on (the Meta App's page).\n\n**`accessToken`** is required when creating the override and optional afterwards: an empty value keeps the stored token, because the dashboard only ever holds a masked hint.\n\n**`conversionEvent`** is required — which moment counts as a conversion is a spend decision and is never defaulted for the merchant.\n\n**`testMode`** requires a `testEventCode`, or the events reach production measurement instead of Meta's test stream.", "operationId": "saveLandingPageTracking", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pixelId": { "type": "string", "minLength": 1, "maxLength": 64 }, "accessToken": { "type": "string", "maxLength": 512 }, "adAccountName": { "type": [ "string", "null" ], "maxLength": 200 }, "testEventCode": { "type": [ "string", "null" ], "maxLength": 64 }, "conversionEvent": { "type": "string", "enum": [ "Lead", "Purchase", "Purchase_Confirmed", "Purchase_Delivered" ] }, "testMode": { "type": "boolean" }, "enabled": { "type": "boolean" } }, "required": [ "pixelId", "conversionEvent" ] } } } }, "responses": { "200": { "description": "Saved tracking configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/LandingPageTracking" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Missing access token on create, or test mode without a test event code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Landing page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Landing Pages" ], "summary": "Remove landing page tracking", "description": "Return the page to the store pixel. Succeeds whether or not an override existed.", "operationId": "deleteLandingPageTracking", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Landing Page UUID", "example": "lp_abc123" }, "required": true, "description": "Landing Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Page returned to the store pixel", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "404": { "description": "Landing page not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/store-pages": { "get": { "tags": [ "Store Pages" ], "summary": "List store pages", "description": "Every page — the 4 seeded legal pages plus any custom pages — with per-locale title, source (template/merchant), and last-updated time.", "operationId": "listStorePages", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of store pages", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StorePageSummary" } }, "count": { "type": "integer" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Store Pages" ], "summary": "Create a custom page", "description": "Create a merchant-authored page (kind=custom) in one locale. Starts as a draft — publish it via PATCH. A taken slug returns 409.", "operationId": "createCustomStorePage", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 3, "maxLength": 60, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "bodyHtml": { "type": "string", "minLength": 1 }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 200 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 300 }, "showInFooter": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0 } }, "required": [ "slug", "locale", "title", "bodyHtml" ] } } } }, "responses": { "201": { "description": "Custom page created (draft)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePageDetail" } }, "required": [ "success", "data" ] } } } } } } }, "/api/store-pages/legal-profile": { "get": { "tags": [ "Store Pages" ], "summary": "Get the legal profile", "description": "The merchant facts (RC/NIF, contact, return and delivery windows) substituted into the legal templates. Never null-guarded on the client — an unset store returns an all-null row shape.", "operationId": "getStoreLegalProfile", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The legal profile, or null if never set", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreLegalProfile" } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Store Pages" ], "summary": "Save the legal profile", "description": "Partial update — send only the fields you want to change. Filling in a fact here does NOT retroactively edit already-seeded pages; use the reset endpoint per page to re-apply the template with the new facts.", "operationId": "saveStoreLegalProfile", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "legalName": { "type": [ "string", "null" ], "maxLength": 200 }, "rcNumber": { "type": [ "string", "null" ], "maxLength": 60 }, "nif": { "type": [ "string", "null" ], "maxLength": 60 }, "address": { "type": [ "string", "null" ], "maxLength": 500 }, "contactEmail": { "type": [ "string", "null" ], "maxLength": 200, "format": "email" }, "contactPhone": { "type": [ "string", "null" ], "maxLength": 40 }, "returnWindowDays": { "type": "integer", "minimum": 0, "maximum": 90 }, "deliveryMinDays": { "type": "integer", "minimum": 0, "maximum": 60 }, "deliveryMaxDays": { "type": "integer", "minimum": 0, "maximum": 60 } } } } } }, "responses": { "200": { "description": "Saved legal profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StoreLegalProfile" } }, "required": [ "success", "data" ] } } } } } } }, "/api/store-pages/seed-defaults": { "post": { "tags": [ "Store Pages" ], "summary": "Seed the 4 default legal pages", "description": "Creates whichever of Terms/Privacy/Refund/Shipping this store does not already have. Idempotent — safe to call repeatedly; returns which kinds were newly created (empty array when all 4 already exist).", "operationId": "seedStoreDefaultPages", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Which kinds were created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "string" } } }, "required": [ "created" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/store-pages/{id}": { "get": { "tags": [ "Store Pages" ], "summary": "Get store page", "description": "Full page detail: settings and the complete body for every locale that has been saved.", "operationId": "getStorePage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Store Page UUID", "example": "sp_abc123" }, "required": true, "description": "Store Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Store page detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePageDetail" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Store Pages" ], "summary": "Update store page settings", "description": "Partial update of slug, publish status, footer visibility, and footer position. To edit the page's words, use the translation endpoints. A taken slug returns 409.", "operationId": "updateStorePage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Store Page UUID", "example": "sp_abc123" }, "required": true, "description": "Store Page UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 3, "maxLength": 60, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }, "status": { "type": "string", "enum": [ "published", "draft" ] }, "showInFooter": { "type": "boolean" }, "position": { "type": "integer", "minimum": 0 } } } } } }, "responses": { "200": { "description": "Store page updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePageDetail" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Store Pages" ], "summary": "Delete a custom page", "description": "Permanently delete a custom page. A legal page (terms/privacy/refund/shipping) cannot be deleted — unpublish it instead (PATCH status=draft). Refused with STORE_PAGE_CANNOT_DELETE_LEGAL otherwise.", "operationId": "deleteStorePage", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Store Page UUID", "example": "sp_abc123" }, "required": true, "description": "Store Page UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Page deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "422": { "description": "Page is a legal kind and cannot be deleted (STORE_PAGE_CANNOT_DELETE_LEGAL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/store-pages/{id}/translations/{locale}": { "put": { "tags": [ "Store Pages" ], "summary": "Save a page's translation", "description": "Save this page's title and body in one locale. The body is sanitised server-side (the same allow-list used for product descriptions) before it is stored — this is the only way to write a page's content. Marks this locale as merchant-reviewed (source=merchant).", "operationId": "saveStorePageTranslation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Store Page UUID", "example": "sp_abc123" }, "required": true, "description": "Store Page UUID", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "ar", "fr", "en" ], "example": "ar" }, "required": true, "name": "locale", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "bodyHtml": { "type": "string", "minLength": 1 }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 200 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 300 } }, "required": [ "title", "bodyHtml" ] } } } }, "responses": { "200": { "description": "Saved translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePageTranslationBody" } }, "required": [ "success", "data" ] } } } } } } }, "/api/store-pages/{id}/translations/{locale}/reset": { "post": { "tags": [ "Store Pages" ], "summary": "Reset a translation to the Wocart template", "description": "Discards whatever is currently saved for this locale and re-renders it from the current legal template and this store's legal profile. Only legal kinds have a template — called on a custom page it is refused with STORE_PAGE_NOT_LEGAL.", "operationId": "resetStorePageTranslation", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Store Page UUID", "example": "sp_abc123" }, "required": true, "description": "Store Page UUID", "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "ar", "fr", "en" ], "example": "ar" }, "required": true, "name": "locale", "in": "path" } ], "responses": { "200": { "description": "Re-seeded translation", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePageTranslationBody" } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Not a legal kind (STORE_PAGE_NOT_LEGAL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/menus": { "get": { "tags": [ "Navigation" ], "summary": "List menus", "description": "Every menu of the store, oldest first, with how many items each holds.", "operationId": "listMenus", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The store's menus", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MenuSummary" } }, "count": { "type": "integer" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Navigation" ], "summary": "Create a menu", "description": "An empty menu; add its items with `PUT /{id}/items`.", "operationId": "createMenu", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "example": "main-menu" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Main menu" } }, "required": [ "handle", "title" ] } } } }, "responses": { "201": { "description": "The new menu", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MenuDetail" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Another menu has this handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/menus/destinations": { "get": { "tags": [ "Navigation" ], "summary": "Find what a menu item can point at", "description": "Up to 20 products, categories, store pages or landing pages whose name or slug contains `q`, each with its public path and whether shoppers can see it now.", "operationId": "searchMenuDestinations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "category", "collection", "product", "page", "landing" ], "example": "product" }, "required": true, "name": "type", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Part of the name or slug", "example": "robe" }, "required": false, "description": "Part of the name or slug", "name": "q", "in": "query" } ], "responses": { "200": { "description": "Matching destinations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MenuDestinationOption" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/menus/{id}": { "get": { "tags": [ "Navigation" ], "summary": "Get a menu", "description": "A menu with its item tree. Each item says whether shoppers can follow it (`destinationStatus`).", "operationId": "getMenu", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Menu id" }, "required": true, "description": "Menu id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The menu", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MenuDetail" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such menu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Navigation" ], "summary": "Rename a menu", "description": "Changes its title or handle. A theme reads a menu by handle, so a new handle moves the menu out of every theme setting that named the old one.", "operationId": "updateMenu", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Menu id" }, "required": true, "description": "Menu id", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the menu", "example": "main-menu" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Main menu" } } } } } }, "responses": { "200": { "description": "The menu", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MenuDetail" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such menu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another menu has this handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Navigation" ], "summary": "Delete a menu", "description": "Deletes the menu with its items and their translations. A theme setting naming it then renders no menu.", "operationId": "deleteMenu", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Menu id" }, "required": true, "description": "Menu id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such menu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/menus/{id}/items": { "put": { "tags": [ "Navigation" ], "summary": "Save a menu's items", "description": "Replaces the menu's items with this tree, at once. An item sent with its `id` keeps it and its translations; an item left out is deleted. At most three levels and 100 items.", "operationId": "saveMenuItems", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Menu id" }, "required": true, "description": "Menu id", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/MenuItemInput" }, "description": "The whole tree, in order; at most three levels and 100 items" } }, "required": [ "items" ] } } } }, "responses": { "200": { "description": "The menu as saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/MenuDetail" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Too many items, or one item sent twice", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such menu", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/menus/items/{id}/translations": { "get": { "tags": [ "Navigation" ], "summary": "Get a menu item's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getMenuitemTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Navigation" ], "summary": "Translate a menu item into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchMenuitemTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 } }, "additionalProperties": false } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/collections": { "get": { "tags": [ "Collections" ], "summary": "List collections", "description": "Every collection of the store, oldest first, with how many products each holds.", "operationId": "listCollections", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The store's collections", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSummary" } }, "count": { "type": "integer" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Collections" ], "summary": "Create a collection", "description": "An empty collection; add products with `PUT /{id}/products` or from a product's page.", "operationId": "createCollection", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "example": "best-sellers" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Best sellers" }, "description": { "type": [ "string", "null" ], "maxLength": 1000 } }, "required": [ "handle", "title" ] } } } }, "responses": { "201": { "description": "The new collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionDetail" } }, "required": [ "success", "data" ] } } } }, "409": { "description": "Another collection has this handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/collections/{id}": { "get": { "tags": [ "Collections" ], "summary": "Get a collection", "description": "A collection with its products in order, each saying whether shoppers see it now.", "operationId": "getCollection", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Collection id" }, "required": true, "description": "Collection id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionDetail" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Collections" ], "summary": "Rename a collection", "description": "Changes its title, description or handle. A theme names a collection by handle, so a new handle moves it out of every theme setting that named the old one.", "operationId": "updateCollection", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Collection id" }, "required": true, "description": "Collection id", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "handle": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]{0,63}$", "description": "Lowercase letters, digits and hyphens; how a theme names the collection", "example": "best-sellers" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "example": "Best sellers" }, "description": { "type": [ "string", "null" ], "maxLength": 1000 } } } } } }, "responses": { "200": { "description": "The collection", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionDetail" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Another collection has this handle", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Collections" ], "summary": "Delete a collection", "description": "Deletes the collection (its products stay in the catalog). A theme section naming it then shows nothing.", "operationId": "deleteCollection", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Collection id" }, "required": true, "description": "Collection id", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/collections/{id}/products": { "put": { "tags": [ "Collections" ], "summary": "Save a collection's products", "description": "Replaces the collection's products with this ordered list, at once. Every id must name a product, once.", "operationId": "saveCollectionProducts", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Collection id" }, "required": true, "description": "Collection id", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "description": "The collection's products, in order; replaces the list. At most 500." } }, "required": [ "productIds" ] } } } }, "responses": { "200": { "description": "The collection as saved", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/CollectionDetail" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "A product listed twice, or one that does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such collection", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/collections/{id}/translations": { "get": { "tags": [ "Collections" ], "summary": "Get a collection's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getCollectionTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Collections" ], "summary": "Translate a collection into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchCollectionTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100 }, "description": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 1000 } }, "additionalProperties": false } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/checkout-form": { "get": { "tags": [ "Checkout Form" ], "summary": "Get the checkout form policy", "description": "The storefront order form's configuration. A store that has never customised it returns the defaults, which describe the form exactly as it behaved before this feature existed.", "operationId": "getCheckoutForm", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The current policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/CheckoutFormPolicy" }, "capabilities": { "type": "object", "properties": { "builtInFields": { "type": "object", "additionalProperties": {} }, "customFieldTypes": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "builtInFields", "customFieldTypes", "limits" ], "description": "The server's own rules — allowed states per built-in field, the custom field types, and the authoring limits. The dashboard renders its editor from these rather than keeping a second copy of them." } }, "required": [ "policy", "capabilities" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Checkout Form" ], "summary": "Replace the checkout form policy", "description": "Replaces the whole policy — a key you omit takes its default rather than keeping the stored value, so what the screen shows is what the store gets.\n\n**Ids are server-owned.** Omit `id` on a field to create it; the response carries the minted id. An id the store does not already have is refused, because ids key the answer snapshots on existing orders.\n\n**Unknown keys are refused** rather than ignored, so a typo cannot silently vanish. Every problem is reported at once in `context.issues`.\n\nSaving the defaults clears the stored policy entirely (the column goes back to NULL), which is also the documented rollback for the feature.\n\nFixed fields — name, phone, wilaya, commune — are not configurable: COD dispatch, customer identity and delivery pricing all depend on them.", "operationId": "putCheckoutForm", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutFormPolicyInput" } } } }, "responses": { "200": { "description": "The saved policy", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "policy": { "$ref": "#/components/schemas/CheckoutFormPolicy" }, "capabilities": { "type": "object", "properties": { "builtInFields": { "type": "object", "additionalProperties": {} }, "customFieldTypes": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "builtInFields", "customFieldTypes", "limits" ], "description": "The server's own rules — allowed states per built-in field, the custom field types, and the authoring limits. The dashboard renders its editor from these rather than keeping a second copy of them." } }, "required": [ "policy", "capabilities" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "The policy was refused — see `context.issues`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps": { "get": { "tags": [ "Apps" ], "summary": "List the store's Apps", "description": "Every App the caller may see, with where it stands for this store.", "operationId": "listApps", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The Apps, in catalog order", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/App" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/apps/meta": { "delete": { "tags": [ "Apps" ], "summary": "Remove the meta App", "description": "Forgets the App's setup and every key it holds, as if it had never been set up. Its Built-in Consumers stay, with nothing to send.", "operationId": "removeMetaApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "get": { "tags": [ "Apps" ], "summary": "Get the Meta App", "description": "The store's Meta pixel and conversions setup, or `null` when the Meta App is not set up. The access token is never returned — only a masked hint.", "operationId": "getMetaApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The Meta App's setup (null when not set up)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/StorePixelConfig" } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Apps" ], "summary": "Set up the Meta App", "description": "Sets up the Meta App, or changes its setup. `conversionEvent` is required — the merchant chooses whether conversions optimize for `Lead` (sent at order placement, deduplicated with the browser pixel) or a `Purchase` stage. An empty `accessToken` keeps the stored token; omitting `perPageTrackingEnabled` keeps the stored switch.", "operationId": "saveMetaApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "pixelId": { "type": "string", "minLength": 1 }, "adAccountName": { "type": [ "string", "null" ], "maxLength": 200 }, "accessToken": { "type": "string", "default": "", "description": "Meta access token. Empty string keeps the stored token (it is never sent back)." }, "testEventCode": { "type": [ "string", "null" ] }, "conversionEvent": { "type": "string", "enum": [ "Purchase", "Purchase_Confirmed", "Purchase_Delivered", "Lead" ] }, "testMode": { "type": "boolean" }, "enabled": { "type": "boolean" }, "perPageTrackingEnabled": { "type": "boolean", "description": "Master switch for per-landing-page pixels. Omitted keeps the stored value — an unrelated edit must not return every landing page to the store pixel." } }, "required": [ "pixelId", "conversionEvent" ] } } } }, "responses": { "200": { "description": "The Meta App's setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StorePixelConfig" } }, "required": [ "success", "data" ] } } } } } } }, "/api/apps/dzverify": { "delete": { "tags": [ "Apps" ], "summary": "Remove the dzverify App", "description": "Forgets the App's setup and every key it holds, as if it had never been set up. Its Built-in Consumers stay, with nothing to send.", "operationId": "removeDzverifyApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "get": { "tags": [ "Apps" ], "summary": "Get the DZVerify App", "description": "The store's DZVerify setup, or `null` when it is not set up (no phone check). The API key is never returned — only a masked hint.", "operationId": "getDzverifyApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The DZVerify App's setup (null when not set up)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "language": { "type": "string", "enum": [ "en", "fr", "ar" ] }, "enabled": { "type": "boolean" }, "apiKeyMasked": { "type": "string", "example": "••••a9f2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "language", "enabled", "apiKeyMasked", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Apps" ], "summary": "Set up the DZVerify App", "description": "Sets up DZVerify, or changes its setup. An empty `apiKey` keeps the stored key; with no key stored or sent, it is refused.", "operationId": "saveDzverifyApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "default": "", "description": "dzverify API key. Empty string keeps the stored key (it is never sent back)." }, "language": { "type": "string", "enum": [ "en", "fr", "ar" ] }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The DZVerify App's setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "language": { "type": "string", "enum": [ "en", "fr", "ar" ] }, "enabled": { "type": "boolean" }, "apiKeyMasked": { "type": "string", "example": "••••a9f2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "language", "enabled", "apiKeyMasked", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No API key stored or sent (REQUIRED_FIELD_MISSING)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/turnstile": { "delete": { "tags": [ "Apps" ], "summary": "Remove the turnstile App", "description": "Forgets the App's setup and every key it holds, as if it had never been set up. Its Built-in Consumers stay, with nothing to send.", "operationId": "removeTurnstileApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "get": { "tags": [ "Apps" ], "summary": "Get the Turnstile App", "description": "The store's Turnstile setup, or `null` when it is not set up (no bot check). The secret key is never returned — only a masked hint.", "operationId": "getTurnstileApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The Turnstile App's setup (null when not set up)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "siteKey": { "type": "string", "description": "Public widget site key — rendered into storefront HTML.", "example": "0x4AAAAAAAxxxxxxxxxxxx" }, "enabled": { "type": "boolean" }, "secretKeyMasked": { "type": "string", "example": "••••a9f2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "siteKey", "enabled", "secretKeyMasked", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Apps" ], "summary": "Set up the Turnstile App", "description": "Sets up Turnstile, or changes its setup. An empty `siteKey` or `secretKey` keeps the stored one; with either missing altogether, it is refused.", "operationId": "saveTurnstileApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "siteKey": { "type": "string", "default": "", "description": "Public Turnstile site key. Empty string keeps the stored one." }, "secretKey": { "type": "string", "default": "", "description": "Siteverify secret key. Empty string keeps the stored one (it is never sent back)." }, "enabled": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The Turnstile App's setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "siteKey": { "type": "string", "description": "Public widget site key — rendered into storefront HTML.", "example": "0x4AAAAAAAxxxxxxxxxxxx" }, "enabled": { "type": "boolean" }, "secretKeyMasked": { "type": "string", "example": "••••a9f2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "siteKey", "enabled", "secretKeyMasked", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "A site or secret key missing (REQUIRED_FIELD_MISSING)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/sendili": { "delete": { "tags": [ "Apps" ], "summary": "Remove the sendili App", "description": "Forgets the App's setup and every key it holds, as if it had never been set up. Its Built-in Consumers stay, with nothing to send.", "operationId": "removeSendiliApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "get": { "tags": [ "Apps" ], "summary": "Get the Sendili App", "description": "The store's Sendili setup, or `null` when it is not set up (the store sends no email). The API key is never returned — only a masked hint.", "operationId": "getSendiliApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The Sendili App's setup (null when not set up)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "fromEmail": { "type": "string", "format": "email", "example": "noreply@acme.com" }, "fromName": { "type": [ "string", "null" ], "example": "Acme Store" }, "enabled": { "type": "boolean" }, "apiKeyMasked": { "type": "string", "example": "••••a9f2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "fromEmail", "fromName", "enabled", "apiKeyMasked", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Apps" ], "summary": "Set up the Sendili App", "description": "Sets up Sendili, or changes its setup. An empty `apiKey` keeps the stored key; with no key stored or sent, it is refused.", "operationId": "saveSendiliApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "default": "", "description": "Sendili API key. Empty string keeps the stored key (it is never sent back)." }, "fromEmail": { "type": "string", "format": "email", "description": "Sender address — its domain must be verified in the Sendili workspace.", "example": "noreply@acme.com" }, "fromName": { "type": [ "string", "null" ], "maxLength": 200, "description": "Optional sender display name (e.g. the store name).", "example": "Acme Store" }, "enabled": { "type": "boolean" } }, "required": [ "fromEmail" ] } } } }, "responses": { "200": { "description": "The Sendili App's setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": [ "object", "null" ], "properties": { "fromEmail": { "type": "string", "format": "email", "example": "noreply@acme.com" }, "fromName": { "type": [ "string", "null" ], "example": "Acme Store" }, "enabled": { "type": "boolean" }, "apiKeyMasked": { "type": "string", "example": "••••a9f2" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "fromEmail", "fromName", "enabled", "apiKeyMasked", "createdAt", "updatedAt" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No API key stored or sent (REQUIRED_FIELD_MISSING), or not an email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/whatsapp-button": { "delete": { "tags": [ "Apps" ], "summary": "Remove the whatsapp-button App", "description": "Forgets the App's setup and every key it holds, as if it had never been set up. Its Built-in Consumers stay, with nothing to send.", "operationId": "removeWhatsappButtonApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResponse" } } } } } }, "get": { "tags": [ "Apps" ], "summary": "Get the WhatsApp button App", "description": "The storefront's WhatsApp button. A store that never set it up gets the defaults, which are 'no button' — nothing renders until a number is saved and the button is switched on.", "operationId": "getWhatsAppButtonApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Its setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/WhatsAppButtonConfig" }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Where browsers fetch the avatar, from the store's Media Delivery" }, "preview": { "allOf": [ { "$ref": "#/components/schemas/StoreWhatsAppWidget" }, { "description": "Exactly what `/store/config` would hand the storefront for this configuration, or null when nothing would render. The same function produces both, so the dashboard's preview cannot drift from the shop window." } ] }, "capabilities": { "type": "object", "properties": { "textFields": { "type": "object", "additionalProperties": { "type": "object", "properties": { "max": { "type": "integer" } }, "required": [ "max" ] } }, "surfaces": { "type": "object", "additionalProperties": { "type": "object", "properties": { "default": { "type": "boolean" } }, "required": [ "default" ] } }, "surfaceOrder": { "type": "array", "items": { "type": "string" } }, "accents": { "type": "array", "items": { "type": "string" } }, "positions": { "type": "array", "items": { "type": "string" } }, "prefillTokens": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "textFields", "surfaces", "surfaceOrder", "accents", "positions", "prefillTokens", "limits" ], "description": "The server's own rules — the text caps, the surface registry and its display order, the allowed accents and sides, and the prefill tokens. The dashboard renders its editor from these rather than keeping a second copy of them." } }, "required": [ "config", "avatarUrl", "preview", "capabilities" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Apps" ], "summary": "Set up the WhatsApp button App", "description": "Replaces the whole configuration — a key you omit takes its default rather than keeping the stored value, so what the screen shows is what the store gets.\n\n**The number is normalised here, once.** Send it however the merchant typed it; it is stored in E.164 and every reader downstream sees the same string.\n\n**Switching the button on without a number is refused** (`PHONE_REQUIRED`): it would leave the merchant looking at an \"on\" switch and a storefront with no button.\n\n**Unknown keys are refused** rather than ignored, so a typo cannot silently vanish. Every problem is reported at once in `context.issues`.\n\nSaving the defaults clears the stored configuration entirely, as removing the App does.\n\nTurning every surface off is accepted — it is a deliberate \"paused\" state and keeps the merchant's text.", "operationId": "saveWhatsAppButtonApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WhatsAppButtonConfigInput" } } } }, "responses": { "200": { "description": "Its setup", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/WhatsAppButtonConfig" }, "avatarUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Where browsers fetch the avatar, from the store's Media Delivery" }, "preview": { "allOf": [ { "$ref": "#/components/schemas/StoreWhatsAppWidget" }, { "description": "Exactly what `/store/config` would hand the storefront for this configuration, or null when nothing would render. The same function produces both, so the dashboard's preview cannot drift from the shop window." } ] }, "capabilities": { "type": "object", "properties": { "textFields": { "type": "object", "additionalProperties": { "type": "object", "properties": { "max": { "type": "integer" } }, "required": [ "max" ] } }, "surfaces": { "type": "object", "additionalProperties": { "type": "object", "properties": { "default": { "type": "boolean" } }, "required": [ "default" ] } }, "surfaceOrder": { "type": "array", "items": { "type": "string" } }, "accents": { "type": "array", "items": { "type": "string" } }, "positions": { "type": "array", "items": { "type": "string" } }, "prefillTokens": { "type": "array", "items": { "type": "string" } }, "limits": { "type": "object", "additionalProperties": { "type": "number" } } }, "required": [ "textFields", "surfaces", "surfaceOrder", "accents", "positions", "prefillTokens", "limits" ], "description": "The server's own rules — the text caps, the surface registry and its display order, the allowed accents and sides, and the prefill tokens. The dashboard renders its editor from these rather than keeping a second copy of them." } }, "required": [ "config", "avatarUrl", "preview", "capabilities" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "The setup was refused — see `context.issues`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/dzverify/test": { "post": { "tags": [ "Apps" ], "summary": "Test the DZVerify key", "description": "Checks the stored (or sent) dzverify API key against the provider's quota. A key lacking the usage:read scope is valid with its quota unavailable. A refusal is a 200 with `ok: false` — the check itself worked.", "operationId": "testDzverifyApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Test this key instead of the stored one (before saving it)." } } } } } }, "responses": { "200": { "description": "What dzverify answered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string" }, "message": { "type": "string" }, "balanceDa": { "type": "number" }, "otpEstimate": { "type": "number", "description": "How many more codes the balance covers" }, "plan": { "type": "string" }, "outOfCredits": { "type": "boolean" } }, "required": [ "ok" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No API key stored or sent (REQUIRED_FIELD_MISSING)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "dzverify unreachable (EXTERNAL_API_FAILURE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/sendili/test": { "post": { "tags": [ "Apps" ], "summary": "Test the Sendili key", "description": "Checks the stored (or sent) Sendili API key and answers the verified sending domains for the from-address picker. A refusal is a 200 with `ok: false` — the check itself worked.", "operationId": "testSendiliApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Test this key instead of the stored one (before saving it)." } } } } } }, "responses": { "200": { "description": "What Sendili answered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "ok": { "type": "boolean" }, "reason": { "type": "string" }, "message": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Verified sending domains — for the from-address picker.", "example": [ "acme.com" ] }, "outOfCredits": { "type": "boolean" } }, "required": [ "ok" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No API key stored or sent (REQUIRED_FIELD_MISSING)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Sendili unreachable (EXTERNAL_API_FAILURE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/whatsapp-button/translations": { "get": { "tags": [ "Apps" ], "summary": "Get a whatsapp button's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getWhatsAppbuttonTranslations", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Apps" ], "summary": "Translate a whatsapp button into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchWhatsAppbuttonTranslations", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "caption": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 60 }, "welcomeMessage": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300 }, "launcherLabel": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 30 }, "ctaLabel": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 30 }, "prefillGeneral": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300 }, "prefillProduct": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300 }, "thankYouButtonLabel": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 40 }, "prefillThankYou": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 300 } }, "additionalProperties": false } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/apps/telegram": { "get": { "tags": [ "Apps" ], "summary": "Get the Telegram App", "description": "The store's bot, its connected chat, which events it tells and in which language, or `null` before a bot was ever saved. The token is never returned — only a masked hint.", "operationId": "getTelegramApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The Telegram App (null when never set up)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TelegramApp" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Apps" ], "summary": "Change the Telegram App", "description": "Which events the bot tells, in which language, and on or off. A change of events applies to what is recorded from then on.", "operationId": "changeTelegramApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TelegramChange" } } } }, "responses": { "200": { "description": "The Telegram App", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TelegramApp" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No events, or one that is not an Event Type (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "No bot saved (TELEGRAM_NOT_SET_UP), or turned on with no chat connected (TELEGRAM_NOT_CONNECTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Apps" ], "summary": "Remove the telegram App", "description": "Asks Telegram to stop sending the bot's updates (`deleteWebhook`), then forgets the bot: its token, its secret and its chat. Its Consumer stays, stopped, with its delivery history. The bot is forgotten even when Telegram cannot be told; `updatesStopped: false` says so.", "operationId": "removeTelegramApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "updatesStopped": { "type": "boolean" }, "error": { "type": [ "string", "null" ] } }, "required": [ "updatesStopped", "error" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/apps/telegram/bot": { "put": { "tags": [ "Apps" ], "summary": "Save the Telegram bot", "description": "Checks the token with Telegram (`getMe`), has Telegram send the bot's updates to this server (`setWebhook`, with a secret), and only then keeps it. Nothing is kept when either step fails. The same bot keeps its connected chat; another bot needs a chat connected again.", "operationId": "saveTelegramBot", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The bot token @BotFather gave. Checked with Telegram before anything is kept; never sent back." } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "The Telegram App", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/TelegramApp" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Telegram refused the token (TELEGRAM_TOKEN_REFUSED) or the webhook (TELEGRAM_REFUSED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "This server has no https public URL for Telegram to call (TELEGRAM_NEEDS_PUBLIC_URL)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "502": { "description": "Telegram unreachable (EXTERNAL_API_FAILURE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/telegram/pairing": { "post": { "tags": [ "Apps" ], "summary": "Open a Telegram pairing link", "description": "A `t.me` link to the bot carrying a one-time code: pressing Start on it connects that private chat. It works once, for 15 minutes, and replaces any link opened before.", "operationId": "openTelegramPairing", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The link and until when it works", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "example": "https://t.me/acme_orders_bot?start=Zx81…" }, "expiresAt": { "type": "string" } }, "required": [ "url", "expiresAt" ] } }, "required": [ "success", "data" ] } } } }, "409": { "description": "No bot saved yet (TELEGRAM_NOT_SET_UP)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/telegram/test": { "post": { "tags": [ "Apps" ], "summary": "Send a Telegram test message", "description": "Sends a test message to the connected chat now and answers what Telegram said. It is recorded nowhere. A refusal is a 200 with `delivered: false` — the test itself worked.", "operationId": "testTelegramApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "What Telegram answered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "delivered": { "type": "boolean" }, "httpStatus": { "type": [ "integer", "null" ] }, "reason": { "type": [ "string", "null" ], "enum": [ "unauthorized", "blocked", "chat_not_found", "bad_request", "rate_limited", "unavailable", "unreachable", null ] }, "error": { "type": [ "string", "null" ] } }, "required": [ "delivered", "httpStatus", "reason", "error" ] } }, "required": [ "success", "data" ] } } } }, "409": { "description": "No bot saved (TELEGRAM_NOT_SET_UP) or no chat connected (TELEGRAM_NOT_CONNECTED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/apps/reviews": { "get": { "tags": [ "Apps" ], "summary": "Get the Reviews App", "description": "The store's rules for its customers' reviews: whether it takes them, what a shopper may send, and what publishes without checking.", "operationId": "getReviewsApp", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The review rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ReviewRules" } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Apps" ], "summary": "Set the Reviews App's rules", "description": "Changes the rules given and keeps the others. Reviews already received keep the status they have.", "operationId": "saveReviewsApp", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "When false, reviews are hidden on the storefront and shoppers cannot send one", "example": true }, "maxPhotos": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Photos a shopper may add to a review, 0 (none) to 6", "example": 3 }, "voiceMaxSeconds": { "anyOf": [ { "type": "number", "enum": [ 30 ] }, { "type": "number", "enum": [ 60 ] }, { "type": "number", "enum": [ 90 ] }, { "type": "number", "enum": [ 120 ] }, { "type": "null" } ], "description": "Longest voice note a shopper may add, in seconds (30, 60, 90, 120); null = no voice notes", "example": 60 }, "autoPublish": { "type": "string", "enum": [ "off", "text_only", "all" ], "description": "Which shopper reviews publish without checking: none (off), text-only ones (text_only: anything with a photo or voice note waits), or all", "example": "text_only" } } } } } }, "responses": { "200": { "description": "The review rules now in force", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/ReviewRules" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "A rule outside its choices (VALIDATION_FAILED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipping-labels/settings": { "get": { "tags": [ "Shipping Labels" ], "summary": "Get the shipping-label settings", "description": "How the store's labels for its own drivers look, and the sender they print. A store that never set them gets the defaults.", "operationId": "getShippingLabelSettings", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "The settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/ShippingLabelConfig" }, "sender": { "$ref": "#/components/schemas/ShippingLabelSender" }, "legalPhone": { "type": [ "string", "null" ], "description": "The legal profile's contact phone: what prints when the settings name no sender phone" }, "currency": { "type": "object", "properties": { "code": { "type": "string" }, "symbol": { "type": "string" } }, "required": [ "code", "symbol" ] } }, "required": [ "config", "sender", "legalPhone", "currency" ] } }, "required": [ "success", "data" ] } } } } } }, "put": { "tags": [ "Shipping Labels" ], "summary": "Replace the shipping-label settings", "description": "Replaces the whole settings: a key you omit takes its default. Unknown keys are refused rather than ignored, and every problem is reported at once in `context.issues` (`path`, `code`). Saving the defaults stores nothing (the column goes back to NULL).", "operationId": "putShippingLabelSettings", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingLabelConfigInput" } } } }, "responses": { "200": { "description": "The saved settings", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/ShippingLabelConfig" }, "sender": { "$ref": "#/components/schemas/ShippingLabelSender" }, "legalPhone": { "type": [ "string", "null" ], "description": "The legal profile's contact phone: what prints when the settings name no sender phone" }, "currency": { "type": "object", "properties": { "code": { "type": "string" }, "symbol": { "type": "string" } }, "required": [ "code", "symbol" ] } }, "required": [ "config", "sender", "legalPhone", "currency" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "The settings were refused — see `context.issues`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipping-labels/delivery-sheet/{driverId}": { "get": { "tags": [ "Shipping Labels" ], "summary": "A driver's delivery sheet", "description": "Every parcel still out with the driver — not delivered, returned or cancelled — in the order they were given, with the cash each has to collect and the total, read in one trip.", "operationId": "getDriverDeliverySheet", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "driverId", "in": "path" } ], "responses": { "200": { "description": "The delivery sheet", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/ShippingLabelConfig" }, "sender": { "$ref": "#/components/schemas/ShippingLabelSender" }, "currency": { "type": "object", "properties": { "code": { "type": "string" }, "symbol": { "type": "string" } }, "required": [ "code", "symbol" ] }, "parcels": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingLabelParcel" } }, "driver": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } }, "required": [ "id", "name", "phone" ] }, "total": { "type": "object", "properties": { "parcels": { "type": "integer" }, "amount": { "type": "number" } }, "required": [ "parcels", "amount" ] } }, "required": [ "config", "sender", "currency", "parcels", "driver", "total" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Driver not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipping-labels": { "post": { "tags": [ "Shipping Labels" ], "summary": "The labels of driver shipments", "description": "Everything the labels of up to 100 driver shipments print, read in one trip: the settings, the sender, and each parcel — the customer, the place, the cash to collect, the lines, the notes and the driver — in the order asked. A carrier prints its own label (`GET /shipments/{id}/label`), so a carrier shipment, like an unknown id, is listed in `missing`. A read: nothing is written.", "operationId": "getDriverShippingLabels", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "shipmentIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 100 } }, "required": [ "shipmentIds" ] } } } }, "responses": { "200": { "description": "The labels", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/ShippingLabelConfig" }, "sender": { "$ref": "#/components/schemas/ShippingLabelSender" }, "currency": { "type": "object", "properties": { "code": { "type": "string" }, "symbol": { "type": "string" } }, "required": [ "code", "symbol" ] }, "parcels": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingLabelParcel" } }, "missing": { "type": "array", "items": { "type": "string" } } }, "required": [ "config", "sender", "currency", "parcels", "missing" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/shipping-profiles": { "get": { "tags": [ "Shipping Profiles" ], "summary": "List shipping profiles", "description": "Returns all shipping rate profiles with `ruleCount` (number of wilaya rules) and `productCount` (how many products override the store default with this profile).", "operationId": "listShippingProfiles", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of shipping profiles", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingProfile" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Shipping Profiles" ], "summary": "Create shipping profile", "description": "Creates a profile (rate-card metadata only). Use `PUT /{id}/rules` afterwards to populate wilaya rates. Setting `isDefault: true` atomically unsets the current default profile.", "operationId": "createShippingProfile", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "example": "Standard Rates" }, "isDefault": { "type": "boolean", "default": false }, "notes": { "type": [ "string", "null" ] } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Profile created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShippingProfileWithRules" } }, "required": [ "success", "data" ] } } } } } } }, "/api/shipping-profiles/default/rules": { "get": { "tags": [ "Shipping Profiles" ], "summary": "Get default-profile rules", "description": "Returns the wilaya rules of the currently-active default profile. Used by the order form to auto-fill `deliveryFee`. Returns an empty array if no profile is marked default.", "operationId": "getDefaultRules", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default profile rules (empty array if no default configured)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingRule" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/shipping-profiles/{id}": { "get": { "tags": [ "Shipping Profiles" ], "summary": "Get shipping profile", "description": "Returns a single profile with its full list of wilaya rules (including `homeEnabled` / `stopDeskEnabled`).", "operationId": "getShippingProfile", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Profile with rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShippingProfileWithRules" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Shipping Profiles" ], "summary": "Update shipping profile", "description": "Partial update of profile metadata. Include only the fields you want to change. Set `notes` to `null` to clear it.\n\n**Default invariant:** the system always keeps exactly one profile marked `isDefault`. Setting `isDefault: true` here atomically unsets the current default. Setting `isDefault: false` on the **only** default profile is rejected with `422 DEFAULT_PROFILE_REQUIRED`.", "operationId": "updateShippingProfile", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "isDefault": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] } } } } } }, "responses": { "200": { "description": "Profile updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShippingProfileWithRules" } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Cannot unset the last default profile — one profile must always be default (code: DEFAULT_PROFILE_REQUIRED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Shipping Profiles" ], "summary": "Delete shipping profile", "description": "Permanently deletes a profile and all of its wilaya rules (commune overrides cascade).\n\n**Blocked when:**\n- The profile is currently referenced by one or more products → `422 PROFILE_IN_USE`\n- The profile is the default profile → `422 DEFAULT_PROFILE_REQUIRED` (set another profile as default first)", "operationId": "deleteShippingProfile", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Profile deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "422": { "description": "Profile cannot be deleted — disambiguate via `code`: PROFILE_IN_USE or DEFAULT_PROFILE_REQUIRED", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipping-profiles/{id}/rules": { "put": { "tags": [ "Shipping Profiles" ], "summary": "Replace wilaya rules", "description": "Atomically replaces the full rules list for a profile — prior rules are deleted (commune overrides cascade) before new ones are inserted.\n\n**Constraints:**\n- Each `wilayaId` may appear **at most once** per profile. Duplicates are rejected with `DUPLICATE_WILAYA_RULE`.\n- Setting both `homeEnabled: false` and `stopDeskEnabled: false` on a wilaya effectively disables delivery for that wilaya under this profile.\n- Sending an empty `rules` array clears all rules for the profile.", "operationId": "setProfileRules", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "wilayaId": { "type": "integer", "minimum": 1, "maximum": 58 }, "homePrice": { "type": "number", "minimum": 0, "default": 0 }, "stopDeskPrice": { "type": "number", "minimum": 0, "default": 0 }, "homeEnabled": { "type": "boolean", "default": true }, "stopDeskEnabled": { "type": "boolean", "default": false } }, "required": [ "wilayaId" ] } } }, "required": [ "rules" ] } } } }, "responses": { "200": { "description": "Rules replaced — returns the profile with its new rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/ShippingProfileWithRules" } }, "required": [ "success", "data" ] } } } }, "400": { "description": "Validation error, including duplicate wilayaId in rules array (code: DUPLICATE_WILAYA_RULE)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/shipping-profiles/{id}/rules/{wilayaId}/communes": { "get": { "tags": [ "Shipping Profiles" ], "summary": "List commune overrides", "description": "Returns every commune in a wilaya with its override status. For each commune the response includes:\n\n- **Raw override fields** (`homeEnabled`, `stopDeskEnabled`, `homePrice`, `stopDeskPrice`) — `null` means that field inherits from the wilaya rule.\n- **Effective values** (`effectiveHome*`, `effectiveStopDesk*`) — the actual values used during fee resolution (commune override merged onto the wilaya defaults).\n- **hasOverride** — `true` if any override row exists for this commune.\n\nRequires that the profile already has a rule for the given wilaya — otherwise responds `404 SHIPPING_RULE_NOT_FOUND`.", "operationId": "listCommuneOverrides", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Wilaya ID (1–58)", "example": 16 }, "required": true, "description": "Wilaya ID (1–58)", "name": "wilayaId", "in": "path" } ], "responses": { "200": { "description": "All communes in this wilaya with override status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CommuneOverride" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/shipping-profiles/{id}/rules/{wilayaId}/communes/{communeId}": { "put": { "tags": [ "Shipping Profiles" ], "summary": "Set or update commune override", "description": "Upserts a commune-level override on top of the wilaya rule.\n\n**Semantics:**\n- Any field set to `null` (or omitted — which is treated as null) **inherits** from the wilaya rule at fee-resolution time.\n- If **all four** override fields (`homeEnabled`, `stopDeskEnabled`, `homePrice`, `stopDeskPrice`) are null, the override row is deleted (equivalent to `DELETE`).\n- Prices must be ≥ 0 when provided.\n\n**Effects on orders:** subsequent online orders with this wilaya + commune pair will use the overridden values. Disabling `homeEnabled` or `stopDeskEnabled` causes `422 DELIVERY_NOT_AVAILABLE` at order creation for that mode.", "operationId": "setCommuneOverride", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Wilaya ID (1–58)", "example": 16 }, "required": true, "description": "Wilaya ID (1–58)", "name": "wilayaId", "in": "path" }, { "schema": { "type": "string", "description": "Commune ID", "example": "c-16-001" }, "required": true, "description": "Commune ID", "name": "communeId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "homeEnabled": { "type": [ "boolean", "null" ] }, "stopDeskEnabled": { "type": [ "boolean", "null" ] }, "homePrice": { "type": [ "number", "null" ], "minimum": 0 }, "stopDeskPrice": { "type": [ "number", "null" ], "minimum": 0 } } } } } }, "responses": { "200": { "description": "Override upserted (or removed if all fields null)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } }, "delete": { "tags": [ "Shipping Profiles" ], "summary": "Remove commune override", "description": "Removes the commune override row — the commune will again inherit the wilaya rule. Returns `404 COMMUNE_OVERRIDE_NOT_FOUND` if no override row exists for this commune.", "operationId": "deleteCommuneOverride", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Shipping profile ID", "example": "profile_123" }, "required": true, "description": "Shipping profile ID", "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 58, "description": "Wilaya ID (1–58)", "example": 16 }, "required": true, "description": "Wilaya ID (1–58)", "name": "wilayaId", "in": "path" }, { "schema": { "type": "string", "description": "Commune ID", "example": "c-16-001" }, "required": true, "description": "Commune ID", "name": "communeId", "in": "path" } ], "responses": { "200": { "description": "Override removed — commune reverts to wilaya defaults", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/driver-payments": { "post": { "tags": [ "Driver Payments" ], "summary": "Create driver payment", "description": "Record a payment that settles delivered shipments of one driver. Each shipment has two parts to settle, once each: the **cash** the driver collected and the driver's **fee**.\n\n- `cod_remittance` — the driver hands over the cash: settles the cash part; the driver's `pendingCash` drops and `totalPaid` rises by the cash total.\n- `fee_payment` — the store pays the driver's fees: settles the fee part; the cash counters do not move.\n- `net_settlement` — both at once: the driver hands over the cash less the fees.\n\n**The amount is computed, never sent:** the shipments' frozen `codAmount` and `driverFee` give `sum(codAmount)`, `sum(driverFee)` or their difference. The payment, its lines and the driver's counters are one atomic write; a part already settled — even by a payment recorded at the same moment — refuses the whole payment.\n\n`createdBy` and `createdByName` come from the authenticated user.", "operationId": "createDriverPayment", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "driverId": { "type": "string", "minLength": 1, "description": "The UUID of the driver receiving or making the payment" }, "type": { "type": "string", "enum": [ "cod_remittance", "fee_payment", "net_settlement" ], "description": "'cod_remittance' (the driver hands over the cash collected), 'fee_payment' (the store pays the driver's fees), or 'net_settlement' (both at once: the cash less the fees)" }, "shipmentIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 500, "description": "The driver's delivered shipments this payment settles" }, "notes": { "type": "string", "description": "Internal notes about this payment record" } }, "required": [ "driverId", "type", "shipmentIds" ] } } } }, "responses": { "201": { "description": "Payment recorded. Returns the new payment record.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/DriverPayment" }, "message": { "type": "string", "example": "Operation completed successfully" } }, "required": [ "success", "data", "message" ] } } } }, "422": { "description": "Nothing was recorded. Distinguish via `code`:\n- `SHIPMENT_NOT_SETTLEABLE` — a shipment is not one of this driver's delivered shipments (`context.shipmentIds`)\n- `PAYMENT_ALREADY_SETTLED` — a part this payment settles already is (`context.kind`: `\"cod\"` or `\"fee\"`; `context.shipmentIds`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/driver-payments/{driverId}": { "get": { "tags": [ "Driver Payments" ], "summary": "List driver payment history", "description": "All payment records of a driver, newest first; an empty array when there are none or the driver does not exist.", "operationId": "listDriverPayments", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "UUID of the driver" }, "required": true, "description": "UUID of the driver", "name": "driverId", "in": "path" } ], "responses": { "200": { "description": "Payment history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DriverPayment" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/driver-payments/{driverId}/pending": { "get": { "tags": [ "Driver Payments" ], "summary": "List shipments awaiting settlement", "description": "The driver's delivered shipments with a part still to settle — the cash (`codPaymentId` null), the fee (`feePaymentId` null), or both — newest delivery first. Use it to prepare a payment.", "operationId": "listPendingSettlements", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "UUID of the driver" }, "required": true, "description": "UUID of the driver", "name": "driverId", "in": "path" } ], "responses": { "200": { "description": "Shipments awaiting settlement (empty array when none)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PendingSettlement" } } }, "required": [ "success", "data" ] } } } } } } }, "/api/stores/me": { "get": { "tags": [ "Store Settings" ], "summary": "Get store configuration", "description": "Returns the current store's configuration including branding, theme, localization, SEO, and storefront settings.", "operationId": "getMyStore", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Store configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Store" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Store Settings" ], "summary": "Update store configuration", "description": "Partially updates the store configuration. All fields are optional — only include the fields you want to change. Set nullable fields to `null` to clear them.", "operationId": "updateMyStore", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "logoKey": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "domain": { "type": [ "string", "null" ], "maxLength": 200, "pattern": "^[a-z0-9][a-z0-9.-]*\\.[a-z]{2,}$/i" }, "lang": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "languages": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] }, "minItems": 1, "maxItems": 3 }, "currencySymbol": { "type": "string", "minLength": 1, "maxLength": 10 }, "metaTitle": { "type": [ "string", "null" ], "maxLength": 200 }, "metaDescription": { "type": [ "string", "null" ], "maxLength": 500 }, "ogImageKey": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 512, "description": "A Media Key: the image's identity in the store's media. Never a URL.", "example": "products/3f2a9c0b1d2e4f5061728394a5b6c7d8.webp" }, "cartEnabled": { "type": "boolean" }, "freeShippingThreshold": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 10000000 }, "cartShippingMode": { "type": "string", "enum": [ "highest", "default_profile" ] } } } } } }, "responses": { "200": { "description": "Updated store configuration", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Store" } }, "required": [ "success", "data" ] } } } } } } }, "/api/stores/me/translations": { "get": { "tags": [ "Store Settings" ], "summary": "Get a store's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getStoreTranslations", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Store Settings" ], "summary": "Translate a store into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchStoreTranslations", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "metaTitle": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "metaDescription": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500 }, "currencySymbol": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 10 } }, "additionalProperties": false } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/reviews": { "get": { "tags": [ "Reviews" ], "summary": "List reviews", "description": "Reviews newest first, with their photos and voice note, filtered by status, product, who entered them, or having media. A review whose files are still being prepared is not listed yet.", "operationId": "listReviews", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "Filter by moderation status" }, "required": false, "description": "Filter by moderation status", "name": "status", "in": "query" }, { "schema": { "type": "string", "description": "Filter by product ID" }, "required": false, "description": "Filter by product ID", "name": "productId", "in": "query" }, { "schema": { "type": "string", "enum": [ "storefront", "merchant" ], "description": "Sent by a shopper (storefront) or entered by the store (merchant)" }, "required": false, "description": "Sent by a shopper (storefront) or entered by the store (merchant)", "name": "source", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "Only reviews with a photo or a voice note" }, "required": false, "description": "Only reviews with a photo or a voice note", "name": "withMedia", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "One page of reviews", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "count": { "type": "integer" }, "total": { "type": "integer", "description": "Matching reviews across all pages" }, "pendingCount": { "type": "integer", "description": "Reviews waiting for a decision, whatever the filters (the badge)" } }, "required": [ "success", "data", "count", "total", "pendingCount" ] } } } } } }, "post": { "tags": [ "Reviews" ], "summary": "Enter a review a customer gave the store", "description": "For a review received by WhatsApp, phone or in person. It names the product and a customer (from the list, or a typed name) and may rest on one of the customer's orders that brought the product — **only a delivered one makes it a verified purchase**. It carries today's date. Photos and a voice note are sent first to `POST /api/reviews/uploads`; with them the review is prepared in the background (`status: processing`, then published or pending).", "operationId": "createReview", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "customerId": { "type": [ "string", "null" ], "minLength": 1, "description": "A customer of the list; their name is shown unless customerName is given" }, "customerName": { "type": [ "string", "null" ], "maxLength": 80, "description": "The name shown; required without a customer" }, "orderId": { "type": [ "string", "null" ], "minLength": 1, "description": "One of the customer's orders that brought the product — a delivered one makes it a verified purchase" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": [ "string", "null" ], "maxLength": 150 }, "body": { "type": "string", "maxLength": 2000, "default": "", "description": "At least 10 characters, unless a voice note says it" }, "uploads": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "maxItems": 8, "description": "Upload IDs from POST /api/reviews/uploads" }, "publish": { "type": "boolean", "default": true, "description": "Publish at once (default), or keep it pending" } }, "required": [ "productId", "rating" ] } } } }, "responses": { "201": { "description": "Review entered", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "processing", "pending", "approved" ] }, "verified": { "type": "boolean" }, "review": { "allOf": [ { "$ref": "#/components/schemas/Review" }, { "type": [ "object", "null" ], "description": "null while its files are being prepared" } ] } }, "required": [ "id", "status", "verified", "review" ] } }, "required": [ "success", "data" ] } } } }, "404": { "description": "Unknown product or customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "This product was already reviewed from this order (ORDER_ALREADY_REVIEWED)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The order did not bring this product, or a file problem (PRODUCT_NOT_IN_ORDER / REVIEW_UPLOAD_NOT_FOUND / REVIEW_MEDIA_LIMIT)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/reviews/order-options": { "get": { "tags": [ "Reviews" ], "summary": "A customer's orders that brought a product", "description": "What a store review may rest on: the customer's orders that brought this product and that they kept, newest first, each saying whether it was delivered and already reviewed.", "operationId": "listReviewOrderOptions", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "customerId", "in": "query" }, { "schema": { "type": "string", "minLength": 1 }, "required": true, "name": "productId", "in": "query" } ], "responses": { "200": { "description": "The orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orderNumber": { "type": "string" }, "createdAt": { "type": "string" }, "delivered": { "type": "boolean" }, "reviewed": { "type": "boolean" } }, "required": [ "id", "orderNumber", "createdAt", "delivered", "reviewed" ] } } }, "required": [ "success", "data" ] } } } } } } }, "/api/reviews/uploads": { "post": { "tags": [ "Reviews" ], "summary": "Send a photo or voice note for a review being entered", "description": "The file itself as the request body (a photo, or a voice note up to 120 s; its length as recorded in **X-Media-Duration-Ms** when known). Name the returned `uploadId`s when creating the review.", "operationId": "uploadReviewMedia", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "responses": { "201": { "description": "Received", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "uploadId": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "audio" ] }, "bytes": { "type": "integer" } }, "required": [ "uploadId", "kind", "bytes" ] } }, "required": [ "success", "data" ] } } } }, "400": { "description": "No file, too large, or not a photo or voice note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/reviews/{id}": { "get": { "tags": [ "Reviews" ], "summary": "Get a review", "description": "One review with its photos and voice note.", "operationId": "getReview", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Review ID" }, "required": true, "description": "Review ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "The review", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Review" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such review (REVIEW_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "patch": { "tags": [ "Reviews" ], "summary": "Approve, reject, or re-queue a review", "description": "approved shows it on the storefront and counts it in the product's rating; rejected hides it; pending puts it back in the queue.", "operationId": "updateReview", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Review ID" }, "required": true, "description": "Review ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "approved", "rejected" ], "description": "New moderation status" } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "The review with its new status", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Review" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such review (REVIEW_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "delete": { "tags": [ "Reviews" ], "summary": "Delete a review", "description": "Removes the review for good, its photos and voice note with it.", "operationId": "deleteReview", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Review ID" }, "required": true, "description": "Review ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Review deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ] } } } }, "404": { "description": "No such review (REVIEW_NOT_FOUND)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/reviews/{id}/media/{mediaId}": { "delete": { "tags": [ "Reviews" ], "summary": "Remove a review's photo or voice note", "description": "Takes one file off the review — a face, a phone number — and keeps the review.", "operationId": "deleteReviewMedia", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": true, "name": "mediaId", "in": "path" } ], "responses": { "200": { "description": "The review without that file", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Review" } }, "required": [ "success", "data" ] } } } }, "404": { "description": "No such review or file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/offers": { "get": { "tags": [ "Offers" ], "summary": "List offers", "description": "Get all Buy X Get Y promotional offers ordered by creation date (newest first).", "operationId": "listOffers", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of offers", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Offer" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Offers" ], "summary": "Create offer", "description": "Create a new Buy X Get Y promotional offer.\n\n**Auto-application rules (applied at order time, not here):**\n- When a store order is submitted via `POST /store/orders`, the server checks for any active offer\n where `triggerProductId` matches, the ordered quantity ≥ `triggerQuantity`, and — if `triggerVariantId`\n is set — the ordered variantId also matches.\n- If the reward item is out of stock, the offer is silently skipped (order still succeeds).\n- The reward is inserted as a `$0` order line item; the COD total only reflects paid products + delivery.", "operationId": "createOffer", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "discountType": { "type": "string", "enum": [ "free", "free_shipping", "quantity_price" ], "default": "free" }, "triggerProductId": { "type": "string", "minLength": 1 }, "triggerVariantId": { "type": [ "string", "null" ], "minLength": 1 }, "triggerQuantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "rewardProductId": { "type": [ "string", "null" ], "minLength": 1 }, "rewardVariantId": { "type": [ "string", "null" ], "minLength": 1 }, "rewardQuantity": { "type": "integer", "minimum": 0, "maximum": 1000 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "price": { "type": "integer", "minimum": 0 }, "freeShipping": { "type": "boolean", "default": false } }, "required": [ "quantity", "price" ] }, "maxItems": 10 }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" } }, "required": [ "name", "triggerProductId" ] } } } }, "responses": { "201": { "description": "Offer created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Offer" } }, "required": [ "success", "data" ] } } } } } } }, "/api/offers/{id}": { "get": { "tags": [ "Offers" ], "summary": "Get offer", "description": "Get a single offer by ID with fully resolved product and variant references.", "operationId": "getOffer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Offer UUID", "example": "off_abc123" }, "required": true, "description": "Offer UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Offer details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Offer" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Offers" ], "summary": "Update offer", "description": "Partially update an offer. All fields are optional — send only the fields you want to change.", "operationId": "updateOffer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Offer UUID", "example": "off_abc123" }, "required": true, "description": "Offer UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 200 }, "discountType": { "type": "string", "enum": [ "free", "free_shipping", "quantity_price" ] }, "triggerProductId": { "type": "string", "minLength": 1 }, "triggerVariantId": { "type": [ "string", "null" ], "minLength": 1 }, "triggerQuantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "rewardProductId": { "type": [ "string", "null" ], "minLength": 1 }, "rewardVariantId": { "type": [ "string", "null" ], "minLength": 1 }, "rewardQuantity": { "type": "integer", "minimum": 0, "maximum": 1000 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "price": { "type": "integer", "minimum": 0 }, "freeShipping": { "type": "boolean", "default": false } }, "required": [ "quantity", "price" ] }, "maxItems": 10 }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } } } } }, "responses": { "200": { "description": "Updated offer", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Offer" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Offers" ], "summary": "Delete offer", "description": "Permanently delete an offer. Already-placed orders are not affected.", "operationId": "deleteOffer", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Offer UUID", "example": "off_abc123" }, "required": true, "description": "Offer UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Offer deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/offers/{id}/translations": { "get": { "tags": [ "Offers" ], "summary": "Get a offer's translations", "description": "The translatable fields in the store's primary language and every stored translation, each flagged `outdated` when its source text changed after it was written.", "operationId": "getOfferTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Source and translations", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Offers" ], "summary": "Translate a offer into one language", "description": "A JSON Merge Patch (RFC 7396) of one language: a string sets a field, `null` removes its translation, other fields are untouched. The language must be one the store has added, and not its primary — the resource's own fields hold that.", "operationId": "patchOfferTranslations", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "values": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 } }, "additionalProperties": false } }, "required": [ "locale", "values" ] } } } }, "responses": { "200": { "description": "Source and translations after the patch", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "resource": { "type": "string" }, "id": { "type": "string" }, "sourceLocale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "targetLocales": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "ar", "fr", "en" ] }, "published": { "type": "boolean" } }, "required": [ "locale", "published" ] } }, "source": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] } }, "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "key": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "key": { "type": "string" } }, "required": [ "value", "key" ] } } }, "required": [ "name", "key", "values" ] } }, "translations": { "type": "object", "properties": { "ar": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "fr": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } }, "en": { "type": "object", "additionalProperties": { "type": "object", "properties": { "value": { "type": "string" }, "outdated": { "type": "boolean" } }, "required": [ "value", "outdated" ] } } } } }, "required": [ "resource", "id", "sourceLocale", "targetLocales", "source", "options", "translations" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/coupons": { "get": { "tags": [ "Coupons" ], "summary": "List coupons", "description": "Every coupon, newest first, with where it stands, its uses and the discount it gave.", "operationId": "listCoupons", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of coupons", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CouponSummary" } }, "count": { "type": "integer", "description": "Number of items returned" } }, "required": [ "success", "data", "count" ] } } } } } }, "post": { "tags": [ "Coupons" ], "summary": "Create coupon", "description": "Create a coupon.\n\n**How it applies (at checkout, not here):** after offers, to the paid lines in its scope that no offer applied to.\nIts discount is shared across those lines, so the order's price stays the sum of its lines.\nA use is an order with the coupon that is not cancelled; the usage limit and one use per customer are enforced by the database when the order is placed.\n\nRefused with `INVALID_COUPON` (`reason` says why) or `COUPON_CODE_TAKEN`.", "operationId": "createCoupon", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "What the shopper types. Stored upper case without spaces; Latin letters, digits, - and _, 3 to 32 long; Arabic-Indic digits are read as 0–9.", "example": "RAMADAN10" }, "kind": { "type": "string", "enum": [ "percentage", "fixed_amount", "free_shipping" ] }, "value": { "type": "integer", "minimum": 0, "description": "Percent (1–100) for `percentage`, dinars for `fixed_amount`; none for `free_shipping`." }, "maxDiscount": { "type": [ "integer", "null" ], "minimum": 1, "description": "The most a `percentage` coupon takes off one order." }, "minSubtotal": { "type": [ "integer", "null" ], "minimum": 1, "description": "What the eligible products must cost together. Never beside `minQuantity`." }, "minQuantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many eligible items the order must hold. Never beside `minSubtotal`." }, "scope": { "type": "string", "enum": [ "store", "products", "collections" ], "default": "store" }, "productIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "description": "The products a `products` coupon covers. At most 500." }, "collectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 100, "description": "The collections a `collections` coupon covers. At most 100." }, "audience": { "type": "string", "enum": [ "everyone", "selected" ], "default": "everyone" }, "customerIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 1000, "description": "Customers a `selected` coupon admits. At most 1000." }, "groupIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Customer groups whose members a `selected` coupon admits. At most 50." }, "usageLimit": { "type": [ "integer", "null" ], "minimum": 1, "description": "Orders that may use it, across all customers; cancelled orders do not count." }, "oncePerCustomer": { "type": "boolean" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active" } }, "required": [ "code", "kind" ] } } } }, "responses": { "201": { "description": "Coupon created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Coupon" } }, "required": [ "success", "data" ] } } } } } } }, "/api/coupons/{id}": { "get": { "tags": [ "Coupons" ], "summary": "Get coupon", "description": "A coupon with the products, collections, customers and groups it names.", "operationId": "getCoupon", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Coupon UUID" }, "required": true, "description": "Coupon UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Coupon details", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Coupon" } }, "required": [ "success", "data" ] } } } } } }, "patch": { "tags": [ "Coupons" ], "summary": "Update coupon", "description": "Partially update a coupon; the coupon it leaves is judged whole. A change of kind starts its value afresh, a change of scope or audience its picks. Orders already placed keep what they were given.", "operationId": "updateCoupon", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Coupon UUID" }, "required": true, "description": "Coupon UUID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "minLength": 1, "maxLength": 64, "description": "What the shopper types. Stored upper case without spaces; Latin letters, digits, - and _, 3 to 32 long; Arabic-Indic digits are read as 0–9.", "example": "RAMADAN10" }, "kind": { "type": "string", "enum": [ "percentage", "fixed_amount", "free_shipping" ] }, "value": { "type": "integer", "minimum": 0, "description": "Percent (1–100) for `percentage`, dinars for `fixed_amount`; none for `free_shipping`." }, "maxDiscount": { "type": [ "integer", "null" ], "minimum": 1, "description": "The most a `percentage` coupon takes off one order." }, "minSubtotal": { "type": [ "integer", "null" ], "minimum": 1, "description": "What the eligible products must cost together. Never beside `minQuantity`." }, "minQuantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "How many eligible items the order must hold. Never beside `minSubtotal`." }, "scope": { "type": "string", "enum": [ "store", "products", "collections" ] }, "productIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "description": "The products a `products` coupon covers. At most 500." }, "collectionIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 100, "description": "The collections a `collections` coupon covers. At most 100." }, "audience": { "type": "string", "enum": [ "everyone", "selected" ] }, "customerIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 1000, "description": "Customers a `selected` coupon admits. At most 1000." }, "groupIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 50, "description": "Customer groups whose members a `selected` coupon admits. At most 50." }, "usageLimit": { "type": [ "integer", "null" ], "minimum": 1, "description": "Orders that may use it, across all customers; cancelled orders do not count." }, "oncePerCustomer": { "type": "boolean" }, "startsAt": { "type": [ "string", "null" ], "format": "date-time" }, "endsAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } } } } } }, "responses": { "200": { "description": "Updated coupon", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/Coupon" } }, "required": [ "success", "data" ] } } } } } }, "delete": { "tags": [ "Coupons" ], "summary": "Delete coupon", "description": "Permanently delete a coupon. Orders that used it keep its code and the discount they were given.", "operationId": "deleteCoupon", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Coupon UUID" }, "required": true, "description": "Coupon UUID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Coupon deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/stock/overview": { "get": { "tags": [ "Stock" ], "summary": "Stock overview", "description": "Returns aggregated inventory health metrics across all tracked SKUs. Includes counters, total inventory value, and segmented lists of out-of-stock and low-stock items.", "operationId": "getStockOverview", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Stock health overview", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/StockOverview" } }, "required": [ "success", "data" ] } } } } } } }, "/api/stock/alerts": { "get": { "tags": [ "Stock" ], "summary": "Low stock and out-of-stock alerts", "description": "Paginated list of all SKUs at or below their low stock threshold (includes out-of-stock). Sorted: out-of-stock first, then by inventory ascending.", "operationId": "getStockAlerts", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Paginated alert items", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/StockAlertItem" } }, "total": { "type": "integer", "description": "Total alert items (for pagination).", "example": 10 } }, "required": [ "items", "total" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/products/{id}/stock/adjust": { "post": { "tags": [ "Stock" ], "summary": "Adjust stock for a simple product", "description": "Applies a signed integer delta to a simple product's inventory and appends a movement log entry.\n\n**`reason` is required for types:** `ADJUSTMENT_ADD`, `ADJUSTMENT_REMOVE`, `OFFLINE_SALE`.\n\n**Delta sign convention:** positive = stock arriving, negative = stock leaving. The server rejects adjustments that would result in negative inventory (HTTP 422).", "operationId": "adjustProductStock", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PURCHASE", "ADJUSTMENT_ADD", "ADJUSTMENT_REMOVE", "ORDER_DEDUCTED", "ORDER_CANCELLED", "ORDER_RETURNED", "OFFLINE_SALE" ] }, "delta": { "type": "integer" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "type", "delta" ] } } } }, "responses": { "200": { "description": "Stock adjusted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "movement": { "$ref": "#/components/schemas/StockMovement" }, "currentInventory": { "type": "integer", "description": "Inventory level after the adjustment.", "example": 15 } }, "required": [ "movement", "currentInventory" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Adjustment would result in negative inventory (INSUFFICIENT_STOCK). Context includes `stockId`, `productName`, `available`, and `required`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products/{id}/stock/history": { "get": { "tags": [ "Stock" ], "summary": "Stock movement history for a product", "description": "Paginated movement log for a product. Use `variantId` to narrow to a specific variant's history. Results are ordered newest-first.", "operationId": "getProductStockHistory", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" }, { "schema": { "type": "string" }, "required": false, "name": "variantId", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 20 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Paginated movement history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "movements": { "type": "array", "items": { "$ref": "#/components/schemas/StockMovement" } }, "total": { "type": "integer", "description": "Total matching movements (for pagination).", "example": 25 } }, "required": [ "movements", "total" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/products/{id}/stock/threshold": { "patch": { "tags": [ "Stock" ], "summary": "Update low stock threshold for a simple product", "description": "Sets the `lowStockThreshold` for a simple (non-variant) product. When inventory drops at or below this value, the product appears in stock alerts.", "operationId": "updateProductThreshold", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lowStockThreshold": { "type": "integer", "minimum": 0, "maximum": 9999 } }, "required": [ "lowStockThreshold" ] } } } }, "responses": { "200": { "description": "Threshold updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/products/{productId}/variants/{variantId}/stock/adjust": { "post": { "tags": [ "Stock" ], "summary": "Adjust stock for a product variant", "description": "Same semantics as the simple-product adjust endpoint but targets a specific variant. The `variantId` must belong to `productId`.", "operationId": "adjustVariantStock", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" }, { "schema": { "type": "string", "description": "Variant ID", "example": "var_abc123" }, "required": true, "description": "Variant ID", "name": "variantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PURCHASE", "ADJUSTMENT_ADD", "ADJUSTMENT_REMOVE", "ORDER_DEDUCTED", "ORDER_CANCELLED", "ORDER_RETURNED", "OFFLINE_SALE" ] }, "delta": { "type": "integer" }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "type", "delta" ] } } } }, "responses": { "200": { "description": "Variant stock adjusted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "movement": { "$ref": "#/components/schemas/StockMovement" }, "currentInventory": { "type": "integer", "description": "Inventory level after the adjustment.", "example": 15 } }, "required": [ "movement", "currentInventory" ] } }, "required": [ "success", "data" ] } } } }, "422": { "description": "Adjustment would result in negative inventory (INSUFFICIENT_STOCK)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/products/{productId}/variants/{variantId}/stock/threshold": { "patch": { "tags": [ "Stock" ], "summary": "Update low stock threshold for a variant", "description": "Sets the `lowStockThreshold` for a specific product variant. The variant must belong to the specified product.", "operationId": "updateVariantThreshold", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Product ID", "example": "prod_abc123" }, "required": true, "description": "Product ID", "name": "productId", "in": "path" }, { "schema": { "type": "string", "description": "Variant ID", "example": "var_abc123" }, "required": true, "description": "Variant ID", "name": "variantId", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "lowStockThreshold": { "type": "integer", "minimum": 0, "maximum": 9999 } }, "required": [ "lowStockThreshold" ] } } } }, "responses": { "200": { "description": "Threshold updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/analytics/order-stages": { "get": { "tags": [ "Analytics" ], "summary": "Orders by stage", "description": "Orders counted by the stage the merchant sees — their processing, then their shipment's delivery (the same stage as `GET /api/orders/{id}`) — with only the stages that have orders, how many orders need the merchant's attention, and how many are archived; `archived=exclude` leaves archived orders out of the stages, as the working lists do (an unknown handoff, a parcel the carrier cancelled or flagged).", "operationId": "getOrderStageStats", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "include", "exclude" ], "default": "include", "description": "Count archived orders in the stages (include — every order, as sales do) or leave them out (exclude — the working lists' counts)" }, "required": false, "description": "Count archived orders in the stages (include — every order, as sales do) or leave them out (exclude — the working lists' counts)", "name": "archived", "in": "query" } ], "responses": { "200": { "description": "Orders per stage, and the count needing attention", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "stages": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "new", "confirmed", "unreachable", "preparing", "ready_to_ship", "handoff_pending", "in_transit", "out_for_delivery", "delivered", "returning", "returned", "delivery_cancelled", "cancelled" ] }, "count": { "type": "integer", "example": 12 } }, "required": [ "stage", "count" ] } }, "needsAttention": { "type": "integer", "example": 3 }, "archived": { "type": "integer", "description": "Archived orders", "example": 40 } }, "required": [ "stages", "needsAttention", "archived" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/analytics/order-activity": { "get": { "tags": [ "Analytics" ], "summary": "Orders placed per day", "description": "Orders placed per store day (Algeria, UTC+1) over the last `days` days, today included, and what they are worth (price plus delivery fee), with the totals of the same number of days just before for comparison. Cancelled orders are left out. Only days with orders appear.", "operationId": "getOrderActivity", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "7", "30", "90" ], "default": "30", "description": "How many days the window spans", "example": "30" }, "required": false, "description": "How many days the window spans", "name": "days", "in": "query" } ], "responses": { "200": { "description": "Orders and sales per day, and the previous window's totals", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "from": { "type": "string", "example": "2026-09-17" }, "to": { "type": "string", "example": "2026-10-16" }, "days": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "example": "2026-10-16" }, "orders": { "type": "integer", "example": 14 }, "sales": { "type": "number", "example": 52400 } }, "required": [ "date", "orders", "sales" ] } }, "previous": { "type": "object", "properties": { "orders": { "type": "integer" }, "sales": { "type": "number" } }, "required": [ "orders", "sales" ] } }, "required": [ "from", "to", "days", "previous" ] } }, "required": [ "success", "data" ] } } } } } } }, "/api/abandoned-orders": { "get": { "tags": [ "Abandoned Orders" ], "summary": "List abandoned orders", "description": "Paginated list of abandoned checkouts, newest first. Filter by recovery status or search by customer name / phone / session.", "operationId": "listAbandonedOrders", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "pending", "abandoned", "contacted", "converted" ], "description": "Filter by recovery status" }, "required": false, "description": "Filter by recovery status", "name": "status", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "search", "in": "query" }, { "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "default": 0 }, "required": false, "name": "offset", "in": "query" } ], "responses": { "200": { "description": "Paginated abandoned orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AbandonedOrder" } }, "total": { "type": "integer", "description": "Total matching records (for pagination)", "example": 42 }, "limit": { "type": "integer", "example": 50 }, "offset": { "type": "integer", "example": 0 } }, "required": [ "success", "data", "total", "limit", "offset" ] } } } } } } }, "/api/abandoned-orders/stats": { "get": { "tags": [ "Abandoned Orders" ], "summary": "Abandoned order statistics", "description": "Summary metrics for the recovery workflow: counts of abandoned vs converted checkouts, the recovered percentage, and estimated lost revenue still on the table.", "operationId": "getAbandonedOrderStats", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Recovery statistics", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "$ref": "#/components/schemas/AbandonedOrderStats" } }, "required": [ "success", "data" ] } } } } } } }, "/api/abandoned-orders/{id}/status": { "patch": { "tags": [ "Abandoned Orders" ], "summary": "Update abandoned order status", "description": "Advances the recovery status of an abandoned checkout (pending → contacted → converted, or mark as abandoned).", "operationId": "updateAbandonedOrderStatus", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Abandoned order ID" }, "required": true, "description": "Abandoned order ID", "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "abandoned", "contacted", "converted" ] } }, "required": [ "status" ] } } } }, "responses": { "200": { "description": "Status updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } }, "/api/abandoned-orders/{id}": { "delete": { "tags": [ "Abandoned Orders" ], "summary": "Delete abandoned order", "description": "Permanently removes an abandoned checkout record.", "operationId": "deleteAbandonedOrder", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "schema": { "type": "string", "description": "Abandoned order ID" }, "required": true, "description": "Abandoned order ID", "name": "id", "in": "path" } ], "responses": { "200": { "description": "Record deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } } } } } }, "webhooks": { "order.created": { "post": { "tags": [ "Events" ], "summary": "An order was placed: on the store, in the dashboard, through the API or by an AI agent.", "description": "POSTed to every webhook subscribed to `order.created`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.created", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700", "sequence": 1040, "type": "order.created", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T09:14:03.120Z", "recordedAt": "2026-10-25T09:14:03.480Z", "actor": { "kind": "shopper", "id": null, "name": null }, "origin": "storefront", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "new", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] } } }, "schema": { "$ref": "#/components/schemas/OrderCreatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.updated": { "post": { "tags": [ "Events" ], "summary": "An order's customer, destination or notes were edited.", "description": "POSTed to every webhook subscribed to `order.updated`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.updated", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080701", "sequence": 1041, "type": "order.updated", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T09:38:12.000Z", "recordedAt": "2026-10-25T09:38:12.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "new", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "changedFields": [ "customerPhone", "notes" ] } }, "schema": { "$ref": "#/components/schemas/OrderUpdatedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.confirmed": { "post": { "tags": [ "Events" ], "summary": "The customer confirmed the order, usually on the phone.", "description": "POSTed to every webhook subscribed to `order.confirmed`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.confirmed", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080702", "sequence": 1042, "type": "order.confirmed", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T09:40:55.000Z", "recordedAt": "2026-10-25T09:40:55.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "confirmed", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "previousStatus": "new" } }, "schema": { "$ref": "#/components/schemas/OrderConfirmedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.unreachable": { "post": { "tags": [ "Events" ], "summary": "The customer could not be reached to confirm the order.", "description": "POSTed to every webhook subscribed to `order.unreachable`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.unreachable", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080703", "sequence": 1043, "type": "order.unreachable", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T09:40:55.000Z", "recordedAt": "2026-10-25T09:40:55.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "unreachable", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "previousStatus": "new" } }, "schema": { "$ref": "#/components/schemas/OrderUnreachableEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.preparing": { "post": { "tags": [ "Events" ], "summary": "The order is being prepared.", "description": "POSTed to every webhook subscribed to `order.preparing`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.preparing", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080704", "sequence": 1044, "type": "order.preparing", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T10:05:00.000Z", "recordedAt": "2026-10-25T10:05:00.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "preparing", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "previousStatus": "confirmed" } }, "schema": { "$ref": "#/components/schemas/OrderPreparingEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.ready": { "post": { "tags": [ "Events" ], "summary": "The order is packed and ready to hand to delivery.", "description": "POSTed to every webhook subscribed to `order.ready`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.ready", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080705", "sequence": 1045, "type": "order.ready", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T10:48:30.000Z", "recordedAt": "2026-10-25T10:48:30.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "previousStatus": "preparing" } }, "schema": { "$ref": "#/components/schemas/OrderReadyEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.cancelled": { "post": { "tags": [ "Events" ], "summary": "The order was cancelled.", "description": "POSTed to every webhook subscribed to `order.cancelled`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.cancelled", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080706", "sequence": 1046, "type": "order.cancelled", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T12:20:00.000Z", "recordedAt": "2026-10-25T12:20:00.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "cancelled", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "previousStatus": "unreachable" } }, "schema": { "$ref": "#/components/schemas/OrderCancelledEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.line_returned": { "post": { "tags": [ "Events" ], "summary": "Units of an order line were refused at the door and came back.", "description": "POSTed to every webhook subscribed to `order.line_returned`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.line_returned", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080707", "sequence": 1047, "type": "order.line_returned", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-26T13:05:00.000Z", "recordedAt": "2026-10-26T13:05:00.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 1 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "lineId": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "previousReturnedQuantity": 0 } }, "schema": { "$ref": "#/components/schemas/OrderLineReturnedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "order.deleted": { "post": { "tags": [ "Events" ], "summary": "The order was deleted; the event carries it as it was.", "description": "POSTed to every webhook subscribed to `order.deleted`, `order.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.order.deleted", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080708", "sequence": 1048, "type": "order.deleted", "version": 1, "subject": { "type": "order", "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T12:30:00.000Z", "recordedAt": "2026-10-25T12:30:00.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "cancelled", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] } } }, "schema": { "$ref": "#/components/schemas/OrderDeletedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.handed_off": { "post": { "tags": [ "Events" ], "summary": "The order was handed to a carrier or to one of the store's drivers.", "description": "POSTed to every webhook subscribed to `shipment.handed_off`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.handed_off", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080709", "sequence": 1049, "type": "shipment.handed_off", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T11:02:40.000Z", "recordedAt": "2026-10-25T11:02:40.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Expédié", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": null, "deliveredAt": null, "returnStartedAt": null, "returnedAt": null, "cancelledAt": null, "deliveryAttempts": 0 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] } } }, "schema": { "$ref": "#/components/schemas/ShipmentHandedOffEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.out_for_delivery": { "post": { "tags": [ "Events" ], "summary": "The parcel left for the customer.", "description": "POSTed to every webhook subscribed to `shipment.out_for_delivery`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.out_for_delivery", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a0908070a", "sequence": 1050, "type": "shipment.out_for_delivery", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-26T08:31:00.000Z", "recordedAt": "2026-10-26T08:31:00.480Z", "actor": { "kind": "carrier", "id": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine" }, "origin": "carrier_webhook", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Sorti en livraison", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": "2026-10-26T08:31:00.000Z", "deliveredAt": null, "returnStartedAt": null, "returnedAt": null, "cancelledAt": null, "deliveryAttempts": 0 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "reason": null } }, "schema": { "$ref": "#/components/schemas/ShipmentOutForDeliveryEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.delivery_failed": { "post": { "tags": [ "Events" ], "summary": "An attempt to deliver the parcel failed.", "description": "POSTed to every webhook subscribed to `shipment.delivery_failed`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.delivery_failed", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a0908070b", "sequence": 1051, "type": "shipment.delivery_failed", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-26T15:47:00.000Z", "recordedAt": "2026-10-26T15:47:00.480Z", "actor": { "kind": "carrier", "id": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine" }, "origin": "carrier_webhook", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Tentative échouée", "label": "Client injoignable" }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": "2026-10-26T08:31:00.000Z", "deliveredAt": null, "returnStartedAt": null, "returnedAt": null, "cancelledAt": null, "deliveryAttempts": 1 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "reason": "Client injoignable", "attempt": 1 } }, "schema": { "$ref": "#/components/schemas/ShipmentDeliveryFailedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.delivered": { "post": { "tags": [ "Events" ], "summary": "The parcel was delivered and paid for on delivery.", "description": "POSTed to every webhook subscribed to `shipment.delivered`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.delivered", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a0908070c", "sequence": 1052, "type": "shipment.delivered", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-26T13:05:00.000Z", "recordedAt": "2026-10-26T13:05:00.480Z", "actor": { "kind": "carrier", "id": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine" }, "origin": "carrier_webhook", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Livré", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": "2026-10-26T08:31:00.000Z", "deliveredAt": "2026-10-26T13:05:00.000Z", "returnStartedAt": null, "returnedAt": null, "cancelledAt": null, "deliveryAttempts": 0 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "reason": null } }, "schema": { "$ref": "#/components/schemas/ShipmentDeliveredEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.return_started": { "post": { "tags": [ "Events" ], "summary": "The parcel is on its way back to the store.", "description": "POSTed to every webhook subscribed to `shipment.return_started`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.return_started", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a0908070d", "sequence": 1053, "type": "shipment.return_started", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-28T09:10:00.000Z", "recordedAt": "2026-10-28T09:10:00.480Z", "actor": { "kind": "carrier", "id": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine" }, "origin": "carrier_sync", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Retour vers vendeur", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": "2026-10-26T08:31:00.000Z", "deliveredAt": null, "returnStartedAt": "2026-10-28T09:10:00.000Z", "returnedAt": null, "cancelledAt": null, "deliveryAttempts": 1 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "reason": "Refusé par le client" } }, "schema": { "$ref": "#/components/schemas/ShipmentReturnStartedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.returned": { "post": { "tags": [ "Events" ], "summary": "The parcel is back with the store.", "description": "POSTed to every webhook subscribed to `shipment.returned`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.returned", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a0908070e", "sequence": 1054, "type": "shipment.returned", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-30T10:00:00.000Z", "recordedAt": "2026-10-30T10:00:00.480Z", "actor": { "kind": "carrier", "id": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine" }, "origin": "carrier_sync", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Retourné au vendeur", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": "2026-10-26T08:31:00.000Z", "deliveredAt": null, "returnStartedAt": "2026-10-28T09:10:00.000Z", "returnedAt": "2026-10-30T10:00:00.000Z", "cancelledAt": null, "deliveryAttempts": 1 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "reason": "Refusé par le client" } }, "schema": { "$ref": "#/components/schemas/ShipmentReturnedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.cancelled": { "post": { "tags": [ "Events" ], "summary": "The shipment was cancelled before it was delivered.", "description": "POSTed to every webhook subscribed to `shipment.cancelled`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.cancelled", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a0908070f", "sequence": 1055, "type": "shipment.cancelled", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T14:00:00.000Z", "recordedAt": "2026-10-25T14:00:00.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Annulé", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": null, "deliveredAt": null, "returnStartedAt": null, "returnedAt": null, "cancelledAt": "2026-10-25T14:00:00.000Z", "deliveryAttempts": 0 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] }, "reason": "Le client a changé d'adresse" } }, "schema": { "$ref": "#/components/schemas/ShipmentCancelledEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } }, "shipment.voided": { "post": { "tags": [ "Events" ], "summary": "The handoff was undone: the order is no longer with delivery.", "description": "POSTed to every webhook subscribed to `shipment.voided`, `shipment.*` or `*`, signed per the Standard Webhooks specification. Delivered at least once and in no promised order: recognise an event by its id, order events by their `sequence` or `occurredAt`.", "operationId": "webhook.shipment.voided", "parameters": [ { "schema": { "type": "string", "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "example": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080700" }, "required": true, "description": "The event's id: the same on every Attempt and every Replay. Deduplicate by it.", "name": "webhook-id", "in": "header" }, { "schema": { "type": "string", "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "example": "1761386400" }, "required": true, "description": "When this Attempt was sent, in Unix seconds. Refuse a request more than five minutes from your clock.", "name": "webhook-timestamp", "in": "header" }, { "schema": { "type": "string", "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "example": "v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=" }, "required": true, "description": "Space-separated `v1,` entries: each the base64 HMAC-SHA256 of `..`, keyed by the base64-decoded part of a Signing Secret after `whsec_`. Accept the request when one entry matches. During a rotation there is one per secret.", "name": "webhook-signature", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a09080710", "sequence": 1056, "type": "shipment.voided", "version": 1, "subject": { "type": "shipment", "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68" }, "orderId": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "occurredAt": "2026-10-25T11:20:00.000Z", "recordedAt": "2026-10-25T11:20:00.480Z", "actor": { "kind": "staff", "id": "1d3f5a7c-9e1b-4d3f-a5c7-9e1b3d5f7a9c", "name": "Samira" }, "origin": "dashboard", "data": { "shipment": { "id": "c41e8d2b-90f3-4a6c-b7d1-5e2a9f0c3b68", "kind": "carrier", "carrier": { "companyId": "9b1d3f5a-7c9e-4b1d-a3f5-7c9e1b3d5f7a", "name": "Yalidine", "provider": "yalidine" }, "driver": null, "trackingNumber": "yal-8KQ2M7", "deliveryType": "home", "stationCode": null, "codAmount": { "amount": "9000.00", "currency": "DZD" }, "providerStatus": { "value": "Expédié", "label": null }, "handedOffAt": "2026-10-25T11:02:40.000Z", "outForDeliveryAt": null, "deliveredAt": null, "returnStartedAt": null, "returnedAt": null, "cancelledAt": null, "deliveryAttempts": 0 }, "order": { "id": "7f3c2a9e-4b1d-4e8a-9c55-2d6f0b8e1a47", "number": "ORD-20261025-0042", "status": "ready", "type": "online", "placedAt": "2026-10-25T09:14:03.120Z", "locale": "ar", "customer": { "id": "5a0e7c13-8f2b-4d9e-a6c4-1b3d5f7e9a20", "name": "Amina Benali", "phone": "0551234567", "email": null }, "destination": { "wilaya": { "id": 16, "name": "Alger", "nameAr": "الجزائر" }, "commune": { "id": "16001", "name": "Alger Centre", "nameAr": "الجزائر الوسطى" }, "city": null, "address": "12 rue Didouche Mourad", "deliveryType": "home", "stationCode": null }, "lines": [ { "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e", "productId": "e8a1c3b5-7d9f-4b2a-a4c6-8e0f2a4c6e8a", "variantId": "f1b3d5c7-9e1a-4c3b-b5d7-9f1b3d5f7a9c", "name": "Robe kabyle", "variantLabel": "Rouge / M", "sku": "RK-R-M", "quantity": 2, "unitPrice": { "amount": "4500.00", "currency": "DZD" }, "discount": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "8500.00", "currency": "DZD" }, "gift": false, "offer": { "id": "a7c9e1b3-5d7f-4a9c-8e1b-3d5f7a9c1e3b", "name": "La deuxième à -500 DA" }, "returnedQuantity": 0 } ], "subtotal": { "amount": "8500.00", "currency": "DZD" }, "deliveryFee": { "amount": "500.00", "currency": "DZD" }, "total": { "amount": "9000.00", "currency": "DZD" }, "coupon": null, "freeDeliveryOffer": null, "notes": "Appeler avant de passer", "customFields": [ { "id": "c3e5a7b9-1d3f-4b5a-9c7e-1f3a5b7d9e1f", "label": "Taille habituelle", "type": "select", "value": "M" } ] } } }, "schema": { "$ref": "#/components/schemas/ShipmentVoidedEvent" } } } }, "responses": { "200": { "description": "Any 2xx, within 15 s: delivered. Answer at once and do the work after." }, "410": { "description": "Gone: the store stops this webhook and sends it nothing more until the merchant starts it again." }, "default": { "description": "Anything else — another status, a redirect, no answer in time: tried again on the retry schedule, no sooner than a `Retry-After` asks." } } } } }, "x-tagGroups": [ { "name": "Storefront", "tags": [ "Store API", "Storefront", "Webhooks", "Images" ] }, { "name": "Commerce", "tags": [ "Orders", "Shipments", "Products", "Product Groups", "Collections", "Stock", "Offers", "Coupons", "Landing Pages", "Reviews" ] }, { "name": "Customers", "tags": [ "Customers", "Customer Groups", "Customer Tags" ] }, { "name": "Delivery", "tags": [ "Drivers", "Driver Payments", "Delivery Companies", "Shipping Profiles", "Wilayas" ] }, { "name": "Store", "tags": [ "Store Settings", "Store Pages", "Navigation", "Checkout Form" ] }, { "name": "Apps and integrations", "tags": [ "Apps", "Events" ] }, { "name": "Operations", "tags": [ "Users", "Activity Logs", "Analytics", "Abandoned Orders" ] } ] }