履约 API 响应模型

标准响应（省略 response_format 或 "standard"）会带顶层字段：

字段	值	含义
`monetary_unit`	`"CNY_minor"`	响应中每个 `{ amount, currency }` 的 `amount` 均为人民币分；1 元 = 100 分

出现在带金额的接口：余额、运费估算、创建、取消（含 refund）、列表、详情、服务。支付、物流轨迹、物品属性，以及 response_format: "upstream" 不带此字段。

运费预估 — quotes[] {#freight-estimate-quotes}

字段	说明
`shipping_channel_code`	传给创建
`shipping_channel_name` / `description`	本地化文案（请求体中的 `language`）
`freight` / `total`	参考价 — 创建后以创建结果为准
`estimated_days_min` / `max`	在提供时的运输天数区间

创建 — pricing {#preview-create-pricing}

字段	说明
`freight`	国际干线运费
`services`	增值服务合计
`discount`	促销扣减
`total` / `total.payment`	`freight + services − discount`
`id` / `order_sn`	创建响应：Public `id` 取仓库数字主键（字符串）；`order_sn` 为仓库单号
`status`	`PENDING`、`WAIT_PAYMENT`、`WAIT_SHIP`、`SHIPPED`、`SIGNED`、`CANCELLED`

发货单列表 {#shipment-list}

GET /v1/fulfillment/shipments 返回轻量行。示例见发货单 · 列表。

字段	说明
`id` / `order_sn`	Public `id` 为仓库数字主键（字符串）；`order_sn` 为仓库单号
`external_shipment_id`	创建时的 ISV 幂等键；仓库空串 → `null`
`status`	`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`international_tracking`	`{ tracking_number, carrier }`。没有顶层 `tracking_number`
`receiver` / `shipping_channel` / `services[]`	与详情同形
`total`	详情风格：`charges` / `discount` / `payable` / `paid` / `outstanding`
`payment_status`	`UNPAID` / `PAID` / `PARTIAL`
`times`	`created_at` / `packed_at` / `paid_at` / `shipped_at` / `delivered_at` / `cancelled_at`
`pagination`	`page` / `page_size` / `total` / `total_pages`

列表不含 boxes、timeline、files、charges、shipping_legs、source_packages、interception。

发货单详情 {#shipment-detail}

GET /v1/fulfillment/shipments/{id} 是完整视图。创建 / 支付仍用汇总 total.freight / services / discount / payment。金额为分。示例见发货单 · 详情。

字段	说明
`id` / `order_sn`	Public `id`（路径参数）为仓库数字主键（字符串）；`order_sn` 为仓库单号
`external_shipment_id`	创建时的 ISV 幂等键；仓库空串 → `null`
`status`	`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`source_packages[]`	合箱前国内包裹（过渡期 `id` 可能为 `null`）
`receiver`	国际收件人；`country_code` 为大写 ISO；`district` 可为 `null`
`shipping_channel`	`{ code, name }`
`multi_box`	`boxes.length > 1` 时为 `true`
`boxes[]`	出库箱：`box_no`（仓库 `box_sn`）、`source_package_ids`（仓库 `package_ids`）、重量 / 尺寸、可选 `tracking`
`international_tracking`	`{ tracking_number, carrier }`；仓库空串 → `null`
`timeline[]`	仓库业务事件 `{ code, title, occurred_at }`。空 `code` → `null`
`shipping_legs[]`	有单号时为 `FIRST_MILE` / `LAST_MILE`；否则 `[]`
`files[]`	`PACKING_IMAGE` / `PACKING_VIDEO`
`services[]`	本单增值服务（`service_code`、`name`、`quantity`、`status`）
`charges[]`	费用行。折扣行为负数
`total`	`charges`（正费用）/ `discount`（正数）/ `payable` / `paid` / `outstanding`
`payment_status`	`UNPAID` / `PAID` / `PARTIAL`
`times`	`created_at` / `packed_at` / `paid_at` / `shipped_at` / `delivered_at` / …；未发生为 `null`

charges[].type：FREIGHT、VALUE_ADDED_SERVICE、CHANNEL_SERVICE_FEE、CHANNEL_RULE_FEE、INSURANCE、DUTIES_AND_TAXES、PACKAGE_SERVICE、COUPON_DISCOUNT、POINTS_DISCOUNT。

运单号在 international_tracking / boxes[].tracking / shipping_legs。详情 timeline 是仓库业务事件（打包 / 支付）。承运商扫描节点在国际物流追踪的 timeline[]（同为 { code, title, occurred_at }）。

余额 {#balance}

字段	说明
`balance.available`	可用于支付
`balance.frozen`	待处理运单占用
`balance.total`	可用 + 冻结

国际轨迹 {#international-trace}

发货单详情的子集 — 仅承运商扫描节点。

字段	说明
`id` / `order_sn`	与详情一致
`shipping_channel`	`{ code, name }`
`international_tracking`	`{ tracking_number, carrier }`；空字符串 → `null`
`status`	`PENDING` / `WAIT_PAYMENT` / `WAIT_SHIP` / `SHIPPED` / `SIGNED` / `CANCELLED`
`status_label`	仓库展示文案
`timeline[]`	`{ code, title, occurred_at }`；空 `code` → `null`；`title` 来自仓库 `description`

详情 timeline[] = 仓库业务节点；本接口 timeline[] = 承运商扫描节点。二者不要混用。

获取支持

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

发送邮件