发货单

创建、支付、取消、拦截、列表与查询国际发货单（/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 — 幂等键
remark

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`	外部订单号已存在

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

POST /v1/fulfillment/shipments/115/pay
Authorization: Bearer <API_KEY>

路径 {shipment_id} 即创建/详情 id（live 为仓库数字主键字符串，如 "115"）。仓库也接受 order_sn。沙箱为 sbs_* / sb_shp_*。body 可为空。仓库上游：POST /api/gateway-worker/v1/shipments/pay，仅 { "shipment_id" } — 不要传 external_shipment_id。

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

支付错误：

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`	余额不足

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

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

cancel_reason 必填。仓库上游：POST /api/gateway-worker/v1/shipments/cancel，body 为 { shipment_id, 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"
      },
      "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} 即详情 id（live：仓库数字主键字符串，如 "107"；沙箱：sbs_* / sb_shp_*）。可选 language 用于展示名（shipping_channel.name、services[].name、charges[].name）。不要依赖 status_name。

仓库上游：POST /api/gateway-worker/v1/shipments/detail，仅 { "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` 为 `null`
`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）。空数组为 []，不要省略。

沙箱：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"
  },
  "shipping_channel": {
    "code": "PUHUO",
    "name": "General Cargo Air Line"
  },
  "multi_box": true,
  "international_tracking": {
    "tracking_number": "1Z999999999",
    "carrier": "UPS"
  },
  "timeline": [
    {
      "code": "CREATED",
      "title": "Shipment created",
      "occurred_at": "2026-08-20T09:41:36Z"
    },
    {
      "code": "PACKED",
      "title": "Packed",
      "occurred_at": "2026-08-20T10:20:00Z"
    },
    {
      "code": "PAID",
      "title": "Paid",
      "occurred_at": "2026-08-20T10:30:00Z"
    }
  ],
  "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 个工作日内回复

发送邮件