仓信AI / Cangxin AI Open API v1 · Seller / ERP API

For your own system or ERP (Lingxing, Dianxiaomi, Mabang ...): create orders and inbound notices, query stock and tracking, and receive webhooks. Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1, import it into Postman / Apifox).

Base URL: https://cangxinai.com/api/v1

curl https://cangxinai.com/api/v1/me \
  -H "X-WMS-Key: <appKey>" \
  -H "Authorization: Bearer <appSecret>"

1. Authentication

The seller creates an API key in the seller portal (API page, login required; only the seller account owner can create keys) and gives it to the system that calls the API. Requests run with that seller's permissions: only the seller's own data in its contracted warehouses.

curl https://cangxinai.com/api/v1/warehouses \
  -H "Authorization: Bearer <API_KEY>"

appkey / appSecret: for ERPs that ask for two values, appkey is the seller code (key.appkey in the GET /me answer; it identifies the seller and is not secret) and appSecret is the API key. With Bearer authentication the appkey may also be sent in the X-WMS-Key header; it must then match the key's seller, otherwise the answer is 401 appkey_mismatch.

Signed requests (optional)

Instead of sending the key, sign every request. Headers: X-WMS-Key (appkey, or the key prefix), X-WMS-Timestamp (Unix seconds; accepted within 300 seconds of our clock), X-WMS-Nonce (8-64 characters [A-Za-z0-9_-], never reused for the same key) and X-WMS-Signature. Errors: 401 invalid_signature, signature_expired, nonce_reused.

import hashlib, hmac, secrets, time

def sign(app_secret: str, method: str, path: str, query: str, body: bytes) -> dict:
    # path and query exactly as sent, e.g. "/api/v1/orders" and "status=pending&page=1"
    timestamp, nonce = str(int(time.time())), secrets.token_hex(16)
    message = "\n".join([method.upper(), path, query, timestamp, nonce,
                         hashlib.sha256(body).hexdigest()])
    key = hashlib.sha256(app_secret.encode()).hexdigest()   # signing key = sha256_hex(appSecret)
    signature = hmac.new(key.encode(), message.encode(), hashlib.sha256).hexdigest()
    return {"X-WMS-Key": "<appkey>", "X-WMS-Timestamp": timestamp,
            "X-WMS-Nonce": nonce, "X-WMS-Signature": "sha256=" + signature}

Per key, the seller can also require signed requests (Bearer then answers 401 signature_required) and set an IP allow-list (other addresses get 403 ip_not_allowed).

2. Conventions

• JSON in and out, UTF-8. Dates are ISO 8601 in UTC (2026-11-10T08:00:00Z).
• Lists: ?page=1&page_size=50 (max 200) → {"data": [...], "pagination": {...}}.
• Errors: {"error": {"code": "...", "message": "...", "details": {...}}} with HTTP 400 / 401 / 403 / 404 / 409 / 422 / 429. Records of other sellers answer 404.
• On POST, send an Idempotency-Key header with a unique value (for example your order number): a retry with the same key and body within 7 days returns the first response (header Idempotent-Replayed: true) and creates nothing twice.
• Rate limit per key (default 120 requests / minute): see X-RateLimit-* headers; HTTP 429 comes with Retry-After.
• Add Accept-Language: zh-CN to get error messages in Chinese.
• Warehouses: GET /warehouses returns each contracted warehouse with its public_code (e.g. WS-ACME-LAX1): unique on the whole platform and never changed. Use it as warehouse_code (or send warehouse_id). The short code is unique per warehouse company only: when two contracted warehouses share it, the API answers 422 ambiguous_warehouse_code.

3. Endpoints

Create an order

The order goes through the same pipeline as uploaded order files: SKUs are matched by SKU code, barcode or your SKU mappings; the same external_id twice answers 409.

curl -X POST https://cangxinai.com/api/v1/orders \
  -H "Authorization: Bearer <API_KEY>" -H "Content-Type: application/json" \
  -H "Idempotency-Key: 111-1234567-1234567" \
  -d '{"warehouse_code": "WS-ACME-LAX1", "external_id": "111-1234567-1234567", "channel": "amazon",
       "ship_by_date": "2026-11-12T07:59:59Z",
       "recipient": {"name": "Jane Smith", "street": "1 Main St", "city": "Los Angeles",
                     "state": "CA", "zip": "90001", "country": "US", "phone": "555-0100"},
       "lines": [{"sku": "MUG-01", "quantity": 2, "external_item_id": "10000000000001"}]}'

Then poll GET /orders/{id} or GET /orders/by-external/{external_id} (status pending → processing → shipped, with tracking_numbers), or subscribe to the order.label_created / order.shipped webhooks. Cancel or hold by your own order number with POST /orders/by-external/{external_id}/cancel and /hold (URL-encode it; order numbers containing "/" must use the numeric id).

4. Webhooks

Register HTTPS URLs on the seller portal API page. We POST a JSON event; answer any 2xx within 10 seconds. Failed deliveries are retried after 1, 5, 15, 60 minutes, 3, 6, 12 and 24 hours (8 attempts), and are listed with their result on the API page. Events may arrive more than once: ignore an id you have already processed.

order.label_created is sent once per order and tracking number, as soon as the warehouse buys the label (before the parcel leaves); order.shipped follows when it leaves.

POST https://erp.example.com/wms/webhook
X-WMS-Event: order.shipped
X-WMS-Timestamp: 1762761600
X-WMS-Signature: sha256=5d41402abc4b2a76b9719d911017c592...

{"id": "evt_...", "type": "order.shipped", "created_at": "2026-11-10T08:00:00Z",
 "seller": {"id": 7, "code": "S001"},
 "data": {"order": {"id": 42, "external_id": "111-1234567-1234567", "status": "shipped",
                    "carrier": "UPS", "tracking_numbers": ["1Z999AA10123456784"], ...}}}

Verify the signature (HMAC-SHA256 of timestamp + "." + raw body with your endpoint secret) and reject old timestamps:

import hashlib, hmac, time

def verify(secret: str, headers: dict, raw_body: bytes) -> bool:
    timestamp = headers["X-WMS-Timestamp"]
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, headers["X-WMS-Signature"])