发货单

创建、支付、取消、拦截、列表与查询国际发货单（/v1/fulfillment/shipments/*）。

生命周期 {#lifecycle}

Public status：PENDING → WAIT_PAYMENT → WAIT_SHIP → SHIPPED → SIGNED。取消 → CANCELLED。

创建 / 支付仍返回汇总 total（freight / services / discount / payment）。列表是轻量行；详情才是完整视图（分箱、打包影像、头尾程换单、费用行、仓库 timeline）。扫描事件见国际物流追踪。字段参考：响应模型。

已作废：POST /v1/fulfillment/shipments/preview、POST /v1/fulfillment/shipments/logistics/trace、POST /v1/fulfillment/shipments/cancel、POST /v1/fulfillment/shipments/detail。请改用 {id}/tracking、{id}/cancel 和 GET {id}。精确运费在创建时返回。

POST /v1/fulfillment/shipments/create {#create}

必填：tracking_numbers[]、receiver、shipping_channel_code。可选：

external_shipment_id — 业务侧稳定对账编号，不是请求重试 key
remark
receiver.personal_code — 可选个人通关码（如韩国 PCCC）。按运输线路要求填写；Gateway 原样转发，不校验格式或是否必填。

运输单标识规则

运输单详情、国际 tracking、取消和支付均可使用 HioBuy 运输单系统 id，或创单时提交的 external_shipment_id。路径值为纯数字时按 HioBuy 内部 ID 查询；只要包含任意非数字字符，就按 external_shipment_id 查询。

建议开发者 ID 添加前缀，例如 shp_MY-INTL-ORDER-001。创单时虽然可以提交纯数字 external_shipment_id，但它通过这些 {shipment_id} 路径查询时会被解释为内部 ID，因此无法明确选中外部编号。

创建时建议携带可选请求头 Idempotency-Key，防止重试或并发请求重复创单。每个逻辑运输单使用一个唯一 key，只在请求体相同时复用。

POST /v1/fulfillment/shipments/create
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: 3b4cc23d-c1a3-41a1-b809-c64200f42a71

total.payment 为支付时扣款金额：

"total": {
  "freight": { "amount": 8900, "currency": "CNY" },
  "services": { "amount": 1500, "currency": "CNY" },
  "discount": { "amount": 200, "currency": "CNY" },
  "payment": { "amount": 10200, "currency": "CNY" }
}

返回 id、order_sn 和 status（通常为 PENDING）。Public id 取仓库数字主键（字符串，如 "115"）；order_sn 为仓库单号（如 JIYUNRI1349）。后续 pay / cancel / detail / tracking 路径使用这个 id。

创建错误（线上仓库 → 4xx error 对象）：

HTTP	`error.code`	仓库 `upstream_code`	典型 `message`
404	`PARCEL_NOT_FOUND`	`SHIPMENT_PACKAGE_NOT_FOUND`	部分包裹不存在
400	`SHIPMENT_CREATE_EXCEPTION`	`SHIPMENT_CREATE_EXCEPTION`	请先更新包裹…物品属性信息 / 有包裹不是已入库，下单失败
409	`EXTERNAL_ORDER_ID_ALREADY_EXISTS`	`EXTERNAL_ORDER_ID_ALREADY_EXISTS`	外部订单号已存在
409	`PACKAGE_ALREADY_CONSOLIDATED`	`PACKAGE_ALREADY_CONSOLIDATED`	一个或多个包裹已在其它运输单中
409	`IDEMPOTENCY_CONFLICT`	—	同一 key 使用了不同参数
409	`IDEMPOTENCY_REQUEST_IN_PROGRESS`	—	同一 key 的请求仍在处理中

可恢复的冲突信息可能包含 existing_resource、existing_resources、conflicting_tracking_numbers、idempotency_key、retry_after_ms。如果已有资源就是目标运输单，请保存其 shipment_id / order_sn 并继续后续流程。

POST /v1/fulfillment/shipments/{shipment_id}/pay {#pay}

POST /v1/fulfillment/shipments/115/pay
Authorization: Bearer <API_KEY>
Idempotency-Key: d7ade627-41ea-416c-89f9-da4693dc73ac

路径 {shipment_id} 遵循运输单标识规则。body 可为空。网关将纯数字值作为 shipment_id 传给仓库，将带前缀或其它非纯数字值作为 external_shipment_id 传给仓库。

从履约钱包扣款。支付成功 → WAIT_SHIP。

支付接口的 Idempotency-Key 也是可选但强烈推荐。相同 key 的并发重试会返回同一支付结果，不会重复扣款；回放响应可能带 Idempotency-Replayed: true。

支付错误：

HTTP	`error.code`	Warehouse `upstream_code`	Typical `message`
404	`NOT_FOUND`	`SHIPMENT_NOT_EXISTS`	订单不存在
409	`SHIPMENT_ALREADY_PAID`	`SHIPMENT_ALREADY_PAID`	订单已支付
402	`INSUFFICIENT_BALANCE`	`INSUFFICIENT_BALANCE`	余额不足

SHIPMENT_ALREADY_PAID 可能通过 error.details.existing_resource 返回已有 transaction_id、shipment_id、payment_status、paid_at。确认运输单一致后可按已支付恢复流程。IDEMPOTENCY_REQUEST_IN_PROGRESS 应等待 retry_after_ms 后用原 key 重试。

沙箱 sb_shp_pay_insufficient 仍可能返回 200 + success: false + error_code。线上仓库使用 4xx error 对象。见错误码。

POST /v1/fulfillment/shipments/{shipment_id}/cancel {#cancel}

路径 {shipment_id} 遵循运输单标识规则：纯数字按 shipment_id，非纯数字按 external_shipment_id。

cancel_reason 必填。仓库上游：POST /api/gateway-worker/v1/shipments/cancel，body 包含解析后的标识字段和 cancel_reason。

{
  "cancel_reason": "buyer_request"
}

PENDING 或 WAIT_PAYMENT 可取消。成功 → CANCELLED。

POST /v1/fulfillment/shipments/{shipment_id}/intercept {#intercept}

出库开始后申请拦截。这不会改变发货单生命周期 status。仓库上游：POST /api/gateway-worker/v1/shipments/set-exceptional，body 为 { shipment_id, reason, remark }。

{
  "reason": "CUSTOMER_REQUEST",
  "remark": "Customer requested to stop the shipment before dispatch."
}

reason 为固定 CODE：CUSTOMER_REQUEST / ADDRESS_ISSUE / ORDER_CHANGE / PAYMENT_ISSUE / COMPLIANCE_ISSUE / PACKAGE_ISSUE / OTHER。reason 为 OTHER 时必须填 remark。

成功：

{
  "shipment_id": "107",
  "interception": {
    "status": "REQUESTED",
    "reason": "ADDRESS_ISSUE",
    "remark": "Customer address needs to be corrected.",
    "requested_at": "2026-08-20T12:30:00Z"
  }
}

interception.status：REQUESTED → PROCESSING → INTERCEPTED / FAILED。详情可以是 status: "SHIPPED" 同时 interception.status: "REQUESTED"。

Mock 允许 WAIT_SHIP 和 SHIPPED。PENDING / WAIT_PAYMENT / SIGNED / CANCELLED → SHIPMENT_NOT_INTERCEPTABLE。出库前请用取消。

HTTP	`error.code`
404	`SHIPMENT_NOT_FOUND`
409	`SHIPMENT_NOT_INTERCEPTABLE`
409	`SHIPMENT_INTERCEPTION_ALREADY_REQUESTED`
422	`INVALID_INTERCEPTION_REASON`
422	`INTERCEPTION_REMARK_REQUIRED`

沙箱：sb_shp_shipped 可申请拦截；sb_shp_unpaid / sb_shp_signed 不可；sb_shp_intercepted 已是 INTERCEPTED。线上仓库 SHIPMENT_NOT_EXISTS 映射为 SHIPMENT_NOT_FOUND。

GET /v1/fulfillment/shipments {#list}

GET /v1/fulfillment/shipments?status=WAIT_SHIP&created_from=2026-08-01&page=1&page_size=20
Authorization: Bearer <API_KEY>

轻量行。分箱、打包影像、头尾程、费用行、timeline 和 interception 仍看详情。仓库上游：POST /api/gateway-worker/v1/shipments/index。

Query	说明
`status`	逗号分隔或重复传参。`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`created_from`	创建时间下界（`YYYY-MM-DD` 或 datetime）
`created_to`	创建时间上界
`page`	默认 `1`
`page_size`	默认 `20`，最大 `100`

每行含 id（仓库数字主键转字符串）、order_sn、external_shipment_id、status、international_tracking、receiver、shipping_channel、services、total、payment_status、times。仓库空串变为 null。金额为分。

国际运单号只在 international_tracking — 没有顶层 tracking_number。列表的 times 不含 updated_at / packing_started_at（那些在详情里）。

沙箱含 fixture（sb_shp_unpaid、sb_shp_shipped、sb_shp_signed、sb_shp_intercepted 等）以及创单产生的动态 sbs_*。

{
  "data": [
    {
      "id": "107",
      "order_sn": "JIYUNRI1338",
      "status": "WAIT_SHIP",
      "external_shipment_id": "MY-INTL-ORDER-001",
      "international_tracking": {
        "tracking_number": null,
        "carrier": null
      },
      "receiver": {
        "name": "John Doe",
        "mobile": "+12025550123",
        "email": "john@example.com",
        "country_code": "US",
        "province": "California",
        "city": "Los Angeles",
        "district": null,
        "postal_code": "90001",
        "address_line1": "123 Main St",
        "address_line2": "Apt 4B",
        "personal_code": null
      },
      "shipping_channel": {
        "code": "PUHUO",
        "name": "General Cargo Air Line"
      },
      "services": [
        {
          "id": "2",
          "service_code": "2",
          "name": "Package Reinforcement",
          "quantity": 1,
          "status": "PENDING"
        }
      ],
      "total": {
        "charges": {
          "amount": 2000,
          "currency": "CNY"
        },
        "discount": {
          "amount": 0,
          "currency": "CNY"
        },
        "payable": {
          "amount": 2000,
          "currency": "CNY"
        },
        "paid": {
          "amount": 0,
          "currency": "CNY"
        },
        "outstanding": {
          "amount": 2000,
          "currency": "CNY"
        }
      },
      "payment_status": "UNPAID",
      "times": {
        "created_at": "2026-08-20T09:41:36Z",
        "packed_at": "2026-08-20T10:20:00Z",
        "paid_at": null,
        "shipped_at": null,
        "delivered_at": null,
        "cancelled_at": null
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  },
  "monetary_unit": "CNY_minor",
  "request_id": "req_xxx"
}

GET /v1/fulfillment/shipments/{shipment_id} {#detail}

GET /v1/fulfillment/shipments/107?language=en
Authorization: Bearer <API_KEY>

路径 {shipment_id} 遵循运输单标识规则。可选 language 用于展示名（shipping_channel.name、services[].name、charges[].name）。不要依赖 status_name。

仓库上游：POST /api/gateway-worker/v1/shipments/detail，body 使用解析后的 shipment_id 或 external_shipment_id。Public id 为仓库数字主键转字符串（如 "107"）；order_sn 为仓库单号。

创建 / 支付无法表达的仓库事实看这里：

问题	看哪里
分箱出库	`boxes[]`；多于一箱时 `multi_box: true`
国际运单号	`international_tracking`；分箱看 `boxes[].tracking`
仓库业务节点	`timeline[]`（创建 / 打包 / 支付）。不是扫描事件
打包照片 / 视频	`files[]`：`PACKING_IMAGE` / `PACKING_VIDEO`
换单（头程 ≠ 尾程）	仓库给了头尾程单号时才有 `shipping_legs[]`

区块	含义
`source_packages`	合箱前国内包裹（`pkg_*` + 国内运单号）
`boxes`	已打包出库箱；打包前为空 `[]`
`international_tracking`	发货单级尾程 `{ tracking_number, carrier }`；出库前均为 `null`
`timeline`	仓库业务事件，统一使用 `{ code, status, title, occurred_at, details }`；code 稳定且不能为空
`shipping_legs`	换单后的干线 vs 目的地尾程；没有单号时为 `[]`
`files`	打包影像（不是包裹上的入库 VAS 照片）
`charges`	费用行。折扣行为负数
`total`	`charges` / `discount`（正数）/ `payable` / `paid` / `outstanding`
`payment_status`	`UNPAID` / `PAID` / `PARTIAL`
`times`	时间戳；未发生为 `null`
`interception`	拦截处理，或 `null`。与发货单 `status` 独立

金额为分（monetary_unit: CNY_minor）。空数组为 []，不要省略。

Timeline 契约

发货单顶层 status 按 PENDING → WAIT_PAYMENT → WAIT_SHIP → SHIPPED → SIGNED 流转，取消统一为 CANCELLED。每个 timeline[] 节点必须包含 code、status、title、occurred_at、details；code 稳定且非空，时间为带时区 ISO 8601，无结构化上下文时 details 返回 {}，并按时间倒序排列。程序逻辑应使用 code 和 status，不能解析本地化的 title。

事件 Code	含义	事件发生后的发货单状态	必填 `details`
`SHIPMENT_CREATED`	发货单已创建	`PENDING`	—
`SHIPMENT_PACKED`	发货单已完成打包	`WAIT_PAYMENT`	—
`SHIPMENT_PAID`	发货单已支付	`WAIT_SHIP`	—
`SHIPMENT_DISPATCHED`	发货单已从仓库发出	`SHIPPED`	—
`SHIPMENT_SIGNED`	发货单已签收	`SIGNED`	—
`SHIPMENT_CANCELLED`	发货单已取消	`CANCELLED`	—
`SHIPMENT_INTERCEPTION_REQUESTED`	已申请拦截	主状态不变：`WAIT_SHIP` 或 `SHIPPED`	`reason`；可选 `remark`
`SHIPMENT_INTERCEPTION_PROCESSING`	拦截处理中	主状态不变：`WAIT_SHIP` 或 `SHIPPED`	`reason`；可选 `remark`
`SHIPMENT_INTERCEPTION_SUCCEEDED`	已成功拦截	主状态不变：`WAIT_SHIP` 或 `SHIPPED`	`reason`；可选 `remark`
`SHIPMENT_INTERCEPTION_FAILED`	拦截失败	主状态不变：`WAIT_SHIP` 或 `SHIPPED`	`reason`；可选 `failure_code`、`failure_message`
`PICKUP_STATION_ARRIVED`	已到达自提点	`SHIPPED`	`station_name`
`PICKUP_STATION_SHELVED`	已在自提点上架	`SHIPPED`	`station_name`
`PICKUP_STATION_CHECKED_OUT`	已从自提点出库	`SHIPPED`	`station_name`
`PICKUP_STATION_TRANSFERRED_OUT`	已从自提点转运出库	`SHIPPED`	`station_name`
`DISTRIBUTION_CENTER_SORTED`	已在分拨中心分拣	`SHIPPED`	可选 `facility_name`

拦截是独立流程：interception.status 按 REQUESTED → PROCESSING → INTERCEPTED 或 FAILED 流转，不覆盖顶层发货单状态。自提点名称同时出现在渲染完成的 title 和 details.station_name。

沙箱：GET /v1/fulfillment/shipments/sb_shp_shipped 含分箱、头尾程和打包影像。创建 → 支付后，动态 sbs_* 详情为 WAIT_SHIP，source_packages 已填、boxes 仍为空。

{
  "id": "107",
  "order_sn": "JIYUNRI1338",
  "status": "SHIPPED",
  "external_shipment_id": "MY-INTL-ORDER-001",
  "source_packages": [
    {
      "id": "pkg_01K2ABC001",
      "tracking_number": "SF2026082001"
    },
    {
      "id": "pkg_01K2ABC002",
      "tracking_number": "YT2026082002"
    }
  ],
  "receiver": {
    "name": "John Doe",
    "mobile": "+12025550123",
    "email": "john@example.com",
    "country_code": "US",
    "province": "California",
    "city": "Los Angeles",
    "district": null,
    "postal_code": "90001",
    "address_line1": "123 Main St",
    "address_line2": "Apt 4B",
    "personal_code": null
  },
  "shipping_channel": {
    "code": "PUHUO",
    "name": "General Cargo Air Line"
  },
  "multi_box": true,
  "international_tracking": {
    "tracking_number": "1Z999999999",
    "carrier": "UPS"
  },
  "timeline": [
    {
      "code": "SHIPMENT_PAID",
      "status": "WAIT_SHIP",
      "title": "发货单已支付",
      "occurred_at": "2026-08-20T10:30:00Z",
      "details": {}
    },
    {
      "code": "SHIPMENT_PACKED",
      "status": "WAIT_PAYMENT",
      "title": "发货单已完成打包",
      "occurred_at": "2026-08-20T10:20:00Z",
      "details": {}
    },
    {
      "code": "SHIPMENT_CREATED",
      "status": "PENDING",
      "title": "发货单已创建",
      "occurred_at": "2026-08-20T09:41:36Z",
      "details": {}
    }
  ],
  "boxes": [
    {
      "id": "box_01K2BOX001",
      "box_no": "JIYUNRI1338-1",
      "status": "SHIPPED",
      "source_package_ids": [
        "pkg_01K2ABC001",
        "pkg_01K2ABC002"
      ],
      "weight": {
        "value": 4.25,
        "unit": "kg"
      },
      "dimensions": {
        "length": 45,
        "width": 35,
        "height": 30,
        "unit": "cm"
      },
      "chargeable_weight": {
        "value": 4.73,
        "unit": "kg"
      },
      "tracking": {
        "tracking_number": "1Z999999001",
        "carrier": "UPS"
      }
    }
  ],
  "shipping_legs": [
    {
      "type": "FIRST_MILE",
      "carrier": "HioBuy Linehaul",
      "tracking_number": "HB202608200001",
      "origin_country": "CN",
      "destination_country": "US",
      "status": "DELIVERED",
      "shipped_at": "2026-08-20T12:00:00Z",
      "delivered_at": "2026-08-22T04:30:00Z"
    },
    {
      "type": "LAST_MILE",
      "carrier": "UPS",
      "tracking_number": "1Z999999999",
      "origin_country": "US",
      "destination_country": "US",
      "status": "IN_TRANSIT",
      "shipped_at": "2026-08-22T08:00:00Z",
      "delivered_at": null
    }
  ],
  "files": [
    {
      "id": "file_01K2ABC001",
      "type": "PACKING_IMAGE",
      "url": "https://cdn.hiobuy.com/shipments/JIYUNRI1338/packing-01.jpg",
      "created_at": "2026-08-20T10:20:00Z"
    }
  ],
  "charges": [
    {
      "type": "FREIGHT",
      "code": "FREIGHT",
      "name": "Shipping Fee",
      "amount": {
        "amount": 3200,
        "currency": "CNY"
      }
    },
    {
      "type": "COUPON_DISCOUNT",
      "code": "COUPON",
      "name": "Coupon Discount",
      "amount": {
        "amount": -300,
        "currency": "CNY"
      }
    }
  ],
  "total": {
    "charges": {
      "amount": 3200,
      "currency": "CNY"
    },
    "discount": {
      "amount": 300,
      "currency": "CNY"
    },
    "payable": {
      "amount": 2900,
      "currency": "CNY"
    },
    "paid": {
      "amount": 2900,
      "currency": "CNY"
    },
    "outstanding": {
      "amount": 0,
      "currency": "CNY"
    }
  },
  "payment_status": "PAID",
  "times": {
    "created_at": "2026-08-20T09:41:36Z",
    "updated_at": "2026-08-22T08:10:00Z",
    "packing_started_at": "2026-08-20T10:00:00Z",
    "packed_at": "2026-08-20T10:20:00Z",
    "paid_at": "2026-08-20T10:30:00Z",
    "shipped_at": "2026-08-20T12:00:00Z",
    "delivered_at": null,
    "cancelled_at": null
  },
  "interception": null,
  "monetary_unit": "CNY_minor",
  "request_id": "req_xxx"
}

费用 type 取值见响应模型。

获取支持

需要集成帮助？请联系开发者支持 support@hiobuy.com · 预计 1–2 个工作日内回复

发送邮件