{
  "openapi": "3.0.3",
  "info": {
    "title": "OminiShip Open API",
    "version": "1.0.0",
    "description": "OminiShip 开放接口 v1。完整说明（含快速开始、客户单号规则、作废审批、测试钥匙与错误码表）见同目录 OPEN_API_GUIDE.md。\n\n- 一把钥匙绑定一个客户；请求里不传客户 id。\n- 7 个接口全部 POST + application/json。\n- 所有经过我方服务的回复都是信封 { success, code, message, data, requestId }；网关自身返回的 404 / 429 / 504 例外。\n- 金额是两位小数的字符串，币种 USD。\n- 测试钥匙（zsk_test_…）的请求不碰承运商、不扣钱。\n- 钥匙在 OminiShip 后台「设置 → API 钥匙」自助生成与吊销（每种最多 2 把有效钥匙，完整钥匙只显示一次）。",
    "x-changelog": [
      {
        "date": "2026-10-19",
        "version": "1.0.0",
        "changes": "v1 首版。"
      },
      {
        "date": "2026-10-20",
        "version": "1.0.0",
        "changes": "钥匙改为在 OminiShip 后台「设置 → API 钥匙」自助生成、查看、吊销（不再通过邮件申请）；API_KEY_REVOKED 的处理建议随之更新。接口与回复格式不变。"
      },
      {
        "date": "2026-10-27",
        "version": "1.0.0",
        "changes": "新增英文版规格（描述文字为英文，结构与本规格完全一致）。接口与回复格式不变。"
      },
      {
        "date": "2026-10-31",
        "version": "1.0.0",
        "changes": "报价（shipments[].serviceCodeGroup）与生成订单（orders[].serviceCodeGroup）可按代码组名称报价 / 下单，用组内最便宜的服务；代码组报价只回一个价，serviceCode / carrier / service 为 null，不说明是哪个服务。CreateOrderItem 的 serviceCode 改为与 serviceCodeGroup 二选一。新增错误码 SERVICE_CODE_GROUP_NOT_FOUND、SERVICE_CODE_GROUP_EMPTY。只用 serviceCode 的请求与回复不变。"
      },
      {
        "date": "2026-11-04",
        "version": "1.0.0",
        "changes": "一个包裹一个跟踪号：一单多个包裹（quantity 计入）在生成订单时拆成多张独立订单，每张 1 个包裹，客户单号作为组号；新增 PackageGroupResult（create / info / labels / cancel 按客户单号作用于全组时的一条结果）、Rate.packageRates（逐个包裹报价）、拆出订单的 packageIndex / packageCount；一单多个包裹时余额必须够全部包裹才会下单（不够整条 INSUFFICIENT_BALANCE，带 required / shortfall，什么都不建）；一单多个包裹时暂不能用 maxCharge；一票最多 50 个包裹，200 组合上限按不同规格的包裹数计。只有一个包裹的请求与回复不变。"
      },
      {
        "date": "2026-11-14",
        "version": "1.0.0",
        "changes": "上限改按包裹（= 订单）计：生成订单一次合计最多 500 个包裹（quantity 计入；校验不通过的条目不计；超过 50 个包裹的条目按 50 计，它本身仍被拒）；订单信息 100、面单 500 / 20 / 100（按 format）、作废 500 按单号对应的订单数计，按客户单号指向一组拆单时组里每张订单都计入。超过整次 400 BATCH_TOO_LARGE，什么都不做（不建单、不扣钱、不取面单、不提交作废）；ErrorData 新增 maxPackages（包裹 / 订单上限）与 packages（本次计数；只是条数超上限时为 null）。条数上限不变，不超上限的请求与回复不变。"
      },
      {
        "date": "2026-11-16",
        "version": "1.0.0",
        "changes": "新增两个只读接口：POST /v1/balance（余额、订单预留、冻结金额、可用金额、信用额度；available 与生成订单检查余额用的是同一个数）与 POST /v1/orders/list（按建单时间从早到晚分页列出钥匙绑定客户的全部订单，用于对账与增量同步；带 nextCursor 翻页）。新增错误码 INVALID_CURSOR。其它接口的请求与回复不变。"
      },
      {
        "date": "2026-11-18",
        "version": "1.0.0",
        "changes": "美国收件地址（shipTo.country 为空 / US / USA）的 shipTo.phone 填了但不是恰好 10 位数字（不能带 +1、分机、空格、横杠、括号）时，报价与出单一律拒绝：新增错误码 RECEIVER_PHONE_INVALID（errors[] 指向 shipTo.phone；什么都没报价、没建单、没扣钱）。只建草稿（confirm: false）与同号重发拿回已有的单不受影响；发件地址、非美国收件地址不检查。其它请求与回复不变。"
      }
    ]
  },
  "servers": [
    {
      "url": "https://openapi.ominiship.com",
      "description": "正式环境（测试钥匙与正式钥匙用同一个地址）"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "rates",
      "description": "报价"
    },
    {
      "name": "orders",
      "description": "订单"
    },
    {
      "name": "account",
      "description": "账户"
    }
  ],
  "paths": {
    "/v1/rates": {
      "post": {
        "operationId": "getRates",
        "tags": [
          "rates"
        ],
        "summary": "批量报价",
        "description": "每次 1..100 条；不填 serviceCode = 报你能用的全部服务；也可以填 serviceCodeGroup（代码组名称），只回组内最便宜的一个价；「条目 × 服务」组合 ≤ 200（超了整次 400 BATCH_TOO_LARGE，不会问承运商）。纯同步，约 20 秒内回复，没报完的服务进 unavailable（RATE_TIMEOUT，可重试）。报价不花钱。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RatesRequest"
              },
              "examples": {
                "twoShipments": {
                  "summary": "一条报全部服务、一条指定服务（邮编写错）",
                  "value": {
                    "unitSystem": "imperial",
                    "shipments": [
                      {
                        "ref": "quote-1",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "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",
                          "country": "US",
                          "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",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "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": "1011",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4,
                            "quantity": 1
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已处理。逐条看 data.results[i].success。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "一条成功、一条字段不合法",
                    "value": {
                      "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"
                    }
                  },
                  "noRate": {
                    "summary": "承运商没给价",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 0,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "success": false,
                            "code": "NO_RATE",
                            "message": "The carrier returned no rate for this package. See carrierMessage for the carrier's own words.",
                            "retryable": false,
                            "ref": "quote-1",
                            "rates": [],
                            "unavailable": [
                              {
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "code": "NO_RATE",
                                "message": "The carrier returned no rate for this package. See carrierMessage for the carrier's own words.",
                                "retryable": false,
                                "carrierMessage": "Package weight exceeds the maximum for this service."
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/create": {
      "post": {
        "operationId": "createOrders",
        "tags": [
          "orders"
        ],
        "summary": "批量生成订单",
        "description": "每次 1..500 条。confirm = true（默认）建单 + 扣钱 + 出面单；false 只建草稿。先受理再后台出单：通过校验的条数 ≤ 20 时最多等 15 秒把已出结果带回，其余为 PROCESSING（success 为 true，用 /v1/orders/info 轮询）。客户单号幂等：同号重发只会拿回那张单，不会多扣钱。每条填 serviceCode 或 serviceCodeGroup，二选一。所有条目的包裹合计（quantity 计入）≤ 500，超了整次 400 BATCH_TOO_LARGE（data.maxPackages / data.packages），什么都不建、不扣钱。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrdersRequest"
              },
              "examples": {
                "threeOrders": {
                  "summary": "两条正常、一条缺城市",
                  "value": {
                    "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",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "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",
                          "country": "US",
                          "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",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "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",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 12,
                            "length": 16,
                            "width": 12,
                            "height": 10,
                            "quantity": 1
                          }
                        ]
                      },
                      {
                        "customerOrderNo": "WMS-10003",
                        "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                        "shipFrom": {
                          "name": "Warehouse A",
                          "company": "Acme Fulfillment",
                          "phone": "9095550100",
                          "email": "ops@example.com",
                          "address1": "1000 E Example Ave",
                          "address2": "Dock 3",
                          "city": "Ontario",
                          "state": "CA",
                          "postalCode": "91761",
                          "country": "US"
                        },
                        "shipTo": {
                          "name": "Jane Doe",
                          "phone": "2125550100",
                          "address1": "350 5th Ave",
                          "address2": "Apt 2",
                          "city": "",
                          "state": "NY",
                          "postalCode": "10118",
                          "country": "US",
                          "residential": true
                        },
                        "packages": [
                          {
                            "weight": 2.5,
                            "length": 10,
                            "width": 8,
                            "height": 4,
                            "quantity": 1
                          }
                        ]
                      }
                    ]
                  }
                },
                "splitOrder": {
                  "summary": "一单 3 个包裹（拆成 3 张订单）",
                  "value": {
                    "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
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已处理。逐条看 data.results[i].success。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrdersResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "已出单 / 处理中 / 字段不合法",
                    "value": {
                      "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,
                            "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
                          },
                          {
                            "index": 2,
                            "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[2].shipTo.city",
                                "code": "REQUIRED",
                                "message": "This field is required."
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  },
                  "failed": {
                    "summary": "余额不足（没买、没扣钱）",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Processed 1 item(s).",
                      "data": {
                        "summary": {
                          "total": 1,
                          "succeeded": 0,
                          "failed": 1
                        },
                        "results": [
                          {
                            "index": 0,
                            "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"
                    }
                  },
                  "split": {
                    "summary": "3 个包裹都已出单：一条结果，orders[] 里 3 张订单",
                    "value": {
                      "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",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556601",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 2,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "replayed": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000202",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556602",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 3,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "replayed": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000203",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "6.92",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556603",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/info": {
      "post": {
        "operationId": "getOrdersInfo",
        "tags": [
          "orders"
        ],
        "summary": "批量订单信息",
        "description": "每次 1..100 条，每条三选一：customerOrderNo / orderNo / trackingNumber。只能查到钥匙绑定客户自己的单（含该客户在后台手工下的单）；别人的单与不存在的单回复完全相同（ORDER_NOT_FOUND）。不实时查询承运商。按客户单号指向一组拆单时，组里每张订单都计入：合计 ≤ 100 张订单，超了整次 400 BATCH_TOO_LARGE，什么都不读。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrdersInfoRequest"
              },
              "examples": {
                "threeRefs": {
                  "summary": "三种单号各一条",
                  "value": {
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001"
                      },
                      {
                        "orderNo": "ORD-20261019-000124"
                      },
                      {
                        "trackingNumber": "1Z999AA10123456784"
                      }
                    ]
                  }
                },
                "splitGroup": {
                  "summary": "按客户单号查一单多个包裹的订单",
                  "value": {
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10005"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已处理。逐条看 data.results[i].success。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrdersInfoResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "两条找到、一条查无此单",
                    "value": {
                      "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",
                            "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,
                            "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
                          },
                          {
                            "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"
                    }
                  },
                  "ambiguous": {
                    "summary": "跟踪号对应多张单",
                    "value": {
                      "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"
                    }
                  },
                  "split": {
                    "summary": "一条结果，orders[] 里每个包裹一张订单",
                    "value": {
                      "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,
                            "customerOrderNo": "WMS-10005",
                            "packageCount": 3,
                            "orders": [
                              {
                                "packageIndex": 1,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000201",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556601",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 2,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000202",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "14.20",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556602",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              },
                              {
                                "packageIndex": 3,
                                "success": true,
                                "code": "OK",
                                "message": "",
                                "retryable": false,
                                "customerOrderNo": "WMS-10005",
                                "orderNo": "ORD-20261104-000203",
                                "status": "CREATED",
                                "statusReason": null,
                                "serviceCode": "b4f1c2de-7a39-4c51-9d0e-3f2a1b6c8d90",
                                "carrier": "usps",
                                "service": "usps_ground_advantage",
                                "totalCharge": "6.92",
                                "currency": "USD",
                                "trackingNumber": "9400111899223344556603",
                                "labelReady": true,
                                "labelStatus": "READY",
                                "labelUrl": null,
                                "labelUrlExpiresAt": null,
                                "trackingStatus": "PRE_SHIPMENT",
                                "trackingUpdatedAt": null,
                                "cancel": null,
                                "createdAt": "2026-11-04T08:00:00Z",
                                "submittedAt": "2026-11-04T08:00:04Z",
                                "packageCount": 3
                              }
                            ]
                          }
                        ]
                      },
                      "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/labels": {
      "post": {
        "operationId": "getLabels",
        "tags": [
          "orders"
        ],
        "summary": "批量面单",
        "description": "format：url（默认，上限 500，每单一个 1 小时有效的我方链接）/ base64（上限 20，单次回复面单内容累计约 5 MB 封顶）/ merged（上限 100，合成一个 PDF）。作废中 / 已作废的单不再提供面单。按客户单号指向一组拆单时，组里每张订单都计入，订单数上限与条数上限相同（url 500 · base64 20 · merged 100），超了整次 400 BATCH_TOO_LARGE，不取任何面单。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LabelsRequest"
              },
              "examples": {
                "url": {
                  "summary": "取链接",
                  "value": {
                    "format": "url",
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001"
                      },
                      {
                        "customerOrderNo": "WMS-10009"
                      }
                    ]
                  }
                },
                "merged": {
                  "summary": "合并成一个 PDF",
                  "value": {
                    "format": "merged",
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001"
                      },
                      {
                        "orderNo": "ORD-20261019-000140"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已处理。逐条看 data.results[i].success。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LabelsResponse"
                },
                "examples": {
                  "url": {
                    "summary": "一张可取、一张已作废",
                    "value": {
                      "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"
                    }
                  },
                  "merged": {
                    "summary": "合并：一张合进、一张格式不支持",
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/cancel": {
      "post": {
        "operationId": "cancelOrders",
        "tags": [
          "orders"
        ],
        "summary": "批量作废（两段式审批）",
        "description": "每次 1..500 条。提交的是「作废申请」：我方向承运商取消后进入审批，审批通过才退款。接口从不说「作废成功」：最好的即时结果是 cancel.status = PENDING_REVIEW。条数 ≤ 20 时最多等 15 秒把承运商结果带回。按客户单号指向一组拆单时，组里每张订单都计入：合计 ≤ 500 张订单，超了整次 400 BATCH_TOO_LARGE，不提交任何作废申请。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CancelRequest"
              },
              "examples": {
                "two": {
                  "summary": "两条",
                  "value": {
                    "orders": [
                      {
                        "customerOrderNo": "WMS-10001",
                        "reason": "Customer changed mind"
                      },
                      {
                        "customerOrderNo": "WMS-10002"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "已处理。逐条看 data.results[i].success。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                },
                "examples": {
                  "mixed": {
                    "summary": "一条进入审批、一条还在出单中",
                    "value": {
                      "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"
                    }
                  },
                  "carrierRejected": {
                    "summary": "承运商拒绝取消",
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/balance": {
      "post": {
        "operationId": "getBalance",
        "tags": [
          "account"
        ],
        "summary": "查余额",
        "description": "只读。返回钥匙绑定客户的余额、订单预留、冻结金额、可用金额与信用额度。available 就是生成订单检查余额用的那个数。读取的是最新数据。测试钥匙返回真实余额（只读；测试单从不改变它）。读取故障时 503，不会说成余额为零。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BalanceRequest"
              },
              "examples": {
                "empty": {
                  "summary": "空对象",
                  "value": {}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "余额。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BalanceResponse"
                },
                "examples": {
                  "noCredit": {
                    "summary": "没有信用额度",
                    "value": {
                      "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"
                    }
                  },
                  "creditInUse": {
                    "summary": "正在使用信用额度",
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    },
    "/v1/orders/list": {
      "post": {
        "operationId": "listOrders",
        "tags": [
          "orders"
        ],
        "summary": "按时间列订单",
        "description": "按建单时间（createdFrom ≤ createdAt < createdTo，整秒）从早到晚分页列出钥匙绑定客户自己的全部订单（含后台手工下的、批量上传的、店铺对接生成的、本接口生成的；已删除的不列）。每项是订单视图全部字段，与订单信息接口相同。时间范围 ≤ 31 天，每页 1–100（默认 50）。带 status 筛选时每次请求最多查看 500 张订单，一页可能少于 limit 甚至为空——只要 nextCursor 不是 null 就继续翻。cursor 只对同一个客户账号、同一种钥匙、同样的 createdFrom / createdTo / status 有效，否则 400 INVALID_CURSOR。测试钥匙只列测试单。读取故障时 503，不会回空列表。",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListOrdersRequest"
              },
              "examples": {
                "firstPage": {
                  "summary": "第一页",
                  "value": {
                    "createdFrom": "2026-11-15T00:00:00Z",
                    "createdTo": "2026-11-16T00:00:00Z",
                    "status": [
                      "CREATED",
                      "CANCELLED"
                    ],
                    "limit": 2
                  }
                },
                "nextPage": {
                  "summary": "下一页（同样的查询 + cursor）",
                  "value": {
                    "createdFrom": "2026-11-15T00:00:00Z",
                    "createdTo": "2026-11-16T00:00:00Z",
                    "status": [
                      "CREATED",
                      "CANCELLED"
                    ],
                    "limit": 2,
                    "cursor": "eyJ2IjoxLCJiIjoiN2ZrUTJ4"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "一页订单。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListOrdersResponse"
                },
                "examples": {
                  "page": {
                    "summary": "两张订单，还有下一页",
                    "value": {
                      "success": true,
                      "code": "OK",
                      "message": "Listed 2 order(s).",
                      "data": {
                        "orders": [
                          {
                            "customerOrderNo": "WMS-10001",
                            "orderNo": "ORD-20261115-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": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": "PRE_SHIPMENT",
                            "trackingUpdatedAt": null,
                            "cancel": null,
                            "createdAt": "2026-11-15T08:00:00Z",
                            "submittedAt": "2026-11-15T08:00:04Z"
                          },
                          {
                            "customerOrderNo": null,
                            "orderNo": "ORD-20261115-000188",
                            "status": "CANCELLED",
                            "statusReason": null,
                            "serviceCode": null,
                            "carrier": "usps",
                            "service": "usps_ground_advantage",
                            "totalCharge": "8.15",
                            "currency": "USD",
                            "trackingNumber": "9400111899223344556688",
                            "labelReady": false,
                            "labelStatus": "BLOCKED_CANCELLED",
                            "labelUrl": null,
                            "labelUrlExpiresAt": null,
                            "trackingStatus": "PRE_SHIPMENT",
                            "trackingUpdatedAt": null,
                            "cancel": {
                              "status": "APPROVED",
                              "code": null,
                              "message": "",
                              "carrierMessage": null,
                              "requestedAt": "2026-11-15T10:00:00Z",
                              "reviewedAt": "2026-11-15T12:00:00Z",
                              "refundAmount": "8.15",
                              "currency": "USD",
                              "rejectReason": null
                            },
                            "createdAt": "2026-11-15T09:30:12Z",
                            "submittedAt": "2026-11-15T09:30:04Z"
                          }
                        ],
                        "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"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "zsk_live_<64 位十六进制> / zsk_test_<64 位十六进制>",
        "description": "Authorization: Bearer <钥匙>。正式钥匙 zsk_live_…，测试钥匙 zsk_test_…。"
      }
    },
    "responses": {
      "BadRequest": {
        "description": "请求格式不对（INVALID_REQUEST / BATCH_TOO_LARGE / INVALID_CURSOR / IMPERSONATION_UNSUPPORTED）。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "invalidRequest": {
                "value": {
                  "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"
                }
              },
              "batchTooLarge": {
                "value": {
                  "success": false,
                  "code": "BATCH_TOO_LARGE",
                  "message": "At most 100 items per request.",
                  "data": {
                    "maxItems": 100
                  },
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              },
              "invalidCursor": {
                "value": {
                  "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"
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "钥匙无效（INVALID_API_KEY / API_KEY_REVOKED）。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "invalidKey": {
                "value": {
                  "success": false,
                  "code": "INVALID_API_KEY",
                  "message": "A valid API key is required. Send it as \"Authorization: Bearer <key>\".",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "账号未开通（ACCOUNT_NOT_ENABLED），或钥匙绑定的客户账号已停用（ACCOUNT_DEACTIVATED）。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "notEnabled": {
                "value": {
                  "success": false,
                  "code": "ACCOUNT_NOT_ENABLED",
                  "message": "The account bound to this API key is not enabled for this operation. Please contact us.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              },
              "deactivated": {
                "value": {
                  "success": false,
                  "code": "ACCOUNT_DEACTIVATED",
                  "message": "The customer account bound to this API key has been deactivated. A new key will not help; please contact us to reactivate the account.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "限流（RATE_LIMITED / QUOTA_EXCEEDED）。注意：平台整体的每秒保护性限流由网关直接返回 429，回复不是信封格式。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "rateLimited": {
                "value": {
                  "success": false,
                  "code": "RATE_LIMITED",
                  "message": "Too many requests for this API key in the current minute. Retry after data.retryAfter seconds.",
                  "data": {
                    "retryAfter": 17
                  },
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "我方暂时故障（SERVICE_UNAVAILABLE / API_KEY_LOOKUP_UNAVAILABLE），可能是 500 或 503。原样重发是安全的。网关超时 504 不是信封格式。",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorEnvelope"
            },
            "examples": {
              "serviceUnavailable": {
                "value": {
                  "success": false,
                  "code": "SERVICE_UNAVAILABLE",
                  "message": "A temporary failure on our side. Resending the same request (same customerOrderNo) is safe; if it keeps happening, contact us with the requestId.",
                  "data": null,
                  "requestId": "c0a8012e-5b1f-4d2a-9e3b-7f6a1d2c3b4a"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "RequestCode": {
        "description": "请求级 code（整次回复的 code）。x-http-status 为对应 HTTP 状态码，x-retryable 表示原样重发是否可能成功。",
        "type": "string",
        "enum": [
          "OK",
          "INVALID_API_KEY",
          "API_KEY_REVOKED",
          "API_KEY_LOOKUP_UNAVAILABLE",
          "IMPERSONATION_UNSUPPORTED",
          "RATE_LIMITED",
          "QUOTA_EXCEEDED",
          "ACCOUNT_NOT_ENABLED",
          "ACCOUNT_DEACTIVATED",
          "INVALID_REQUEST",
          "BATCH_TOO_LARGE",
          "INVALID_CURSOR",
          "NOT_FOUND",
          "SERVICE_UNAVAILABLE"
        ],
        "x-retryable": {
          "OK": false,
          "INVALID_API_KEY": false,
          "API_KEY_REVOKED": false,
          "API_KEY_LOOKUP_UNAVAILABLE": true,
          "IMPERSONATION_UNSUPPORTED": false,
          "RATE_LIMITED": true,
          "QUOTA_EXCEEDED": true,
          "ACCOUNT_NOT_ENABLED": false,
          "ACCOUNT_DEACTIVATED": false,
          "INVALID_REQUEST": false,
          "BATCH_TOO_LARGE": false,
          "INVALID_CURSOR": false,
          "NOT_FOUND": false,
          "SERVICE_UNAVAILABLE": true
        },
        "x-http-status": {
          "OK": 200,
          "INVALID_API_KEY": 401,
          "API_KEY_REVOKED": 401,
          "API_KEY_LOOKUP_UNAVAILABLE": 503,
          "IMPERSONATION_UNSUPPORTED": 400,
          "RATE_LIMITED": 429,
          "QUOTA_EXCEEDED": 429,
          "ACCOUNT_NOT_ENABLED": 403,
          "ACCOUNT_DEACTIVATED": 403,
          "INVALID_REQUEST": 400,
          "BATCH_TOO_LARGE": 400,
          "INVALID_CURSOR": 400,
          "NOT_FOUND": 404,
          "SERVICE_UNAVAILABLE": 503
        },
        "x-enum-descriptions": {
          "OK": "请求已处理。批量接口请逐条看 results[i].success。",
          "INVALID_API_KEY": "缺少钥匙、钥匙不存在或格式不对。",
          "API_KEY_REVOKED": "钥匙已吊销或已过期，请在 OminiShip 后台「设置 → API 钥匙」生成新钥匙。",
          "API_KEY_LOOKUP_UNAVAILABLE": "我方暂时无法验证钥匙（不是钥匙的问题），稍后原样重试，不要换钥匙。",
          "IMPERSONATION_UNSUPPORTED": "请求带了不支持的身份切换请求头（X-Impersonate-Session），去掉后重发。",
          "RATE_LIMITED": "本分钟内请求次数超限，等 data.retryAfter 秒后重试。",
          "QUOTA_EXCEEDED": "今日（UTC）请求次数用完，等 data.retryAfter 秒（UTC 零点重置）后重试。",
          "ACCOUNT_NOT_ENABLED": "钥匙绑定的账号没有开通此功能，请联系我们。",
          "ACCOUNT_DEACTIVATED": "钥匙绑定的客户账号已被停用（正式、测试钥匙都一样）。换新钥匙没用；请联系我们重新启用账号，启用后原钥匙继续可用。",
          "INVALID_REQUEST": "请求体格式不对，按 data.errors 修正后重发。",
          "BATCH_TOO_LARGE": "一次请求的条数（data.maxItems）或包裹 / 订单数（data.maxPackages，本次计数为 data.packages）超过上限，请拆批。",
          "INVALID_CURSOR": "按时间列订单的 cursor 对这次请求无效（不是这个账号、这种钥匙、这组 createdFrom / createdTo / status 发出的，或已损坏）。原样传回上一页的 nextCursor；想从头开始就不传 cursor。",
          "NOT_FOUND": "接口路径不存在，请检查方法（POST）与路径。",
          "SERVICE_UNAVAILABLE": "我方暂时故障。用同样的请求（同样的客户单号）原样重发是安全的；持续出现请带 requestId 联系我们。"
        }
      },
      "ItemCode": {
        "description": "逐条 code（results[i].code、statusReason.code、cancel.code、unavailable[i].code）。x-retryable 表示原样重发是否可能成功；x-item-success 为该码对应的 results[i].success。",
        "type": "string",
        "enum": [
          "OK",
          "INVALID_IDENTIFIER",
          "ORDER_NOT_FOUND",
          "AMBIGUOUS_TRACKING_NUMBER",
          "DUPLICATE_IN_BATCH",
          "INVALID_ORDER",
          "INVALID_SHIPMENT",
          "SERVICE_NOT_AVAILABLE",
          "SERVICE_CODE_GROUP_NOT_FOUND",
          "SERVICE_CODE_GROUP_EMPTY",
          "RECEIVER_PHONE_INVALID",
          "NO_RATE",
          "CARRIER_RATE_ERROR",
          "RATE_TIMEOUT",
          "PRICE_ABOVE_MAX",
          "INSUFFICIENT_BALANCE",
          "CARRIER_REJECTED",
          "SUBMIT_PAUSED",
          "PRICE_CHANGED",
          "SUBMIT_FAILED",
          "CUSTOMER_ORDER_NO_CONFLICT",
          "CUSTOMER_ORDER_NO_USED",
          "ACCEPT_TIMEOUT",
          "LABEL_NOT_READY",
          "LABEL_PREPARING",
          "LABEL_BLOCKED_CANCELLED",
          "LABEL_UNAVAILABLE",
          "LABEL_FORMAT_UNSUPPORTED",
          "RESPONSE_TOO_LARGE",
          "ORDER_NOT_SHIPPED",
          "ORDER_PROCESSING",
          "CANCEL_ALREADY_REQUESTED",
          "ALREADY_CANCELLED",
          "CARRIER_CANCEL_REJECTED",
          "CARRIER_ORDER_NOT_FOUND",
          "CARRIER_CANCEL_UNCONFIRMED",
          "CANCEL_TEMPORARILY_UNAVAILABLE"
        ],
        "x-retryable": {
          "OK": false,
          "INVALID_IDENTIFIER": false,
          "ORDER_NOT_FOUND": false,
          "AMBIGUOUS_TRACKING_NUMBER": false,
          "DUPLICATE_IN_BATCH": false,
          "INVALID_ORDER": false,
          "INVALID_SHIPMENT": false,
          "SERVICE_NOT_AVAILABLE": false,
          "SERVICE_CODE_GROUP_NOT_FOUND": false,
          "SERVICE_CODE_GROUP_EMPTY": false,
          "RECEIVER_PHONE_INVALID": false,
          "NO_RATE": false,
          "CARRIER_RATE_ERROR": true,
          "RATE_TIMEOUT": true,
          "PRICE_ABOVE_MAX": false,
          "INSUFFICIENT_BALANCE": true,
          "CARRIER_REJECTED": false,
          "SUBMIT_PAUSED": true,
          "PRICE_CHANGED": true,
          "SUBMIT_FAILED": true,
          "CUSTOMER_ORDER_NO_CONFLICT": false,
          "CUSTOMER_ORDER_NO_USED": false,
          "ACCEPT_TIMEOUT": true,
          "LABEL_NOT_READY": true,
          "LABEL_PREPARING": true,
          "LABEL_BLOCKED_CANCELLED": false,
          "LABEL_UNAVAILABLE": true,
          "LABEL_FORMAT_UNSUPPORTED": false,
          "RESPONSE_TOO_LARGE": true,
          "ORDER_NOT_SHIPPED": false,
          "ORDER_PROCESSING": true,
          "CANCEL_ALREADY_REQUESTED": false,
          "ALREADY_CANCELLED": false,
          "CARRIER_CANCEL_REJECTED": false,
          "CARRIER_ORDER_NOT_FOUND": false,
          "CARRIER_CANCEL_UNCONFIRMED": false,
          "CANCEL_TEMPORARILY_UNAVAILABLE": true
        },
        "x-item-success": {
          "OK": true,
          "INVALID_IDENTIFIER": false,
          "ORDER_NOT_FOUND": false,
          "AMBIGUOUS_TRACKING_NUMBER": false,
          "DUPLICATE_IN_BATCH": false,
          "INVALID_ORDER": false,
          "INVALID_SHIPMENT": false,
          "SERVICE_NOT_AVAILABLE": false,
          "SERVICE_CODE_GROUP_NOT_FOUND": false,
          "SERVICE_CODE_GROUP_EMPTY": false,
          "RECEIVER_PHONE_INVALID": false,
          "NO_RATE": false,
          "CARRIER_RATE_ERROR": false,
          "RATE_TIMEOUT": false,
          "PRICE_ABOVE_MAX": false,
          "INSUFFICIENT_BALANCE": false,
          "CARRIER_REJECTED": false,
          "SUBMIT_PAUSED": false,
          "PRICE_CHANGED": false,
          "SUBMIT_FAILED": false,
          "CUSTOMER_ORDER_NO_CONFLICT": false,
          "CUSTOMER_ORDER_NO_USED": false,
          "ACCEPT_TIMEOUT": false,
          "LABEL_NOT_READY": false,
          "LABEL_PREPARING": false,
          "LABEL_BLOCKED_CANCELLED": false,
          "LABEL_UNAVAILABLE": false,
          "LABEL_FORMAT_UNSUPPORTED": false,
          "RESPONSE_TOO_LARGE": false,
          "ORDER_NOT_SHIPPED": false,
          "ORDER_PROCESSING": false,
          "CANCEL_ALREADY_REQUESTED": true,
          "ALREADY_CANCELLED": true,
          "CARRIER_CANCEL_REJECTED": false,
          "CARRIER_ORDER_NOT_FOUND": false,
          "CARRIER_CANCEL_UNCONFIRMED": false,
          "CANCEL_TEMPORARILY_UNAVAILABLE": false
        },
        "x-enum-descriptions": {
          "OK": "成功 / 已受理。",
          "INVALID_IDENTIFIER": "每条必须且只能填 customerOrderNo、orderNo、trackingNumber 中的一个，且格式正确。",
          "ORDER_NOT_FOUND": "查无此单（包括不属于你的单）。",
          "AMBIGUOUS_TRACKING_NUMBER": "这个跟踪号对应你的多张单，改用客户单号或我方单号（候选见该条的 orderNos）。",
          "DUPLICATE_IN_BATCH": "与同一请求中前面的某条重复，已跳过。",
          "INVALID_ORDER": "订单字段不合法，见该条 errors。",
          "INVALID_SHIPMENT": "报价条目字段不合法，见该条 errors。",
          "SERVICE_NOT_AVAILABLE": "该服务代码不属于你、已停用，或该服务暂不可用（我方原因时文案会写明请联系我们）。",
          "SERVICE_CODE_GROUP_NOT_FOUND": "你的账号下没有这个名字的代码组。组名区分大小写，需完全一致（购买前代码组被删除也是这个码）。",
          "SERVICE_CODE_GROUP_EMPTY": "这个代码组里没有可用的服务。请联系我们，或改用 serviceCode。",
          "RECEIVER_PHONE_INVALID": "美国收件地址（shipTo.country 为空 / US / USA）的 shipTo.phone 填了但不是恰好 10 位数字（不能带 +1、分机、空格、横杠、括号），见该条 errors。没报价、没建单、没扣钱；改好后重发（生成订单可继续用同一个客户单号；该单号下已有草稿或失败的单时请换新单号）。",
          "NO_RATE": "承运商没有给这个包裹报价（承运商原话见 carrierMessage）。",
          "CARRIER_RATE_ERROR": "承运商报价服务出错，稍后重试。",
          "RATE_TIMEOUT": "本次没来得及报完这个服务，重试即可。",
          "PRICE_ABOVE_MAX": "报价高于 maxCharge，没有购买、没有扣钱（当时报价见 statusReason.quotedCharge）。",
          "INSUFFICIENT_BALANCE": "余额不足，没有购买、没有扣钱；充值后同号原样重发即可。",
          "CARRIER_REJECTED": "承运商拒单（见 carrierCode / carrierMessage），没有扣钱；修改内容后用新客户单号重发。",
          "SUBMIT_PAUSED": "我方暂停出单（维护），没有扣钱，稍后重试。",
          "PRICE_CHANGED": "报价与购买之间价格变了（变贵），没有购买、没有扣钱；同号原样重发会按当前价格再试。",
          "SUBMIT_FAILED": "我方原因没能购买，且确定没有扣钱；同号原样重发是安全的，持续失败请带 requestId 联系我们。",
          "CUSTOMER_ORDER_NO_CONFLICT": "这个客户单号已对应一张内容不同的单，请换新客户单号。",
          "CUSTOMER_ORDER_NO_USED": "这个客户单号对应的单已在后台删除，客户单号不能复用，请换新号。",
          "ACCEPT_TIMEOUT": "本次没来得及受理这条，原样重发是安全的。",
          "LABEL_NOT_READY": "面单还没出（部分渠道稍后才出面单），稍后重试。",
          "LABEL_PREPARING": "我方正在准备面单文件，稍后重试。",
          "LABEL_BLOCKED_CANCELLED": "订单作废中或已作废，不再提供面单。",
          "LABEL_UNAVAILABLE": "承运商的面单文件暂时取不到，稍后重试。",
          "LABEL_FORMAT_UNSUPPORTED": "该面单格式不能合并进 PDF，请用 format \"url\" 单独取。",
          "RESPONSE_TOO_LARGE": "本次回复已装满，剩余面单请另发一次请求取。",
          "ORDER_NOT_SHIPPED": "订单没有出单、没有扣钱（草稿或购买失败），无需作废，也没有面单。",
          "ORDER_PROCESSING": "订单还在处理中，稍后再试。",
          "CANCEL_ALREADY_REQUESTED": "已提交过作废申请，正在等我方审批（成功条目，尚未退款）。",
          "ALREADY_CANCELLED": "已作废并已退款（成功条目）。",
          "CARRIER_CANCEL_REJECTED": "承运商拒绝取消（常见：已揽收），订单不变、没有退款。",
          "CARRIER_ORDER_NOT_FOUND": "承运商查不到这张面单，需要我方人工核对；不要重复提交，请带 requestId 联系我们。",
          "CARRIER_CANCEL_UNCONFIRMED": "承运商回复无法确认是否已取消，需要我方人工核对；不要重复提交，请带 requestId 联系我们。",
          "CANCEL_TEMPORARILY_UNAVAILABLE": "本次没能把作废请求发出去，什么都没变，稍后重试。"
        }
      },
      "FieldErrorCode": {
        "type": "string",
        "enum": [
          "REQUIRED",
          "INVALID_TYPE",
          "INVALID_VALUE",
          "TOO_LONG",
          "OUT_OF_RANGE"
        ],
        "description": "REQUIRED 缺失 · INVALID_TYPE 类型不对 · INVALID_VALUE 取值不对 · TOO_LONG 超长 · OUT_OF_RANGE 超出范围。"
      },
      "FieldError": {
        "type": "object",
        "required": [
          "field",
          "code",
          "message"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "完整 JSON 路径，如 orders[1].shipTo.postalCode。",
            "example": "orders[1].shipTo.postalCode"
          },
          "code": {
            "$ref": "#/components/schemas/FieldErrorCode"
          },
          "message": {
            "type": "string",
            "description": "我方英文说明，不回显你提交的值。"
          }
        }
      },
      "Envelope": {
        "type": "object",
        "description": "所有经过我方服务的回复都是这个形状（含 4xx / 5xx）。先读 success / code，再看 HTTP 状态码。",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "code": {
            "type": "string",
            "description": "成功时为 OK；失败时为 RequestCode 之一。"
          },
          "message": {
            "type": "string",
            "description": "英文说明，失败时含下一步。永远不是 \"Internal server error\"。"
          },
          "data": {
            "type": "object",
            "description": "接口数据；失败时可能带细节或为 null。",
            "nullable": true
          },
          "requestId": {
            "type": "string",
            "description": "本次请求编号。联系我们时请附上。"
          }
        }
      },
      "ErrorData": {
        "type": "object",
        "description": "失败回复的 data，按 code 只出现相应的键；5xx 时只可能带 retryAfter 或为 null。",
        "properties": {
          "errors": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "description": "INVALID_REQUEST 时的字段错误。"
          },
          "maxItems": {
            "type": "integer",
            "description": "BATCH_TOO_LARGE 时：本接口（本 format）一次允许的条数上限。"
          },
          "maxPackages": {
            "type": "integer",
            "description": "生成订单 / 订单信息 / 面单 / 作废的 BATCH_TOO_LARGE：一次允许的包裹（= 订单）数上限，与 maxItems 相同。"
          },
          "packages": {
            "type": "integer",
            "nullable": true,
            "description": "生成订单 / 订单信息 / 面单 / 作废的 BATCH_TOO_LARGE：本次请求计到的包裹（= 订单）数；只是条数超上限时为 null。"
          },
          "maxCombinations": {
            "type": "integer",
            "description": "仅 /v1/rates 的 BATCH_TOO_LARGE：一次允许的「条目 × 服务」组合上限（200）。"
          },
          "combinations": {
            "type": "integer",
            "description": "仅 /v1/rates 的 BATCH_TOO_LARGE：本次请求的组合数。"
          },
          "retryAfter": {
            "type": "integer",
            "description": "RATE_LIMITED / QUOTA_EXCEEDED 时：多少秒后再试。"
          }
        },
        "nullable": true
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              false
            ]
          },
          "code": {
            "$ref": "#/components/schemas/RequestCode"
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/ErrorData"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "BatchSummary": {
        "type": "object",
        "required": [
          "total",
          "succeeded",
          "failed"
        ],
        "properties": {
          "total": {
            "type": "integer"
          },
          "succeeded": {
            "type": "integer",
            "description": "success 为 true 的条数（含 PROCESSING 等「已受理」条目）。"
          },
          "failed": {
            "type": "integer"
          }
        }
      },
      "ItemResultBase": {
        "type": "object",
        "description": "每条结果都有这 5 个键。success 与 retryable 只由 code 决定（见 ItemCode 的 x-item-success / x-retryable）。",
        "required": [
          "index",
          "success",
          "code",
          "message",
          "retryable"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "description": "对应请求数组里的下标（从 0 开始，与请求同序）。"
          },
          "success": {
            "type": "boolean"
          },
          "code": {
            "$ref": "#/components/schemas/ItemCode"
          },
          "message": {
            "type": "string",
            "description": "英文说明；OK 时为空字符串。"
          },
          "retryable": {
            "type": "boolean",
            "description": "原样重发这一条是否可能成功。"
          }
        }
      },
      "UnitSystem": {
        "type": "string",
        "enum": [
          "imperial",
          "metric"
        ],
        "description": "必填，无默认。imperial = 磅 / 英寸（lb / in）；metric = 千克 / 厘米（kg / cm）。"
      },
      "Currency": {
        "type": "string",
        "enum": [
          "USD"
        ]
      },
      "Address": {
        "type": "object",
        "description": "字符串会去掉首尾空格；不认识的字段会被忽略。",
        "required": [
          "name",
          "address1",
          "city",
          "state",
          "postalCode"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 100
          },
          "company": {
            "type": "string",
            "maxLength": 100
          },
          "phone": {
            "type": "string",
            "maxLength": 30,
            "description": "美国收件地址（shipTo）报价与出单时：填了就必须是恰好 10 位数字（如 2125550100，不能带 +1、分机、空格、横杠、括号），否则该条 RECEIVER_PHONE_INVALID。发件地址（shipFrom）与非美国地址不检查。"
          },
          "email": {
            "type": "string",
            "maxLength": 100
          },
          "address1": {
            "type": "string",
            "maxLength": 100
          },
          "address2": {
            "type": "string",
            "maxLength": 100
          },
          "city": {
            "type": "string",
            "maxLength": 60
          },
          "state": {
            "type": "string",
            "maxLength": 30,
            "description": "美国地址必须是 2 位州代码（如 CA），大小写都可，会转成大写。"
          },
          "postalCode": {
            "type": "string",
            "maxLength": 20,
            "description": "美国地址必须是 12345 或 12345-6789。"
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "default": "US",
            "description": "2 位国家代码，可省略（默认 US），会转成大写。"
          },
          "residential": {
            "type": "boolean",
            "default": false,
            "description": "是否住宅地址（影响住宅附加费），默认 false。"
          }
        }
      },
      "Package": {
        "type": "object",
        "required": [
          "weight",
          "length",
          "width",
          "height"
        ],
        "properties": {
          "weight": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 2000,
            "description": "单件重量，单位由 unitSystem 决定。"
          },
          "length": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 500
          },
          "width": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 500
          },
          "height": {
            "type": "number",
            "exclusiveMinimum": true,
            "minimum": 0,
            "maximum": 500
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 1,
            "description": "同规格件数。每件是一个包裹，也就是一张订单；一票所有条目的件数合计最多 50。"
          }
        }
      },
      "Packages": {
        "type": "array",
        "minItems": 1,
        "maxItems": 50,
        "items": {
          "$ref": "#/components/schemas/Package"
        },
        "description": "1–50 个条目；quantity 计入后一票最多 50 个包裹（x-max-packages）。多个包裹的订单会拆成多张订单。",
        "x-max-packages": 50
      },
      "RateShipment": {
        "type": "object",
        "required": [
          "shipFrom",
          "shipTo",
          "packages"
        ],
        "properties": {
          "ref": {
            "type": "string",
            "maxLength": 64,
            "description": "可选，原样回显，方便你对应结果。"
          },
          "serviceCode": {
            "type": "string",
            "description": "可选。与 serviceCodeGroup 二选一；两个都不填 = 报你能用的全部服务。"
          },
          "serviceCodeGroup": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "可选。你的代码组名称（区分大小写、需完全一致，首尾空格忽略）。只回一个价：组内当前最便宜的价格（serviceCode / carrier / service 为 null，不说明是哪个服务）。与 serviceCode 同时填 ⇒ 该条 INVALID_SHIPMENT；找不到 ⇒ SERVICE_CODE_GROUP_NOT_FOUND；组里没有你现在能用的服务 ⇒ SERVICE_CODE_GROUP_EMPTY。"
          },
          "shipFrom": {
            "$ref": "#/components/schemas/Address"
          },
          "shipTo": {
            "$ref": "#/components/schemas/Address"
          },
          "packages": {
            "$ref": "#/components/schemas/Packages"
          }
        }
      },
      "RatesRequest": {
        "type": "object",
        "required": [
          "unitSystem",
          "shipments"
        ],
        "properties": {
          "unitSystem": {
            "$ref": "#/components/schemas/UnitSystem"
          },
          "shipments": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/RateShipment"
            },
            "description": "1..100 条；且「条目数 × 要报的服务数 × 条目里不同规格的包裹数」≤ 200。",
            "x-max-combinations": 200
          }
        }
      },
      "Rate": {
        "type": "object",
        "required": [
          "serviceCode",
          "carrier",
          "service",
          "totalCharge",
          "currency"
        ],
        "properties": {
          "serviceCode": {
            "type": "string",
            "description": "服务代码（不透明字符串，下单时原样回传）。代码组报价时为 null。",
            "nullable": true
          },
          "carrier": {
            "type": "string",
            "example": "usps",
            "description": "承运商，如 ups / usps / fedex。代码组报价时为 null。",
            "nullable": true
          },
          "service": {
            "type": "string",
            "example": "usps_ground_advantage",
            "description": "承运商服务，如 ups_ground / fedex_ground。代码组报价时为 null。",
            "nullable": true
          },
          "serviceCodeGroup": {
            "type": "string",
            "description": "仅代码组报价时出现：你发来的组名（去掉首尾空格后）。下单时把它填进 serviceCodeGroup。"
          },
          "totalCharge": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "应付总价。金额字符串，美元，两位小数。做算术前请先转成数字。"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "packageRates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PackageRate"
            },
            "description": "仅多个包裹（quantity 计入）的报价出现：每个包裹一个价，按包裹顺序；totalCharge 是它们的合计。"
          }
        }
      },
      "UnavailableService": {
        "type": "object",
        "required": [
          "serviceCode",
          "code",
          "message",
          "retryable",
          "carrierMessage"
        ],
        "properties": {
          "serviceCode": {
            "type": "string",
            "description": "没报出价的服务代码；代码组报价时为 null。",
            "nullable": true
          },
          "code": {
            "type": "string",
            "enum": [
              "NO_RATE",
              "CARRIER_RATE_ERROR",
              "RATE_TIMEOUT",
              "SERVICE_NOT_AVAILABLE",
              "SERVICE_CODE_GROUP_NOT_FOUND",
              "SERVICE_CODE_GROUP_EMPTY",
              "RECEIVER_PHONE_INVALID"
            ]
          },
          "message": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "carrierMessage": {
            "type": "string",
            "description": "承运商原话（已做脱敏与截断），没有时为 null；代码组报价时恒为 null。",
            "nullable": true
          }
        }
      },
      "RateResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "required": [
              "ref",
              "rates",
              "unavailable"
            ],
            "properties": {
              "ref": {
                "type": "string",
                "nullable": true
              },
              "rates": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Rate"
                },
                "description": "按价格从低到高。"
              },
              "unavailable": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/UnavailableService"
                },
                "description": "没报出价的服务及原因。"
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FieldError"
                },
                "description": "INVALID_SHIPMENT 或 RECEIVER_PHONE_INVALID 时出现。"
              }
            }
          }
        ]
      },
      "References": {
        "type": "object",
        "properties": {
          "reference1": {
            "type": "string",
            "maxLength": 50
          },
          "reference2": {
            "type": "string",
            "maxLength": 50
          }
        }
      },
      "CreateOrderItem": {
        "type": "object",
        "required": [
          "customerOrderNo",
          "shipFrom",
          "shipTo",
          "packages"
        ],
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "pattern": "^[A-Za-z0-9._\\-/]{1,64}$",
            "description": "客户单号，必填。区分大小写，不做任何归一化（前后有空格直接无效）。用过一次就永远属于那一张单。"
          },
          "serviceCode": {
            "type": "string",
            "maxLength": 128,
            "description": "从 /v1/rates 拿到的服务代码，原样回传。与 serviceCodeGroup 必须填且只填一个。"
          },
          "serviceCodeGroup": {
            "type": "string",
            "minLength": 1,
            "maxLength": 50,
            "description": "你的代码组名称（区分大小写、需完全一致，首尾空格忽略）。购买前按组内当时最便宜的服务出单；订单视图出单前不给 carrier / service，serviceCode 恒为 null。与 serviceCode 必须填且只填一个（都不填或都填 ⇒ 该条 INVALID_ORDER）；找不到 ⇒ SERVICE_CODE_GROUP_NOT_FOUND；组里没有你现在能用的服务 ⇒ SERVICE_CODE_GROUP_EMPTY。"
          },
          "shipDate": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
            "description": "发货日 YYYY-MM-DD。可省略：省略时取建单当天的 UTC 日期。"
          },
          "maxCharge": {
            "type": "string",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$",
            "description": "可选，金额字符串（不收数字类型）。购买前我方报价高于它就不买（该单 FAILED / PRICE_ABOVE_MAX，不扣钱）。一单多个包裹（quantity 计入）时暂不能用：该条 INVALID_ORDER。"
          },
          "shipFrom": {
            "$ref": "#/components/schemas/Address"
          },
          "shipTo": {
            "$ref": "#/components/schemas/Address"
          },
          "packages": {
            "$ref": "#/components/schemas/Packages"
          },
          "references": {
            "$ref": "#/components/schemas/References"
          }
        }
      },
      "CreateOrdersRequest": {
        "type": "object",
        "required": [
          "unitSystem",
          "orders"
        ],
        "properties": {
          "unitSystem": {
            "$ref": "#/components/schemas/UnitSystem"
          },
          "confirm": {
            "type": "boolean",
            "default": true,
            "description": "true（默认）= 建单 + 扣钱 + 出面单；false = 只建草稿。"
          },
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/CreateOrderItem"
            },
            "description": "1..500 条；所有条目的包裹合计（quantity 计入）≤ 500。"
          }
        }
      },
      "OrderStatus": {
        "type": "string",
        "enum": [
          "DRAFT",
          "PROCESSING",
          "CREATED",
          "FAILED",
          "CANCEL_PENDING",
          "CANCELLED"
        ],
        "description": "DRAFT 草稿 · PROCESSING 处理中（不是失败，不要换单号重发）· CREATED 已出单已扣费 · FAILED 明确失败（没出面单、没扣钱）· CANCEL_PENDING 作废申请已提交、等我方审批退款 · CANCELLED 已作废已退款。"
      },
      "LabelStatus": {
        "type": "string",
        "enum": [
          "NOT_CREATED",
          "PENDING",
          "READY",
          "BLOCKED_CANCELLED"
        ],
        "description": "NOT_CREATED 未出单 · PENDING 已出单但面单稍后才出 · READY 可取 · BLOCKED_CANCELLED 作废中 / 已作废，不再提供。"
      },
      "TrackingStatus": {
        "type": "string",
        "enum": [
          "PRE_SHIPMENT",
          "IN_TRANSIT",
          "OUT_FOR_DELIVERY",
          "DELIVERED",
          "RETURNED",
          "EXCEPTION",
          "UNKNOWN"
        ]
      },
      "CancelStatus": {
        "type": "string",
        "enum": [
          "PROCESSING",
          "PENDING_REVIEW",
          "APPROVED",
          "REJECTED",
          "FAILED"
        ],
        "description": "PROCESSING 正在向承运商取消 · PENDING_REVIEW 承运商已取消、等我方审批退款（未退款）· APPROVED 已退款 · REJECTED 审批驳回、未退款 · FAILED 没取消成功、未退款。"
      },
      "StatusReason": {
        "type": "object",
        "description": "仅 status 为 FAILED 或 PROCESSING 时非 null；五个键恒在。",
        "required": [
          "code",
          "message",
          "carrierCode",
          "carrierMessage",
          "quotedCharge"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "PROCESSING 时为 ORDER_PROCESSING；FAILED 时为失败原因码（ItemCode 之一）。"
          },
          "message": {
            "type": "string"
          },
          "carrierCode": {
            "type": "string",
            "description": "仅 CARRIER_REJECTED 且承运商给了码时；代码组订单恒为 null。",
            "nullable": true
          },
          "carrierMessage": {
            "type": "string",
            "description": "承运商原话（已做脱敏与截断）；代码组订单恒为 null（原因与下一步看 code / message）。",
            "nullable": true
          },
          "quotedCharge": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "27.40",
            "description": "仅 PRICE_ABOVE_MAX：购买前那次报价。金额字符串，美元，两位小数。做算术前请先转成数字。",
            "nullable": true
          }
        },
        "nullable": true
      },
      "CancelView": {
        "type": "object",
        "description": "从未申请过作废时为 null；九个键恒在。",
        "required": [
          "status",
          "code",
          "message",
          "carrierMessage",
          "requestedAt",
          "reviewedAt",
          "refundAmount",
          "currency",
          "rejectReason"
        ],
        "properties": {
          "status": {
            "$ref": "#/components/schemas/CancelStatus"
          },
          "code": {
            "type": "string",
            "description": "仅 FAILED 时：CARRIER_CANCEL_REJECTED / CARRIER_ORDER_NOT_FOUND / CARRIER_CANCEL_UNCONFIRMED / CANCEL_TEMPORARILY_UNAVAILABLE / ORDER_NOT_SHIPPED / ORDER_PROCESSING。",
            "nullable": true
          },
          "message": {
            "type": "string"
          },
          "carrierMessage": {
            "type": "string",
            "description": "承运商原话。承运商普通拒绝取消（CARRIER_CANCEL_REJECTED）时为 null。",
            "nullable": true
          },
          "requestedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "reviewedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "refundAmount": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "仅 APPROVED：退款金额。金额字符串，美元，两位小数。做算术前请先转成数字。",
            "nullable": true
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "rejectReason": {
            "type": "string",
            "description": "仅 REJECTED：驳回理由。",
            "nullable": true
          }
        },
        "nullable": true
      },
      "OrderView": {
        "type": "object",
        "description": "一张订单对外的样子。所有键恒在（没有值时为 null）。",
        "required": [
          "customerOrderNo",
          "orderNo",
          "status",
          "statusReason",
          "serviceCode",
          "carrier",
          "service",
          "totalCharge",
          "currency",
          "trackingNumber",
          "labelReady",
          "labelStatus",
          "labelUrl",
          "labelUrlExpiresAt",
          "trackingStatus",
          "trackingUpdatedAt",
          "cancel",
          "createdAt",
          "submittedAt"
        ],
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "description": "客户单号；在后台手工下的单为 null。",
            "nullable": true
          },
          "orderNo": {
            "type": "string",
            "description": "我方单号（ORD-…；测试单为 SBX-…）。",
            "nullable": true
          },
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          },
          "statusReason": {
            "$ref": "#/components/schemas/StatusReason"
          },
          "serviceCode": {
            "type": "string",
            "description": "仅通过本接口用 serviceCode 建的单给出；后台建的单、用代码组建的单为 null。",
            "nullable": true
          },
          "carrier": {
            "type": "string",
            "description": "承运商；用代码组建的单出单前为 null。",
            "nullable": true
          },
          "service": {
            "type": "string",
            "description": "承运商服务；用代码组建的单出单前为 null。",
            "nullable": true
          },
          "totalCharge": {
            "type": "string",
            "pattern": "^\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "已扣费金额（仅 CREATED / CANCEL_PENDING / CANCELLED 时有值）。金额字符串，美元，两位小数。做算术前请先转成数字。",
            "nullable": true
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "trackingNumber": {
            "type": "string",
            "description": "仅已扣费的状态有值。",
            "nullable": true
          },
          "labelReady": {
            "type": "boolean"
          },
          "labelStatus": {
            "$ref": "#/components/schemas/LabelStatus"
          },
          "labelUrl": {
            "type": "string",
            "format": "uri",
            "description": "仅 READY 且我方已准备好面单文件时给出（1 小时有效）；否则为 null，请用 /v1/orders/labels 取。",
            "nullable": true
          },
          "labelUrlExpiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "trackingStatus": {
            "$ref": "#/components/schemas/TrackingStatus",
            "nullable": true
          },
          "trackingUpdatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "我方最近一次更新物流状态的时间（非实时查询）。",
            "nullable": true
          },
          "cancel": {
            "$ref": "#/components/schemas/CancelView"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "submittedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "PackageRate": {
        "type": "object",
        "description": "一个包裹的价格。",
        "required": [
          "packageIndex",
          "totalCharge"
        ],
        "properties": {
          "packageIndex": {
            "type": "integer",
            "minimum": 1,
            "description": "第几个包裹（从 1 起，quantity 展开后按请求顺序）。"
          },
          "totalCharge": {
            "type": "string",
            "example": "7.10",
            "description": "金额字符串，USD，2 位小数。"
          }
        }
      },
      "SplitOrderFields": {
        "type": "object",
        "description": "仅一单多个包裹拆出的订单出现（只有一个包裹的订单没有这两个键）。",
        "properties": {
          "packageIndex": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "description": "这张订单是这一组的第几个包裹（从 1 起）。"
          },
          "packageCount": {
            "type": "integer",
            "minimum": 2,
            "maximum": 50,
            "description": "这一组共几个包裹（即几张订单）。"
          }
        }
      },
      "PackageOrderEntry": {
        "type": "object",
        "description": "一个包裹的那张订单：packageIndex + success / code / message / retryable，其余字段与单独指定这张订单（orderNo）时该条的字段相同：生成订单再带 replayed 与订单视图全部字段，订单信息带订单视图全部字段，面单带面单字段，作废带作废字段。",
        "required": [
          "packageIndex",
          "success",
          "code",
          "message",
          "retryable"
        ],
        "properties": {
          "packageIndex": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50
          },
          "success": {
            "type": "boolean"
          },
          "code": {
            "$ref": "#/components/schemas/ItemCode"
          },
          "message": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        },
        "additionalProperties": true
      },
      "PackageGroupResult": {
        "description": "按客户单号作用于一单多个包裹的订单时的一条结果（生成订单 / 订单信息 / 面单 / 作废通用）。code：所有包裹相同就是那个码；否则全部成功为 OK，有没成功的取第一个没成功的包裹的码。",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "required": [
              "customerOrderNo",
              "packageCount",
              "orders"
            ],
            "properties": {
              "replayed": {
                "type": "boolean",
                "description": "仅生成订单：所有包裹的订单都早已存在时为 true。"
              },
              "customerOrderNo": {
                "type": "string",
                "description": "客户单号（这一组的号）。"
              },
              "packageCount": {
                "type": "integer",
                "minimum": 2,
                "maximum": 50
              },
              "orders": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PackageOrderEntry"
                },
                "description": "每个包裹一项，按包裹顺序。"
              }
            }
          }
        ]
      },
      "CreateOrderAccepted": {
        "description": "受理 / 回放：带订单视图全部字段。订单 FAILED 时 code 为失败原因码、success 为 false；PROCESSING 时 success 为 true。",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "required": [
              "replayed"
            ],
            "properties": {
              "replayed": {
                "type": "boolean",
                "description": "true = 这个客户单号的单早已存在，本次返回的是那张单。"
              }
            }
          },
          {
            "$ref": "#/components/schemas/OrderView"
          },
          {
            "$ref": "#/components/schemas/SplitOrderFields"
          }
        ]
      },
      "CreateOrderRefused": {
        "description": "被拒：本次请求没有为这一条建任何东西、没有扣钱。",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string",
                "nullable": true
              },
              "errors": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/FieldError"
                },
                "description": "仅 INVALID_ORDER 时出现。"
              },
              "required": {
                "type": "string",
                "example": "36.00",
                "description": "仅一单多个包裹、余额不够全部包裹时（INSUFFICIENT_BALANCE）：买下这次要买的全部包裹需要的金额（各包裹报价 + 价格变动预留之和）。金额字符串，USD，2 位小数。"
              },
              "shortfall": {
                "type": "string",
                "example": "6.00",
                "description": "与 required 同时出现：还差的金额。金额字符串，USD，2 位小数。"
              },
              "carrierMessage": {
                "type": "string",
                "description": "仅一单多个包裹、其中某个包裹报不出价而整条被拒时可能出现：承运商的原话。"
              }
            }
          }
        ]
      },
      "CreateOrderResult": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/CreateOrderAccepted"
          },
          {
            "$ref": "#/components/schemas/CreateOrderRefused"
          },
          {
            "$ref": "#/components/schemas/PackageGroupResult"
          }
        ]
      },
      "OrderRef": {
        "type": "object",
        "description": "三选一：必须且只能填一个。",
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "maxLength": 64
          },
          "orderNo": {
            "type": "string",
            "maxLength": 64,
            "description": "我方单号，不区分大小写。"
          },
          "trackingNumber": {
            "type": "string",
            "maxLength": 64,
            "description": "刚出单约 1 分钟内可能查不到，请优先用客户单号。"
          }
        }
      },
      "IdentifierFailure": {
        "description": "单号类失败：回显你发来的那个单号字段。",
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string"
              },
              "orderNo": {
                "type": "string"
              },
              "trackingNumber": {
                "type": "string"
              },
              "orderNos": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "仅 AMBIGUOUS_TRACKING_NUMBER：你自己名下的候选我方单号。"
              }
            }
          }
        ]
      },
      "OrdersInfoRequest": {
        "type": "object",
        "required": [
          "orders"
        ],
        "properties": {
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/OrderRef"
            },
            "description": "1..100 条；按单号对应的订单合计 ≤ 100（一组拆单的每张订单都计入）。"
          }
        }
      },
      "OrderInfoFound": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "$ref": "#/components/schemas/OrderView"
          },
          {
            "$ref": "#/components/schemas/SplitOrderFields"
          }
        ]
      },
      "OrderInfoResult": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/OrderInfoFound"
          },
          {
            "$ref": "#/components/schemas/IdentifierFailure"
          },
          {
            "$ref": "#/components/schemas/PackageGroupResult"
          }
        ]
      },
      "LabelsRequest": {
        "type": "object",
        "required": [
          "orders"
        ],
        "properties": {
          "format": {
            "type": "string",
            "enum": [
              "url",
              "base64",
              "merged"
            ],
            "default": "url"
          },
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/OrderRef"
            },
            "description": "上限按 format：url 500 · base64 20 · merged 100；按单号对应的订单数同一上限（一组拆单的每张订单都计入）。",
            "x-max-items-by-format": {
              "url": 500,
              "base64": 20,
              "merged": 100
            }
          }
        }
      },
      "LabelResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string",
                "nullable": true
              },
              "orderNo": {
                "type": "string",
                "nullable": true
              },
              "trackingNumber": {
                "type": "string",
                "nullable": true
              },
              "fileType": {
                "type": "string",
                "description": "url / base64：PDF / PNG / JPEG，或承运商原样给的其它格式（如 ZPL）；无法识别时为 UNKNOWN。"
              },
              "labelUrl": {
                "type": "string",
                "format": "uri",
                "description": "url：我方下载链接，1 小时有效。"
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "contentBase64": {
                "type": "string",
                "description": "base64：面单文件内容。"
              },
              "merged": {
                "type": "boolean",
                "enum": [
                  true
                ],
                "description": "merged：这一单已放进合并文件。"
              },
              "orderNos": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "MergedLabel": {
        "type": "object",
        "description": "仅 format = merged：所有能合并的面单合成的一个 PDF；一个都合不进时为 null。",
        "required": [
          "labelUrl",
          "expiresAt",
          "pageCount"
        ],
        "properties": {
          "labelUrl": {
            "type": "string",
            "format": "uri"
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "pageCount": {
            "type": "integer"
          }
        },
        "nullable": true
      },
      "CancelRequestItem": {
        "type": "object",
        "description": "三选一单号 + 可选 reason。",
        "properties": {
          "customerOrderNo": {
            "type": "string",
            "maxLength": 64
          },
          "orderNo": {
            "type": "string",
            "maxLength": 64
          },
          "trackingNumber": {
            "type": "string",
            "maxLength": 64
          },
          "reason": {
            "type": "string",
            "maxLength": 200,
            "description": "可选，作废原因。不是字符串或超过 200 字 ⇒ 整次请求 400，什么都不发。"
          }
        }
      },
      "CancelRequest": {
        "type": "object",
        "required": [
          "orders"
        ],
        "properties": {
          "orders": {
            "type": "array",
            "minItems": 1,
            "maxItems": 500,
            "items": {
              "$ref": "#/components/schemas/CancelRequestItem"
            },
            "description": "1..500 条；按单号对应的订单合计 ≤ 500（一组拆单的每张订单都计入）。"
          }
        }
      },
      "CancelResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ItemResultBase"
          },
          {
            "type": "object",
            "properties": {
              "customerOrderNo": {
                "type": "string",
                "nullable": true
              },
              "orderNo": {
                "type": "string",
                "nullable": true
              },
              "trackingNumber": {
                "type": "string",
                "nullable": true
              },
              "status": {
                "$ref": "#/components/schemas/OrderStatus"
              },
              "cancel": {
                "$ref": "#/components/schemas/CancelView"
              },
              "orderNos": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        ]
      },
      "RatesResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/RateResult"
                },
                "description": "与请求同序。"
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "CreateOrdersResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CreateOrderResult"
                },
                "description": "与请求同序。"
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "OrdersInfoResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/OrderInfoResult"
                },
                "description": "与请求同序。"
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "LabelsResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/LabelResult"
                    },
                    {
                      "$ref": "#/components/schemas/PackageGroupResult"
                    }
                  ]
                },
                "description": "与请求同序。"
              },
              "merged": {
                "$ref": "#/components/schemas/MergedLabel"
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "CancelResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Processed 2 item(s)."
          },
          "data": {
            "type": "object",
            "required": [
              "summary",
              "results"
            ],
            "properties": {
              "summary": {
                "$ref": "#/components/schemas/BatchSummary"
              },
              "results": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/CancelResult"
                    },
                    {
                      "$ref": "#/components/schemas/PackageGroupResult"
                    }
                  ]
                },
                "description": "与请求同序。"
              }
            }
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "BalanceRequest": {
        "type": "object",
        "description": "空对象 {}；对象里的键会被忽略。"
      },
      "CreditView": {
        "type": "object",
        "description": "信用额度；没有信用额度时整个为 null。三个键恒在。",
        "required": [
          "limit",
          "used",
          "remaining"
        ],
        "properties": {
          "limit": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "信用额度。金额字符串，美元，两位小数。"
          },
          "used": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "已用：余额低于零的部分（最多到 limit）。"
          },
          "remaining": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "剩余：limit − used。"
          }
        },
        "nullable": true
      },
      "BalanceView": {
        "type": "object",
        "description": "六个键恒在。金额都是两位小数的字符串，美元；做算术前请先转成数字。",
        "required": [
          "currency",
          "balance",
          "reserved",
          "frozen",
          "available",
          "credit"
        ],
        "properties": {
          "currency": {
            "$ref": "#/components/schemas/Currency"
          },
          "balance": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "余额；正在使用信用额度时为负数。"
          },
          "reserved": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "订单预留：正在出单的订单暂时占用的金额。"
          },
          "frozen": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "冻结金额：由我方冻结，只有我方能解冻。"
          },
          "available": {
            "type": "string",
            "pattern": "^-?\\d+\\.\\d{2}$",
            "example": "12.34",
            "description": "现在可以用来下单的金额 = balance − reserved − frozen（+ credit.limit）。与生成订单检查余额用的是同一个数：一张单需要的金额（报价 + 价格变动预留）不超过它就能出单。"
          },
          "credit": {
            "$ref": "#/components/schemas/CreditView"
          }
        }
      },
      "BalanceResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/BalanceView"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "ListOrdersRequest": {
        "type": "object",
        "required": [
          "createdFrom",
          "createdTo"
        ],
        "properties": {
          "createdFrom": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-15T00:00:00Z",
            "description": "起始时间（含）。ISO 8601 日期时间，必须带时区（Z 或 ±hh:mm）；只写日期或不带时区会被拒。按整秒比较。"
          },
          "createdTo": {
            "type": "string",
            "format": "date-time",
            "example": "2026-11-15T00:00:00Z",
            "description": "结束时间（不含），格式同上；必须晚于 createdFrom，相差不超过 31 天。"
          },
          "status": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/OrderStatus"
            },
            "description": "只列这些状态的订单；不填 = 全部状态。"
          },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50,
            "description": "每页最多几张订单。"
          },
          "cursor": {
            "type": "string",
            "description": "上一页回复里的 nextCursor，原样传回；第一页不填。只对同一个客户账号、同一种钥匙、同样的 createdFrom / createdTo / status 有效，否则 400 INVALID_CURSOR。"
          }
        },
        "x-max-range-days": 31
      },
      "ListedOrder": {
        "allOf": [
          {
            "$ref": "#/components/schemas/OrderView"
          },
          {
            "$ref": "#/components/schemas/SplitOrderFields"
          }
        ]
      },
      "ListOrdersQuery": {
        "type": "object",
        "description": "实际生效的查询（整秒、UTC）。",
        "required": [
          "createdFrom",
          "createdTo",
          "status",
          "limit"
        ],
        "properties": {
          "createdFrom": {
            "type": "string",
            "format": "date-time"
          },
          "createdTo": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderStatus"
            },
            "nullable": true,
            "description": "没填时为 null。"
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "ListOrdersData": {
        "type": "object",
        "required": [
          "orders",
          "nextCursor",
          "query"
        ],
        "properties": {
          "orders": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListedOrder"
            },
            "description": "按建单时间从早到晚。可能少于 limit，甚至为空；只要 nextCursor 不是 null 就继续翻。后台手工下的一单多个包裹的订单按包裹拆成的订单逐张列出、总在同一页（包裹数多于 limit 时这一页会多于 limit）。"
          },
          "nextCursor": {
            "type": "string",
            "nullable": true,
            "description": "可能还有下一页时为字符串，原样放进下一次请求的 cursor；没有了为 null。"
          },
          "query": {
            "$ref": "#/components/schemas/ListOrdersQuery"
          }
        }
      },
      "ListOrdersResponse": {
        "type": "object",
        "required": [
          "success",
          "code",
          "message",
          "data",
          "requestId"
        ],
        "properties": {
          "success": {
            "type": "boolean",
            "enum": [
              true
            ]
          },
          "code": {
            "type": "string",
            "enum": [
              "OK"
            ]
          },
          "message": {
            "type": "string",
            "example": "Listed 2 order(s)."
          },
          "data": {
            "$ref": "#/components/schemas/ListOrdersData"
          },
          "requestId": {
            "type": "string"
          }
        }
      }
    }
  }
}
