{ "openapi": "3.0.0", "info": { "title": "Altexpress External API", "description": "External API for creating shipment orders, generating AWB labels, managing warehouse stocks, and querying shipments on the Altexpress platform.\n\n## Environments\n| Environment | Base URL |\n|---|---|\n| **Production** | `https://myaltexpress.com/external` |\n| **Staging** | `https://staging.altexpress.ro/external` |\n\n## Authentication\nAll requests require a JWT token in the `X-Authorization` header. Tokens are issued separately per environment - contact Altexpress support.\n\n## Address Parsing (GLS)\nThe address field is automatically split into Street / HouseNumber / HouseNumberInfo for GLS. Use courier_overrides when your system already has split GLS Street / HouseNumber / HouseNumberInfo fields.\n\n## Stock Draft Workflow\nStock-changing endpoints create warehouse import drafts. Final review and confirmation normally happens in `/admin/warehouse/import` under Receptions & inventories. For companies explicitly approved by a Super Admin, `received` imports created through `POST /stocks/import` are finalized immediately and apply stock in the same request.\n\nDraft flow values:\n- `received`: inbound reception / add stock\n- `recalled`: stock recall / deduct stock\n- `count`: inventory count / overwrite counted stock\n\n## AWB Import & Tracking (v2)\nIf you generate AWBs in your own system (Shopify, WooCommerce, PrestaShop, Magento, or a custom platform), use the **AWB Import (v2)** endpoints under `/v2/...` to attach those AWBs to Altexpress orders and keep tracking statuses in sync. Typical integration flow:\n\n1. **Create the order** with `POST /orders` (without `generate_awb`). The order reserves stock.\n2. **Import your AWB** with `POST /v2/awb/import`. This links your AWB number to the order, deducts the reserved stock, and (by default) generates a printable A6 PDF label. Pass any `courier_slug` — if it is not configured on your account, a virtual courier is created automatically so the shipment can still be tracked.\n3. **Push status changes** with `POST /v2/awb/status-update` whenever the order moves in your system. Supply your platform's raw status (e.g. `fulfilled`, `delivered`, `returned`) and it is mapped to the matching Altexpress status automatically.\n\n### Status mapping is bidirectional\nUse `GET /v2/awb/status-map` to fetch the full external⇆Altexpress mapping table for any platform. A few common examples:\n\n| Platform | External status | Altexpress status |\n|---|---|---|\n| Shopify | `fulfilled` | 4 — Dispatched |\n| Shopify | `delivered` | 6 — Delivered |\n| Shopify | `returned` | 12 — Return Complete |\n| WooCommerce | `wc-processing` | 3 — Ready to Ship |\n| WooCommerce | `delivered` | 6 — Delivered |\n\n### Automatic stock behavior\n- **On import:** reserved stock is deducted. If there is no reserved/available stock, the order is moved to **On Hold (status 20)** instead of failing, so your warehouse team can action it.\n- **On Return Complete (status 12):** stock is automatically added back to the warehouse. This is idempotent — sending status 12 more than once for the same order restores stock only once.", "version": "1.0.0" }, "servers": [ { "url": "https://myaltexpress.com/external", "description": "Production" }, { "url": "https://staging.altexpress.ro/external", "description": "Staging" } ], "paths": { "/shipments": { "get": { "tags": [ "Shipments" ], "summary": "List shipments", "operationId": "listShipments", "parameters": [ { "name": "order_no", "in": "query", "description": "Filter by order reference", "schema": { "type": "string" } }, { "name": "awb", "in": "query", "description": "Filter by AWB number", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by status code", "schema": { "type": "integer" } }, { "name": "country", "in": "query", "description": "ISO2 country code", "schema": { "type": "string", "example": "RO" } }, { "name": "from", "in": "query", "description": "Date from (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "Date to (YYYY-MM-DD)", "schema": { "type": "string", "format": "date" } }, { "name": "warehouse", "in": "query", "description": "Filter by warehouse ID", "schema": { "type": "integer" } }, { "name": "cod_status", "in": "query", "description": "COD status filter", "schema": { "type": "string" } }, { "name": "receiverName", "in": "query", "description": "Filter by receiver name", "schema": { "type": "string" } }, { "name": "receiverCompany", "in": "query", "description": "Filter by receiver company", "schema": { "type": "string" } }, { "name": "per_page", "in": "query", "description": "Results per page", "schema": { "type": "integer", "default": 20 } }, { "name": "page", "in": "query", "description": "Page number", "schema": { "type": "integer", "default": 1 } } ], "responses": { "200": { "description": "Paginated shipments list", "content": { "application/json": { "schema": {} } } }, "400": { "description": "User or validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/shipments/{id}/download-label": { "get": { "tags": [ "Shipments" ], "summary": "Download / regenerate AWB label for a shipment", "description": "Download/regenerate AWB label for a shipment", "operationId": "downloadShipmentLabel", "parameters": [ { "name": "id", "in": "path", "description": "Shipment ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Label downloaded successfully", "content": { "application/json": { "schema": { "properties": { "status": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Label downloaded successfully" }, "data": { "properties": { "shipment_id": { "type": "integer" }, "awb": { "type": "string" }, "label_url": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" } } } }, "400": { "description": "Missing AWB or validation error" }, "404": { "description": "Shipment not found" }, "500": { "description": "Label download failed" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/send_orders": { "post": { "tags": [ "Orders" ], "summary": "Trigger AWB generation for existing received orders", "description": "Generates AWB labels for orders that are in \"Received\" status and do not yet have an AWB.", "operationId": "sendOrders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "order_no" ], "properties": { "order_no": { "description": "Array of order reference numbers", "type": "array", "items": { "type": "string" }, "example": [ "ORD-2026-00123", "ORD-2026-00124" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Processing results per order", "content": { "application/json": { "schema": { "properties": { "received_order_no_count": { "type": "integer" }, "query_count": { "type": "integer" }, "processing_data": { "type": "object" } }, "type": "object" } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/orders": { "post": { "tags": [ "Orders" ], "summary": "Create orders (+ optionally generate AWB)", "description": "Create one or more shipment orders. `warehouse` is optional for backwards compatibility; multi-warehouse accounts should send the warehouse ID for deterministic stock deduction and sender address selection. Set `generate_awb: true` to generate AWB labels in the same call. **GLS address behavior:** `address` is automatically split into Street / HouseNumber / HouseNumberInfo. Use `courier_overrides` when your system already has split Street / HouseNumber / HouseNumberInfo fields.", "operationId": "storeOrders", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": {} } }, "type": "object" }, "examples": { "door_to_door_no_warehouse": { "summary": "Door-to-door GLS order, no warehouse ID", "description": "Valid GLS door-to-door order. Omits warehouse_id/warehouse so the account default or single warehouse is used.", "value": { "orders": [ { "order_no": "ORD-2026-00123", "name": "Maria Popescu", "phone": "0723456789", "email": "maria@example.com", "address": "Strada Victoriei 42, Bl.B, Sc.2, Ap.5", "city": "Bucuresti", "county": "Sector 1", "zip_code": "010101", "country": "RO", "type": 1, "weight": 1.5, "currency": "RON", "courier": 301, "cod": 0, "generate_awb": true, "sku": "NSTT4795", "products": [ { "name": "Crema hidratanta", "sku": "NSTT4795", "qty": 1, "price": 89.99 } ] } ] } }, "door_to_door_override_no_warehouse": { "summary": "Door-to-door GLS order with overrides, no warehouse ID", "description": "Valid GLS order with pre-split Street/HouseNumber/HouseNumberInfo. Omits warehouse_id/warehouse.", "value": { "orders": [ { "order_no": "ORD-2026-00124", "name": "Ion Ionescu", "phone": "0712345678", "email": "ion@example.com", "address": "Bd. Unirii 45", "city": "Cluj-Napoca", "county": "Cluj", "zip_code": "400000", "country": "RO", "type": 1, "weight": 2, "currency": "RON", "courier": 301, "cod": 149, "generate_awb": true, "sku": "NSTT4795", "products": [ { "name": "Set ingrijire", "sku": "NSTT4795", "qty": 1, "price": 149 } ], "courier_overrides": { "street": "Bd. Unirii", "house_number": "45", "house_number_info": "Bl.C2, Sc.3, Ap.18", "content": "Set ingrijire piele" } } ] } }, "pudo_no_warehouse": { "summary": "GLS PUDO / ParcelShop order, no warehouse ID", "description": "Valid GLS PUDO order using a pudo_location_id returned by POST /external/pudo_locations. Omits warehouse_id/warehouse.", "value": { "orders": [ { "order_no": "ORD-2026-00125", "name": "Elena Marin", "phone": "0734567890", "email": "elena@example.com", "country": "RO", "type": 1, "currency": "RON", "pudo_location_id": 665, "cod": 0, "generate_awb": true, "sku": "NSTT4795", "products": [ { "name": "Crema hidratanta", "sku": "NSTT4795", "qty": 1, "price": 89.99 } ] } ] } } } } } }, "responses": { "200": { "description": "Orders processed (may include per-order errors)", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation errors — all orders rejected", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string" }, "error": { "type": "object" } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehousing/addStock": { "post": { "tags": [ "Stocks" ], "summary": "[DEPRECATED] Legacy single-stock change — use POST /stocks/import or PATCH /stocks/{id}", "description": "**Deprecated.** This legacy endpoint is retained for backwards compatibility only. It no longer updates stock immediately — it creates a warehouse import draft that must be reviewed and finalized through the new admin UI at `/admin/warehouse/import` (Receptions & inventories).\n\nNew integrations must use:\n- `POST /stocks/import` for bulk SKU-based imports (recommended), or\n- `PATCH /stocks/{id}` for single stock-id changes.\n\nDrafts created here appear in the same `/admin/warehouse/import` review queue and follow the identical finalization flow.", "operationId": "updateWarehouseStock", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "stockId", "status" ], "properties": { "stockId": { "description": "ID of the stock entry", "type": "integer", "example": 42 }, "status": { "description": "New status ID (see GET /stock-statuses)", "type": "integer", "example": 2 }, "qty": { "description": "Quantity delta (added or deducted according to status operation)", "type": "integer", "example": 5 } }, "type": "object" } } } }, "responses": { "200": { "description": "Draft warehouse import created — review and finalize at /admin/warehouse/import" }, "400": { "description": "Missing or invalid parameters" }, "404": { "description": "Stock not found" }, "500": { "description": "Draft creation failed" } }, "deprecated": true, "security": [ { "ApiKeyAuth": [] } ] } }, "/stocks": { "get": { "tags": [ "Stocks" ], "summary": "List warehouse stocks", "operationId": "listStocks", "parameters": [ { "name": "stockIds", "in": "query", "description": "Comma-separated list of stock IDs to retrieve", "schema": { "type": "string", "example": "1,2,3" } } ], "responses": { "200": { "description": "Stock list", "content": { "application/json": { "schema": { "properties": { "total": { "type": "integer" }, "stocks": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stocks/{id}": { "get": { "tags": [ "Stocks" ], "summary": "Get a single stock entry by ID", "operationId": "getStock", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Stock details" }, "404": { "description": "Stock not found" } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "tags": [ "Stocks" ], "summary": "Create stock change draft (single stock-id)", "description": "Creates a warehouse import draft for a single existing stock entry. The draft does **not** change inventory immediately; the warehouse team reviews and finalizes it from `/admin/warehouse/import` (Receptions & inventories).\n\nThe selected `status` determines the draft flow automatically:\n- add status => `received` / inbound reception\n- deduct status => `recalled` / stock recall\n- overwrite status => `count` / inventory count\n\nReplaces the deprecated `POST /warehousing/addStock` endpoint. For bulk SKU-based imports use `POST /stocks/import` instead.", "operationId": "updateStock", "parameters": [ { "name": "id", "in": "path", "description": "Existing stock row ID from GET /stocks", "required": true, "schema": { "type": "integer", "example": 101 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "status", "qty" ], "properties": { "status": { "description": "Stock status ID from GET /stock-statuses. The status operation controls the draft flow: add = received/inbound reception, deduct = recalled/stock recall, overwrite = count/inventory count.", "type": "integer", "example": 8 }, "qty": { "description": "Quantity to submit for review. Stock changes only after the draft is finalized in /admin/warehouse/import.", "type": "integer", "example": 50, "minimum": 1 }, "notes": { "description": "Optional notes shown on the draft manifest for the warehouse team.", "type": "string", "example": "Supplier ABC delivery", "nullable": true }, "manifest_details": { "description": "Optional transport, packaging, sender, and receiver data. These fields pre-fill the draft manifest and can be corrected by the warehouse team during review.", "properties": { "awb_number": { "type": "string", "example": "1234567890" }, "transport_document": { "type": "string", "example": "CMR-2026-001" }, "transporter": { "type": "string", "example": "DHL" }, "vehicle_number": { "type": "string", "example": "B123ABC" }, "package_type": { "type": "string", "example": "pallets", "enum": [ "pallets", "boxes", "mixed" ] }, "pallets_count": { "type": "integer", "example": 2 }, "boxes_count": { "type": "integer", "example": 0 }, "total_weight": { "type": "number", "format": "float", "example": 120.5 }, "sender_company": { "type": "string", "example": "Supplier SRL" }, "sender_contact": { "type": "string", "example": "Ion Popescu" }, "sender_mobile": { "type": "string", "example": "+40722111222" }, "receiver_company": { "type": "string", "example": "ALT EXPRESS" }, "receiver_contact": { "type": "string", "example": "Warehouse Team" } }, "type": "object", "nullable": true } }, "type": "object" }, "examples": { "inboundReception": { "summary": "Inbound reception / add stock", "description": "Use a stock status whose operation is add. The created draft appears as received in /admin/warehouse/import.", "value": { "status": 8, "qty": 50, "notes": "Inbound reception from supplier ABC", "manifest_details": { "transporter": "DHL", "awb_number": "1234567890", "package_type": "pallets", "pallets_count": 2 } } }, "stockRecall": { "summary": "Stock recall / deduct stock", "description": "Use a stock status whose operation is deduct. The created draft appears as recalled in /admin/warehouse/import.", "value": { "status": 1, "qty": 3, "notes": "Recall damaged units from stock", "manifest_details": { "transporter": "Internal transfer", "package_type": "boxes", "boxes_count": 1 } } }, "inventoryCount": { "summary": "Inventory count / overwrite stock", "description": "Use a stock status whose operation is overwrite. The created draft appears as count in /admin/warehouse/import.", "value": { "status": 11, "qty": 125, "notes": "Physical inventory count correction" } } } } } }, "responses": { "200": { "description": "Draft warehouse import created. Response includes draft.reference, draft.file, draft.flow_type, draft.status, draft.items_count, and draft.review_url.", "content": { "application/json": { "schema": {}, "example": { "status": "draft_created", "message": "Stock change has been submitted as a draft import for warehouse team review.", "draft": { "reference": "RCP-20260508-047-977B2", "file": "api-import-20260508-101500-ab12cd34ef.xls", "flow_type": "received", "status": "draft", "items_count": 1, "existing_products": 1, "new_products": 0, "review_url": "/admin/warehouse/import/review/api-import-20260508-101500-ab12cd34ef.xls" } } } } }, "400": { "description": "Validation error" }, "404": { "description": "Stock not found" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stock-statuses": { "get": { "tags": [ "Stocks" ], "summary": "List available stock statuses", "description": "Returns the list of stock statuses that can be used to create stock change drafts with PATCH /stocks/{id} (or the deprecated POST /warehousing/addStock).", "operationId": "listStockStatuses", "responses": { "200": { "description": "Stock statuses list" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/shipment-statuses": { "get": { "tags": [ "Shipments" ], "summary": "List shipment statuses", "description": "Returns the list of statuses that a shipment can hold, as defined in the shipments model.", "operationId": "listShipmentStatuses", "responses": { "200": { "description": "Shipment statuses list" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stocks/import": { "post": { "tags": [ "Stocks" ], "summary": "Bulk stock import draft (recommended)", "description": "**Recommended replacement for the deprecated `POST /warehousing/addStock`.** Creates a warehouse import draft. Normally the warehouse team reviews and finalizes it from `/admin/warehouse/import` (Receptions & inventories). For companies explicitly approved for automatic API stock completion by a Super Admin, `received` drafts are finalized immediately by this request and stock is applied. `recalled` and `count` drafts always require warehouse review.\n\nDraft flows:\n- `received` = inbound reception / add stock\n- `recalled` = stock recall / deduct stock\n- `count` = inventory count / overwrite counted stock\n\nSupports up to 500 SKUs per call. `warehouse_id` is required when the account has multiple warehouses; for single-warehouse accounts it may be omitted. New SKUs can be created on the fly by including `name` and optional product fields.", "operationId": "importStocks", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "products" ], "properties": { "flow_type": { "description": "Draft flow shown in /admin/warehouse/import. received = inbound reception/add stock; recalled = stock recall/deduct stock; count = inventory count/overwrite stock.", "type": "string", "example": "received", "default": "received", "enum": [ "received", "recalled", "count" ] }, "notes": { "description": "Optional notes shown on the draft manifest for the warehouse team.", "type": "string", "example": "API import from supplier ABC", "nullable": true }, "manifest_details": { "description": "Optional transport, packaging, sender, and receiver data. These fields pre-fill the draft manifest and can be corrected by the warehouse team during review.", "properties": { "awb_number": { "type": "string", "example": "1234567890" }, "transport_document": { "type": "string", "example": "CMR-2026-001" }, "transporter": { "type": "string", "example": "DHL" }, "vehicle_number": { "type": "string", "example": "B123ABC" }, "package_type": { "type": "string", "example": "pallets", "enum": [ "pallets", "boxes", "mixed" ] }, "pallets_count": { "type": "integer", "example": 2 }, "boxes_count": { "type": "integer", "example": 0 }, "total_weight": { "type": "number", "format": "float", "example": 120.5 }, "total_volume": { "type": "number", "format": "float", "example": 1.4 }, "sender_email": { "type": "string", "format": "email", "example": "supplier@example.com" }, "sender_company": { "type": "string", "example": "Supplier SRL" }, "sender_contact": { "type": "string", "example": "Ion Popescu" }, "sender_mobile": { "type": "string", "example": "+40722111222" }, "sender_street": { "type": "string", "example": "Strada Exemplu 10" }, "sender_city": { "type": "string", "example": "Bucuresti" }, "sender_county": { "type": "string", "example": "Bucuresti" }, "sender_postal_code": { "type": "string", "example": "010101" }, "sender_country": { "type": "string", "example": "RO" }, "receiver_company": { "type": "string", "example": "ALT EXPRESS" }, "receiver_contact": { "type": "string", "example": "Warehouse Team" }, "receiver_email": { "type": "string", "format": "email", "example": "warehouse@example.com" }, "receiver_mobile": { "type": "string", "example": "+40722111333" }, "receiver_street": { "type": "string", "example": "Strada Depozitului 1" }, "receiver_city": { "type": "string", "example": "Bucuresti" }, "receiver_county": { "type": "string", "example": "Ilfov" }, "receiver_postal_code": { "type": "string", "example": "077000" }, "receiver_country": { "type": "string", "example": "RO" } }, "type": "object", "nullable": true }, "importOption": { "description": "Deprecated legacy field. Use flow_type instead; the draft flow ignores importOption.", "type": "string", "deprecated": true, "enum": [ "stock_correction", "add" ] }, "products": { "type": "array", "items": { "required": [ "sku", "qty" ], "properties": { "sku": { "description": "Product SKU", "type": "string", "example": "NSTT4795" }, "qty": { "description": "Quantity prefilled for warehouse confirmation, or applied immediately for an approved auto-complete company using the received flow.", "type": "integer", "example": 5, "minimum": 1 }, "warehouse_id": { "description": "Warehouse ID. Required when the account has multiple warehouses. For single-warehouse accounts it may be omitted.", "type": "integer", "example": 38, "nullable": true }, "warehouse": { "description": "Legacy warehouse name. Prefer warehouse_id for new integrations.", "type": "string", "example": "Main Warehouse" }, "name": { "description": "Required only when the SKU does not already exist", "type": "string", "example": "Crema hidratanta" }, "type": { "description": "Optional product type for new products; defaults to simple.", "type": "string", "example": "simple", "enum": [ "simple", "piece", "compound", "multi_pieces" ] }, "barcode": { "description": "Optional barcode for new products or product metadata pre-fill.", "type": "string", "example": "5941234567890" }, "code": { "description": "Optional product code.", "type": "string", "example": "CRM-001" }, "description": { "description": "Optional product description for new products.", "type": "string", "example": "Crema hidratanta 50ml" }, "weight": { "description": "Optional product weight in kg.", "type": "number", "format": "float", "example": 0.35 }, "length": { "description": "Optional product length.", "type": "number", "format": "float", "example": 10 }, "width": { "description": "Optional product width.", "type": "number", "format": "float", "example": 6 }, "height": { "description": "Optional product height.", "type": "number", "format": "float", "example": 4 }, "location": { "description": "New products only: suggested warehouse location. Existing products ignore this field and use the location already assigned by the warehouse team.", "type": "string", "example": "A-01-02", "nullable": true }, "expiry": { "description": "Optional expiry date, format YYYY-MM-DD.", "type": "string", "format": "date", "example": "2027-12-31", "nullable": true }, "sub_products": { "description": "For compound/multi_pieces products, for example \"2xSKU1 3xSKU2\".", "type": "string", "example": "2xNSTT4795 1xNSTT4796", "nullable": true } }, "type": "object" }, "maxItems": 500 } }, "type": "object" }, "examples": { "inboundReceptionExistingSku": { "summary": "Inbound reception - existing SKU", "description": "Adds stock after warehouse finalization, or immediately when API stock auto-completion is enabled for the company.", "value": { "flow_type": "received", "notes": "Inbound reception from supplier ABC", "manifest_details": { "transporter": "DHL", "awb_number": "1234567890", "package_type": "pallets", "pallets_count": 2 }, "products": [ { "sku": "NSTT4795", "qty": 5, "warehouse_id": 38, "expiry": "2027-12-31" } ] } }, "stockRecallExistingSku": { "summary": "Stock recall - existing SKU", "description": "Creates a recalled draft. Inventory is deducted only when finalized in /admin/warehouse/import.", "value": { "flow_type": "recalled", "notes": "Recall stock for damaged goods", "manifest_details": { "transporter": "Internal transfer", "package_type": "boxes", "boxes_count": 1 }, "products": [ { "sku": "NSTT4795", "qty": 2, "warehouse_id": 38 } ] } }, "inventoryCountExistingSku": { "summary": "Inventory count - overwrite counted stock", "description": "Creates a count draft. Finalization overwrites stock to the counted quantity.", "value": { "flow_type": "count", "notes": "Physical count from warehouse shelf A-01", "products": [ { "sku": "NSTT4795", "qty": 125, "warehouse_id": 38 } ] } }, "newSkuInboundReception": { "summary": "New SKU creation during inbound reception", "description": "For a SKU that does not exist yet, name is required. Optional product metadata pre-fills the draft for review.", "value": { "flow_type": "received", "notes": "Inbound reception with new product setup", "products": [ { "sku": "NEW-SKU-001", "name": "Crema hidratanta 50ml", "type": "simple", "barcode": "5941234567890", "code": "CRM-001", "description": "Crema hidratanta 50ml", "qty": 24, "warehouse_id": 38, "location": "A-01-02", "weight": 0.35, "length": 10, "width": 6, "height": 4, "expiry": "2027-12-31" } ] } }, "mixedManifestMultipleProducts": { "summary": "Manifest with multiple products and sender/receiver details", "description": "Shows transport, packaging, sender, receiver, existing SKU, and new SKU fields together.", "value": { "flow_type": "received", "notes": "Container import with mixed products", "manifest_details": { "transporter": "DHL Freight", "awb_number": "AWB-99887766", "transport_document": "CMR-2026-001", "vehicle_number": "B123ABC", "package_type": "mixed", "pallets_count": 3, "boxes_count": 12, "total_weight": 540.5, "sender_company": "Supplier SRL", "sender_contact": "Ion Popescu", "sender_mobile": "+40722111222", "sender_city": "Bucuresti", "sender_country": "RO", "receiver_company": "ALT EXPRESS", "receiver_contact": "Warehouse Team", "receiver_city": "Bucuresti", "receiver_country": "RO" }, "products": [ { "sku": "NSTT4795", "qty": 10, "warehouse_id": 38 }, { "sku": "BUNDLE-NEW-001", "name": "Bundle cosmetic set", "type": "compound", "sub_products": "2xNSTT4795 1xNSTT4796", "qty": 5, "warehouse_id": 38 } ] } } } } } }, "responses": { "200": { "description": "Warehouse import created. Status is draft_created for manual review or finalized for an approved company using the received flow.", "content": { "application/json": { "schema": {}, "example": { "status": "draft_created", "message": "Stock import draft created. Review and finalize it from /admin/warehouse/import.", "draft": { "reference": "RCP-20260508-047-28BBC", "file": "api-import-20260508-101455-a1b2c3d4e5.xls", "flow_type": "received", "status": "draft", "items_count": 2, "existing_products": 1, "new_products": 1, "review_url": "/admin/warehouse/import/review/api-import-20260508-101455-a1b2c3d4e5.xls" }, "errors": [] } } } }, "400": { "description": "Validation errors" }, "401": { "description": "Unauthorized" }, "500": { "description": "Draft created but automatic finalization failed; the response includes the draft reference" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/stocks/import/{reference}/complete": { "post": { "tags": [ "Stocks" ], "summary": "Complete an API-created stock reception", "description": "Finalizes a `received` stock-import draft created by `POST /stocks/import`. This applies the submitted quantities to stock and marks the reception finalized. Repeating the same request is safe: an already finalized reference is returned without applying stock again.", "operationId": "completeStockReception", "parameters": [ { "name": "reference", "in": "path", "description": "Draft reference returned by POST /stocks/import", "required": true, "schema": { "type": "string" }, "example": "RCP-20260713-118-AE517" } ], "responses": { "200": { "description": "Reception finalized or already finalized" }, "400": { "description": "Invalid or non-reception draft" }, "404": { "description": "Reception reference not found" }, "409": { "description": "Reception is currently being finalized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehouses": { "get": { "tags": [ "Configuration" ], "summary": "List your warehouses", "description": "Returns warehouses associated with your account. Use the `id` as the `warehouse` field when creating orders.", "operationId": "listWarehouses", "responses": { "200": { "description": "Warehouses list" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/couriers": { "get": { "tags": [ "Configuration" ], "summary": "List enabled couriers", "description": "Returns couriers configured and enabled for your account. Use the `courier_id` / `platform_id` as the `courier` field when creating orders.", "operationId": "listCouriers", "responses": { "200": { "description": "Couriers list" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/pudo_locations": { "post": { "tags": [ "Configuration" ], "summary": "Query PUDO / ParcelShop pickup locations", "operationId": "listPudoLocations", "requestBody": { "content": { "application/json": { "schema": {} } } }, "responses": { "200": { "description": "PUDO locations matching the filter", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "platforms_slug": { "type": "string" }, "pudo_id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "county": { "type": "string" }, "postal_code": { "type": "string" } }, "type": "object" } } }, "type": "object" } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/upload-invoice": { "post": { "tags": [ "Invoices" ], "summary": "Upload a single invoice and link it to a shipment", "operationId": "uploadInvoice", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "order_no": { "description": "Order reference number", "type": "string", "example": "ORD-2026-00123" }, "invoice_no": { "description": "Invoice number", "type": "string", "example": "INV-0042" }, "invoice_date": { "type": "string", "format": "date", "example": "2026-04-21" }, "invoice_value": { "type": "number", "format": "float", "example": 89.99 } }, "type": "object" } } } }, "responses": { "200": { "description": "Invoice processed" }, "400": { "description": "Validation errors" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/upload-invoices": { "post": { "tags": [ "Invoices" ], "summary": "Upload multiple invoices in a single request", "operationId": "uploadInvoices", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "properties": { "order_no": { "type": "string", "example": "ORD-2026-00123" }, "invoice_no": { "type": "string", "example": "INV-0042" }, "invoice_date": { "type": "string", "format": "date" }, "invoice_value": { "type": "number", "format": "float" } }, "type": "object" } } } } }, "responses": { "200": { "description": "All invoices processed" }, "400": { "description": "Validation errors in one or more items" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/addresses/cities": { "get": { "tags": [ "Addresses" ], "summary": "Search deliverable cities", "description": "Returns cities that at least one courier (DPD or Cargus) can deliver to. Use the returned id as city_id in the streets endpoint and to confirm correct courier IDs before building an AWB.", "operationId": "listAddressCities", "parameters": [ { "name": "country", "in": "query", "description": "ISO2 country code (RO, BG …)", "schema": { "type": "string", "example": "RO" } }, { "name": "q", "in": "query", "description": "City name prefix (min 2 chars)", "schema": { "type": "string", "example": "Abrud" } }, { "name": "limit", "in": "query", "description": "Max results (default 20, max 50)", "schema": { "type": "integer", "default": 20 } } ], "responses": { "200": { "description": "List of deliverable cities with courier IDs", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Validation error" } } } }, "/api/addresses/cities/{city_id}": { "get": { "tags": [ "Addresses" ], "summary": "City detail with courier IDs", "description": "Returns the correct Cargus locality_id / county_id and DPD site_id / country_id for one city. Use these exact values in your AWB payload — wrong locality_id is the most common Cargus rejection reason.", "operationId": "getCityDetail", "parameters": [ { "name": "city_id", "in": "path", "description": "Internal city ID (from /api/addresses/cities)", "required": true, "schema": { "type": "integer", "example": 89874 } } ], "responses": { "200": { "description": "City detail including couriers block", "content": { "application/json": { "schema": {}, "example": { "status": true, "data": { "id": 89874, "name": "Abrud", "post_code": "515100", "couriers": { "cargus": { "locality_id": 551, "county_id": 3, "county_abbr": "AB" }, "dpd": { "site_id": 642101160, "country_id": 642 } } } } } } }, "404": { "description": "City not found or not deliverable" } } } }, "/api/addresses/streets": { "get": { "tags": [ "Addresses" ], "summary": "Street autocomplete for a city", "description": "Returns up to 20 street name suggestions for the given city. Cargus streets are returned first (deduped by diacritics), DPD streets fill remaining slots. Use source=cargus or source=dpd to restrict.", "operationId": "searchAddressStreets", "parameters": [ { "name": "city_id", "in": "query", "description": "Internal city ID", "required": true, "schema": { "type": "integer", "example": 89874 } }, { "name": "q", "in": "query", "description": "Street name prefix (min 1 char)", "required": true, "schema": { "type": "string", "example": "MAI" } }, { "name": "source", "in": "query", "description": "cargus | dpd | all (default: all)", "schema": { "type": "string", "default": "all", "enum": [ "all", "cargus", "dpd" ] } } ], "responses": { "200": { "description": "Street suggestions", "content": { "application/json": { "schema": {}, "example": { "status": true, "count": 2, "data": [ { "id": 44326, "name": "1 Mai, Strada", "source": "cargus" }, { "id": 642000599, "name": "str. 1 MAI", "source": "dpd" } ] } } } }, "400": { "description": "Missing city_id or q" }, "404": { "description": "City not found or not deliverable" } } } }, "/v2/awb/import": { "post": { "tags": [ "AWB Import (v2)" ], "summary": "Import AWBs from an external platform and link to configured couriers", "description": "Import one or more AWBs generated by an external system and associate them with existing Altexpress orders.\n\n**`courier_slug`** can be any slug — if the courier is already configured on your account it will be linked directly. If the slug is not found, a virtual courier entry is created automatically so you can still track the shipment.\n\nEach item in `orders` maps an `order_no` to an `awb`. The order must already exist in Altexpress.\n\nSet `generate_pdf: true` to produce a printable A6 AWB label (PDF) for every imported AWB. The label is stored and accessible via the Print Labels queue, regardless of courier type.\n\nOptionally supply `platform` + `external_status` per order to auto-map the external status to an Altexpress status.", "operationId": "importExternalAwb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "courier_slug", "orders" ], "properties": { "courier_slug": { "description": "Courier slug to link AWBs against. Use GET /external/v2/couriers for configured ones. Any unknown slug creates a virtual courier automatically.", "type": "string", "example": "dpd" }, "courier_label": { "description": "Human-readable courier name printed on the PDF label. Defaults to courier_slug if omitted.", "type": "string", "example": "DPD Romania", "nullable": true }, "platform": { "description": "External platform slug for status mapping (shopify, woocommerce, prestashop, magento, custom). Omit to skip status update.", "type": "string", "example": "shopify", "nullable": true }, "generate_pdf": { "description": "Generate an A6 AWB PDF label for every imported AWB. Works for all courier types.", "type": "boolean", "default": true }, "orders": { "description": "List of orders to import", "type": "array", "items": { "required": [ "order_no", "awb" ], "properties": { "order_no": { "description": "Altexpress order number", "type": "string", "example": "ORD-2026-001" }, "awb": { "description": "External AWB number", "type": "string", "example": "DPD123456789" }, "external_status": { "description": "Raw status string from the external platform. Used with `platform` to map to Altexpress status.", "type": "string", "example": "fulfilled", "nullable": true } }, "type": "object" } } }, "type": "object" }, "examples": { "configuredCourier": { "summary": "Import to a configured courier (DPD)", "description": "Links AWBs to an existing courier on your account. A PDF label is generated for each AWB.", "value": { "courier_slug": "dpd", "courier_label": "DPD Romania", "generate_pdf": true, "orders": [ { "order_no": "ORD-2026-00123", "awb": "DPD123456789" }, { "order_no": "ORD-2026-00124", "awb": "DPD987654321" } ] } }, "unknownCourierAutoCreate": { "summary": "Import with an unknown courier slug", "description": "The courier_slug is not configured on your account, so a virtual courier is created automatically. The shipment can still be tracked via the imported AWB.", "value": { "courier_slug": "my-3pl-courier", "courier_label": "My 3PL Courier", "generate_pdf": true, "orders": [ { "order_no": "ORD-2026-00130", "awb": "EXT-AWB-55512345" } ] } }, "importWithStatusMapping": { "summary": "Import + map a Shopify status in one call", "description": "Supply platform + external_status per order. \"fulfilled\" maps to Altexpress status 4 (Dispatched). Reserved stock is deducted; if none is available the order goes to On Hold (20).", "value": { "courier_slug": "dpd", "platform": "shopify", "generate_pdf": true, "orders": [ { "order_no": "ORD-2026-00140", "awb": "DPD111222333", "external_status": "fulfilled" } ] } } } } } }, "responses": { "200": { "description": "Import results — per-order success/failure breakdown", "content": { "application/json": { "schema": { "properties": { "imported": { "description": "Number of AWBs successfully imported", "type": "integer" }, "failed": { "description": "Number of orders that could not be imported", "type": "integer" }, "results": { "type": "array", "items": { "properties": { "order_no": { "type": "string" }, "awb": { "type": "string" }, "status": { "type": "string", "enum": [ "imported", "failed" ] }, "altexpress_status": { "description": "Altexpress Codes:: value applied", "type": "integer", "nullable": true }, "altexpress_status_label": { "type": "string", "nullable": true }, "stock_deducted": { "description": "Whether reserved stock was successfully deducted. false means stock was 0 or not reserved — order set to On Hold (status 20).", "type": "boolean" }, "pdf_generated": { "description": "Whether a PDF AWB label was successfully generated.", "type": "boolean" }, "courier_created": { "description": "true when a virtual courier entry was auto-created for an unknown slug.", "type": "boolean" }, "error": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "example": { "imported": 1, "failed": 0, "results": [ { "order_no": "ORD-2026-00140", "awb": "DPD111222333", "status": "imported", "altexpress_status": 4, "altexpress_status_label": "Dispatched", "stock_deducted": true, "pdf_generated": true, "courier_created": false, "error": null } ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v2/awb/status-update": { "post": { "tags": [ "AWB Import (v2)" ], "summary": "Update Altexpress shipment status from an external platform status", "description": "Translate an external platform's shipment status to an Altexpress status and apply it to one or more shipments.\n\n**Two ways to set the status per update entry:**\n1. Supply `platform` (at the top level) + `external_status` per entry — the status is mapped automatically. Use `GET /v2/awb/status-map` to see the full mapping table.\n2. Supply `altexpress_status` directly (an Altexpress status integer) to bypass mapping. This takes precedence over `external_status` if both are present.\n\n**Look up the shipment** by `order_no` or `awb` (at least one is required per entry).\n\n**Return Complete (status 12)** automatically adds the order's stock back to the warehouse. This is idempotent — repeated status-12 updates for the same order restore stock only once, and the response field `stock_restored` reflects whether this call performed the restock.", "operationId": "updateAwbStatus", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "updates" ], "properties": { "platform": { "description": "Platform slug for status mapping (shopify, woocommerce, prestashop, magento, custom)", "type": "string", "example": "woocommerce", "nullable": true }, "updates": { "type": "array", "items": { "properties": { "order_no": { "description": "Find shipment by order number", "type": "string", "nullable": true }, "awb": { "description": "Find shipment by AWB (alternative to order_no)", "type": "string", "nullable": true }, "external_status": { "description": "Raw status from the external platform", "type": "string", "nullable": true }, "altexpress_status": { "description": "Override: set this Altexpress status value directly, bypassing platform mapping", "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" }, "examples": { "mapShopifyStatuses": { "summary": "Map several Shopify statuses at once", "description": "Looks up each shipment by order_no and maps the Shopify status to Altexpress. \"returned\" maps to status 12 and triggers stock restoration.", "value": { "platform": "shopify", "updates": [ { "order_no": "ORD-2026-00140", "external_status": "in_transit" }, { "order_no": "ORD-2026-00123", "external_status": "delivered" }, { "order_no": "ORD-2026-00130", "external_status": "returned" } ] } }, "lookupByAwb": { "summary": "Update by AWB instead of order_no", "description": "When you only have the AWB, look the shipment up by awb.", "value": { "platform": "woocommerce", "updates": [ { "awb": "DPD123456789", "external_status": "delivered" } ] } }, "directAltexpressStatus": { "summary": "Set the Altexpress status directly (no mapping)", "description": "Bypass platform mapping by sending altexpress_status. 12 = Return Complete, which restores stock to the warehouse.", "value": { "updates": [ { "order_no": "ORD-2026-00130", "altexpress_status": 12 } ] } } } } } }, "responses": { "200": { "description": "Per-shipment status update results", "content": { "application/json": { "schema": { "properties": { "updated": { "type": "integer" }, "failed": { "type": "integer" }, "results": { "type": "array", "items": { "properties": { "order_no": { "type": "string", "nullable": true }, "awb": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "updated", "failed" ] }, "external_status": { "type": "string", "nullable": true }, "altexpress_status": { "type": "integer", "nullable": true }, "altexpress_status_label": { "type": "string", "nullable": true }, "stock_restored": { "description": "Present only when status is Return Complete (12). true = stock added back to warehouse on this call; false = already restored on an earlier call (idempotent).", "type": "boolean", "nullable": true }, "error": { "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "example": { "updated": 3, "failed": 0, "results": [ { "order_no": "ORD-2026-00140", "awb": "DPD111222333", "status": "updated", "external_status": "in_transit", "altexpress_status": 5, "altexpress_status_label": "In Transit", "error": null }, { "order_no": "ORD-2026-00123", "awb": "DPD123456789", "status": "updated", "external_status": "delivered", "altexpress_status": 6, "altexpress_status_label": "Delivered", "error": null }, { "order_no": "ORD-2026-00130", "awb": "EXT-AWB-55512345", "status": "updated", "external_status": "returned", "altexpress_status": 12, "altexpress_status_label": "Return Complete", "stock_restored": true, "error": null } ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v2/awb/status-map": { "get": { "tags": [ "AWB Import (v2)" ], "summary": "Get the status mapping table for one or all supported platforms", "description": "Returns the full mapping of external platform statuses to Altexpress status codes. Call this first to discover exactly which `external_status` strings each platform accepts and what they map to.\n\nUse the optional `platform` query param to narrow to a single platform.\n\nThe response includes both directions per platform: `external_to_altexpress` and `altexpress_to_external`. It also returns `altexpress_statuses` — the full list of Altexpress status codes and their human-readable labels.", "operationId": "getStatusMap", "parameters": [ { "name": "platform", "in": "query", "description": "Platform slug (shopify, woocommerce, prestashop, magento, custom). Omit for all.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status mapping table", "content": { "application/json": { "schema": { "properties": { "supported_platforms": { "type": "array", "items": { "type": "string" } }, "altexpress_statuses": { "description": "All Altexpress status codes and their labels", "type": "object", "additionalProperties": { "type": "string" } }, "maps": { "description": "Per-platform mappings", "type": "object", "additionalProperties": { "properties": { "external_to_altexpress": { "type": "object", "additionalProperties": { "type": "integer" } }, "altexpress_to_external": { "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object" } } }, "type": "object" }, "example": { "supported_platforms": [ "shopify", "woocommerce", "prestashop", "magento", "custom" ], "altexpress_statuses": { "2": "Printed", "4": "Dispatched", "5": "In Transit", "6": "Delivered", "12": "Return Complete", "20": "On Hold" }, "maps": { "shopify": { "external_to_altexpress": { "fulfilled": 4, "in_transit": 5, "delivered": 6, "returned": 12 }, "altexpress_to_external": { "4": "fulfilled", "5": "in_transit", "6": "delivered", "12": "returned" } } } } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v2/couriers": { "get": { "tags": [ "AWB Import (v2)" ], "summary": "List couriers configured for your account (v2)", "description": "Returns all courier platforms enabled for your account. Use the `slug` field as `courier_slug` when calling `POST /external/v2/awb/import`.\n\nNote: you are not limited to this list — `POST /v2/awb/import` accepts any `courier_slug`, and an unknown one auto-creates a virtual courier. This endpoint simply tells you which couriers are already set up.", "operationId": "listCouriersV2", "responses": { "200": { "description": "List of configured couriers", "content": { "application/json": { "schema": { "properties": { "couriers": { "type": "array", "items": { "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": "string" }, "nickname": { "type": "string" }, "type": { "type": "string" }, "enabled": { "type": "boolean" } }, "type": "object" } } }, "type": "object" }, "example": { "couriers": [ { "id": 164, "slug": "dpd", "name": "DPD", "nickname": "DPD Romania", "type": "couriers", "enabled": true }, { "id": 414, "slug": "gls", "name": "GLS", "nickname": "GLS", "type": "couriers", "enabled": true }, { "id": 268, "slug": "virtual_courier", "name": "Virtual courier", "nickname": "My 3PL Courier", "type": "couriers", "enabled": true } ] } } } }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v2/awb/delete": { "post": { "tags": [ "AWB Import (v2)" ], "summary": "Delete an imported AWB and return the order to Received", "description": "Remove an AWB that was previously imported via `POST /v2/awb/import`. The order's AWB is cleared, its status returns to **Received (0)**, and the deducted stock is reserved back to the warehouse — mirroring the native Delete-AWB flow.\n\n**Restriction:** only AWBs imported through this API can be deleted here. Platform/courier-generated AWBs are refused — those must be voided through the courier in the Altexpress UI so the label is cancelled at the courier too.\n\nLook up each order by `order_no` or `awb` (at least one required).", "operationId": "deleteImportedAwb", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": { "properties": { "order_no": { "description": "Find shipment by order number", "type": "string", "nullable": true }, "awb": { "description": "Find shipment by AWB (alternative to order_no)", "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "examples": { "deleteByOrderNo": { "summary": "Delete imported AWB by order number", "description": "Clears the AWB, returns the order to Received, and restocks.", "value": { "orders": [ { "order_no": "ORD-2026-00130" } ] } } } } } }, "responses": { "200": { "description": "Per-order delete results", "content": { "application/json": { "schema": {}, "example": { "deleted": 1, "failed": 0, "results": [ { "order_no": "ORD-2026-00130", "awb": "EXT-AWB-55512345", "status": "deleted", "new_status": 0, "stock_restored": true, "error": null } ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v2/awb/cancel": { "post": { "tags": [ "AWB Import (v2)" ], "summary": "Cancel an order (with or without an imported AWB)", "description": "Cancel an order. The order's status becomes **Cancelled (10)** and the AWB (if any) is kept on the record for audit — mirroring the native Cancel-Order flow.\n\n**Stock handling:** if the order actually deducted stock (it reached Print Labels or beyond), that stock is added back to the warehouse. Orders in Received (0) or On Hold (20) never deducted stock, so only their reserved rows are released — no restock.\n\n**Works on orders without an AWB:** a Received (status 0) order with no AWB can be cancelled to free its reserved stock.\n\n**Restriction:** if the order has an AWB, it must have been imported via `POST /v2/awb/import`. Orders with platform/courier-generated AWBs are refused — cancel those through the courier in the Altexpress UI. Orders that are already Cancelled (10) or Return Complete (12) are refused (nothing to cancel).\n\nLook up each order by `order_no` or `awb` (at least one required).", "operationId": "cancelImportedOrder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": { "properties": { "order_no": { "description": "Find shipment by order number", "type": "string", "nullable": true }, "awb": { "description": "Find shipment by AWB (alternative to order_no)", "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" }, "examples": { "cancelByOrderNo": { "summary": "Cancel an imported order by order number", "description": "Sets status to Cancelled (10), restocks, keeps the AWB for audit.", "value": { "orders": [ { "order_no": "ORD-2026-00130" } ] } } } } } }, "responses": { "200": { "description": "Per-order cancel results", "content": { "application/json": { "schema": {}, "example": { "cancelled": 1, "failed": 0, "results": [ { "order_no": "ORD-2026-00130", "awb": "EXT-AWB-55512345", "status": "cancelled", "new_status": 10, "stock_restored": true, "error": null } ] } } } }, "400": { "description": "Validation error" }, "401": { "description": "Unauthorized" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/warehousing/importStock": { "post": { "tags": [ "Stocks" ], "summary": "Import stock products (legacy)", "description": "**Deprecated.** Use `POST /stocks/import` instead.\n\nSubmits a batch of products for stock import using the legacy warehouse-name-based format. Unlike the current endpoint, this uses warehouse names (not IDs) and requires all product fields. Maximum 500 products per call.\n\nProducts are grouped by type (`simple`/`compound`) before import.", "operationId": "legacyImportStock", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "products" ], "properties": { "importOption": { "description": "Import mode. `stock_correction` overwrites counted stock; `add` adds to existing stock.", "type": "string", "example": "stock_correction", "default": "stock_correction", "enum": [ "stock_correction", "add" ] }, "products": { "type": "array", "items": { "required": [ "warehouse", "type", "sku", "name", "code", "barcode", "description", "qty", "weight", "length", "width", "height" ], "properties": { "warehouse": { "description": "Warehouse name (must match an existing warehouse).", "type": "string", "example": "Main Warehouse" }, "type": { "description": "Product type. `piece` is an alias for `simple`; `multi_pieces` is an alias for `compound`.", "type": "string", "example": "simple", "enum": [ "simple", "piece", "compound", "multi_pieces" ] }, "sku": { "description": "Product SKU.", "type": "string", "example": "NSTT4795", "maxLength": 45 }, "name": { "description": "Product name.", "type": "string", "example": "Crema hidratanta 50ml", "maxLength": 100 }, "code": { "description": "Internal product code.", "type": "string", "example": "CRM-001", "maxLength": 45 }, "barcode": { "description": "Product barcode (EAN/UPC).", "type": "string", "example": "5941234567890", "maxLength": 45 }, "description": { "description": "Product description.", "type": "string", "example": "Crema hidratanta 50ml", "maxLength": 255 }, "qty": { "description": "Quantity to import.", "type": "integer", "example": 10, "minimum": 1 }, "weight": { "description": "Product weight in kg.", "type": "number", "format": "float", "example": 0.35 }, "length": { "description": "Product length in cm.", "type": "number", "format": "float", "example": 10 }, "width": { "description": "Product width in cm.", "type": "number", "format": "float", "example": 6 }, "height": { "description": "Product height in cm.", "type": "number", "format": "float", "example": 4 }, "location": { "description": "Optional warehouse shelf/location.", "type": "string", "example": "A-01-02", "nullable": true, "maxLength": 45 }, "expiry": { "description": "Optional expiry date in YYYY-MM-DD format.", "type": "string", "format": "date", "example": "2027-12-31", "nullable": true }, "company_id": { "description": "Optional company ID override; defaults to the authenticated user's company.", "type": "integer", "example": 5, "nullable": true } }, "type": "object" }, "maxItems": 500 } }, "type": "object" }, "example": { "importOption": "stock_correction", "products": [ { "warehouse": "Main Warehouse", "type": "simple", "sku": "NSTT4795", "name": "Crema hidratanta 50ml", "code": "CRM-001", "barcode": "5941234567890", "description": "Crema hidratanta 50ml", "qty": 10, "weight": 0.35, "length": 10, "width": 6, "height": 4, "location": "A-01-02", "expiry": "2027-12-31" } ] } } } }, "responses": { "200": { "description": "Import result with success flag and per-product errors when applicable." }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": {}, "example": { "errors": { "success": false, "message": "Products limit exceeded (max: 500)" } } } } }, "401": { "description": "Unauthorized" } }, "deprecated": true, "security": [ { "ApiKeyAuth": [] } ] } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "description": "JWT token provided by Altexpress support", "name": "X-Authorization", "in": "header" } } }, "tags": [ { "name": "AWB Import (v2)", "description": "Import AWBs from external platforms and map tracking statuses to Altexpress" }, { "name": "Shipments", "description": "Shipments" }, { "name": "Orders", "description": "Orders" }, { "name": "Stocks", "description": "Stocks" }, { "name": "Configuration", "description": "Configuration" }, { "name": "Invoices", "description": "Invoices" }, { "name": "Addresses", "description": "Addresses" } ] }