Stark TMS Open API

Send outbound orders and inbound shipments to the Stark Group warehouse, read your stock, tracking and products, and be told by a signed callback the moment an order ships or an inbound is received.

For clients’ own systems and for the ERPs they use — Mabang, Lingxing, Jushuitan, Wangdiantong and others.

Overview

  • Base address: https://stark.anmc.dev/open-api/v1
  • JSON in and out, UTF-8. Send Content-Type: application/json with a body.
  • Every call carries an API key that belongs to one client account. A key sees and changes only that account’s orders, stock, inbounds, products and callbacks — never another account’s.
  • Version 1 is stable: fields may be added to answers, but none is renamed or removed within v1. Ignore fields you don’t know.
  • The same API, described for code generators: /open-api/v1/openapi.json (OpenAPI 3.0).

Quick start

1. Ask the warehouse for an API key. A supervisor issues it in Stark TMS under Settings → Open API and gives it to you once; it starts with stk_. You also receive a signing secret (whsec_…) for checking callbacks.

2. Check the key:

curl https://stark.anmc.dev/open-api/v1/me \
  -H "Authorization: Bearer stk_your_key"

3. Make sure your products exist (an order may only name your own SKUs):

curl -X POST https://stark.anmc.dev/open-api/v1/products \
  -H "Authorization: Bearer stk_your_key" -H "Content-Type: application/json" \
  -d '{"sku":"ANZO-123","name":"Tail light, left","weight":{"value":2.5,"unit":"lb"}}'

4. Send an order, and read it back with its tracking once the warehouse has shipped it:

curl -X POST https://stark.anmc.dev/open-api/v1/orders \
  -H "Authorization: Bearer stk_your_key" -H "Content-Type: application/json" \
  -d '{"orderNo":"SO-10001","shipTo":{"name":"Jane Buyer","street1":"100 Main St","city":"Austin","state":"TX","postalCode":"78701","country":"US"},"items":[{"sku":"ANZO-123","quantity":2}]}'

curl https://stark.anmc.dev/open-api/v1/orders/SO-10001 -H "Authorization: Bearer stk_your_key"

5. Optionally, tell us where to send callbacks: PUT /webhook with {"url": "https://your-system.example.com/stark"}.

快速开始(中文)

  • 接口地址:https://stark.anmc.dev/open-api/v1,JSON 格式,UTF-8 编码。
  • 鉴权:请仓库主管在 Stark TMS「设置 → Open API」为您的客户账户生成 API 密钥(以 stk_ 开头,只显示一次)。每次请求携带请求头 Authorization: Bearer <密钥> 或 X-Api-Key: <密钥>。一个密钥只能访问其所属客户账户的数据。
  • 返回格式:成功为 {"ok": true, "data": …, "requestId": "…"};失败为 {"ok": false, "error": {"code", "message", "messageZh", "details"}}。error.code 稳定不变,可用于程序判断;messageZh 为中文说明。
  • 创建出库订单:POST /orders。orderNo(您的订单号)是订单的唯一标识:相同内容重复提交会返回已存在的订单(created: false),不会重复发货;同一订单号但内容不同会返回 ORDER_EXISTS。批量提交用 POST /orders/batch(每批最多 50 单)。
  • 查询订单与物流单号:GET /orders/{orderNo}、GET /orders?updatedSince=…。状态:awaiting_shipment(待发货)、on_hold(暂停)、shipped(已出面单,含物流单号)、cancelled(已取消)。
  • 库存:GET /stock?skus=A,B&warehouseCode=CA1,返回在库 onHand、可用 available、残次 damaged、在途 inbound,并按仓库细分。
  • 入库单(ASN):POST /inbounds,reference 为您的入库单号(唯一标识)。仓库收货完成后会推送 inbound.received 回调。
  • 产品:GET /products、POST /products、POST /products/batch(每批最多 100 个)。
  • 回调:订单出面单后推送 order.shipped(含物流单号),面单重开推送 order.tracking_updated,仓库取消推送 order.cancelled。回调使用 HMAC-SHA256 签名,请求头 X-Stark-Signature: t=<时间戳>,v1=<签名>,签名内容为 "<时间戳>.<原始请求体>",密钥为签名密钥(whsec_…)。请在 10 秒内返回 2xx;失败会在 1 分钟、5 分钟、30 分钟、2 小时、6 小时、12 小时、24 小时后重试。
  • 限流:每个密钥默认每分钟 120 次,超出返回 429 和 Retry-After 头。
  • 幂等:创建类接口支持 Idempotency-Key 请求头:同一键加相同请求体会重放第一次的结果(24 小时内有效)。
  • 暂不支持:客户自带面单的订单(相当于 Shipout 的 sysServiceId = 6)、通过 API 修改产品。

Keys and permissions

Send the key as Authorization: Bearer stk_…, or in an X-Api-Key header. Each key belongs to one client account and is shown once, when the warehouse issues it; Stark TMS keeps only a fingerprint of it, so a lost key can’t be looked up — ask for a new one. The warehouse can revoke a key at any time; it stops working at once (API_KEY_REVOKED).

A key has full access or is read-only:

PermissionAllowsFullRead-only
orders:readRead orders and their tracking✓✓
orders:writeCreate and cancel orders✓
stock:readRead stock✓✓
inbound:readRead inbound shipments✓✓
inbound:writeCreate and cancel inbound shipments✓
products:readRead products✓✓
products:writeCreate products✓
webhook:readRead the callback settings and recent callbacks✓✓
webhook:writeChange the callback address, make a new signing secret, send a test✓

Requests and answers

Every answer is JSON with the same outer shape:

{ "ok": true,  "data": { … },  "requestId": "req_5f1c…" }
{ "ok": false, "error": { "code": "SKU_NOT_FOUND", "message": "…", "messageZh": "…", "details": [ … ] }, "requestId": "req_…" }
  • The requestId (also in the X-Request-Id header) identifies the call; quote it when you ask the warehouse about one.
  • Lists are paged: ?page=1&pageSize=50; the answer has items, page, pageSize, total and hasMore.
  • Times are ISO 8601 in UTC (2026-10-07T15:30:00Z); dates are YYYY-MM-DD.
  • Your own identifiers (order number, inbound reference, SKU) go in the path URL-encoded: /orders/SO%2F10001. SKUs are matched ignoring case and surrounding spaces.
  • Weights are in oz, lb, g or kg; lengths in in or cm.

Errors

Decide on error.code, which never changes; the message may be reworded. details lists every problem with a request at once, by field (for example items[0].sku), so one correction fixes them all.

HTTPCodeMeaning中文
400VALIDATION_FAILEDOne or more fields are missing or wrong; see details.请求参数校验失败
400INVALID_JSONThe body is not JSON.请求体不是有效的 JSON
401UNAUTHENTICATEDNo key was sent.缺少 API 密钥
401INVALID_API_KEYThe key is not recognised.API 密钥无效
401API_KEY_REVOKEDThe warehouse revoked this key.API 密钥已被撤销
403CLIENT_INACTIVEThe account is not active at the warehouse.该客户账户已停用
403INSUFFICIENT_SCOPEThe key lacks the permission (e.g. a read-only key writing).该 API 密钥没有此操作的权限
404NOT_FOUNDNo such endpoint.接口不存在
404ORDER_NOT_FOUND · INBOUND_NOT_FOUND · PRODUCT_NOT_FOUND · DELIVERY_NOT_FOUNDNot one of yours.订单 / 入库单 / 产品 / 回调记录不存在
409ORDER_EXISTS · INBOUND_EXISTS · PRODUCT_EXISTSThat order number, reference or SKU already exists with different content.已存在,且内容不同
409ORDER_IN_PROGRESS · INBOUND_IN_PROGRESSAnother request for the same one is being handled; retry in a few seconds.同一单号的请求正在处理中
409ORDER_NOT_CANCELLABLE · INBOUND_NOT_CANCELLABLEToo late to cancel: the label is bought / receiving has started.已出面单或已开始收货,无法取消
409SKU_TAKENThe SKU is used in this warehouse by another account.该 SKU 已被其他账户使用
409IDEMPOTENCY_KEY_REUSED · IDEMPOTENCY_IN_PROGRESSThe Idempotency-Key was used for another request / is being handled.幂等键已被使用 / 处理中
409WEBHOOK_NOT_CONFIGUREDSet a callback address first.尚未设置回调地址
413PAYLOAD_TOO_LARGEBody over 1 MB.请求体过大
422SKU_NOT_FOUNDA SKU is not one of your products; details names each.SKU 不存在或不属于该客户
422WAREHOUSE_NOT_FOUNDNo warehouse has that code (GET /warehouses).仓库不存在或未启用
422CALLBACK_URL_REJECTEDA callback address must be a public https address.回调地址不可用
422FEATURE_NOT_AVAILABLENot offered yet — see Not available yet.该功能暂未开放
429RATE_LIMITEDToo many calls; wait for Retry-After seconds.请求过于频繁
500INTERNAL_ERRORA fault at the warehouse; retry, and report the requestId if it persists.服务器内部错误

Rate limits

Each key may make 120 calls a minute unless the warehouse set another limit (GET /me shows yours). Every answer carries RateLimit and RateLimit-Policy headers; over the limit the answer is 429 RATE_LIMITED with a Retry-After header in seconds. Calls with a key that doesn’t work are limited separately, so a broken key retried in a loop slows only itself.

To send many orders, use POST /orders/batch (50 per call) rather than one call per order.

Sending twice safely

Networks fail, so retrying must never ship twice. Two things make that so:

  • Your identifiers are identities. An order’s orderNo, an inbound’s reference and a product’s sku are unique within your account. Sending the same one again with the same content returns what exists, with created: false and HTTP 200 (201 when it was made). The same identifier with different content is refused (ORDER_EXISTS, INBOUND_EXISTS, PRODUCT_EXISTS).
  • The Idempotency-Key header (any unique string up to 200 characters) works on every create call, batches included. A second call with the same key and the same body returns the first call’s answer, with Idempotent-Replayed: true; the same key with a different body is refused (IDEMPOTENCY_KEY_REUSED). Kept for 24 hours. Only successful answers are kept, so a failed call can simply be retried.

Account

GET

/me

any key

Whose key this is, its permissions and rate limit. Use it to test a connection.

{ "ok": true, "data": { "client": { "code": "ANZO", "name": "Anzo USA" },
  "key": { "id": 12, "scopes": ["orders:read", "orders:write", …], "rateLimitPerMinute": 120 }, "apiVersion": "v1" } }
GET

/warehouses

any key

The warehouses an order or inbound can name, by code.

Orders

An outbound order: something the warehouse picks, packs and ships to your buyer. The warehouse buys the label; you are told the tracking.

POST

/orders

orders:write

Creates an order. Answers 201 with { "created": true, "order": … }, or 200 with created: false when this orderNo already exists with the same content.

FieldTypeNotes
orderNo requiredstring ≤ 60Your order number; unique in your account.
shipTo requiredobjectname, street1, city, postalCode required; state required (2 letters) for US and CA; country ISO 3166-1 alpha-2, default US; optional company, street2, phone, email, residential (true/false).
items requiredarray, 1–200Each { sku, quantity, unitPrice?, name? }. Every SKU must be one of your products.
orderDatedate-timeWhen the buyer ordered.
warehouseCodestringThe warehouse to ship from (GET /warehouses).
shippingServicestring ≤ 100The service the buyer chose, as text; shown to the warehouse.
weight{ value, unit }Parcel weight. Default: the sum of your products’ weights.
dimensions{ length, width, height, unit }Parcel size, if known.
notesstring ≤ 1000The buyer’s note.
references{ po, ref1, ref2 }Your references, kept with the order.
storeNamestring ≤ 80Shown as the store in the warehouse’s list; default “Open API · your code”.
callbackUrlhttps URL ≤ 512Also receives this order’s callbacks (besides your webhook address).
POST /open-api/v1/orders
{
  "orderNo": "SO-10001",
  "orderDate": "2026-10-07T15:30:00Z",
  "warehouseCode": "CA1",
  "shipTo": { "name": "Jane Buyer", "street1": "100 Main St", "street2": "Apt 4", "city": "Austin",
              "state": "TX", "postalCode": "78701", "country": "US", "phone": "5125550100" },
  "items": [ { "sku": "ANZO-123", "quantity": 2, "unitPrice": 19.99 } ],
  "shippingService": "Standard",
  "references": { "po": "PO-7781" },
  "callbackUrl": "https://erp.example.com/stark/callback"
}

The order, as every order endpoint returns it:

{
  "orderNo": "SO-10001", "warehouseOrderNo": "MW-48211", "status": "shipped", "hold": null,
  "orderDate": "2026-10-07T15:30:00.000Z", "warehouseCode": "CA1", "shippingService": "Standard",
  "shipTo": { "name": "Jane Buyer", … }, "items": [ { "sku": "ANZO-123", "name": "Tail light, left", "quantity": 2, "unitPrice": 19.99 } ],
  "notes": "", "references": { "po": "PO-7781", "ref1": "", "ref2": "" },
  "trackingNumbers": [ "794100000123" ],
  "packages": [ { "packageId": 9921, "status": "label_created", "trackingNumber": "794100000123", "carrier": "FedEx",
                  "service": "FEDEX_GROUND", "trackingUrl": "https://www.fedex.com/fedextrack/?trknbr=794100000123",
                  "labelCreatedAt": "2026-10-08T17:02:11.000Z", "weight": { "value": 80, "unit": "oz" },
                  "dimensions": { "length": 12, "width": 10, "height": 8, "unit": "in" } } ],
  "shippedAt": "2026-10-08T17:02:11.000Z", "callbackUrl": "https://erp.example.com/stark/callback",
  "createdAt": "2026-10-07T15:31:02.000Z", "updatedAt": "2026-10-08T17:02:11.000Z"
}
statusMeans
awaiting_shipmentIn the warehouse’s queue; no label yet (or not every package has one).
on_holdHeld by the warehouse; hold.reason says why.
shippedEvery package has its label; trackingNumbers lists them.
cancelledCancelled, by you or by the warehouse.
POST

/orders/batch

orders:write

Up to 50 orders, as a list or { "orders": [ … ] }. Each succeeds or fails on its own; the answer lists them in your order: { "results": [ { "index": 0, "id": "SO-10001", "ok": true, "created": true, "order": … }, { "index": 1, "id": "SO-10002", "ok": false, "error": { "code": "SKU_NOT_FOUND", … } } ], "succeeded": 1, "failed": 1 }.

GET

/orders

orders:read

Your orders, most recently changed first. Filters: status, orderNos (comma-separated, up to 100), updatedSince (ISO 8601 — poll with the time of your last poll to collect what changed), page, pageSize (≤ 100).

GET

/orders/{orderNo}

orders:read

One order with its packages and tracking.

POST

/orders/{orderNo}/cancel

orders:write

Cancels an order the warehouse has not bought a label for; answers { "order": … }. Cancelling an already cancelled order is fine. Once a label is bought: ORDER_NOT_CANCELLABLE — contact the warehouse.

Stock

GET

/stock

stock:read

Stock of your products. Filters: skus (comma-separated, up to 200; without it, every active product), warehouseCode, page, pageSize (≤ 200). A product with nothing on hand reads 0.

{ "sku": "ANZO-123", "name": "Tail light, left",
  "onHand": 120, "available": 118, "damaged": 2, "inbound": 500,
  "warehouses": [ { "warehouseCode": "CA1", "onHand": 120, "available": 118, "damaged": 2, "inbound": 500 } ] }
FieldMeans
onHandUnits on the warehouse’s shelves.
damagedUnits set aside as damaged (not shippable).
availableonHand − damaged.
inboundUnits your open inbound shipments still bring.

Units on orders not yet shipped are not subtracted from available yet; that comes with the warehouse’s picking. Keep a margin when you list stock on a marketplace.

GET

/stock/{sku}

stock:read

One product; ?warehouseCode= narrows it to one warehouse.

Inbound shipments

An inbound (ASN) tells the warehouse what you are sending, so it can be checked in on arrival. It appears in the warehouse’s Receiving list at once.

POST

/inbounds

inbound:write
FieldTypeNotes
reference requiredstring ≤ 80Your ASN or PO number; unique in your account.
warehouseCode requiredstringWhere it is going.
lines requiredarray, 1–2000Each { sku, quantity }; a SKU listed twice is added up.
typestringcontainer, pallet, parcel (default) or other.
containerSizestring20GP, 40GP, 40HQ or 45HQ; containers only.
expectedDateYYYY-MM-DDWhen it should arrive.
notesstring ≤ 2000For the warehouse.
callbackUrlhttps URLAlso receives this inbound’s callback.
{ "reference": "ASN-2026-001", "warehouseCode": "CA1", "type": "container", "containerSize": "40HQ",
  "expectedDate": "2026-10-20", "lines": [ { "sku": "ANZO-123", "quantity": 500 } ] }

The answer’s inbound: reference, warehouseInboundNo (the warehouse’s number, e.g. IN201026-01), status (awaiting → receiving → received, or cancelled), lines with expected and received (and unexpected: true for something that arrived but was not listed), totals, receivedAt.

GET

/inbounds

inbound:read

Newest first. Filters: status, references (comma-separated), page, pageSize.

GET

/inbounds/{reference}

inbound:read

One inbound, with what has been received so far.

POST

/inbounds/{reference}/cancel

inbound:write

Cancels an inbound nothing has been received against.

Products

POST

/products

products:write

Creates a product. sku (≤ 80) and name are required; optional upc (8–14 digits), fnsku, asin, weight, dimensions. Sending an existing SKU with the same details answers created: false; with different details, PRODUCT_EXISTS. A SKU another account uses in this warehouse is SKU_TAKEN.

{ "sku": "ANZO-123", "name": "Tail light, left", "upc": "012345678905",
  "weight": { "value": 2.5, "unit": "lb" }, "dimensions": { "length": 12, "width": 8, "height": 6, "unit": "in" } }
POST

/products/batch

products:write

Up to 100 products, as a list or { "products": [ … ] }; each succeeds or fails on its own, like the order batch.

GET

/products

products:read

Your products, by SKU. Filters: skus, updatedSince, includeInactive=true, page, pageSize (≤ 200).

GET

/products/{sku}

products:read

One product.

Callbacks

Instead of asking again and again, let the warehouse tell you. A callback is an HTTPS POST of JSON to your address:

EventSent whendata
order.shippedEvery package of an order has its label.{ "order": … } with trackingNumbers
order.tracking_updatedA label was voided and bought again: the tracking changed.{ "order": … }
order.cancelledThe warehouse cancelled an order (not sent when you cancelled it).{ "order": … }
inbound.receivedThe warehouse marked an inbound received.{ "inbound": … } with what arrived
pingYou asked for a test (POST /webhook/test).{ "message": … }

They go to your webhook address, for the events you chose, and to the callbackUrl of that order or inbound if it has one.

POST https://your-system.example.com/stark
Content-Type: application/json
X-Stark-Event: order.shipped
X-Stark-Event-Id: evt_0b6f3c1e9d2a4f5b6c7d8e9f
X-Stark-Delivery-Id: 4182
X-Stark-Attempt: 1
X-Stark-Signature: t=1791504131,v1=5d41402abc4b2a76b9719d911017c592…

{ "id": "evt_0b6f3c1e9d2a4f5b6c7d8e9f", "type": "order.shipped", "apiVersion": "v1",
  "createdAt": "2026-10-08T17:02:11.000Z", "client": { "code": "ANZO" },
  "data": { "order": { "orderNo": "SO-10001", "status": "shipped", "trackingNumbers": [ "794100000123" ], … } } }

Checking the signature

Every callback is signed with your signing secret (whsec_…): v1 is the hex HMAC-SHA256 of "<t>.<raw body>". Compute it over the body exactly as received (before parsing), compare in constant time, and refuse a t more than 5 minutes old.

// Node.js
const crypto = require('crypto');
function verifyStark(secret, header, rawBody) {
  const parts = Object.fromEntries(String(header).split(',').map(p => p.split('=')));
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return fresh && typeof parts.v1 === 'string' && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}
# Python
import hashlib, hmac, time
def verify_stark(secret: str, header: str, raw_body: bytes) -> bool:
    parts = dict(p.split('=', 1) for p in header.split(','))
    expected = hmac.new(secret.encode(), parts['t'].encode() + b'.' + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(parts['t'])) < 300 and hmac.compare_digest(expected, parts.get('v1', ''))
// Java 17
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
String expected = HexFormat.of().formatHex(mac.doFinal((t + "." + rawBody).getBytes(StandardCharsets.UTF_8)));
boolean ok = Math.abs(System.currentTimeMillis() / 1000 - t) < 300
    && MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), v1.getBytes(StandardCharsets.UTF_8));

Answering, retries and duplicates

  • Answer any 2xx within 10 seconds; do slow work afterwards. Redirects are not followed.
  • Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, then given up; the warehouse can send it again, and so can you (POST /webhook/deliveries/{id}/retry).
  • A callback can arrive more than once and not always in order: X-Stark-Event-Id is the same on every retry, so skip one you have already handled, and trust the order’s status and updatedAt over arrival order.
  • Addresses must be public https; addresses inside private networks are refused.
GET

/webhook

webhook:read

Your webhook address, events, and the last four characters of the signing secret.

PUT

/webhook

webhook:write

{ "url": "https://…", "events": ["order.shipped", "order.tracking_updated", "order.cancelled", "inbound.received"] }. An empty url turns callbacks off; leaving url out keeps the address and changes only the events; events defaults to what is set (all four at first).

POST

/webhook/secret

webhook:write

Makes a new signing secret and returns it this once (signingSecret). Callbacks are signed with it from then on.

POST

/webhook/test

webhook:write

Sends a signed ping to your webhook address now and answers with how it went (delivery.status, lastStatus, lastError).

GET

/webhook/deliveries

webhook:read

Your recent callbacks (?limit= up to 200): event, address, status (pending, delivered, failed), attempts, last answer.

POST

/webhook/deliveries/{id}/retry

webhook:write

Sends one again now.

Coming from Shipout

If your system already sends orders to Shipout’s Open API, the mapping is direct:

ShipoutStark TMS
orderNoorderNo
orderSummary.orderDate · noteFromBuyerorderDate · notes
toAddress.name / company / addressLine1 / addressLine2 / city / stateCode / zipCode / countryCode / phone / emailshipTo.name / company / street1 / street2 / city / state / postalCode / country / phone / email
shipmentForms[].productList[].omsSku / qty / priceitems[].sku / quantity / unitPrice (one order, one list of lines)
warehouseIdwarehouseCode (GET /warehouses)
openAPIExtendData.po / ref1 / ref2references.po / ref1 / ref2
callBackUrlcallbackUrl (and a webhook address for all orders)
sysServiceId 9 / 10 (the warehouse ships)the default — the warehouse buys the label
sysServiceId 6 (your own label)not yet — see below
order status 2 / 3 / 4 / 6awaiting_shipment / awaiting_shipment / shipped / cancelled
orderShipments[].trackingNumber, packageListtrackingNumbers, packages
stock standardQty / brokenQty / inboundingQtyavailable / damaged / inbound
inbound submitInbound: inboundArrivalType, estimatedInboundDate, packageList[].packageItemList[]POST /inbounds: type / containerSize, expectedDate, lines[] (units per SKU)
product omsSku / skuNameEN / upc / fnSku / weight1 / length…sku / name / upc / fnsku / weight / dimensions

Not available yet

  • Orders with your own label (Shipout’s sysServiceId 6): an order carrying a label is refused with FEATURE_NOT_AVAILABLE, so the warehouse never ships a box twice. Send it without the label for now.
  • Changing a product through the API: ask the warehouse.
  • Reserving stock for open orders: available does not yet subtract orders waiting to ship.
  • Returns and billing through the API.

Changelog

  • 2026-10-07 — v1.0.0. Orders, stock, inbound shipments, products, signed callbacks with retries, per-key rate limits, idempotency.