{ "openapi": "3.1.0", "info": { "title": "NBOX NOW Tenant API", "version": "1.0.0", "description": "The NBOX NOW Tenant API provides ERP and accounting systems with read and write access\nto shipment, seller, transaction, and rate data.\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\nTokens are generated by NBOX superadmins in the admin panel.\n\n```\nAuthorization: Bearer \n```\n\n## Rate Limits\n\n| Window | Max Requests |\n|--------|-------------|\n| 15 seconds | 60 |\n\nWhen exceeded, the API returns `429 Too Many Requests` with a `retryAfter` field\nindicating seconds to wait.\n\n## Response Format\n\n**Success:**\n```json\n{\n \"status\": \"success\",\n \"data\": { ... },\n \"pagination\": { \"page\": 1, \"limit\": 100, \"total\": 500, \"totalPages\": 5 }\n}\n```\n\n**Error:**\n```json\n{\n \"status\": \"failed\",\n \"message\": \"Human-readable error message\",\n \"errors\": [{ \"field\": \"fieldName\", \"code\": \"ERROR_CODE\", \"message\": \"...\" }]\n}\n```\n\n## Date Range Limits\n\nDate-filtered endpoints accept a maximum range of **90 days**.\nDates use ISO 8601 format (e.g., `2024-01-01`).\n\n## Postman Import\n\nDownload the spec as JSON from [`/api/erp/openapi-spec.json`](/api/erp/openapi-spec.json)\nand import into Postman via **File > Import**.\n", "x-logo": { "url": "/images/nbox-logo-blue.png", "altText": "NBOX NOW" }, "contact": { "name": "NBOX Systems", "email": "support@nbox.qa" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://nbox.now", "description": "Production" }, { "url": "https://staging.nbox.now", "description": "Staging" } ], "tags": [ { "name": "Shipments", "description": "Shipment listing, detail, updates, status changes, and retry operations" }, { "name": "Sellers", "description": "Seller listing, detail, and profile updates" }, { "name": "COD Invoices", "description": "Cash-on-Delivery invoice confirmation and handover tracking" }, { "name": "Transactions", "description": "Financial transaction lookups by seller or shipment" }, { "name": "Rates", "description": "Shipping rate calculation" }, { "name": "Webhooks", "description": "ERP webhook endpoint management" }, { "name": "Reference", "description": "Status codes and transition rules" } ], "paths": { "/api/erp/cod-invoice/{id}/confirm": { "post": { "operationId": "confirmErpCodInvoice", "tags": [ "COD Invoices" ], "summary": "Confirm COD payment", "description": "Confirms a cash or POS collection for a COD invoice. Credits the seller wallet and debits the handling fee.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment detail ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodConfirmRequest" } } } }, "responses": { "200": { "description": "COD collection confirmed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/cod-invoice/{id}/handover": { "post": { "operationId": "handoverErpCodInvoice", "tags": [ "COD Invoices" ], "summary": "COD handover", "description": "Advances a COD invoice through the handover chain: collected -> with_reception -> with_accounts -> deposited.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment detail ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodHandoverRequest" } } } }, "responses": { "200": { "description": "Handover status updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/rates": { "post": { "operationId": "calculateErpRates", "tags": [ "Rates" ], "summary": "Calculate rates", "description": "Calculate shipping rates for ERP system integration. Supports both public rates (no discount) and seller-specific rates (with plan discount).", "security": [ { "ErpBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateRequest" } } } }, "responses": { "200": { "description": "Rates calculated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RateOption" } }, "metadata": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/sellers/{id}/transactions": { "get": { "operationId": "getErpSellerTransactions", "tags": [ "Transactions" ], "summary": "Get transactions", "description": "Returns a paginated list of transactions for a specific seller.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Seller user ID" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Items per page" }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date filter (YYYY-MM-DD)" }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date filter (YYYY-MM-DD)" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Transaction status filter" }, { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Transaction source filter" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Transaction type filter" } ], "responses": { "200": { "description": "Seller transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/ErpPagination" }, "seller": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "company": { "type": "string" }, "balance": { "type": "number" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/sellers/{id}": { "get": { "operationId": "getErpSeller", "tags": [ "Sellers" ], "summary": "Get seller", "description": "Returns detailed information about a specific seller.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Seller ID" } ], "responses": { "200": { "description": "Seller details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/SellerDetail" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "operationId": "updateErpSeller", "tags": [ "Sellers" ], "summary": "Update seller", "description": "Updates a seller profile with the provided fields.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Seller ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SellerUpdateRequest" } } } }, "responses": { "200": { "description": "Seller updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "updated": { "type": "object" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/sellers/count": { "get": { "operationId": "countErpSellers", "tags": [ "Sellers" ], "summary": "Count sellers", "description": "Returns the total count of sellers matching the given filters.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "prepaid", "postpaid" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive", "incomplete" ] } }, { "name": "hasShops", "in": "query", "schema": { "type": "boolean" } }, { "name": "isLocal", "in": "query", "schema": { "type": "boolean" } }, { "name": "isInternational", "in": "query", "schema": { "type": "boolean" } }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter sellers created after this date (YYYY-MM-DD)" }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter sellers created before this date (YYYY-MM-DD)" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name, email, or company" } ], "responses": { "200": { "description": "Seller count retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "count": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/sellers": { "get": { "operationId": "listErpSellers", "tags": [ "Sellers" ], "summary": "List sellers", "description": "Returns a paginated list of sellers with optional filtering and sorting.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 500 }, "description": "Items per page" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "fullName", "company", "totalShipments", "shopCount", "activeShopCount" ], "default": "createdAt" } }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "role", "in": "query", "schema": { "type": "string", "enum": [ "prepaid", "postpaid" ] } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "inactive", "incomplete" ] } }, { "name": "hasShops", "in": "query", "schema": { "type": "boolean" } }, { "name": "isLocal", "in": "query", "schema": { "type": "boolean" } }, { "name": "isInternational", "in": "query", "schema": { "type": "boolean" } }, { "name": "createdAfter", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter sellers created after this date (YYYY-MM-DD)" }, { "name": "createdBefore", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Filter sellers created before this date (YYYY-MM-DD)" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Search by name, email, or company" }, { "name": "includeFilterCounts", "in": "query", "schema": { "type": "boolean" }, "description": "Include aggregated filter counts in response" } ], "responses": { "200": { "description": "Sellers retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SellerListItem" } }, "pagination": { "$ref": "#/components/schemas/ErpPagination" }, "filterCounts": { "type": "object", "description": "Aggregated filter counts (only if includeFilterCounts=true)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/shipments/{id}/cod-invoice": { "get": { "operationId": "getErpCodInvoice", "tags": [ "Shipments" ], "summary": "Get COD invoice", "description": "Generates a COD payment link for a shipment. Idempotent: returns the existing unpaid invoice if one already exists.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID (accepts shipmentDetailId, orderId, shipmentId, unifiedRefId, AWB, or tracking number)" } ], "responses": { "200": { "description": "COD invoice details", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "invoiceId": { "type": "string" }, "refId": { "type": "integer" }, "paymentUrl": { "type": "string" }, "paymentMethod": { "type": "string" }, "codAmount": { "type": "number" }, "handlingFeePercent": { "type": "number" }, "handlingFeeAmount": { "type": "number" }, "customerName": { "type": "string" }, "customerPhone": { "type": "string" }, "status": { "type": "string" }, "existing": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/notes": { "get": { "operationId": "getErpShipmentNotes", "tags": [ "Shipments" ], "summary": "Get shipment notes", "description": "Returns all notes for a shipment.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "responses": { "200": { "description": "Note list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "post": { "operationId": "addErpShipmentNote", "tags": [ "Shipments" ], "summary": "Add shipment note", "description": "Creates a new note on a shipment. Accepts JSON or multipart/form-data for file uploads.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddNoteRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/AddNoteRequest" } } } }, "responses": { "201": { "description": "Note created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/Note" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/repack": { "post": { "operationId": "repackErpShipment", "tags": [ "Shipments" ], "summary": "Repack shipment", "description": "Reverses a shipment verification so operators can re-measure with correct dimensions. Deletes the adjustment invoice (if unpaid), clears verification data, and reverts status to at_sorting.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepackRequest" } } } }, "responses": { "200": { "description": "Repack successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "shipmentId": { "type": "string" }, "previousStatus": { "type": "string" }, "newStatus": { "type": "string" }, "adjustmentInvoiceDeleted": { "type": "boolean" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/retry": { "post": { "operationId": "retryErpShipment", "tags": [ "Shipments" ], "summary": "Retry shipment", "description": "Retries a failed pickup, redelivers an item on hold, returns to sender, or cancels a pending retry.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RetryRequest" } } } }, "responses": { "200": { "description": "Retry initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/return": { "post": { "operationId": "createErpReturnShipment", "tags": [ "Shipments" ], "summary": "Create return shipment", "description": "Creates a new return shipment by reversing origin/destination of a delivered shipment. Calculates new rate and handles billing.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment Detail ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Reason for creating return", "maxLength": 500 }, "waiveFee": { "type": "boolean", "description": "Waive return shipping fee (default: false)", "default": false }, "notes": { "type": "string", "description": "Additional notes" }, "operatorEmail": { "type": "string", "format": "email", "description": "Email of the Portal staff member initiating the return (for audit trail)" } } } } } }, "responses": { "200": { "description": "Return shipment created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Return already exists for this shipment" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/status": { "post": { "operationId": "changeErpShipmentStatus", "tags": [ "Shipments" ], "summary": "Update shipment status", "description": "Changes the status of a shipment with full business logic including cancellation handling and refunds.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusChangeRequest" } } } }, "responses": { "200": { "description": "Status changed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "previousStatus": { "type": "string" }, "newStatus": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/timeline": { "post": { "operationId": "addErpShipmentTimelineEvent", "tags": [ "Shipments" ], "summary": "Add timeline event", "description": "Records a timeline event on a shipment. Used by Portal to push events like address confirmations, customer contacts, and other external events into the shipment timeline.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "eventType", "description" ], "properties": { "eventType": { "type": "string", "description": "Snake-case event identifier", "example": "address_confirmed", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 100 }, "description": { "type": "string", "description": "Human-readable event description", "example": "Customer confirmed address via WhatsApp", "maxLength": 500 }, "actor": { "type": "string", "description": "Who triggered the event (staff name, system name)", "example": "John Smith", "maxLength": 100 }, "metadata": { "type": "object", "description": "Additional context", "example": { "channel": "whatsapp", "confirmedBy": "customer" } } } } } } }, "responses": { "201": { "description": "Timeline event recorded", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Timeline event recorded" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "eventType": { "type": "string" }, "description": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}": { "get": { "operationId": "getErpShipment", "tags": [ "Shipments" ], "summary": "Get shipment", "description": "Returns full details of a single shipment.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "responses": { "200": { "description": "Shipment detail", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/ShipmentDetail" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "put": { "operationId": "updateErpShipment", "tags": [ "Shipments" ], "summary": "Update shipment", "description": "Updates shipment recipient, destination address, AWB, tracking URL, or notes. For status changes, use POST /api/erp/shipments/{id}/status.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShipmentUpdateRequest" } } } }, "responses": { "200": { "description": "Shipment updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "updated": { "type": "object" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/{id}/verify": { "post": { "operationId": "verifyErpShipment", "tags": [ "Shipments" ], "summary": "Verify shipment", "description": "Accepts actual package measurements from the sorting facility, compares against declared values, recalculates cost, and creates an adjustment invoice if needed.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Shipment ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" } } } }, "responses": { "200": { "description": "Verification result", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "shipmentDetailId": { "type": "string" }, "previousStatus": { "type": "string" }, "newStatus": { "type": "string" }, "adjustmentRequired": { "type": "boolean" }, "comparison": { "type": "object" }, "originalCost": { "type": "number" }, "newCost": { "type": "number" }, "adjustmentAmount": { "type": "number" }, "paymentLink": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments/count": { "get": { "operationId": "countErpShipments", "tags": [ "Shipments" ], "summary": "Count shipments", "description": "Returns the total count of shipments matching the given filters.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of date range (YYYY-MM-DD). Must be paired with endDate." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of date range (YYYY-MM-DD). Must be paired with startDate." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by shipment status" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across reference, AWB, recipient, etc." }, { "name": "carrier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by carrier name" }, { "name": "isLocal", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by local/international" }, { "name": "isCOD", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by cash-on-delivery" }, { "name": "paymentStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by NBox billing status" }, { "name": "sellerIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated seller IDs" }, { "name": "codInvoiceStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by COD invoice status" }, { "name": "driver", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by driver" }, { "name": "pickupTaskShortId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pickup task short ID" }, { "name": "taskShortId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by any Onfleet task short ID (pickup or dropoff)" } ], "responses": { "200": { "description": "Shipment count", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "count": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/shipments": { "get": { "operationId": "listErpShipments", "tags": [ "Shipments" ], "summary": "List shipments", "description": "Returns a paginated list of shipments with optional filters.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start of date range (YYYY-MM-DD). Must be paired with endDate." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End of date range (YYYY-MM-DD). Must be paired with startDate." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by shipment status" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 500 }, "description": "Items per page (max 500)" }, { "name": "sortBy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "createdAt", "updatedAt", "reference", "carrier" ], "default": "createdAt" }, "description": "Field to sort by" }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Sort direction" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Free-text search across reference, AWB, recipient, etc." }, { "name": "carrier", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by carrier name" }, { "name": "isLocal", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by local/international" }, { "name": "isCOD", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by cash-on-delivery" }, { "name": "paymentStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by NBox billing status" }, { "name": "sellerIds", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated seller IDs" }, { "name": "codInvoiceStatus", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by COD invoice status" }, { "name": "driver", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by driver" }, { "name": "pickupTaskShortId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by pickup task short ID" }, { "name": "taskShortId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by any Onfleet task short ID (pickup or dropoff)" } ], "responses": { "200": { "description": "Paginated shipment list", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShipmentListItem" } }, "pagination": { "$ref": "#/components/schemas/ErpPagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/api/erp/statuses": { "get": { "operationId": "getErpStatuses", "tags": [ "Reference" ], "summary": "List statuses", "description": "Returns all available statuses in the NBox system, allowing third-party applications to programmatically discover valid status values, their meanings, and transition rules.", "security": [ { "ErpBearerAuth": [] } ], "responses": { "200": { "description": "Status definitions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "groups": { "type": "array", "items": { "$ref": "#/components/schemas/StatusDefinition" } }, "meta": { "type": "object", "properties": { "totalStatusTypes": { "type": "integer" }, "apiVersion": { "type": "string" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/transactions": { "get": { "operationId": "lookupErpTransactions", "tags": [ "Transactions" ], "summary": "List transactions", "description": "Unified transactions lookup endpoint. Look up transactions by seller or shipment.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "lookupType", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "seller", "shipment" ] }, "description": "Type of lookup" }, { "name": "lookupId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "User ID or ShipmentDetail ID" }, { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 }, "description": "Items per page" }, { "name": "startDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "Start date filter (YYYY-MM-DD)" }, { "name": "endDate", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "End date filter (YYYY-MM-DD)" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "Transaction status filter" }, { "name": "source", "in": "query", "schema": { "type": "string" }, "description": "Transaction source filter" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Transaction type filter" }, { "name": "sortBy", "in": "query", "schema": { "type": "string", "enum": [ "createdAt", "amount" ] }, "description": "Sort field" }, { "name": "sortOrder", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "description": "Sort direction" } ], "responses": { "200": { "description": "Transactions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "pagination": { "$ref": "#/components/schemas/ErpPagination" }, "lookupType": { "type": "string" }, "lookupId": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/erp/webhooks": { "get": { "operationId": "listErpWebhooks", "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List all webhook endpoints, or get a single endpoint by ID.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Webhook endpoint ID (returns single endpoint with delivery history if specified)" } ], "responses": { "200": { "description": "Webhook endpoints retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ErpWebhookEndpoint" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "operationId": "createErpWebhook", "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Create a new webhook endpoint.", "security": [ { "ErpBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook endpoint created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ErpWebhookEndpoint" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "operationId": "updateErpWebhook", "tags": [ "Webhooks" ], "summary": "Update webhook", "description": "Update an existing webhook endpoint.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } } }, "responses": { "200": { "description": "Webhook endpoint updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/ErpWebhookEndpoint" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "operationId": "deleteErpWebhook", "tags": [ "Webhooks" ], "summary": "Delete webhook", "description": "Delete a webhook endpoint.", "security": [ { "ErpBearerAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Webhook endpoint ID" } ], "responses": { "200": { "description": "Webhook endpoint deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimitExceeded" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "ErpBearerAuth": { "type": "http", "scheme": "bearer", "description": "ERP API token passed as a Bearer token.\nGenerated by NBOX superadmins in the admin settings panel.\n" } }, "responses": { "BadRequest": { "description": "Bad request — missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErpErrorResponse" }, "example": { "status": "failed", "message": "Invalid parameters", "errors": [ { "field": "startDate", "code": "REQUIRED", "message": "startDate is required when endDate is provided" } ] } } } }, "Unauthorized": { "description": "Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErpErrorResponse" }, "example": { "status": "failed", "message": "Unauthorized" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErpErrorResponse" }, "example": { "status": "failed", "message": "Shipment not found" } } } }, "MethodNotAllowed": { "description": "HTTP method not allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErpErrorResponse" }, "example": { "status": "failed", "message": "Method not allowed" } } } }, "RateLimitExceeded": { "description": "Rate limit exceeded (60 requests per 15 seconds)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "failed" }, "message": { "type": "string" }, "retryAfter": { "type": "integer", "description": "Seconds to wait before retrying" } }, "required": [ "status", "message", "retryAfter" ] }, "example": { "status": "failed", "message": "Rate limit exceeded", "retryAfter": 12 } } } }, "InternalError": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErpErrorResponse" }, "example": { "status": "failed", "message": "Internal server error" } } } } }, "schemas": { "ErpErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "const": "failed" }, "message": { "type": "string", "description": "Human-readable error message" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationError" }, "description": "Field-level validation errors (when applicable)" }, "retryAfter": { "type": "integer", "description": "Seconds to wait before retrying (rate limit errors only)" } }, "required": [ "status", "message" ] }, "ValidationError": { "type": "object", "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "field", "code", "message" ] }, "ErpPagination": { "type": "object", "properties": { "page": { "type": "integer" }, "limit": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } }, "required": [ "page", "limit", "total", "totalPages" ] }, "OrderStatus": { "type": "string", "enum": [ "new", "fulfilled", "pickup", "in_transit_pickup", "picked_up", "pickup_failed", "at_sorting", "pending_adjustment", "awaiting_collection", "ready_to_book", "booked", "not_collected", "cancelled", "in_transit", "delivered", "return_to_sender", "item_on_hold", "failed" ] }, "CodInvoiceStatus": { "type": "string", "enum": [ "none", "uncollected", "collected", "with_reception", "with_accounts", "deposited", "cancelled" ] }, "ShipmentListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique shipment detail ID" }, "reference": { "type": "string", "description": "Human-readable reference number" }, "source": { "type": "string", "enum": [ "order", "shipnow", "return" ], "description": "Source type" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "paymentStatus": { "type": "string", "description": "NBox billing status" }, "carrier": { "type": [ "string", "null" ], "description": "Carrier name (e.g., aramex, fedex)" }, "awb": { "type": [ "string", "null" ], "description": "Airway Bill / tracking number" }, "isLocal": { "type": "boolean", "description": "Whether shipment is domestic" }, "isReturn": { "type": "boolean" }, "shippingRate": { "type": "number", "format": "double", "description": "Shipping rate charged" }, "currency": { "type": "string", "description": "Currency code (e.g., QAR)" }, "sellerName": { "type": [ "string", "null" ] }, "sellerCompany": { "type": [ "string", "null" ] }, "destination": { "$ref": "#/components/schemas/DestinationAddress" }, "customer": { "$ref": "#/components/schemas/Customer" }, "initialDistance": { "type": [ "number", "null" ], "format": "double", "description": "Estimated distance in km" }, "actualDistance": { "type": [ "number", "null" ], "format": "double", "description": "Actual road distance in km" }, "waitingTime": { "type": [ "number", "null" ], "description": "Waiting time in minutes" }, "workerId": { "type": [ "string", "null" ], "description": "OnFleet worker/driver ID" }, "workerName": { "type": [ "string", "null" ], "description": "Driver name" }, "deliveryNote": { "type": [ "string", "null" ], "description": "Customer delivery instructions (ShipNow only)" }, "totalCbm": { "type": [ "number", "null" ], "format": "double", "description": "Total cubic meters" }, "contentType": { "type": "string", "enum": [ "document", "non_document" ] }, "deliveryTracking": { "type": "array", "items": { "$ref": "#/components/schemas/DeliveryTrackingEntry" } }, "statusMilestones": { "type": "object", "additionalProperties": { "type": "string", "format": "date-time" }, "description": "Status name to earliest timestamp map" }, "isCOD": { "type": "boolean", "description": "Whether this is a Cash on Delivery shipment" }, "collectionAmount": { "type": [ "number", "null" ], "format": "double", "description": "COD amount to collect" }, "codInvoice": { "type": [ "object", "null" ], "description": "COD invoice details" } } }, "ShipmentDetail": { "description": "Full shipment detail (extends list item with origin, items, timeline, etc.)", "allOf": [ { "$ref": "#/components/schemas/ShipmentListItem" }, { "type": "object", "properties": { "unifiedRefId": { "type": [ "string", "null" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "trackingUrl": { "type": [ "string", "null" ], "format": "uri" }, "origin": { "$ref": "#/components/schemas/Address" }, "seller": { "$ref": "#/components/schemas/ShipmentSeller" }, "displayRate": { "type": [ "number", "null" ], "format": "double", "description": "Rate shown to customer" }, "codAmount": { "type": [ "number", "null" ], "format": "double" }, "orderSubtotal": { "type": [ "number", "null" ], "format": "double" }, "chargeableWeight": { "type": [ "number", "null" ], "format": "double", "description": "Billing weight in kg" }, "packageWeight": { "type": [ "number", "null" ], "format": "double" }, "packageLength": { "type": [ "number", "null" ], "format": "double" }, "packageWidth": { "type": [ "number", "null" ], "format": "double" }, "packageHeight": { "type": [ "number", "null" ], "format": "double" }, "boxName": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "timeline": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineEvent" } }, "adjustmentInvoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "unpaid", "paid", "cancelled" ] }, "adjustmentAmount": { "type": "number", "format": "double" }, "paymentLink": { "type": [ "string", "null" ] }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "verifiedMeasurements": { "type": [ "object", "null" ], "properties": { "totalWeight": { "type": "number", "format": "double" }, "totalVolume": { "type": "number", "format": "double" }, "chargeableWeight": { "type": "number", "format": "double" }, "packages": { "type": "array", "items": { "$ref": "#/components/schemas/PackageMeasurement" } }, "verifiedAt": { "type": "string", "format": "date-time" }, "recalculatedRate": { "type": "number", "format": "double" } } } } } ] }, "Address": { "type": "object", "properties": { "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "countryCode": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] } } }, "DestinationAddress": { "allOf": [ { "$ref": "#/components/schemas/Address" }, { "type": "object", "properties": { "lat": { "type": [ "number", "null" ], "format": "double" }, "lng": { "type": [ "number", "null" ], "format": "double" } } } ] }, "Customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" } } }, "ShipmentSeller": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "mobile": { "type": [ "string", "null" ] }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/SellerContact" } } } }, "SellerContact": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "email", "phone", "whatsapp" ] }, "value": { "type": "string" }, "countryCode": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "personal", "business", "billing", "shipping", "support", "legal", "other" ] }, "isDefault": { "type": "boolean" } } }, "DeliveryTrackingEntry": { "type": "object", "properties": { "taskId": { "type": "string" }, "shortId": { "type": "string" }, "taskCreatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "taskStartedAt": { "type": [ "string", "null" ], "format": "date-time" }, "taskArrivedAt": { "type": [ "string", "null" ], "format": "date-time" }, "taskCompletedAt": { "type": [ "string", "null" ], "format": "date-time" }, "success": { "type": [ "boolean", "null" ] }, "pickupTask": { "type": "boolean" }, "workerId": { "type": [ "string", "null" ] }, "workerName": { "type": [ "string", "null" ] } } }, "TimelineEvent": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "creation", "status", "delivery", "payment", "note" ] }, "timestamp": { "type": "string", "format": "date-time" }, "title": { "type": "string" }, "actor": { "type": [ "string", "null" ] }, "details": { "type": [ "object", "null" ] } } }, "OrderItem": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" }, "price": { "type": "number", "format": "double" }, "weight": { "type": [ "number", "null" ], "format": "double", "description": "Weight in kg" }, "length": { "type": [ "number", "null" ], "format": "double", "description": "Length in cm" }, "width": { "type": [ "number", "null" ], "format": "double" }, "height": { "type": [ "number", "null" ], "format": "double" } } }, "PackageMeasurement": { "type": "object", "properties": { "weight": { "type": "number", "format": "double", "description": "Weight in kg" }, "length": { "type": "number", "format": "double", "description": "Length in cm" }, "width": { "type": "number", "format": "double" }, "height": { "type": "number", "format": "double" } }, "required": [ "weight", "length", "width", "height" ] }, "Note": { "type": "object", "properties": { "id": { "type": "string" }, "content": { "type": "string" }, "fileUrl": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "createdBy": { "type": "object", "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "staff", "system" ] }, "isExternal": { "type": "boolean" } } } } }, "ShipmentUpdateRequest": { "type": "object", "description": "At least one field is required", "properties": { "notes": { "type": "string", "maxLength": 2000 }, "awb": { "type": "string", "maxLength": 100, "description": "Air Waybill number from external carrier" }, "trackingUrl": { "type": "string", "format": "uri", "maxLength": 500 }, "recipient": { "$ref": "#/components/schemas/RecipientUpdate" }, "destinationAddress": { "$ref": "#/components/schemas/DestinationAddressUpdate" } } }, "RecipientUpdate": { "type": "object", "description": "At least one field required", "properties": { "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "phone": { "type": "string", "description": "International format (7-15 digits, optional + prefix)" }, "email": { "type": "string", "format": "email", "maxLength": 255 } } }, "DestinationAddressUpdate": { "type": "object", "required": [ "address", "city" ], "properties": { "address": { "type": "string", "maxLength": 500 }, "city": { "type": "string", "maxLength": 100 }, "countryCode": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "ISO 3166-1 alpha-2 (e.g., \"QA\")" }, "country": { "type": "string", "maxLength": 100 }, "state": { "type": "string", "maxLength": 100 }, "postalCode": { "type": "string", "maxLength": 20 }, "lat": { "type": "number", "format": "double", "minimum": -90, "maximum": 90 }, "lng": { "type": "number", "format": "double", "minimum": -180, "maximum": 180 } } }, "StatusChangeRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/OrderStatus" }, "reason": { "type": "string", "maxLength": 500, "description": "Reason for status change" }, "shouldRefund": { "type": "boolean", "description": "Whether to refund to seller wallet (required for cancellation of paid shipments)" } } }, "VerificationRequest": { "type": "object", "required": [ "packages" ], "properties": { "packages": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PackageMeasurement" } }, "contentType": { "type": "string", "enum": [ "document", "non_document" ] }, "notes": { "type": "string", "maxLength": 500 } } }, "RetryRequest": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "retry_pickup", "redelivery", "return_to_sender", "cancel_retry" ] }, "reason": { "type": "string", "maxLength": 500 }, "waiveFee": { "type": "boolean", "default": false } } }, "RepackRequest": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 }, "notes": { "type": "string", "maxLength": 500 } } }, "AddNoteRequest": { "type": "object", "description": "At least one of content or file is required. Use multipart/form-data for file uploads.", "properties": { "content": { "type": "string", "maxLength": 2000 }, "name": { "type": "string", "maxLength": 100, "description": "External commenter name" }, "email": { "type": "string", "format": "email" } } }, "SellerListItem": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "status": { "type": "string", "enum": [ "active", "inactive", "incomplete" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "mobile": { "type": [ "string", "null" ] }, "contract": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "isLocal": { "type": "boolean" }, "isInternational": { "type": "boolean" }, "subscription": { "type": [ "string", "null" ] }, "blockedCarriers": { "type": [ "array", "null" ], "items": { "type": "string" } }, "useAutoBoxSelection": { "type": [ "boolean", "null" ] }, "disableAutoPickup": { "type": [ "boolean", "null" ] }, "codAllowed": { "type": [ "boolean", "null" ] }, "orderSyncDisabled": { "type": [ "boolean", "null" ] }, "notifyCustomers": { "type": [ "boolean", "null" ] } } }, "businessHours": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "daysStart": { "type": "integer", "minimum": 1, "maximum": 7 }, "daysEnd": { "type": "integer", "minimum": 1, "maximum": 7 }, "hoursStart": { "type": [ "string", "null" ] }, "hoursEnd": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] } } }, "shops": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SellerShop" } }, "contacts": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/SellerContact" } }, "statistics": { "type": "object", "properties": { "totalShipments": { "type": "integer" }, "activeShops": { "type": "integer" }, "inactiveShops": { "type": "integer" }, "totalOrders": { "type": [ "integer", "null" ] } } } } }, "SellerDetail": { "description": "Full seller detail (extends list item with account status, WMS, shops, contacts)", "allOf": [ { "$ref": "#/components/schemas/SellerListItem" }, { "type": "object", "properties": { "accountStatus": { "type": "object", "properties": { "isDisabled": { "type": "boolean" }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "disabledReason": { "type": [ "string", "null" ] } } }, "wms": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "sellerCode": { "type": [ "string", "null" ] } } } } } ] }, "SellerShop": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "platform": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "orderCount": { "type": "integer" } } }, "SellerUpdateRequest": { "type": "object", "description": "At least one field is required", "properties": { "company": { "type": [ "string", "null" ], "maxLength": 200, "description": "Business/brand name (null to clear)" }, "firstName": { "type": "string", "maxLength": 100 }, "lastName": { "type": "string", "maxLength": 100 }, "mobile": { "type": "string", "maxLength": 20 }, "accountType": { "type": "string", "enum": [ "prepaid", "postpaid" ] }, "isDisabled": { "type": "boolean" }, "disabledReason": { "type": [ "string", "null" ], "maxLength": 500 }, "codAllowed": { "type": "boolean" }, "disableAutoPickup": { "type": "boolean" }, "useAutoBoxSelection": { "type": "boolean" }, "isLocal": { "type": "boolean" }, "isInternational": { "type": "boolean" }, "orderSyncDisabled": { "type": "boolean" }, "notifyCustomers": { "type": "boolean" }, "wmsEnabled": { "type": "boolean" }, "wmsSellerCode": { "type": [ "string", "null" ], "maxLength": 100 }, "enableBusinessHours": { "type": "boolean" }, "businessDaysStart": { "type": "integer", "minimum": 1, "maximum": 7 }, "businessDaysEnd": { "type": "integer", "minimum": 1, "maximum": 7 }, "businessHoursStart": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "HH:MM format (e.g., \"09:00\")" }, "businessHoursEnd": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "HH:MM format (e.g., \"18:00\")" }, "businessTimezone": { "type": "string", "maxLength": 50, "description": "IANA timezone (e.g., \"Asia/Qatar\")" } } }, "Transaction": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "description": "topup, automatic, reversal, shipment, unified, subscription" }, "status": { "type": "string", "description": "pending, completed, failed, cancelled, refunded" }, "source": { "type": "string", "description": "automatic, skipcash, tap, manual, webhook" }, "amount": { "type": "number", "format": "double", "description": "Negative for deductions, positive for credits" }, "currency": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "gateway": { "type": [ "string", "null" ], "description": "skipcash, tap, or null" }, "beforeBalance": { "type": [ "number", "null" ], "format": "double" }, "afterBalance": { "type": [ "number", "null" ], "format": "double" }, "sourceReference": { "type": [ "string", "null" ], "description": "External payment gateway transaction ID" }, "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "orderReference": { "type": [ "string", "null" ] } } } }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "refId": { "type": [ "string", "null" ] } } } }, "statusDisplay": { "type": "string" }, "sourceDisplay": { "type": "string" }, "referenceInfo": { "type": [ "string", "null" ] } } }, "ErpWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "shipment.new", "shipment.update" ] } }, "isActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "maxRetries": { "type": "integer" }, "timeoutMs": { "type": "integer" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "totalDeliveries": { "type": "integer" }, "totalFailures": { "type": "integer" }, "consecutiveFailures": { "type": "integer" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "name", "url", "events" ], "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "shipment.new", "shipment.update" ] } } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "shipment.new", "shipment.update" ] } }, "isActive": { "type": "boolean" } } }, "RateRequest": { "type": "object", "required": [ "origin", "destination" ], "properties": { "origin": { "type": "object", "description": "Origin location" }, "destination": { "type": "object", "description": "Destination location" }, "weight": { "type": "number", "format": "double", "description": "Package weight in kg" }, "volume": { "type": "number", "format": "double", "description": "Package volume in cm³" }, "type": { "type": "string", "enum": [ "document", "non_document" ], "default": "non_document" }, "products": { "type": "array", "items": { "type": "object" }, "description": "Array of products (alternative to weight/volume)" }, "sellerId": { "type": "string", "description": "Seller user ID for plan discount" } } }, "RateOption": { "type": "object", "properties": { "id": { "type": "string" }, "service_name": { "type": "string" }, "service_code": { "type": "string", "description": "ARAMEX, FEDEX, EMS, QPOST, WABA, or NBOX" }, "currency": { "type": "string" }, "description": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "displayRate": { "type": "number", "format": "double", "description": "Customer-facing rate" }, "actualRate": { "type": "number", "format": "double", "description": "Business rate charged by NBox" }, "baseRate": { "type": [ "number", "null" ], "format": "double" }, "discountAmount": { "type": [ "number", "null" ], "format": "double" }, "hasDisplayRule": { "type": "boolean" }, "appliedRules": { "type": "array", "items": { "type": "object" } }, "isSubsidized": { "type": "boolean" }, "isMarkup": { "type": "boolean" }, "distanceKm": { "type": [ "number", "null" ], "format": "double" } } }, "CodConfirmRequest": { "type": "object", "required": [ "collectedAmount" ], "properties": { "collectedAmount": { "type": "number", "format": "double", "description": "Actual amount collected (QAR)" }, "paymentMethod": { "type": "string", "enum": [ "cash", "pos", "farwan" ], "default": "cash" }, "driverName": { "type": "string" }, "reference": { "type": "string" }, "posReceiptNumber": { "type": "string" }, "posTerminalId": { "type": "string" }, "notes": { "type": "string" } } }, "CodHandoverRequest": { "type": "object", "required": [ "action", "staffName", "staffEmail", "receivedAmount" ], "properties": { "action": { "type": "string", "enum": [ "receive_at_reception", "receive_at_accounts", "mark_deposited" ] }, "staffName": { "type": "string" }, "staffEmail": { "type": "string", "format": "email" }, "receivedAmount": { "type": "number", "format": "double" }, "reference": { "type": "string", "description": "Required when action is mark_deposited" }, "notes": { "type": "string" }, "collectedAmount": { "type": "number", "format": "double", "description": "Required when invoice not yet confirmed (auto-confirm)" }, "paymentMethod": { "type": "string", "enum": [ "cash", "pos", "farwan" ] }, "driverName": { "type": "string" }, "collectionReference": { "type": "string" }, "posReceiptNumber": { "type": "string" }, "posTerminalId": { "type": "string" } } }, "StatusDefinition": { "type": "object", "properties": { "status": { "type": "string" }, "description": { "type": "string" }, "terminal": { "type": "boolean" }, "allowedTransitions": { "type": "array", "items": { "type": "string" } } } } } } }