OminiShip
Developers · API v1

OminiShip 开放接口 v1 对接文档

版本 v1 · 更新日期 2026-11-18
机器可读规格:同目录 openapi.json(OpenAPI 3.0.3,可直接导入 Postman 或用于生成 SDK)。本文与规格内容一致,有出入时请联系我们。

本接口让你的系统(WMS、ERP、自建后台等)以「你在 OminiShip 的客户账号」的身份完成七件事:

能做什么接口每次上限
批量报价POST /v1/rates100 条(且「条目 × 服务」≤ 200)
批量生成订单(默认一步到位:建单 + 扣费 + 出面单)POST /v1/orders/create500 条,合计 ≤ 500 个包裹(见 5.2)
批量查订单信息(状态、价格、跟踪号、面单链接、物流状态、作废进度)POST /v1/orders/info100 条,合计 ≤ 100 张订单(见 5.3)
批量取面单(链接 / base64 / 合并 PDF)POST /v1/orders/labels500 / 20 / 100 条,订单数同上限(见 5.4)
批量作废(提交作废申请,经我方审批后退款)POST /v1/orders/cancel500 条,合计 ≤ 500 张订单(见 5.5)
查余额(余额、订单预留、冻结金额、可用金额、信用额度)POST /v1/balance无(请求体 {},见 5.6)
按建单时间列出订单(对账、增量同步)POST /v1/orders/list每页 1–100 张,时间范围 ≤ 31 天(见 5.7)


获取 API 钥匙

钥匙由你在 OminiShip 后台自助生成、查看和吊销,不需要发邮件申请。

  1. 用你的 OminiShip 客户账号登录后台,进入「设置 → API 钥匙」。还没有客户账号的,请联系我们开通。
  2. 先生成一把测试钥匙(zsk_test_ 开头)联调:不联系承运商、不扣钱(见第 9 节)。
  3. 调通后再生成正式钥匙(zsk_live_ 开头),换到你的系统里即可上线,其它代码不用改。
  4. 完整钥匙只在生成时显示一次,请立即保存;测试、正式每种最多 2 把有效钥匙。泄露或人员变动时,先生成新钥匙换上,再吊销旧的(见2.8 节)。
登录后台生成钥匙

联系我们

以下事项请发邮件给我们:

  • 开通 OminiShip 客户账号
  • 账号被停用(钥匙一律返回 403)后需要重新启用
  • 需要更高的调用额度
  • 持续出现 5xx 或看不懂的错误

邮箱:support@ominiship.com。涉及具体请求的,请附上回复里的 requestId。

1. 快速开始

#
  1. 拿钥匙:用你的客户账号登录 OminiShip 后台,进入「设置 → API 钥匙」,自己生成:先生成一把测试钥匙(以 zsk_test_ 开头)联调,调通后再生成正式钥匙(以 zsk_live_ 开头)。钥匙只在生成的那一刻完整显示一次,请立即妥善保存;我方不保存明文,丢了就在同一页吊销旧的、再生成一把新的。测试钥匙、正式钥匙每种最多 2 把有效(吊销后名额释放),详见 2.8 节。还没有 OminiShip 客户账号的,请联系我们开通。
  2. 用测试钥匙调通:测试钥匙调用的是同一个地址、同一套接口,但不会联系任何承运商、不会扣任何钱,返回测试单号、测试跟踪号和样例面单(见第 9 节)。把七个接口和你关心的异常分支都跑一遍。
  3. 换正式钥匙上线:把钥匙换成 zsk_live_…,其它代码不用改。从这一刻起生成订单会真实扣费、真实出面单。

最小可运行示例(报价):

curl -X POST https://openapi.ominiship.com/v1/rates \
  -H "Authorization: Bearer zsk_test_<你的测试钥匙>" \
  -H "Content-Type: application/json" \
  -d '{
    "unitSystem": "imperial",
    "shipments": [{
      "shipFrom": { "name": "Warehouse A", "address1": "1000 E Example Ave", "city": "Ontario", "state": "CA", "postalCode": "91761" },
      "shipTo":   { "name": "Jane Doe", "address1": "350 5th Ave", "city": "New York", "state": "NY", "postalCode": "10118", "residential": true },
      "packages": [{ "weight": 2.5, "length": 10, "width": 8, "height": 4 }]
    }]
  }'

2. 基本约定

#

2.1 地址与方法

#
项约定
地址(Base URL)https://openapi.ominiship.com(只有正式环境;测试钥匙与正式钥匙用同一个地址)
方法5 个接口全部 POST
请求头Content-Type: application/json;Authorization: Bearer <钥匙>
路径只开放 /v1/... 下的 5 个路径。其它任何路径(包括早期测试版的旧路径)都回复 404 NOT_FOUND
字段命名一律 camelCase;区分大小写;不认识的字段会被忽略

2.2 鉴权

#
  • 每个请求都要带 Authorization: Bearer <钥匙>。
  • 一把钥匙 = 一个客户。 请求里不需要也不能传公司或客户 id:钥匙绑定的客户就是下单人、付款人、作废申请人;你只能看到、操作这个客户自己的订单(包括该客户在 OminiShip 后台手工下的单)。
  • 正式钥匙 zsk_live_ + 64 位十六进制;测试钥匙 zsk_test_ + 64 位十六进制。
  • 钥匙泄露或人员变动时,请在后台「设置 → API 钥匙」先生成一把新钥匙换到你的系统里,再吊销旧的;吊销立即生效、不可恢复,旧钥匙从下一次请求起返回 401 API_KEY_REVOKED。需要协助可以联系我们:我方员工可以代为吊销,但不能代为生成(完整钥匙只给你本人看)。
  • 不要在请求里带 X-Impersonate-Session 请求头(会被拒绝:400 IMPERSONATION_UNSUPPORTED)。
  • 钥匙绑定的客户账号被停用后,这个客户的钥匙(正式钥匙、测试钥匙都一样)一律返回 403 ACCOUNT_DEACTIVATED。钥匙本身没有被吊销,换新钥匙没有用;请联系我们,账号重新启用后原钥匙继续可用。被拒的请求不计入限流次数。
  • 鉴权按以下顺序检查,遇到第一个不满足的就返回:
    带了 X-Impersonate-Session 请求头 ⇒ 400 IMPERSONATION_UNSUPPORTED →
    缺少钥匙或格式不对 ⇒ 401 INVALID_API_KEY →
    我方暂时无法验证钥匙 ⇒ 503 API_KEY_LOOKUP_UNAVAILABLE →
    钥匙无效(不存在 ⇒ 401 INVALID_API_KEY;已吊销或已过期 ⇒ 401 API_KEY_REVOKED)→
    客户账号已停用 ⇒ 403 ACCOUNT_DEACTIVATED →
    超出限流 ⇒ 429 RATE_LIMITED / QUOTA_EXCEEDED。
    通过之后才检查账号是否开通此功能(403 ACCOUNT_NOT_ENABLED)和请求体(400 INVALID_REQUEST / BATCH_TOO_LARGE)。

2.3 统一回复格式(信封)

#

我方服务产生的所有回复(成功、4xx、5xx 都一样)都是这个形状:

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": { },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}
字段说明
success整次请求是否被处理
code成功为 OK;失败为请求级错误码(第 10.1 节)
message英文说明,失败时写明下一步。永远不会是 "Internal server error"
data接口数据;失败时可能带细节(如 errors、maxItems、maxPackages、retryAfter),也可能为 null
requestId本次请求编号。遇到问题联系我们时请附上

处理顺序建议:先读 success / code,再看 HTTP 状态码。

  • 业务结果(包括「某几条失败」)一律 HTTP 200。
  • 鉴权失败 401、账号未开通或已停用 403、请求格式不对 400、路径不存在 404、限流 429、我方故障 5xx(可能是 500 或 503)——回复体仍然是上面的信封。

例外(不是信封格式,只能按 HTTP 状态码处理):

情况你会看到怎么办
平台整体每秒级的保护性限流HTTP 429,回复体不是信封稍等几秒后重试
请求超时(约 30 秒)HTTP 504,回复体不是信封用同样的客户单号原样重发是安全的(见第 3 节),不会重复扣费
极少数情况下路径不存在由网关直接拒绝HTTP 404,回复体不是信封检查方法与路径

2.4 批量结果

#

报价、生成订单、订单信息、面单、作废这五个接口都是批量接口,成功时 data 形如:

{
  "summary": { "total": 2, "succeeded": 1, "failed": 1 },
  "results": [
    { "index": 0, "success": true,  "code": "OK", "message": "", "retryable": false, "...": "该接口的字段" },
    { "index": 1, "success": false, "code": "ORDER_NOT_FOUND", "message": "No order of yours matches this identifier.", "retryable": false }
  ]
}
  • results 与请求数组同序,index 就是请求里的下标(从 0 开始)。
  • 整次回复 success: true, code: "OK" 只表示「请求被处理了」,请逐条看 results[i].success。
  • 每条都有 index、success、code、message、retryable 五个键。retryable: true 表示「这一条原样重发可能成功」。
  • summary.succeeded 统计 success: true 的条数——包括「已受理、处理中」的条目。

2.5 金额、币种、单位、时间

#
项约定
金额字符串,两位小数,美元,例如 "12.34"、"0.00"。做加减等算术前请先转成数字,展示时再格式化回两位小数
币种每个金额旁都带 "currency": "USD"
单位报价与生成订单的请求体顶层 unitSystem 必填、没有默认值:"imperial"(磅 / 英寸)或 "metric"(千克 / 厘米)。缺了整次 400
时间戳ISO 8601 UTC,例如 2026-10-19T08:00:00Z
发货日 shipDateYYYY-MM-DD;省略时取建单当天的 UTC 日期
可选字段为空回复里没有值的字段一律是 null,键始终存在

2.6 限流

#
维度默认额度超限回复
每把钥匙每分钟(UTC 自然分钟)60 次429 RATE_LIMITED,data.retryAfter = 距下一分钟的秒数
每把钥匙每天(UTC 自然日)5000 次429 QUOTA_EXCEEDED,data.retryAfter = 距 UTC 零点的秒数
  • 一次批量调用算 1 次,与里面有多少条无关。所以请尽量批量调用,而不是一条一条调。
  • 测试钥匙与正式钥匙各自计数。
  • 超限后请按 retryAfter 等待;等待期间继续发送仍会被拒。
  • 需要更高额度请联系我们。

2.7 超时与重试

#
  • 每个接口都会在约 20 秒内回复。建议客户端超时设为 30 秒或以上。
  • 什么时候原样重发是安全的:看到 retryable: true、5xx、504、或网络断开不知道结果时,用完全相同的请求体(同样的客户单号)重发即可——生成订单按客户单号去重,不会多建单、不会多扣钱(第 3 节)。
  • 不要因为看到 PROCESSING 就换新客户单号重发:那会真的再买一张面单。

2.8 获取与管理钥匙

#

钥匙由你在 OminiShip 后台自助管理,入口是「设置 → API 钥匙」(用你的客户账号登录)。

  • 生成:选择测试钥匙或正式钥匙,填一个备注名(1–50 个字,例如「WMS 正式环境」),点生成。完整钥匙只显示这一次,关掉之后任何人(包括我们)都无法再看到,请立即复制保存。
  • 每种最多 2 把:每个客户账号测试钥匙、正式钥匙各最多 2 把有效钥匙;已吊销的不占名额。满了还想生成,先吊销一把不用的。
  • 列表:能看到每把钥匙的备注名、类型、末 4 位、创建时间、最近使用时间(约 1 分钟精度)和状态。已吊销的钥匙也会留在列表里,方便核对。
  • 换钥匙(轮换):先生成一把新钥匙 → 换到你的系统里、确认调用成功 → 再吊销旧钥匙。按这个顺序不会中断对接。
  • 吊销:立即生效、不可恢复。吊销后,用这把钥匙的请求从下一次起就返回 401 API_KEY_REVOKED。
  • 限流按每把钥匙分别计算(见 2.6)。
  • 怀疑账号被盗:先修改登录密码,再到「设置 → API 钥匙」检查并吊销你不认识的钥匙。修改密码不会自动吊销钥匙。
  • 我方员工可以帮你查看、吊销钥匙,但不能代你生成——完整钥匙只给你本人看。

3. 客户单号(防重复下单)

#

3.1 规则

#

生成订单的每一条都必须带 customerOrderNo(你系统里的单号)。

规则说明
格式1–64 个字符,只能是字母、数字和 . _ - /
区分大小写,不做任何处理ref-1 与 REF-1 是两个不同的单号;前后带空格直接判为无效
作用范围在你这个客户账号内唯一;同公司的其它客户用同样的号互不影响、互相看不到
测试与正式独立测试钥匙下的单号与正式钥匙下的单号互不相干
用过一次就永远属于那一张单同号重发只会拿回那张单,绝不会多建单、多扣钱
一单多个包裹 = 多张订单一条订单带多个包裹(quantity 计入)会拆成多张订单,每张 1 个包裹、各有自己的我方单号和跟踪号;客户单号就是这一组的号,同号重发拿回同一组订单(见 5.2)
作废后不能再用作废(或申请作废)过的单号不能用来重新发货;要重新发货请换新号(例如 WMS-10001-2)
改内容要换新号同号但内容不同会被拒绝(CUSTOMER_ORDER_NO_CONFLICT);要改请换新号,或到 OminiShip 后台修改草稿
后台删除过的单号也不能再用返回 CUSTOMER_ORDER_NO_USED

「内容相同」指:unitSystem、serviceCode(或 serviceCodeGroup)、shipDate(按你发送的原值;省略就是省略)、maxCharge、两个地址(去掉首尾空格后)、包裹、references 全部一致。省略 shipDate 的请求第二天原样重发,仍算内容相同。

3.2 同一客户单号再次提交时会发生什么

#
这个单号已有的那张单这次 confirm: false(只建草稿)这次 confirm: true(默认,要出单)
没有新建草稿新建并出单
草稿 DRAFT返回这张草稿内容相同 ⇒ 把这张草稿拿去出单;内容不同 ⇒ CUSTOMER_ORDER_NO_CONFLICT(不改、不出单)
处理中 PROCESSING返回现状返回现状,不会重复排队
已出单 CREATED返回这张单返回这张单,不会再扣钱(不比对内容)
失败 FAILED返回失败原因内容相同 ⇒ 按原内容重试出单一次(单号不变);内容不同 ⇒ CUSTOMER_ORDER_NO_CONFLICT
作废中 CANCEL_PENDING / 已作废 CANCELLED返回这张单返回这张单(不能复用,重新发货请换新号)
已在后台删除CUSTOMER_ORDER_NO_USEDCUSTOMER_ORDER_NO_USED

返回已存在的单时,该条 replayed: true。返回已存在的单不再检查 serviceCode(或代码组)现在是否仍可用——即使这个服务后来被停用,同号重发也照样拿回那张单;只有本次要新建或要出单时,服务不可用才会返回 SERVICE_NOT_AVAILABLE(用代码组时是 SERVICE_CODE_GROUP_NOT_FOUND / SERVICE_CODE_GROUP_EMPTY;此时本次什么都没建、没扣钱)。

一单多个包裹时(见 5.2),上表对每个包裹的订单各判一次;只要有一个包裹被拒(例如其中一张已在后台删除),整条都被拒,本次什么都不建、不扣钱。包裹数变了(例如从 3 个变成 2 个)也算「内容不同」:已出单的照旧返回原来那一组,草稿或失败单返回 CUSTOMER_ORDER_NO_CONFLICT。

一句话:客户单号用过一次就永远属于那一张单;同号重发只会拿回那张单,绝不会多扣钱。


4. 单号三选一

#

订单信息、面单、作废三个接口的每一条,都用下面三个字段中的恰好一个来指定订单(填 0 个或 2 个以上 ⇒ 该条 INVALID_IDENTIFIER):

字段是什么注意
customerOrderNo你的客户单号最推荐:立即可查、唯一
orderNo我方单号(ORD-…,测试单为 SBX-…)不区分大小写;在 OminiShip 后台手工下的单只能用它或跟踪号查
trackingNumber承运商跟踪号刚出单约 1 分钟内可能查不到;如果对应你的多张单,返回 AMBIGUOUS_TRACKING_NUMBER 并在该条 orderNos 里列出你名下的候选我方单号
  • 每个值最长 64 个字符,不能含空格。
  • 查不到、或者单不是你的,都只会返回 ORDER_NOT_FOUND(两种情况回复完全一样)。
  • 同一请求里两条指向同一张单时,后一条返回 DUPLICATE_IN_BATCH。
  • 单号类失败的条目会原样带回你发来的那个单号字段,方便对应。

5. 接口说明

#

5.1 批量报价 POST /v1/rates

#

报价不花钱。纯同步,约 20 秒内回复。

请求

字段类型必填说明
unitSystemstring是imperial / metric
shipmentsarray是1–100 条
shipments[].refstring否≤ 64 字符,原样回显,方便你对应结果
shipments[].serviceCodestring否只报这个服务;与 serviceCodeGroup 二选一,两个都不填 = 报你能用的全部服务
shipments[].serviceCodeGroupstring否你的代码组名称(≤ 50 字符;区分大小写、需完全一致,首尾空格忽略)。只回一个价:组内当前最便宜的价格,不说明是哪个服务;与 serviceCode 同时填 ⇒ 该条 INVALID_SHIPMENT
shipments[].shipFrom / shipToobject是地址,见 6.1
shipments[].packagesarray是包裹,见 6.2;多个包裹(quantity 计入)按包裹逐个报价,一票最多 50 个

「条目数 × 要报的服务数」(代码组按组内你能用的服务数计;多个包裹的条目再乘以其中不同规格的包裹数)不能超过 200,超了整次 400 BATCH_TOO_LARGE(data 带 maxItems、maxCombinations、combinations),此时不会询问任何承运商——请减少条目或指定 serviceCode。

每条结果

字段说明
index / success / code / message / retryable见 2.4
ref你发来的 ref(没发为 null)
rates[]报出的价格,按价格从低到高:{ serviceCode, carrier, service, totalCharge, currency };代码组报价只有一条:{ serviceCode: null, carrier: null, service: null, serviceCodeGroup, totalCharge, currency };多个包裹时每个价另带 packageRates:[ { packageIndex, totalCharge } ],每个包裹一个价,totalCharge 是它们的合计
unavailable[]没报出价的服务:{ serviceCode, code, message, retryable, carrierMessage }
errors[]INVALID_SHIPMENT 或 RECEIVER_PHONE_INVALID 时出现,字段错误(6.6)
  • 至少报出一个价 ⇒ 该条 OK;一个都没有 ⇒ 该条 code 取第一个不可用服务的原因。
  • unavailable[].code:NO_RATE(承运商没给价,或多个包裹中有包裹没报出价,附原话或我方说明)、CARRIER_RATE_ERROR(可重试)、RATE_TIMEOUT(可重试)、SERVICE_NOT_AVAILABLE(我方配置原因,请联系我们)。
  • 指定的 serviceCode 不属于你 / 已停用 ⇒ 该条 SERVICE_NOT_AVAILABLE。指定的 serviceCodeGroup 找不到 ⇒ SERVICE_CODE_GROUP_NOT_FOUND;组里没有你现在能用的服务 ⇒ SERVICE_CODE_GROUP_EMPTY(两种都不会询问承运商)。
  • 美国收件地址(shipTo.country 为空 / US / USA)的 shipTo.phone 填了但不是恰好 10 位数字(不能带 +1、分机、空格、横杠、括号)⇒ 该条 RECEIVER_PHONE_INVALID,errors[] 指向 shipments[i].shipTo.phone(不会询问承运商)。
  • serviceCode 是不透明字符串:请原样保存、原样回传给生成订单接口,不要解析或拼接。
  • 用代码组报价:代码组由我方为你的账号设置,组名与你在 OminiShip 后台下单时看到的一致。回复不说明是组内哪个服务(serviceCode / carrier / service 为 null);组内都没报出价时 unavailable[] 只有一条,其 serviceCode 与 carrierMessage 为 null。下单时把同一个组名填进生成订单接口的 serviceCodeGroup(见 5.2)。
  • carrier 例:ups、usps、fedex;service 例:ups_ground、usps_ground_advantage、fedex_ground。
  • 多个包裹(quantity 计入)会按包裹逐个报价:每个包裹以后都是一张单、一个跟踪号,所以价格是每个包裹单独的价格之和;同样的包裹只问一次承运商。所有包裹都报出价,这个服务才算报出价;否则它进 unavailable[],message 以 Package k: 开头,说明是第几个包裹没报出价。一票最多 50 个包裹(quantity 计入),超过 ⇒ 该条 INVALID_SHIPMENT。

成功示例(一条报全部服务、一条邮编写错)

请求:

{
  "unitSystem": "imperial",
  "shipments": [
    {
      "ref": "quote-1",
      "shipFrom": { "name": "Warehouse A", "company": "Acme Fulfillment", "phone": "9095550100", "address1": "1000 E Example Ave", "city": "Ontario", "state": "CA", "postalCode": "91761", "country": "US" },
      "shipTo": { "name": "Jane Doe", "phone": "2125550100", "address1": "350 5th Ave", "address2": "Apt 2", "city": "New York", "state": "NY", "postalCode": "10118", "residential": true },
      "packages": [ { "weight": 2.5, "length": 10, "width": 8, "height": 4, "quantity": 1 } ]
    },
    {
      "ref": "quote-2",
      "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
      "shipFrom": { "name": "Warehouse A", "address1": "1000 E Example Ave", "city": "Ontario", "state": "CA", "postalCode": "91761" },
      "shipTo": { "name": "Jane Doe", "address1": "350 5th Ave", "city": "New York", "state": "NY", "postalCode": "1011" },
      "packages": [ { "weight": 2.5, "length": 10, "width": 8, "height": 4 } ]
    }
  ]
}

回复:

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 1, "failed": 1 },
    "results": [
      {
        "index": 0, "success": true, "code": "OK", "message": "", "retryable": false,
        "ref": "quote-1",
        "rates": [
          { "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90", "carrier": "usps", "service": "usps_ground_advantage", "totalCharge": "6.92", "currency": "USD" },
          { "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21", "carrier": "fedex", "service": "fedex_ground", "totalCharge": "9.87", "currency": "USD" }
        ],
        "unavailable": []
      },
      {
        "index": 1, "success": false, "code": "INVALID_SHIPMENT", "message": "The shipment is invalid; see errors for the fields to fix.", "retryable": false,
        "ref": "quote-2", "rates": [], "unavailable": [],
        "errors": [ { "field": "shipments[1].shipTo.postalCode", "code": "INVALID_VALUE", "message": "For a US address, postalCode must be 12345 or 12345-6789." } ]
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

失败示例(缺 unitSystem,整次 400)

{
  "success": false,
  "code": "INVALID_REQUEST",
  "message": "The request body is invalid. See data.errors for the fields to fix.",
  "data": { "errors": [ { "field": "unitSystem", "code": "REQUIRED", "message": "unitSystem is required: \"imperial\" (lb / in) or \"metric\" (kg / cm)." } ] },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

5.2 批量生成订单 POST /v1/orders/create

#

请求

字段类型必填说明
unitSystemstring是imperial / metric
confirmboolean否默认 true:建单 + 扣费 + 出面单;false:只建草稿(之后可在 OminiShip 后台手动提交,或用同样内容 + confirm: true 再调一次本接口)
ordersarray是1–500 条;所有条目的包裹合计(quantity 计入)≤ 500 个,超了整次 400 BATCH_TOO_LARGE(data 带 maxItems、maxPackages、packages),什么都不建、不扣钱。校验不通过的条目计 0;超过 50 个包裹的条目按 50 计(它本身仍被拒)
orders[].customerOrderNostring是客户单号,见第 3 节
orders[].serviceCodestring二选一从报价接口拿到的服务代码,原样回传(≤ 128 字符);与 serviceCodeGroup 必须填且只填一个
orders[].serviceCodeGroupstring二选一你的代码组名称(≤ 50 字符,规则见 5.1)。购买前按组内当时最便宜的服务出单;订单视图出单前不给 carrier / service,serviceCode 恒为 null;购买失败时 statusReason.carrierCode 与 carrierMessage 恒为 null(失败原因码与下一步照常给)。两个都不填或都填 ⇒ 该条 INVALID_ORDER
orders[].shipDatestring否YYYY-MM-DD;省略取建单当天的 UTC 日期
orders[].maxChargestring否金额字符串(如 "25.00",数字类型会被拒)。购买前我方报价高于它就不买:该单 FAILED / PRICE_ABOVE_MAX,不扣钱;一单多个包裹时暂不能用(该条 INVALID_ORDER,见下方「一单多个包裹」)
orders[].shipFrom / shipToobject是地址,见 6.1
orders[].packagesarray是包裹,见 6.2;多个包裹(quantity 计入)会拆成多张订单,见下方「一单多个包裹」
orders[].referencesobject否{ "reference1": "…", "reference2": "…" },各 ≤ 50 字符;保存在订单上,承运商支持时会带到面单上

处理方式

  1. 先受理再出单:每条通过校验后立即建好订单(从这一刻起订单信息接口就查得到),confirm: true 的订单随后在后台报价并购买面单。
  2. 本次通过校验的订单 ≤ 20 张时(一单多个包裹按包裹数计),接口最多等 15 秒,把已经出结果的单直接带回(CREATED 或 FAILED);还没出结果的为 PROCESSING。> 20 条时立即回复。
  3. PROCESSING 的条目 success: true(已受理,不是失败),请用订单信息接口轮询,不要换单号重发。
  4. 时间用完时还没受理的条目返回 ACCEPT_TIMEOUT(可重试,原样重发安全)。

关于价格

  • maxCharge 约束的是购买前那一刻我方的报价(已含全部费用)。
  • 实际购买时我方会再报一次价,价格只许不涨:如果变贵,该单不购买、不扣钱,状态 FAILED / PRICE_CHANGED(可重试:原样重发会按当前价格再试)。
  • 已出单的扣费金额以订单的 totalCharge 为准。
  • 想调高 maxCharge:maxCharge 属于订单内容,改了就是「内容不同」,需要换新客户单号。

关于发件地址:部分服务绑定了固定的发货仓库。使用这类服务时,shipFrom 只作记录,实际以绑定的仓库地址发货。

每条结果

  • 受理 / 返回已有单:{ index, success, code, message, retryable, replayed, …订单视图全部字段(6.3) }。code 为 OK;订单 FAILED 时 code 为失败原因码、success: false。
  • 被拒(本次没有为这一条建任何东西、没扣钱):{ index, success: false, code, message, retryable, customerOrderNo, errors? },code 可能是:
code含义下一步
INVALID_ORDER字段不合法,见 errors[](含一单多个包裹时填了 maxCharge、包裹超过 50 个)改好后重发;因为什么都没建,可以继续用同一个客户单号
DUPLICATE_IN_BATCH同一请求里客户单号重复只保留一条
SERVICE_NOT_AVAILABLE服务代码不属于你或已停用先调报价接口确认可用服务
SERVICE_CODE_GROUP_NOT_FOUND你的账号下没有这个名字的代码组(组名区分大小写)核对组名后重发;因为什么都没建,可以继续用同一个客户单号
SERVICE_CODE_GROUP_EMPTY这个代码组里没有你现在能用的服务联系我们,或改用 serviceCode
RECEIVER_PHONE_INVALID美国收件地址的 shipTo.phone 填了但不是恰好 10 位数字(不能带 +1、分机、空格、横杠、括号),见 errors[];只在本次要出单时检查(confirm: false 只建草稿,不检查)改好后重发;因为什么都没建,可以继续用同一个客户单号(该单号下已有之前 confirm: false 建的草稿或失败的单时除外:那张单的电话改不了,请换新单号)
CUSTOMER_ORDER_NO_CONFLICT该单号已有一张内容不同的单(或一张 2026-11-04 前建的、多个包裹共用一张面单的单,已不能出单)换新单号
CUSTOMER_ORDER_NO_USED该单号的单已在后台删除换新单号
ACCEPT_TIMEOUT这次没来得及受理原样重发

注意区分:入口校验失败的 INVALID_ORDER 什么都没建,同号可重发;而已建好的订单在购买时因数据问题失败(订单 FAILED、原因 INVALID_ORDER)时,这个单号已经属于那张失败单,改内容需要换新号。

失败原因码(订单 FAILED 时的 code / statusReason.code)

FAILED 一定表示没有出面单、没有扣钱(我方能确认时才会给 FAILED;不确定时一律是 PROCESSING):

原因说明下一步
INSUFFICIENT_BALANCE可用余额不足(可用 = 余额 − 在途订单预留 − 被我们冻结的金额);一单多个包裹时余额不够全部包裹 ⇒ 整条拒、一个都不建,带 required / shortfall(见下方「一单多个包裹」)充值,或联系我们解冻后同号原样重发
PRICE_ABOVE_MAX报价高于 maxCharge,当时报价见 statusReason.quotedCharge接受新价格请换新单号并调高 maxCharge
PRICE_CHANGED购买前复核价格变贵同号原样重发
CARRIER_REJECTED承运商拒单,见 statusReason.carrierCode / carrierMessage改内容后换新单号
NO_RATE承运商没给这个包裹报价换服务或改包裹(换新单号)
CARRIER_RATE_ERROR承运商报价服务出错同号原样重发
SERVICE_NOT_AVAILABLE服务暂不可用(我方原因时文案会写明请联系我们)联系我们或换服务
SERVICE_CODE_GROUP_NOT_FOUND购买前这个代码组已被删除换代码组或改用 serviceCode(换新单号)
SERVICE_CODE_GROUP_EMPTY购买前组里已没有你能用的服务联系我们,或改用 serviceCode(换新单号)
INVALID_ORDER订单数据不被接受改内容后换新单号
SUBMIT_PAUSED我方暂停出单(维护)稍后同号原样重发
SUBMIT_FAILED我方原因没能购买,确定没扣钱(用代码组时也可能是:报价选中的服务在购买前被移出了组)同号原样重发(代码组会重新报价);持续失败请联系我们

成功示例

请求:

{
  "unitSystem": "imperial",
  "confirm": true,
  "orders": [
    {
      "customerOrderNo": "WMS-10001",
      "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
      "shipDate": "2026-10-20",
      "maxCharge": "25.00",
      "shipFrom": { "name": "Warehouse A", "company": "Acme Fulfillment", "phone": "9095550100", "address1": "1000 E Example Ave", "city": "Ontario", "state": "CA", "postalCode": "91761", "country": "US" },
      "shipTo": { "name": "Jane Doe", "phone": "2125550100", "address1": "350 5th Ave", "address2": "Apt 2", "city": "New York", "state": "NY", "postalCode": "10118", "residential": true },
      "packages": [ { "weight": 2.5, "length": 10, "width": 8, "height": 4, "quantity": 1 } ],
      "references": { "reference1": "PO-7781" }
    },
    {
      "customerOrderNo": "WMS-10002",
      "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21",
      "shipFrom": { "name": "Warehouse A", "address1": "1000 E Example Ave", "city": "Ontario", "state": "CA", "postalCode": "91761" },
      "shipTo": { "name": "Jane Doe", "address1": "350 5th Ave", "city": "New York", "state": "NY", "postalCode": "10118" },
      "packages": [ { "weight": 12, "length": 16, "width": 12, "height": 10, "quantity": 1 } ]
    }
  ]
}

回复(第一单已出单,第二单还在处理中):

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 2, "failed": 0 },
    "results": [
      {
        "index": 0, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false,
        "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261019-000123",
        "status": "CREATED", "statusReason": null,
        "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90", "carrier": "usps", "service": "usps_ground_advantage",
        "totalCharge": "6.92", "currency": "USD",
        "trackingNumber": "9400111899223344556677",
        "labelReady": true, "labelStatus": "READY",
        "labelUrl": "https://example.com/labels/ORD-20261019-000123?signature=abc123", "labelUrlExpiresAt": "2026-10-19T09:00:00Z",
        "trackingStatus": "PRE_SHIPMENT", "trackingUpdatedAt": null,
        "cancel": null,
        "createdAt": "2026-10-19T08:00:00Z", "submittedAt": "2026-10-19T08:00:03Z"
      },
      {
        "index": 1, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false,
        "customerOrderNo": "WMS-10002", "orderNo": "ORD-20261019-000124",
        "status": "PROCESSING",
        "statusReason": { "code": "ORDER_PROCESSING", "message": "We are buying this label. Check again shortly; do not resend with a new customerOrderNo.", "carrierCode": null, "carrierMessage": null, "quotedCharge": null },
        "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21", "carrier": "fedex", "service": "fedex_ground",
        "totalCharge": null, "currency": "USD", "trackingNumber": null,
        "labelReady": false, "labelStatus": "NOT_CREATED", "labelUrl": null, "labelUrlExpiresAt": null,
        "trackingStatus": null, "trackingUpdatedAt": null, "cancel": null,
        "createdAt": "2026-10-19T08:00:00Z", "submittedAt": null
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

失败示例(一条字段不合法、一条余额不足)

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 0, "failed": 2 },
    "results": [
      {
        "index": 0, "success": false, "code": "INVALID_ORDER",
        "message": "The order is invalid; see errors for the fields to fix. Nothing was created — fix it and send it again (the same customerOrderNo may be used).",
        "retryable": false, "customerOrderNo": "WMS-10003",
        "errors": [ { "field": "orders[0].shipTo.city", "code": "REQUIRED", "message": "This field is required." } ]
      },
      {
        "index": 1, "success": false, "code": "INSUFFICIENT_BALANCE",
        "message": "Your available balance (balance minus amounts reserved for orders in progress or frozen by us) is not enough for this label. Nothing was bought or charged; top up, or ask us to unfreeze, then resend the same request unchanged.",
        "retryable": true, "replayed": false,
        "customerOrderNo": "WMS-10004", "orderNo": "ORD-20261019-000125",
        "status": "FAILED",
        "statusReason": { "code": "INSUFFICIENT_BALANCE", "message": "Your available balance (balance minus amounts reserved for orders in progress or frozen by us) is not enough for this label. Nothing was bought or charged; top up, or ask us to unfreeze, then resend the same request unchanged.", "carrierCode": null, "carrierMessage": null, "quotedCharge": null },
        "serviceCode": "e2a7d913-5c40-4b8e-a1f6-0d9c3b7e5a21", "carrier": "fedex", "service": "fedex_ground",
        "totalCharge": null, "currency": "USD", "trackingNumber": null,
        "labelReady": false, "labelStatus": "NOT_CREATED", "labelUrl": null, "labelUrlExpiresAt": null,
        "trackingStatus": null, "trackingUpdatedAt": null, "cancel": null,
        "createdAt": "2026-10-19T08:00:00Z", "submittedAt": null
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

一单多个包裹

  • 一条订单带多个包裹(quantity 计入,例如一个包裹 quantity: 2 再加一个包裹 = 3 个包裹)会拆成 3 张独立订单,每张 1 个包裹,各自报价、扣费、出面单、拿跟踪号。一条最多 50 个包裹。
  • 客户单号不变,是这一组的号:同号原样重发拿回同一组订单(不新建、不重复扣钱);包裹数或内容变了按第 3 节判定。每张订单另有自己的我方单号 orderNo。
  • 这一条的结果只有一条,带 packageCount(几个包裹)和 orders[](每个包裹一项,按包裹顺序:packageIndex + 那张订单的 success / code / message / retryable / replayed + 订单视图全部字段)。这一条的 code:所有包裹相同就是那个码;否则全部成功为 OK,有没成功的取第一个没成功的包裹的码。
  • 被拒(INVALID_ORDER、CUSTOMER_ORDER_NO_CONFLICT 等)时与一个包裹时一样只有那几个键,整组什么都没建、没扣钱。
  • 钱要够整组才下单:confirm 为 true 时,我们先把这次要买的每个包裹按它自己出单时的方式报一次价,可用余额必须够全部包裹(每个包裹的报价 + 价格变动预留之和);不够就整条 INSUFFICIENT_BALANCE,message 里写明还差多少,并带 required(需要的金额)与 shortfall(还差的金额),一个包裹都不建、不买、不扣钱,充值后同号原样重发即可。某个包裹报不出价时同样整条拒(code 为该包裹的报价码,message 以 Package k: 开头)。
  • 余额够了之后每个包裹单独出单,所以仍可能部分包裹已出单、部分 FAILED(例如承运商拒了其中一个,或同一时间别处也在花这笔钱);同号原样重发只重试失败的那几个,已出单的不会再扣钱。
  • 一单多个包裹时暂不能用 maxCharge(该条 INVALID_ORDER);要限价请把每个包裹作为单独的订单发,各用自己的客户单号和 maxCharge。
  • 订单信息、面单、作废接口按这个客户单号指定时,作用于这一组的全部订单(见 5.3 / 5.4 / 5.5);按 orderNo 或 trackingNumber 只作用于那一张。
  • 一张订单只放一个包裹,是为了每个包裹都有自己的跟踪号;在 OminiShip 后台也不能给这些订单再加包裹。

请求:

{
  "unitSystem": "imperial",
  "orders": [
    {
      "customerOrderNo": "WMS-10005",
      "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
      "shipFrom": { "name": "Warehouse A", "address1": "1000 E Example Ave", "city": "Ontario", "state": "CA", "postalCode": "91761" },
      "shipTo": { "name": "Jane Doe", "address1": "350 5th Ave", "city": "New York", "state": "NY", "postalCode": "10118" },
      "packages": [
        { "weight": 12, "length": 16, "width": 12, "height": 10, "quantity": 2 },
        { "weight": 2.5, "length": 10, "width": 8, "height": 4 }
      ]
    }
  ]
}

回复(3 个包裹都已出单):

{
  "success": true,
  "code": "OK",
  "message": "Processed 1 item(s).",
  "data": {
    "summary": { "total": 1, "succeeded": 1, "failed": 0 },
    "results": [
      {
        "index": 0, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false,
        "customerOrderNo": "WMS-10005", "packageCount": 3,
        "orders": [
          { "packageIndex": 1, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false, "customerOrderNo": "WMS-10005", "orderNo": "ORD-20261104-000201", "status": "CREATED", "totalCharge": "14.20", "trackingNumber": "9400111899223344556601", "packageCount": 3, "...": "订单视图其余字段(6.3)" },
          { "packageIndex": 2, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false, "customerOrderNo": "WMS-10005", "orderNo": "ORD-20261104-000202", "status": "CREATED", "totalCharge": "14.20", "trackingNumber": "9400111899223344556602", "packageCount": 3, "...": "订单视图其余字段(6.3)" },
          { "packageIndex": 3, "success": true, "code": "OK", "message": "", "retryable": false, "replayed": false, "customerOrderNo": "WMS-10005", "orderNo": "ORD-20261104-000203", "status": "CREATED", "totalCharge": "6.92", "trackingNumber": "9400111899223344556603", "packageCount": 3, "...": "订单视图其余字段(6.3)" }
        ]
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

5.3 批量订单信息 POST /v1/orders/info

#

请求:{ "orders": [ 单号三选一, … ] },1–100 条(第 4 节);按客户单号指向一组拆单时组里每张订单都计入,合计 ≤ 100 张订单,超了整次 400 BATCH_TOO_LARGE,什么都不读。

每条结果

  • 找到:{ index, success: true, code: "OK", message: "", retryable: false, …订单视图全部字段(6.3) }。
  • 没找到:INVALID_IDENTIFIER / ORDER_NOT_FOUND / AMBIGUOUS_TRACKING_NUMBER(附 orderNos)/ DUPLICATE_IN_BATCH,并带回你发来的那个单号字段。
  • 我方读取故障时整次 503 SERVICE_UNAVAILABLE(不会把故障说成「查无此单」),稍后重试。
  • 按客户单号查一单多个包裹的订单(见 5.2):返回一条,带 packageCount 与 orders[](每个包裹一项:packageIndex + success / code / message / retryable + 订单视图全部字段);某个包裹查不到时那一项为 ORDER_NOT_FOUND。按 orderNo / trackingNumber 查只返回那一张,订单视图多带 packageIndex / packageCount(6.3)。同一请求里既查这一组又单独查其中一张 ⇒ 后一条 DUPLICATE_IN_BATCH。

说明:

  • 只能查到钥匙绑定客户自己的单;在 OminiShip 后台手工下的单也查得到(customerOrderNo 为 null,用我方单号或跟踪号查)。
  • 不会实时查询承运商:trackingStatus 是我方保存的最近一次物流状态,trackingUpdatedAt 是它的更新时间。
  • labelUrl 只在面单文件已经准备好时给出;labelReady: true 但 labelUrl 为 null 时,请用面单接口取。

成功示例

请求:

{ "orders": [ { "customerOrderNo": "WMS-10001" }, { "orderNo": "ORD-20261019-000124" }, { "trackingNumber": "1Z999AA10123456784" } ] }

回复(前两条与 5.2 示例中的两张单相同,此处只展示第三条):

{
  "success": true,
  "code": "OK",
  "message": "Processed 3 item(s).",
  "data": {
    "summary": { "total": 3, "succeeded": 2, "failed": 1 },
    "results": [
      { "index": 0, "success": true, "code": "OK", "message": "", "retryable": false, "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261019-000123", "status": "CREATED", "...": "订单视图其余字段" },
      { "index": 1, "success": true, "code": "OK", "message": "", "retryable": false, "customerOrderNo": "WMS-10002", "orderNo": "ORD-20261019-000124", "status": "PROCESSING", "...": "订单视图其余字段" },
      { "index": 2, "success": false, "code": "ORDER_NOT_FOUND", "message": "No order of yours matches this identifier.", "retryable": false, "trackingNumber": "1Z999AA10123456784" }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

失败示例(跟踪号对应你的两张单)

{
  "success": true,
  "code": "OK",
  "message": "Processed 1 item(s).",
  "data": {
    "summary": { "total": 1, "succeeded": 0, "failed": 1 },
    "results": [
      {
        "index": 0, "success": false, "code": "AMBIGUOUS_TRACKING_NUMBER",
        "message": "This tracking number matches more than one of your orders. Use customerOrderNo or orderNo instead (the candidates are listed in orderNos).",
        "retryable": false,
        "trackingNumber": "9400111899223344556677",
        "orderNos": [ "ORD-20261019-000123", "ORD-20261019-000188" ]
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

候选单号在该条的 orderNos 字段里。

5.4 批量面单 POST /v1/orders/labels

#

请求

字段类型必填说明
formatstring否url(默认)/ base64 / merged
ordersarray是单号三选一;上限按 format:url 500、base64 20、merged 100;按客户单号指向一组拆单时组里每张订单都计入,订单数同一上限,超了整次 400 BATCH_TOO_LARGE,不取任何面单

按客户单号取一单多个包裹的面单(见 5.2):返回一条,orders[] 里每个包裹一项(各自的 code、单号与面单字段);merged 时每个包裹的面单都按包裹顺序合进同一个 PDF。按 orderNo / trackingNumber 只取那一张。

三种格式

format每条成功时的字段说明
urlfileType、labelUrl、expiresAt我方下载链接,1 小时有效;过期后重新调本接口拿新链接
base64fileType、contentBase64一次回复里面单内容(按 base64 编码后计)累计约 5 MB 封顶:放进去会超过上限的那一条返回 RESPONSE_TOO_LARGE(可重试,另发一次请求取),后面放得下的更小的面单仍会给出
mergedmerged: true所有能合并的面单合成一个 PDF,链接在 data.merged = { labelUrl, expiresAt, pageCount }(一个都合不进时为 null);不能合并的格式(如 ZPL)该条返回 LABEL_FORMAT_UNSUPPORTED,可用 url 方式单独取
  • 每条(成功或面单类失败)都带 customerOrderNo、orderNo、trackingNumber。
  • fileType:PDF、PNG、JPEG,或承运商原样给的其它格式(如 ZPL);无法识别时为 UNKNOWN。
  • 链接是我方链接,主机名可能变化,请当作不透明 URL 直接下载。下载文件名为我方单号。
  • 作废中或已作废的单不再提供面单(LABEL_BLOCKED_CANCELLED)。作废前已经发出去的链接,最多还能用到它自己的 1 小时有效期结束。
  • 部分渠道出单后面单稍晚才出:返回 LABEL_NOT_READY(可重试)。订单还在处理中时也是 LABEL_NOT_READY。
  • 草稿或失败的单没有面单:ORDER_NOT_SHIPPED。
  • 本次时间用完还没准备好的条目:LABEL_PREPARING(可重试);承运商的文件暂时取不到:LABEL_UNAVAILABLE(可重试)。

成功示例

请求:

{ "format": "url", "orders": [ { "customerOrderNo": "WMS-10001" }, { "customerOrderNo": "WMS-10009" } ] }

回复(第二单已作废):

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 1, "failed": 1 },
    "results": [
      {
        "index": 0, "success": true, "code": "OK", "message": "", "retryable": false,
        "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261019-000123", "trackingNumber": "9400111899223344556677",
        "fileType": "PDF", "labelUrl": "https://example.com/labels/ORD-20261019-000123?signature=abc123", "expiresAt": "2026-10-19T09:00:00Z"
      },
      {
        "index": 1, "success": false, "code": "LABEL_BLOCKED_CANCELLED",
        "message": "This order is being cancelled or is cancelled, so its label is no longer provided.", "retryable": false,
        "customerOrderNo": "WMS-10009", "orderNo": "ORD-20261019-000131", "trackingNumber": "9400111899223344550000"
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

合并示例

请求:

{ "format": "merged", "orders": [ { "customerOrderNo": "WMS-10001" }, { "orderNo": "ORD-20261019-000140" } ] }

回复:

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 1, "failed": 1 },
    "results": [
      { "index": 0, "success": true, "code": "OK", "message": "", "retryable": false, "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261019-000123", "trackingNumber": "9400111899223344556677", "merged": true },
      { "index": 1, "success": false, "code": "LABEL_FORMAT_UNSUPPORTED", "message": "This label's format cannot be merged into a PDF. Fetch it on its own with format \"url\".", "retryable": false, "customerOrderNo": null, "orderNo": "ORD-20261019-000140", "trackingNumber": "1Z999AA10123456799" }
    ],
    "merged": { "labelUrl": "https://example.com/labels/merged/7d3f?signature=def456", "expiresAt": "2026-10-19T09:00:00Z", "pageCount": 1 }
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

失败示例(base64 超过 20 条,整次 400)

{
  "success": false,
  "code": "BATCH_TOO_LARGE",
  "message": "At most 20 items per request.",
  "data": { "maxItems": 20, "maxPackages": 20, "packages": null },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

5.5 批量作废 POST /v1/orders/cancel

#

先读第 8 节:作废需要我方审批,接口从不说「作废成功」。

请求

字段类型必填说明
ordersarray是1–500 条,每条单号三选一;按客户单号指向一组拆单时组里每张订单都计入,合计 ≤ 500 张订单,超了整次 400 BATCH_TOO_LARGE,不提交任何作废申请
orders[].reasonstring否作废原因,≤ 200 字符。不是字符串或超长 ⇒ 整次 400,什么都不会发出

每条结果:{ index, success, code, message, retryable, customerOrderNo, orderNo, trackingNumber, status, cancel }(status 为订单状态,cancel 见 6.5)。

按客户单号作废一单多个包裹的订单(见 5.2):这一组里每张能作废的订单各提一次作废申请(各自审批、各自退款),其余按下表各自回答;返回一条,orders[] 里每个包裹一项(上面的字段 + packageIndex)。按 orderNo / trackingNumber 只作废那一张。

订单当前状态该条结果
CREATED(已出单)受理:OK,cancel.status = PROCESSING。本次请求 ≤ 20 条时最多等 15 秒,可能直接拿到 PENDING_REVIEW(承运商已取消、等我方审批退款),或 FAILED(该条 code 为承运商拒绝的原因、success: false)
CREATED 且已有一次作废正在进行OK,cancel.status = PROCESSING,不会重复发出
CANCEL_PENDING(已申请)CANCEL_ALREADY_REQUESTED(success: true),cancel.status = PENDING_REVIEW
CANCELLED(已作废)ALREADY_CANCELLED(success: true),cancel.status = APPROVED
DRAFT / FAILEDORDER_NOT_SHIPPED:没出单、没扣钱,无需作废(草稿可在后台删除)
PROCESSINGORDER_PROCESSING(可重试):还在出单中,稍后再试
本次没能发出CANCEL_TEMPORARILY_UNAVAILABLE(可重试):什么都没变,稍后重发
单号问题INVALID_IDENTIFIER / ORDER_NOT_FOUND / AMBIGUOUS_TRACKING_NUMBER / DUPLICATE_IN_BATCH

没在本次回复里拿到最终结果的,请用订单信息接口看 cancel。

成功示例

请求:

{ "orders": [ { "customerOrderNo": "WMS-10001", "reason": "Customer changed mind" }, { "customerOrderNo": "WMS-10002" } ] }

回复:

{
  "success": true,
  "code": "OK",
  "message": "Processed 2 item(s).",
  "data": {
    "summary": { "total": 2, "succeeded": 1, "failed": 1 },
    "results": [
      {
        "index": 0, "success": true, "code": "OK", "message": "", "retryable": false,
        "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261019-000123", "trackingNumber": "9400111899223344556677",
        "status": "CANCEL_PENDING",
        "cancel": {
          "status": "PENDING_REVIEW", "code": null,
          "message": "The carrier has accepted the cancellation and the refund is waiting for our review. No refund has been issued yet.",
          "carrierMessage": null, "requestedAt": "2026-10-19T10:00:00Z", "reviewedAt": null,
          "refundAmount": null, "currency": "USD", "rejectReason": null
        }
      },
      {
        "index": 1, "success": false, "code": "ORDER_PROCESSING", "message": "This order is still being processed. Retry the cancellation shortly.", "retryable": true,
        "customerOrderNo": "WMS-10002", "orderNo": "ORD-20261019-000124", "trackingNumber": null,
        "status": "PROCESSING", "cancel": null
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

失败示例(承运商拒绝取消)

{
  "success": true,
  "code": "OK",
  "message": "Processed 1 item(s).",
  "data": {
    "summary": { "total": 1, "succeeded": 0, "failed": 1 },
    "results": [
      {
        "index": 0, "success": false, "code": "CARRIER_CANCEL_REJECTED",
        "message": "The carrier refused to cancel this label (often because the parcel was already picked up). The order is unchanged and nothing was refunded. Contact us with the requestId if you need help.",
        "retryable": false,
        "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261019-000123", "trackingNumber": "9400111899223344556677",
        "status": "CREATED",
        "cancel": {
          "status": "FAILED", "code": "CARRIER_CANCEL_REJECTED",
          "message": "The carrier refused to cancel this label (often because the parcel was already picked up). The order is unchanged and nothing was refunded. Contact us with the requestId if you need help.",
          "carrierMessage": null, "requestedAt": "2026-10-19T10:00:00Z", "reviewedAt": null,
          "refundAmount": null, "currency": "USD", "rejectReason": null
        }
      }
    ]
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

5.6 查余额 POST /v1/balance

#

请求:{}(空对象;对象里的键会被忽略)。不是 JSON 对象时整次 400 INVALID_REQUEST。只读,不改任何数据。

回复:data 恒有下面六个键(金额都是两位小数的字符串,美元):

字段类型说明
currencystring恒为 USD
balancestring余额;正在使用信用额度时为负数
reservedstring订单预留:正在出单的订单暂时占用的金额,出单完成后转为扣费或释放
frozenstring冻结金额:由我方冻结,只有我方能解冻
availablestring现在可以用来下单的金额 = balance − reserved − frozen + 信用额度(有信用额度时加上 credit.limit)
creditobject | null信用额度;没有信用额度时为 null,否则三个键:limit(额度)、used(已用,即余额低于零的部分)、remaining(剩余)

说明:

  • available 就是生成订单时检查余额用的同一个数:一张单需要的金额(报价 + 价格变动预留)不超过 available 就能出单,超过就是 INSUFFICIENT_BALANCE(见 5.2);同一次请求里的多张单依次占用它。
  • 余额随时会变(别的订单出单、退款、充值),这里给的是读取那一刻的数字;能不能出单以生成订单接口的回复为准。
  • 读取的是最新数据,不是缓存。
  • 测试钥匙返回你账号真实的余额,只读;测试单从不扣钱、从不退钱,不会改变它(第 9 节)。
  • 我方读取故障时整次 503 SERVICE_UNAVAILABLE,不会把故障说成余额为零。

示例

请求:

{}

回复(没有信用额度):

{
  "success": true,
  "code": "OK",
  "message": "",
  "data": { "currency": "USD", "balance": "120.50", "reserved": "20.00", "frozen": "30.00", "available": "70.50", "credit": null },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

回复(正在使用信用额度):

{
  "success": true,
  "code": "OK",
  "message": "",
  "data": { "currency": "USD", "balance": "-40.00", "reserved": "5.00", "frozen": "0.00", "available": "55.00", "credit": { "limit": "100.00", "used": "40.00", "remaining": "60.00" } },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}
curl -X POST https://openapi.ominiship.com/v1/balance \
  -H "Authorization: Bearer zsk_live_<你的正式钥匙>" \
  -H "Content-Type: application/json" \
  -d '{}'

5.7 按时间列订单 POST /v1/orders/list

#

按建单时间列出钥匙绑定客户自己的全部订单(含在后台手工下的、批量上传的、店铺对接自动生成的、通过本接口生成的),用于对账和增量同步。

请求

字段类型必填说明
createdFromstring是起始时间(含)。ISO 8601 日期时间,必须带时区,如 2026-11-15T00:00:00Z 或 2026-11-15T00:00:00-08:00;只写日期(2026-11-15)或不带时区会被拒
createdTostring是结束时间(不含),格式同上;必须晚于 createdFrom,两者相差不超过 31 天
statusstring[]否只列这些状态的订单(取值见 7.1),如 ["CREATED", "CANCELLED"];不填 = 全部状态
limitinteger否每页最多几张订单,1–100,默认 50
cursorstring否上一页回复里的 nextCursor,原样传回;第一页不填

时间按整秒比较:建单时间满足 createdFrom ≤ createdAt < createdTo 的订单会被列出。所以「昨天一整天」就是 createdFrom = 昨天零点、createdTo = 今天零点,相邻两段首尾相接、不重不漏。字段写错时整次 400 INVALID_REQUEST,data.errors 列出每个要改的字段。

回复:data = { orders, nextCursor, query }

字段说明
orders订单数组,按建单时间从早到晚排列;每项就是订单视图全部字段(6.3),与订单信息接口逐字段相同(一单多个包裹拆出的订单另带 packageIndex / packageCount)
nextCursor可能还有下一页时是一个字符串,原样放进下一次请求的 cursor;没有了为 null
query实际生效的查询:createdFrom / createdTo(整秒、UTC)、status(没填为 null)、limit

说明:

  • 只列钥匙绑定客户自己的订单;别的客户的订单永远不会出现,已删除的订单也不会出现。
  • 一页的订单可能少于 limit,甚至一张都没有;只要 nextCursor 不是 null 就继续翻。 带 status 筛选时,我方每次请求最多查看 500 张订单,查完还没凑满一页也会先回复。
  • 在后台手工下的一单多个包裹的订单,按包裹拆成的每张订单逐张列出(各有自己的单号、跟踪号和扣费),排在原订单的位置上,并且总在同一页;它的包裹数多于 limit 时,那一页的订单数会多于 limit。
  • 同一秒建的订单顺序是固定的,翻页不会重复,也不会遗漏。
  • 作废中 / 已作废的订单不带面单链接(与订单信息接口相同);labelUrl 只在面单文件已经准备好时给出。
  • cursor 只对同一个客户账号、同一种钥匙(正式 / 测试)、同样的 createdFrom / createdTo / status 有效(limit 可以变);否则整次 400 INVALID_CURSOR,什么都不读。想从头开始就不传 cursor。
  • 我方读取故障时整次 503 SERVICE_UNAVAILABLE,不会回一个空列表;原样重发即可。

示例

请求(第一页):

{ "createdFrom": "2026-11-15T00:00:00Z", "createdTo": "2026-11-16T00:00:00Z", "status": ["CREATED", "CANCELLED"], "limit": 2 }

回复:

{
  "success": true,
  "code": "OK",
  "message": "Listed 2 order(s).",
  "data": {
    "orders": [
      { "customerOrderNo": "WMS-10001", "orderNo": "ORD-20261115-000123", "status": "CREATED", "totalCharge": "6.92", "currency": "USD", "createdAt": "2026-11-15T08:00:00Z", "...": "订单视图其余字段" },
      { "customerOrderNo": null, "orderNo": "ORD-20261115-000188", "status": "CANCELLED", "totalCharge": "8.15", "currency": "USD", "createdAt": "2026-11-15T09:30:12Z", "...": "订单视图其余字段" }
    ],
    "nextCursor": "eyJ2IjoxLCJiIjoiN2ZrUTJ4",
    "query": { "createdFrom": "2026-11-15T00:00:00Z", "createdTo": "2026-11-16T00:00:00Z", "status": ["CANCELLED", "CREATED"], "limit": 2 }
  },
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}

请求(下一页:同样的查询 + cursor):

{ "createdFrom": "2026-11-15T00:00:00Z", "createdTo": "2026-11-16T00:00:00Z", "status": ["CREATED", "CANCELLED"], "limit": 2, "cursor": "eyJ2IjoxLCJiIjoiN2ZrUTJ4" }

失败示例(cursor 与这次查询不符)

{
  "success": false,
  "code": "INVALID_CURSOR",
  "message": "This cursor is not valid for this request. Send nextCursor from the previous reply unchanged, with the same createdFrom, createdTo and status; to start over, omit cursor.",
  "data": null,
  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
}
curl -X POST https://openapi.ominiship.com/v1/orders/list \
  -H "Authorization: Bearer zsk_live_<你的正式钥匙>" \
  -H "Content-Type: application/json" \
  -d '{ "createdFrom": "2026-11-15T00:00:00-08:00", "createdTo": "2026-11-16T00:00:00-08:00" }'

6. 数据结构

#

6.1 地址(shipFrom / shipTo)

#
字段类型必填限制 / 说明
namestring是≤ 100
companystring否≤ 100
phonestring否≤ 30;美国收件地址(shipTo)报价与出单时,填了就必须是恰好 10 位数字(如 2125550100,不能带 +1、分机、空格、横杠、括号),否则该条 RECEIVER_PHONE_INVALID;shipFrom 不检查
emailstring否≤ 100
address1string是≤ 100
address2string否≤ 100
citystring是≤ 60
statestring是≤ 30;美国地址必须是 2 位州代码(如 CA),会转成大写
postalCodestring是≤ 20;美国地址必须是 12345 或 12345-6789
countrystring否2 位国家代码,默认 US,会转成大写
residentialboolean否是否住宅地址(影响住宅附加费),默认 false

字符串会去掉首尾空格;不认识的字段会被忽略。

6.2 包裹(packages[])

#

每票 1–50 个包裹条目;quantity 计入后一票最多 50 个包裹,每个包裹会成为一张单独的订单(见 5.2)。单位由请求顶层的 unitSystem 决定。

字段类型必填限制
weightnumber是单件重量,> 0 且 ≤ 2000
length / width / heightnumber是> 0 且 ≤ 500
quantityinteger否同规格件数,1–100,默认 1;每件是一个包裹

6.3 订单视图

#

订单信息接口的每条、生成订单接口的每条受理结果、按时间列订单接口的每一项,都带下面全部字段(键始终存在,没有值时为 null):

字段类型说明
customerOrderNostring | null客户单号;在后台手工下的单为 null
orderNostring | null我方单号 ORD-…(测试单 SBX-…)
statusstring订单状态,见 7.1
statusReasonobject | null仅 FAILED / PROCESSING 时有值,见 6.4
serviceCodestring | null仅通过本接口用 serviceCode 建的单给出;后台建的单、用代码组建的单为 null
carrierstring | null承运商,如 usps;用代码组建的单出单前为 null
servicestring | null承运商服务,如 usps_ground_advantage;用代码组建的单出单前为 null
totalChargestring | null已扣费金额;仅 CREATED / CANCEL_PENDING / CANCELLED 时有值
currencystring恒为 USD
trackingNumberstring | null跟踪号;仅 CREATED / CANCEL_PENDING / CANCELLED 时有值
labelReadyboolean现在能不能取面单
labelStatusstring面单状态,见 7.2
labelUrlstring | null面单链接(1 小时有效),仅在面单文件已准备好时给出;否则用面单接口取
labelUrlExpiresAtstring | null上面链接的过期时间
trackingStatusstring | null物流状态,见 7.3;未出单为 null
trackingUpdatedAtstring | null我方最近一次更新物流状态的时间
cancelobject | null作废进度,见 6.5;从未申请过作废为 null
createdAtstring | null建单时间
submittedAtstring | null出单时间

一单多个包裹拆出的订单(见 5.2)另带两个字段:packageIndex(第几个包裹,从 1 起)和 packageCount(这一组共几个包裹);只有一个包裹的订单没有这两个字段。

6.4 statusReason

#

仅订单 status 为 FAILED 或 PROCESSING 时非 null,五个键始终存在:

字段说明
codePROCESSING 时为 ORDER_PROCESSING;FAILED 时为失败原因码(见 5.2「失败原因码」)
message英文说明与下一步
carrierCode仅 CARRIER_REJECTED 且承运商给了码时有值。代码组订单恒为 null(原码同样可能说出组里是哪个服务)
carrierMessage承运商原话(已去除敏感信息、截断到一行)。代码组订单恒为 null(原话可能说出组里是哪个服务);原因与下一步看 code / message
quotedCharge仅 PRICE_ABOVE_MAX:购买前那次报价(金额字符串)

6.5 cancel

#

从未申请过作废时为 null;否则九个键始终存在:

字段说明
status作废状态,见 7.4
code仅 FAILED 时有值:CARRIER_CANCEL_REJECTED / CARRIER_ORDER_NOT_FOUND / CARRIER_CANCEL_UNCONFIRMED / CANCEL_TEMPORARILY_UNAVAILABLE / ORDER_NOT_SHIPPED / ORDER_PROCESSING
message英文说明与下一步
carrierMessage承运商原话。承运商普通拒绝取消(CARRIER_CANCEL_REJECTED)时为 null;只有「承运商查不到这张面单」「承运商回复无法确认」时可能带原话
requestedAt申请时间
reviewedAt审批时间(APPROVED / REJECTED)
refundAmount仅 APPROVED:退款金额(字符串)
currency恒为 USD
rejectReason仅 REJECTED:驳回理由

6.6 字段错误 errors[]

#

整次 400 INVALID_REQUEST 的 data.errors,以及逐条 INVALID_ORDER / INVALID_SHIPMENT 的 errors,元素都是:

字段说明
field完整 JSON 路径,如 orders[1].shipTo.postalCode
codeREQUIRED(缺失)/ INVALID_TYPE(类型不对)/ INVALID_VALUE(取值不对)/ TOO_LONG(超长)/ OUT_OF_RANGE(超出范围)
message英文说明(不会回显你提交的值)

7. 状态说明

#

7.1 订单状态 status

#
值含义你该做什么
DRAFT草稿:只建了单,没出面单、没扣钱(confirm: false 建的)需要出单时用同样内容 + confirm: true 再调生成订单,或在后台提交
PROCESSING处理中:已受理正在出单,或我方正在自动核对一张结果待确认的单。不是失败用订单信息接口轮询;不要换单号重发
CREATED已出单、已扣费取面单
FAILED明确失败:没出面单、没扣钱,原因见 statusReason按 5.2「失败原因码」处理
CANCEL_PENDING已提交作废申请、承运商已取消,等我方审批退款(还没退款)等待;用订单信息接口看 cancel
CANCELLED已作废、已退款—

7.2 面单状态 labelStatus

#
值含义
NOT_CREATED还没出单(草稿 / 处理中 / 失败)
PENDING已出单,但面单稍后才出(部分渠道),稍后再取
READY可以取面单
BLOCKED_CANCELLED作废中或已作废,不再提供面单

7.3 物流状态 trackingStatus

#
值含义
PRE_SHIPMENT已出面单,承运商尚未揽收
IN_TRANSIT运输中
OUT_FOR_DELIVERY派送中
DELIVERED已签收
RETURNED已退回
EXCEPTION异常
UNKNOWN暂无法判断

本接口不提供逐条物流轨迹,只给最近一次状态。

7.4 作废状态 cancel.status

#
值含义钱
PROCESSING已受理,正在向承运商取消未退款
PENDING_REVIEW承运商已取消,等我方审批退款(订单 CANCEL_PENDING)未退款
APPROVED审批通过,已退款(订单 CANCELLED),金额见 refundAmount已退款
REJECTED审批驳回(订单回到 CREATED),理由见 rejectReason未退款
FAILED没取消成功(见 cancel.code),订单仍是 CREATED未退款

8. 作废与退款(两段式审批)

#
  1. 你调用作废接口 ⇒ 我方当场向承运商取消这张面单。
  2. 承运商取消成功 ⇒ 订单变为 CANCEL_PENDING,cancel.status = PENDING_REVIEW。此时还没有退款。
  3. 我方审核:
    • 批准 ⇒ 退款,订单 CANCELLED,cancel.status = APPROVED,退款金额见 refundAmount。
    • 驳回 ⇒ 不退款,订单回到 CREATED,cancel.status = REJECTED,理由见 rejectReason。驳回后可以再次申请作废。

要点:

  • 接口从不回「作废成功」。 最好的即时结果是 PENDING_REVIEW(承运商已取消、等审批)。退款只在审批通过后发生。
  • 承运商拒绝取消(CARRIER_CANCEL_REJECTED,常见原因是包裹已被揽收):订单不变、没有退款、cancel.carrierMessage 为 null;如需处理请带 requestId 联系我们。
  • 承运商查不到这张面单(CARRIER_ORDER_NOT_FOUND)或回复无法确认是否已取消(CARRIER_CANCEL_UNCONFIRMED):需要我方人工核对,不要重复提交,请带 requestId 联系我们。
  • 作废中 / 已作废的订单不再提供面单;作废前已发出的面单链接最多还能用到它的 1 小时有效期结束。
  • 作废过的客户单号不能复用;要重新发货请换新单号。

9. 测试钥匙(沙箱)

#

9.1 和正式钥匙有什么不同

#
项测试钥匙(zsk_test_…)
地址、接口、字段、错误码与正式钥匙完全相同
承运商从不联系任何承运商
钱从不扣钱、从不退钱(余额不变);查余额接口返回你账号真实的余额,只读(见 5.6)
报价返回你账号真实可用的服务列表,但价格是测试价:5.00 + 1.00 × 总重量(磅)(总重量 = 各包裹重量 × 件数之和,公制按千克换算成磅;一单多个包裹时每个包裹各按自己的重量算一次,再相加),向上取整到分,所有服务同价。测试价不代表真实价格;要看真实价格请用正式钥匙报价——报价不花钱
一单多个包裹与正式钥匙相同:拆成多张测试单,每个包裹按它自己的重量算测试价;按客户单号查、取面单、作废都作用于全部包裹
单号测试单号 SBX-YYYYMMDD-NNNNNN;测试跟踪号 TEST + 16 位数字
面单一张样例 PDF,大字 SAMPLE - NOT VALID FOR SHIPPING,印有单号;url / base64 / merged 三种格式都支持
状态推进按时间自动推进:受理后约 5 秒内为 PROCESSING,之后 CREATED(≤ 20 条时接口会等过这 5 秒再回复);作废后约 60 秒内为 PENDING_REVIEW,之后自动 APPROVED(订单 CANCELLED,refundAmount 为测试价)
物流状态恒为 PRE_SHIPMENT
客户单号规则与正式完全相同(第 3 节),但与正式钥匙下的单号互不相干
可见范围测试单不会出现在 OminiShip 后台的订单列表、账单、流水里
保留时间测试单 30 天后自动清除
按时间列订单只列测试单(不含正式单),按测试单的受理时间筛选与排序;cursor 在测试钥匙与正式钥匙之间不通用
模拟的承运商原话以 SANDBOX: 开头,例如 SANDBOX: simulated carrier response.

9.2 触发异常场景的魔法值

#
想测的场景怎么触发结果
承运商拒单生成订单时 shipTo.name 填 SANDBOX_REJECT订单 FAILED / CARRIER_REJECTED
余额不足客户单号以 -NOFUNDS 结尾(如 T-1-NOFUNDS)订单 FAILED / INSUFFICIENT_BALANCE
报价高于上限maxCharge 填一个低于测试价的数订单 FAILED / PRICE_ABOVE_MAX(statusReason.quotedCharge 为测试价)
面单延迟客户单号以 -SLOWLABEL 结尾出单后约 60 秒内面单 LABEL_NOT_READY
作废被驳回作废时 reason 填 SANDBOX_REJECT先 PENDING_REVIEW,约 60 秒后 REJECTED(订单回到 CREATED,可再申请)
承运商拒绝取消作废时 reason 填 SANDBOX_CARRIER_REJECTcancel.status = FAILED / CARRIER_CANCEL_REJECTED,订单仍 CREATED

魔法值区分大小写,必须完全一致(首尾空格会先被去掉再比较)。测试钥匙下这类模拟原话会以 SANDBOX: 开头(正式环境里承运商普通拒绝取消时 carrierMessage 为 null)。


10. 错误码表

#

「可否重试」= 原样重发同一个请求(同样的客户单号)有没有可能成功。

10.1 请求级(整次回复的 code)

#
codeHTTP含义与下一步可否重试
OK200请求已处理;批量接口请逐条看 results[i].success否(成功)
INVALID_API_KEY401缺少钥匙、钥匙不存在或格式不对。检查 Authorization: Bearer <钥匙>否
API_KEY_REVOKED401钥匙已吊销或已过期,在后台「设置 → API 钥匙」生成新钥匙否
API_KEY_LOOKUP_UNAVAILABLE503我方暂时无法验证钥匙(不是钥匙的问题),稍后原样重试,不要换钥匙是
IMPERSONATION_UNSUPPORTED400请求带了 X-Impersonate-Session 请求头,去掉后重发否
RATE_LIMITED429本分钟请求次数超限,等 data.retryAfter 秒是
QUOTA_EXCEEDED429今日(UTC)请求次数用完,等 data.retryAfter 秒(UTC 零点重置)是
ACCOUNT_NOT_ENABLED403钥匙绑定的账号没有开通此功能,联系我们否
ACCOUNT_DEACTIVATED403钥匙绑定的客户账号已被停用(正式、测试钥匙都一样)。换新钥匙没用;联系我们重新启用账号后,原钥匙继续可用否
INVALID_REQUEST400请求体格式不对(不是 JSON 对象、缺 unitSystem、数组为空等),按 data.errors 修正否
BATCH_TOO_LARGE400条数或包裹 / 订单数超上限(data.maxItems、data.maxPackages,本次计数为 data.packages;报价另有 data.maxCombinations),请拆批否
INVALID_CURSOR400按时间列订单的 cursor 对这次请求无效(不是这个账号、这种钥匙、这组 createdFrom / createdTo / status 发出的,或已损坏)。原样传回上一页的 nextCursor;想从头开始就不传 cursor否
NOT_FOUND404路径不存在,检查方法(POST)与路径否
SERVICE_UNAVAILABLE503我方暂时故障(也可能是 HTTP 500)。原样重发是安全的;持续出现请带 requestId 联系我们是

10.2 逐条(results[i].code,以及 statusReason.code、cancel.code、unavailable[i].code)

#
code出现在含义与下一步可否重试
OK全部成功 / 已受理否(成功)
INVALID_IDENTIFIERinfo / labels / cancel单号三选一没填对(0 个、多个或格式不对)否
ORDER_NOT_FOUNDinfo / labels / cancel查无此单(含不属于你的单)否
AMBIGUOUS_TRACKING_NUMBERinfo / labels / cancel跟踪号对应你的多张单,改用客户单号或我方单号(候选见该条 orderNos)否
DUPLICATE_IN_BATCHcreate / info / labels / cancel与同一请求中前面的某条重复,已跳过否
INVALID_ORDERcreate订单字段不合法(见 errors);也是失败原因之一(见 5.2);一单多个包裹时填 maxCharge 或包裹超过 50 个也是它否
INVALID_SHIPMENTrates报价条目字段不合法(见 errors)否
SERVICE_NOT_AVAILABLErates / create服务代码不属于你、已停用,或暂不可用;先调报价接口确认否
SERVICE_CODE_GROUP_NOT_FOUNDrates / create你的账号下没有这个名字的代码组。组名区分大小写,需完全一致(购买前代码组被删除也是这个码)否
SERVICE_CODE_GROUP_EMPTYrates / create这个代码组里没有可用的服务。请联系我们,或改用 serviceCode否
RECEIVER_PHONE_INVALIDrates / create美国收件地址的 shipTo.phone 不是恰好 10 位数字(不能带 +1、分机、空格、横杠、括号),见 errors;没报价、没建单、没扣钱,改好后重发(生成订单可继续用同一个客户单号;这个客户单号下已经有单——之前 confirm: false 建的草稿或失败的单——时,那张单的电话改不了,请换新单号)否
NO_RATErates / create承运商没有给这个包裹报价(原话见 carrierMessage)否
CARRIER_RATE_ERRORrates / create承运商报价服务出错是
RATE_TIMEOUTrates本次没来得及报完这个服务是
PRICE_ABOVE_MAXcreate报价高于 maxCharge,没买没扣钱(报价见 statusReason.quotedCharge)否
INSUFFICIENT_BALANCEcreate可用余额不足(余额 − 在途订单预留 − 被冻结的金额),没买没扣钱;充值或联系我们解冻后同号原样重发是
CARRIER_REJECTEDcreate承运商拒单(见 carrierCode / carrierMessage),没扣钱;改内容后换新单号否
SUBMIT_PAUSEDcreate我方暂停出单(维护),没扣钱是
PRICE_CHANGEDcreate购买前复核价格变贵,没买没扣钱;同号原样重发按当前价格再试是
SUBMIT_FAILEDcreate我方原因没能购买,确定没扣钱;同号原样重发是
CUSTOMER_ORDER_NO_CONFLICTcreate该客户单号已有一张内容不同的单(或一张已不能出单的旧多包裹单),换新单号否
CUSTOMER_ORDER_NO_USEDcreate该客户单号对应的单已在后台删除,换新单号否
ACCEPT_TIMEOUTcreate本次没来得及受理,原样重发安全是
LABEL_NOT_READYlabels面单还没出(部分渠道延迟,或订单仍在处理中)是
LABEL_PREPARINGlabels我方正在准备文件是
LABEL_BLOCKED_CANCELLEDlabels作废中 / 已作废,不再提供面单否
LABEL_UNAVAILABLElabels承运商面单文件暂时取不到是
LABEL_FORMAT_UNSUPPORTEDlabels(merged)该面单格式不能合并(如 ZPL),用 url 方式单独取否
RESPONSE_TOO_LARGElabels(base64)本次回复已满约 5 MB,剩余面单另发一次请求取是
ORDER_NOT_SHIPPEDcancel / labels / cancel.code订单没出单、没扣钱(草稿或失败),无需作废,也没有面单否
ORDER_PROCESSINGcancel / statusReason.code / cancel.code订单还在处理中,稍后再试是
CANCEL_ALREADY_REQUESTEDcancel已在审批中(成功条目,尚未退款)否(成功)
ALREADY_CANCELLEDcancel已作废已退款(成功条目)否(成功)
CARRIER_CANCEL_REJECTEDcancel / cancel.code承运商拒绝取消(常见:已揽收),订单不变、没退款;carrierMessage 为 null否
CARRIER_ORDER_NOT_FOUNDcancel / cancel.code承运商查不到这张面单,需我方人工核对;不要重复提交,带 requestId 联系我们否
CARRIER_CANCEL_UNCONFIRMEDcancel / cancel.code承运商回复无法确认是否已取消,需我方人工核对;不要重复提交,带 requestId 联系我们否
CANCEL_TEMPORARILY_UNAVAILABLEcancel / cancel.code本次没能把作废发出去,什么都没变(我方配置问题时文案会写明请联系我们)是

11. 常见问题

#

Q:生成订单回复里是 PROCESSING,我是不是应该重发?
不用。PROCESSING 是「已受理、正在出单」,用订单信息接口隔几秒查一次即可。如果一定要重发,用同一个客户单号原样重发——只会拿回同一张单。千万不要换新单号,那会再买一张面单。

Q:请求超时 / 网络断了,不知道下单成没成功,怎么办?
用完全相同的请求体(同样的客户单号)原样重发。已经建好的单会原样返回,已经出单的不会再扣钱。

Q:FAILED 的单会不会其实已经扣钱了?
不会。只有我方能确认「没出面单、没扣钱」时才会给 FAILED;不确定的一律显示 PROCESSING,并由我方自动核对。

Q:想修改一张已经提交的单怎么办?
已出单的单不能通过接口修改。需要的话先作废(经审批退款),再用新的客户单号重新下单。草稿可以在 OminiShip 后台修改。

Q:作废后多久退款?
作废需要我方审批,审批通过才退款。用订单信息接口看 cancel.status:PENDING_REVIEW 表示在等审批,APPROVED 表示已退款。

Q:为什么 labelReady 是 true,但 labelUrl 是 null?
订单信息接口只在面单文件已经准备好时才给链接。直接调面单接口即可拿到链接。

Q:面单链接过期了怎么办?
重新调面单接口,会给一个新的 1 小时有效链接。

Q:同一个客户单号,测试钥匙和正式钥匙都能用吗?
能,两边互不相干。测试单不会占用正式环境的单号。

Q:测试钥匙的报价为什么和正式的不一样?
测试价是固定公式算出来的(第 9 节),只用于联调。真实价格请用正式钥匙报价——报价不花钱。

Q:钥匙丢了或泄露了怎么办?
在后台「设置 → API 钥匙」吊销它,再生成一把新的(见 2.8 节)。我们也看不到你的完整钥匙,没法帮你找回。

Q:怎么核对昨天的全部订单?
用按时间列订单接口(见 5.7):createdFrom 填昨天零点、createdTo 填今天零点(都带上你所在的时区),不填 status,按 nextCursor 一直翻到它为 null。得到的就是昨天建的全部订单(含在后台手工下的单),每张都带状态、扣费金额和跟踪号。

Q:下单前怎么知道钱够不够?
调查余额接口(见 5.6),看 available:它就是生成订单时检查的那个数。一张单需要的金额(报价 + 价格变动预留)不超过它就能出单,一次下多张单时要够它们的总和。余额随时会变,最终以生成订单接口的回复为准。

Q:遇到 5xx 或看不懂的错误怎么办?
先按「可否重试」处理;持续出现请把回复里的 requestId 发给我们。


12. 变更记录

#
日期版本变更
2026-10-19v1v1 首版;此前的测试版接口已下线
2026-10-20v1钥匙改为在 OminiShip 后台「设置 → API 钥匙」自助生成、查看、吊销(不再通过邮件申请),新增 2.8 节;接口与回复格式不变
2026-10-27v1新增英文版对接文档与英文版规格,内容与中文版一致;接口与回复格式不变
2026-10-31v1报价与生成订单新增 serviceCodeGroup:按代码组名称报价 / 下单,用组内最便宜的服务(见 5.1);代码组报价只回一个价,不说明是哪个服务;新增错误码 SERVICE_CODE_GROUP_NOT_FOUND、SERVICE_CODE_GROUP_EMPTY;代码组订单购买失败时 carrierCode 与 carrierMessage 为 null;只用 serviceCode 的请求与回复不变
2026-11-04v1一个包裹一个跟踪号:一单多个包裹(quantity 计入)在生成订单时拆成多张订单,每张 1 个包裹,客户单号作为组号(见 5.2);报价按包裹逐个报价,多个包裹时 rates[] 每个价带 packageRates;订单信息、面单、作废按客户单号作用于全组;拆出的订单视图带 packageIndex / packageCount;一单多个包裹时余额必须够全部包裹才会下单(不够整条 INSUFFICIENT_BALANCE、什么都不建);一单多个包裹时暂不能用 maxCharge;一票最多 50 个包裹;只有一个包裹的请求与回复不变
2026-11-14v1上限改按包裹(= 订单)计:生成订单一次合计最多 500 个包裹(quantity 计入);订单信息 100、面单 500 / 20 / 100、作废 500 按单号对应的订单数计,按客户单号指向一组拆单时组里每张订单都计入;超过整次 400 BATCH_TOO_LARGE,什么都不做,data 新增 maxPackages、packages;条数上限不变,不超上限的请求与回复不变
2026-11-16v1新增两个只读接口:查余额 POST /v1/balance(余额、订单预留、冻结金额、可用金额、信用额度,见 5.6)与按时间列订单 POST /v1/orders/list(按建单时间从早到晚分页列出全部订单,用于对账与增量同步,见 5.7);新增错误码 INVALID_CURSOR;其它接口的请求与回复不变
2026-11-18v1美国收件地址(shipTo.country 为空 / US / USA)的 shipTo.phone 填了但不是恰好 10 位数字(不能带 +1、分机、空格、横杠、括号)时,报价与出单一律拒绝,新增错误码 RECEIVER_PHONE_INVALID(errors[] 指向 shipTo.phone,什么都没报价、没建单、没扣钱,见 5.1);只建草稿(confirm: false)与同号重发拿回已有的单不受影响;发件地址与非美国收件地址不检查;其它请求与回复不变