OrangeShip 开放接口：订单履约 API

01概述

OrangeShip 是订单履约平台。渠道方（电商平台、订单管理系统、ERP 等）通过本接口把已确认的订单推送给 OrangeShip，由 OrangeShip 分配海外仓或承运商完成履约；渠道方再通过本接口取回运单号和物流状态，回写到自己的系统。

调用方向是单向的：只有渠道方调用 OrangeShip，OrangeShip 不回调渠道方。订单状态的变化通过「拉取订单变更」接口按游标增量获取。

1.1接口一览

1.2对接流程

1. 获取凭证

   商家在 OrangeShip 后台「渠道接入」创建连接，把 AppKey 和 AppSecret 交给渠道方（§2.2）。

2. 实现签名

   按 §3.2 实现签名，先用 §3.4 的测试向量离线自测。

3. 验证连通

   调用 GET /ping，返回 code: 0 即凭证与签名正确。

4. 推送与取消

   订单锁定后调用 POST /orders；退款、取消或改地址时调用 POST /orders/{order_id}/cancel。

5. 取回运单号

   定时调用 GET /orders/changes，按游标拉取状态与运单号并回写（§6）。

6. 按需查询

   买家查看物流时调用 GET /orders/{order_id}/tracking。

1.3渠道专用字段

部分字段只适用于特定渠道类型，在字段说明中以标签注明（如 PledgeBox）。其余字段，以及鉴权、幂等、订单变更、订单状态、错误码与限流，对所有渠道相同。

02环境与凭证

2.1环境

本文所有路径都相对于 Base URL。例如「推送订单」的完整地址是 POST https://orangeshipping.xyz/open/v1/orders。

2.2凭证

• 一个连接对应渠道方的一个店铺或项目。
• 订单归属哪个商家、哪个连接由 AppKey 决定，请求中不需要传商家或企业标识。
• order_id 在连接内唯一；不同连接可以出现相同的 order_id。
• 轮换凭证：商家新建连接并切换到新凭证，再停用旧连接。停用后旧连接拒绝推单和取消，但仍可读：请继续用旧凭证拉取其订单变更，直到在途订单全部取回（订单不会在连接之间迁移）。

2.3通用约定

03鉴权

每个请求都用连接的 AppSecret 做 HMAC-SHA256 签名，并把签名放在请求头里。不需要登录，也没有 token 交换。

3.1请求头

3.2签名算法

method      = 大写的 HTTP 方法，如 POST、GET
path        = 请求路径，含 /open/v1 前缀，不含 query string，如 /open/v1/orders/changes
body_hash   = lowercase_hex( SHA-256( 请求体的原始字节 ) )
canonical   = X-Timestamp + "." + method + "." + path + "." + body_hash
X-Signature = lowercase_hex( HMAC-SHA256( key = AppSecret, message = canonical ) )

规则：

1. 签名的是实际发送的字节。请求体只序列化一次，用这串字节计算 body_hash 并原样发送；签名后不要再次序列化。
2. 无请求体（所有 GET）时按空串计算，其 SHA-256 为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。
3. path 为绝对路径，以 / 开头并包含 /open/v1 前缀；不含 scheme、host、端口和 query string。路径中的 order_id 先做百分号编码再参与签名，与发出的请求行保持一致。
4. X-Timestamp 原样参与签名，不补零、不带小数。
5. 方法用大写，十六进制用小写。
6. AppSecret 按 UTF-8 原始字节使用，不做 base64 解码。
7. 四段之间用字符 . 连接，末尾没有换行。

3.3示例代码

const { createHash, createHmac } = require('node:crypto');

// url：完整请求地址；body：将要发送的字符串（GET 传 ''）
function signRequest({ appKey, appSecret, method, url, body = '' }) {
  const timestamp = String(Math.floor(Date.now() / 1000));
  const path = new URL(url).pathname;   // 如 /open/v1/orders，不含 query
  const bodyHash = createHash('sha256').update(body, 'utf8').digest('hex');
  const canonical = `${timestamp}.${method.toUpperCase()}.${path}.${bodyHash}`;
  const signature = createHmac('sha256', appSecret).update(canonical, 'utf8').digest('hex');
  return {
    'X-App-Key': appKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    ...(body ? { 'Content-Type': 'application/json' } : {}),
  };
}

// 调用示例：推送订单
const url = 'https://orangeshipping.xyz/open/v1/orders';
const body = JSON.stringify(payload);          // 只序列化一次
const res = await fetch(url, { method: 'POST', body, headers: signRequest({ appKey, appSecret, method: 'POST', url, body }) });

import hashlib, hmac, json, time, urllib.parse, urllib.request

def sign_request(app_key, app_secret, method, url, body=b""):
    timestamp = str(int(time.time()))
    path = urllib.parse.urlsplit(url).path      # 如 /open/v1/orders，不含 query
    body_hash = hashlib.sha256(body).hexdigest()
    canonical = f"{timestamp}.{method.upper()}.{path}.{body_hash}".encode("utf-8")
    signature = hmac.new(app_secret.encode("utf-8"), canonical, hashlib.sha256).hexdigest()
    headers = {"X-App-Key": app_key, "X-Timestamp": timestamp, "X-Signature": signature}
    if body:
        headers["Content-Type"] = "application/json"
    return headers

# 调用示例：推送订单
url = "https://orangeshipping.xyz/open/v1/orders"
body = json.dumps(payload, separators=(",", ":")).encode("utf-8")   # 只序列化一次
req = urllib.request.Request(url, data=body, method="POST",
                             headers=sign_request(app_key, app_secret, "POST", url, body))
with urllib.request.urlopen(req, timeout=60) as resp:
    result = json.loads(resp.read())

3.4测试向量

用以下固定输入验证签名实现，结果必须逐字一致。向量已分别用 Node.js 与 Python 独立计算。

AppSecret

demo-secret-do-not-use-in-production

X-Timestamp

1789000000

向量 A：POST /orders（带请求体）

向量 B：GET /orders/changes（空请求体；query string 不影响签名）

向量 C：POST /orders/{order_id}/cancel（请求体 {}）

命令行复现向量 A（两条均输出 dba4cb3f99da1ca98e32848cfa7a6b918f2f230fa432aebfc1fc1e00017f8fd5）：

node -e "const c=require('crypto');const b='{\"batch_id\":\"wave-2-2026-09-18-001\",\"orders\":[]}';console.log(c.createHmac('sha256','demo-secret-do-not-use-in-production').update('1789000000.POST./open/v1/orders.'+c.createHash('sha256').update(b).digest('hex')).digest('hex'))"

python3 -c "import hashlib,hmac;b=b'{\"batch_id\":\"wave-2-2026-09-18-001\",\"orders\":[]}';print(hmac.new(b'demo-secret-do-not-use-in-production',('1789000000.POST./open/v1/orders.'+hashlib.sha256(b).hexdigest()).encode(),hashlib.sha256).hexdigest())"

3.5时间窗与重放

• X-Timestamp 与服务器时间相差超过 300 秒（任一方向）返回 41102。请开启 NTP 时间同步；收到 41102 时，用 GET /ping 返回的 server_time 核对时钟后，换新时间戳重试。
• 不使用 nonce。方法、路径、时间戳与请求体都参与签名，截获的签名只对同一个请求在 300 秒内有效；用于其它路径或方法会被拒绝（41101）。在时间窗内重放同一个请求是无害的：写接口幂等（§5），查询接口只读。
• 三个鉴权请求头应视为机密：只走 HTTPS，代理与日志不要记录请求头。

04接口参考

所有接口都需要 §3.1 的鉴权请求头。鉴权失败、连接停用、限流等通用错误统一见 §8.2，以下各接口只列出特有的错误。

4.1连通性检查

校验凭证与签名，返回连接信息和服务器时间。适合做「测试连接」按钮。

请求参数

无。

请求示例

GET /open/v1/ping HTTP/1.1
Host: orangeshipping.xyz
X-App-Key: 3f9c1d2e4b5a69788796a5b4c3d2e1f0
X-Timestamp: 1789000000
X-Signature: 0ffa6fd797ff65dc66f440be6a1911f99ac4d1bb357292621bd10bdf13a18cef

示例签名由 §3.4 的演示密钥对 1789000000.GET./open/v1/ping.e3b0c442…b855 计算得出。

响应

响应字段（data）

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "tenant_name": "Shenzhen Damai Technology",
    "connection_name": "Foldable Drone",
    "connection_code": "PB-7K3M9Q",
    "status": "active",
    "server_time": "2026-09-18T02:10:00.000Z"
  }
}

4.2推送订单

批量推送已锁定的订单。每次最多 200 单、请求体不超过 2 MB；每单独立处理，单个订单不合法不影响同批其它订单。按 order_id 幂等（§5）。

请求参数（body）

「必填」列：必填 缺失或不合规时该单进入 rejected；应填 缺失时仍接收，但可能在分发时转异常（如直发承运商要求电话）；可选 可省略。长度与格式限制对所有出现的字段生效，超限时整单进入 rejected，原因形如 shipping.wave must be at most 64 characters。

请求示例

POST /open/v1/orders HTTP/1.1
Host: orangeshipping.xyz
Content-Type: application/json
X-App-Key: 3f9c1d2e4b5a69788796a5b4c3d2e1f0
X-Timestamp: 1789000000
X-Signature: <按 §3.2 计算>

{
  "batch_id": "wave-2-2026-09-18-001",
  "orders": [
    {
      "order_id": "ord_8f3a1c",
      "pbid": "PB123456",
      "platform": "kickstarter",
      "platform_backer_id": "KS-98765",
      "project": { "id": "prj_001", "name": "Foldable Drone" },
      "status": "locked",
      "locked_at": "2026-09-18T02:10:00Z",
      "updated_at": "2026-09-18T02:10:00Z",
      "currency": "USD",
      "amount": { "total": "129.00", "shipping": "19.00", "tax": "0.00" },
      "backer": { "email": "backer@example.com" },
      "shipping_address": {
        "name": "Jane Doe", "phone": "+1 415 555 0100",
        "address1": "1 Market St", "address2": "Suite 300",
        "city": "San Francisco", "province": "CA", "zip": "94105", "country_code": "US"
      },
      "shipping": { "method": "Standard", "wave": "Wave 2", "region": "North America" },
      "items": [
        { "line_id": "L1", "type": "reward", "sku": "DRONE-BLK", "name": "Drone (Black)", "quantity": 1, "unit_price": "99.00" },
        { "line_id": "L2", "type": "addon",  "sku": "BATT-01",   "name": "Extra Battery", "quantity": 2, "unit_price": "15.00" }
      ],
      "note": "Leave at door"
    }
  ]
}

处理规则（按订单）

响应

响应字段（data）

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "accepted": [
      { "order_id": "ord_8f3a1c", "pbid": "PB123456", "oms_order_id": "1024", "result": "created" },
      { "order_id": "ord_8f3a1f", "pbid": "PB123459", "oms_order_id": null,   "result": "queued" }
    ],
    "rejected": [
      { "order_id": "ord_8f3a1d", "pbid": "PB123457", "reason": "items[0].sku is required" },
      { "order_id": "ord_8f3a1e", "pbid": "PB123458", "reason": "already_shipped" }
    ]
  }
}

4.3取消订单

因退款、取消或买家修改地址而取消订单。修改地址的正确做法是取消旧订单后用新的 order_id 重新推送（§9）。

请求参数

请求示例

POST /open/v1/orders/ord_8f3a1c/cancel HTTP/1.1
Host: orangeshipping.xyz
Content-Type: application/json
X-App-Key: 3f9c1d2e4b5a69788796a5b4c3d2e1f0
X-Timestamp: 1789000000
X-Signature: <按 §3.2 计算>

{ "reason": "refunded" }

处理规则

响应

响应字段（data）

响应示例

{ "code": 0, "message": "ok", "data": { "order_id": "ord_8f3a1c", "oms_order_id": "1024", "result": "cancelled" } }

4.4拉取订单变更

按游标增量返回对外可见状态发生变化的订单，是取回运单号的主通道。每个订单只返回最新状态。拉取协议与客户端处理要求见 §6。

请求参数（query）

请求示例

GET /open/v1/orders/changes?cursor=eyJ0IjoiMjAyNi0wOS0yMFQwODowMDowNS4wMDBaIiwiaWQiOiIxMDI0In0&limit=100 HTTP/1.1
Host: orangeshipping.xyz
X-App-Key: 3f9c1d2e4b5a69788796a5b4c3d2e1f0
X-Timestamp: 1789000000
X-Signature: <按 §3.2 计算>

响应

响应字段（data）

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "orders": [
      {
        "order_id": "ord_8f3a1e", "pbid": "PB123458", "status": "exception",
        "tracking_code": null, "carrier": null, "carrier_code": null, "courier_code": null,
        "shipped_at": null, "delivered_at": null,
        "exception_code": "sku_unmapped", "exception_reason": "SKU mapping missing: DRONE-RED",
        "changed_at": "2026-09-19T10:00:00.000Z"
      },
      {
        "order_id": "ord_8f3a1c", "pbid": "PB123456", "status": "shipped",
        "tracking_code": "1Z999AA10123456784", "carrier": "UPS", "carrier_code": "UPS-EXP", "courier_code": "UPS",
        "shipped_at": "2026-09-20T08:00:00.000Z", "delivered_at": null,
        "exception_code": null, "exception_reason": null,
        "changed_at": "2026-09-20T08:00:05.000Z"
      }
    ],
    "next_cursor": "eyJ0IjoiMjAyNi0wOS0yMFQwODowMDowNS4wMDBaIiwiaWQiOiIxMDI0In0",
    "has_more": false,
    "server_time": "2026-09-21T03:10:00.000Z"
  }
}

4.5查询订单

返回单笔订单快照：包含订单变更行的全部字段，另加仓库参考号与商品行。不返回收件人个人信息（姓名、地址、电话、邮箱）。

请求参数

响应

响应字段（data）

包含 §4.4 orders[] 的全部字段，另加：

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_id": "ord_8f3a1c", "pbid": "PB123456", "status": "shipped",
    "tracking_code": "1Z999AA10123456784", "carrier": "UPS", "carrier_code": "UPS-EXP", "courier_code": "UPS",
    "shipped_at": "2026-09-20T08:00:00.000Z", "delivered_at": null,
    "exception_code": null, "exception_reason": null,
    "changed_at": "2026-09-20T08:00:05.000Z",
    "reference_number": "PB123456",
    "external_number": "WH2609200000456",
    "items": [
      { "line_id": "L1", "sku": "DRONE-BLK", "quantity": 1, "mapping_ok": true },
      { "line_id": "L2", "sku": "BATT-01",   "quantity": 2, "mapping_ok": true }
    ],
    "locked_at": "2026-09-18T02:10:00.000Z",
    "updated_at": "2026-09-20T08:00:05.000Z"
  }
}

4.6查询物流轨迹

返回单笔订单的物流事件。请在买家查看物流时按需调用，不要定时全量轮询；签收状态会通过订单变更返回。

海外仓发货的订单只有里程碑事件（shipped、delivered）。直发订单另有承运商的转运事件：对已发货、未签收的直发订单，调用时若距上次成功刷新超过 30 分钟，OrangeShip 会先向承运商刷新再返回（刷新最多等待数秒，失败时返回已有事件，5 分钟后才会再次尝试）；刷新到签收会同时将订单置为 delivered。订单还没有任何事件时，按订单的发货、签收时间生成里程碑，source 为 oms。

请求参数

响应

响应字段（data）

响应示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_id": "ord_8f3a1c", "pbid": "PB123456",
    "status": "in_transit",
    "tracking_code": "1Z999AA10123456784", "carrier": "UPS", "carrier_code": "UPS-EXP", "courier_code": "UPS",
    "shipped_at": "2026-09-20T08:00:00.000Z", "delivered_at": null,
    "events": [
      { "status": "in_transit", "raw_status": "NT", "description": "Departed facility", "location": "Shenzhen", "occurred_at": "2026-09-21T02:00:00.000Z", "source": "carrier" },
      { "status": "shipped",    "raw_status": "PU", "description": null, "location": null, "occurred_at": "2026-09-20T08:00:00.000Z", "source": "carrier" }
    ],
    "refreshed_at": "2026-09-21T03:10:00.000Z"
  }
}

05幂等与重试

5.1重试策略

• 超时、HTTP 5xx：用同一串请求体字节重试（重新生成时间戳与签名），指数退避，从 1 秒开始，最多 5 次。
• HTTP 429：至少等待 1 秒后指数退避重试。
• 41102：核对时钟后换新时间戳重试。
• 40001、41101、41103、41104、41300：修正请求后再发，原样重试没有意义。
• 客户端超时请设为 60 秒以上。推送订单通常在 30 秒内返回：请求内同步处理最多 25 秒，未处理到的订单返回 queued 后异步完成。超时后重试时，已保存的订单返回 duplicate 或 queued，其余正常处理。

5.2顺序保证

对已存在的订单，推送的 updated_at 与已存值比较：严格更早的推送返回 stale 并被忽略，乱序到达的旧报文不会覆盖新报文。updated_at 相等时正常处理。

06订单变更拉取

6.1规则

• 触发条件。订单的 changed_at 只在对外可见的内容变化时更新：状态、运单号、承运商、发货时间、签收时间、异常信息，或新增物流事件。渠道方自己的重推若没有改变这些内容，不会出现在变更中；新建的订单会出现一次，状态为拉取时已到达的状态。
• 排序与游标。结果按 (changed_at, 内部 id) 升序。游标记录最后一行的位置，下次返回其后的行。游标不透明，不要解析或自行构造；游标不会过期。
• 安全滞后。changed_at 晚于 server_time − 60 秒 的变更暂不返回，以免并发提交的变更落在已推进的游标之前。因此变化最多约一分钟后可见。
• 只返回最新状态。两次拉取之间发生多次变化的订单只返回一行，可能跳过中间状态（例如 processing 之后直接是 delivered）。同一订单可能再次出现（例如商家修正承运商映射后重新下发），请按 order_id 更新而不是新增。
• 已取走标记。返回过的、带运单号的已发货订单，会在响应发出时被记为「已取走」，除非订单再次变化，不会重复返回。请持久化并处理完整页后再拉取下一页。

6.2拉取频率

每个连接每 15–60 分钟拉取一次；has_more 为 true 时立即继续，直到为 false。

6.3客户端处理

function pull(conn):
    loop:
        resp = GET /orders/changes?limit=200 + (conn.cursor ? &cursor=conn.cursor : "")
        if resp 不是 HTTP 200 / code 0:
            按 §8.2 处理；return               # 保留原游标，不推进
        for row in resp.data.orders:
            apply(row)                          # 必须幂等
        conn.cursor = resp.data.next_cursor     # 整页处理完后再持久化（存数据库）
        if not resp.data.has_more: break

function apply(row):
    order = 按 row.order_id 查本地订单；不存在则记录并跳过
    if row.changed_at <= order.last_changed_at: return    # 已处理过
    switch row.status:
        shipped / in_transit / delivered:
            if row.tracking_code 与本地不同:
                标记已发货（tracking_code、courier_code）；通知买家   # 仅首次拿到运单号时通知
            if row.status == delivered: 标记已签收
        exception:  提示商家（按 exception_code 分类，exception_reason 用于展示）
        cancelled:  标记已取消
        pending / processing: 标记履约中（可选）
    order.last_changed_at = row.changed_at

• 收到错误响应时不推进游标；处理完整页后再保存 next_cursor，空页也要保存。
• 一个连接一个游标。
• 订单首次出现时可能是任意状态，不要假设从 pending 开始。
• 游标丢失时，不带 cursor 和 since 重新从头拉取；数据量大时可用 since 指定一个明显早于丢失时刻的时间（留出几分钟时钟偏差余量）。重新收到的行按幂等规则处理。

07数据字典

7.1订单状态 status

同一状态可能多次出现（例如商家修正映射期间 exception → pending → exception），每次有新的 changed_at。

7.2异常代码 exception_code

v1 内可能新增异常代码，客户端遇到未知值时按 other 处理。

7.3推单结果

7.4取消结果 result

status、推单结果与取消结果在 v1 内为封闭集合，新增取值会提前通知（§10）。

7.5承运商字段

如果渠道系统要求承运商代码来自固定列表，请提供列表，商家会在 OrangeShip 后台维护映射。

7.6物流事件来源 events[].source

遇到未知值时按 carrier 处理。

08错误处理与限流

8.1错误响应

{ "code": 41101, "message": "signature invalid", "data": null, "requestId": "c1f4…" }

请按 code 判断，不要依赖 message 文本。联系技术支持时请提供 requestId。

8.2错误码

超过 5 MB 的请求会被网关直接拒绝（HTTP 413，无 JSON 响应体）；HTTP 502 / 503 / 504 也可能没有 JSON 响应体，可退避重试。

8.3限流

限流在签名校验通过后按连接计数，不按来源 IP，多个连接共用出口 IP 时互不影响。其它限制：请求体 ≤ 2 MB，每次推送 ≤ 200 单，每页变更 ≤ 200 行。

8.4签名失败排查

1. 用 §3.4 的测试向量离线验证签名函数。
2. 确认 path 以 /open/v1 开头且不含 query string。
3. 确认签名的是实际发送的字节，HTTP 库没有重新序列化请求体。
4. 确认方法大写、十六进制小写、X-Timestamp 为秒。
5. 路径中的 order_id 已百分号编码后再签名。
6. POST 请求带有 Content-Type: application/json。

09对接要求

渠道方的实现须满足以下要求。

1. 只推送已锁定、不会再修改的订单。推送即进入履约。
2. 修改地址 = 取消旧订单 + 新 order_id 推送。不要用同一个 order_id 推送改过地址的订单：已进仓的订单地址不会更新，已取消的 order_id 会被拒收。
3. order_id 订单级且不可变。升级、追加商品、拆单产生的新发货都是新订单。
4. 每个商品行都是可发货的 SKU。组合商品推送前拆成最小可发货 SKU；尺码、颜色等选项编入 SKU 本身（如 TEE-BLK-L）。同一个 SKU 在商家的所有店铺 / 项目中必须代表同一件实物：OrangeShip 按商家维度把 SKU 映射到仓库货品。
5. 退款和取消都调用取消接口，且越早越好。订单进入 processing 后需人工拦截，shipped 后无法拦截。
6. 按 §6 拉取订单变更，每 15–60 分钟一次；拿到运单号后在渠道系统标记发货并通知买家。
7. 物流轨迹按需查询，不要定时全量轮询。
8. 一单一包裹。v1 不支持多包裹，仓库拆包时只返回第一个运单号。

10版本管理

• 版本号在路径中（/open/v1）。不兼容的变更会使用新的路径（/open/v2），v2 发布后 v1 至少继续运行 6 个月。
• v1 内只做兼容的新增：新增可选请求字段、新增响应字段、新增接口、新增枚举取值（至少提前两周通知）。客户端必须忽略未知字段。
• v1 内不会重命名或删除字段、修改字段类型、修改签名算法、破坏游标兼容，也不会收紧已接受输入的校验。
• 变更会在上线前通知各渠道方的对接人。

10.1变更记录