物流订单 API
海运(整箱/拼箱)、空运、快递、FBA 与官网客户中心共用订单流程。支持下单、查询本人订单及应收账单、按状态修改或取消作废;后续订舱、出单由业务处理。
订单归属 AppKey 所属开发者绑定的官网客户。该客户须完成个人或企业实名认证;不能通过请求指定其他客户或业务员。
外部单号与重试#
client_order_no 在「同一客户 + 同一订单类型」内唯一,跨该客户不同应用也共用。相同单号和相同有效参数重试返回原订单,replayed=true;相同单号更换有效参数返回 HTTP 409 / code 1003。每次重试生成新的签名时间戳和 nonce,订单号与下单内容保持不变。超时后可按外部单号查订单,再以原内容重试。
公共参数#
所有POST接口使用 application/json,选项GET接口使用URL查询参数,并按鉴权文档签名。创建/修改/取消请求体最多256KB;明细列表每组最多200项。数字字段(含明细)范围为0–100000000,另有正数/整数要求时以下表为准。字符串通常最多255字;超过或另有上限时会单独注明。
先查看公共参数和所选订单类型的参数表。「是」为必填;条件项在对应条件满足时必填。有默认值的参数可以省略;传空字符串不等于省略,将按字段规则校验。联系人对象的 company、contact、tel、address 四项必填。漏填或格式错误会在一次响应中列出所有可校验的问题。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| client_order_no | string | 是 | 客户自己的订单号,1–64位字母、数字或 . _ : -,区分大小写;用于防重与后续查询。 |
| goods_type | string | 是 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| goods_pcs | integer | 是 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| goods_pcs_unit | string | 否 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| goods_weight | number | 是 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| goods_cbm | number | 海运 / FBA 必填 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| custom | object | 否 | 报关服务,可省略;子字段见“附加服务”。 |
| insurance | object | 否 | 保险服务,可省略;子字段见“附加服务”。 |
| collecting | array<object> | 否 | 集货/入仓快递明细,默认[],最多200项;子字段见“附加服务”。 |
| packup | array<object> | 否 | 上门提货安排,默认[],最多200项;子字段见“附加服务”。 |
| note | string | 否 | 客户备注,默认空字符串,最多255字。 |
海运(整箱 / 拼箱)#
/api/openapi/v1/orders/ocean/create支持整箱和拼箱。下面包含本接口全部公开顶层参数;packing[] 是柜型/柜量明细。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| client_order_no | string | 是 | 客户自己的订单号,1–64位字母、数字或 . _ : -,区分大小写;用于防重与后续查询。 |
| goods_type | string | 是 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| goods_pcs | integer | 是 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| goods_pcs_unit | string | 否 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| goods_weight | number | 是 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| goods_cbm | number | 海运 / FBA 必填 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| custom | object | 否 | 报关服务,可省略;子字段见“附加服务”。 |
| insurance | object | 否 | 保险服务,可省略;子字段见“附加服务”。 |
| collecting | array<object> | 否 | 集货/入仓快递明细,默认[],最多200项;子字段见“附加服务”。 |
| packup | array<object> | 否 | 上门提货安排,默认[],最多200项;子字段见“附加服务”。 |
| note | string | 否 | 客户备注,默认空字符串,最多255字。 |
| pol | string | 是 | 起运港内部 code,如 CNSHA;取港口字典 code,不要用 locode 替代。 |
| pod | string | 是 | 目的港内部 code,如 USLSA;必须与 pol 不同。 |
| carrier | string | 否 | 船公司内部 code,取船公司字典;默认空字符串。 |
| etc | string | 否 | 预计货好日期,建议 YYYY-MM-DD;默认空字符串。 |
| mx | integer | 否 | 进出口:1进口、2出口;默认2。 |
| transport_type | string | 否 | 运输类型,默认 fcl;拼箱传 lcl,其它可用值取 transport_types[].value。fcl/fob 须填柜型柜量。 |
| shipping_mode | string | 是 | 运输条款,取 shipping_modes[].value,如 CY-CY。 |
| goods_marks | string | 是 | 唛头,最多4000字。 |
| goods | string | 是 | 货物名称/描述,最多4000字;此处是文本。 |
| sender | integer | object | 是 | 发货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| consignee | integer | object | 是 | 收货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| notifier | integer | object | 是 | 通知人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| packing | array<object> | fcl / fob 必填 | 柜型/柜量明细,最多200项;整箱不得为空,拼箱可省略。子字段逐项列于下表。 |
| blt | integer | 否 | 提单类型,取 bill_types[].value,范围0–3,默认0。 |
| payment | integer | 否 | 运费付款方式:0预付、1到付;默认0。不是账单付款状态。 |
packing[] 柜型与货物明细#
以下路径中的 [] 表示数组中的一项。子字段的必填要求仅在提交该明细项时生效;每组最多200项。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| packing[].ctn_no | string | 否 | 集装箱号,最多255字。 |
| packing[].ctt | string | 是 | 柜型,取 container_sizes[].value,如20GP;提交明细项时须使用有效柜型。 |
| packing[].seal_no | string | 否 | 封条号,最多255字。 |
| packing[].ctn_num | number | fcl / fob 必填 | 柜量;fcl/fob必须为大于0的整数。 |
| packing[].qty | number | 否 | 该行货物件数,非负数。 |
| packing[].qty_unit | string | 否 | 该行包装单位,例如 CTN。 |
| packing[].wgt | number | 否 | 该行货物总重量,单位kg;外层 goods_weight 仍需填写。 |
| packing[].vol | number | 否 | 该行货物总体积,单位m³;外层 goods_cbm 仍需填写。 |
请求示例(填写实际选项后提交)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"pol": "CNSHA",
"pod": "USLSA",
"transport_type": "fcl",
"shipping_mode": "CY-CY",
"goods": "General cargo",
"goods_marks": "MY-MARKS",
"sender": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"consignee": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"notifier": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"packing": [
{
"ctt": "20GP",
"ctn_num": 1
}
]
}空运#
/api/openapi/v1/orders/air/create下面包含本接口全部公开顶层参数。goods_list[] 为分行货物数据,整票件重体请在顶层填写。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| client_order_no | string | 是 | 客户自己的订单号,1–64位字母、数字或 . _ : -,区分大小写;用于防重与后续查询。 |
| goods_type | string | 是 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| goods_pcs | integer | 是 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| goods_pcs_unit | string | 否 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| goods_weight | number | 是 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| goods_cbm | number | 海运 / FBA 必填 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| custom | object | 否 | 报关服务,可省略;子字段见“附加服务”。 |
| insurance | object | 否 | 保险服务,可省略;子字段见“附加服务”。 |
| collecting | array<object> | 否 | 集货/入仓快递明细,默认[],最多200项;子字段见“附加服务”。 |
| packup | array<object> | 否 | 上门提货安排,默认[],最多200项;子字段见“附加服务”。 |
| note | string | 否 | 客户备注,默认空字符串,最多255字。 |
| pol | string | 是 | 起飞机场 IATA 三字码,如 PVG。 |
| pod | string | 是 | 目的机场 IATA 三字码,如 LAX;必须与 pol 不同。 |
| airline | string | 否 | 航空公司内部 code 或 IATA 码,取航空公司字典;默认空字符串。 |
| etc | string | 否 | 预计货好日期,建议 YYYY-MM-DD;默认空字符串。 |
| mx | integer | 否 | 进出口:1进口、2出口;默认2。 |
| transport_type | string | 否 | 空运类型:regular普通空运(默认)、consol集中托运、chartered包机。 |
| air_mode | integer | 否 | 运输条款:0机场到机场(默认)、1 DDU、2 DDP、3 DAP、4双清。 |
| goods_marks | string | 否 | 唛头,默认空字符串,最多255字。 |
| goods | string | 是 | 货物名称/描述,最多255字;此处是文本。 |
| sender | integer | object | 是 | 发货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| consignee | integer | object | 是 | 收货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| notifier | integer | object | 是 | 通知人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| goods_list | array<object> | 否 | 货物明细,默认[],最多200项;子字段见下表。 |
goods_list[] 空运货物明细#
以下路径中的 [] 表示数组中的一项。子字段的必填要求仅在提交该明细项时生效;每组最多200项。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| goods_list[].goods | string | 否 | 该行品名,最多255字。 |
| goods_list[].goods_packing | string | 否 | 该行包装单位,如 CTN。 |
| goods_list[].goods_pcs | number | 否 | 该行包装件数,非负数。 |
| goods_list[].goods_weight | number | 否 | 该行总重量,单位kg。 |
| goods_list[].goods_length | number | 否 | 单件包装长度,单位cm。 |
| goods_list[].goods_width | number | 否 | 单件包装宽度,单位cm。 |
| goods_list[].goods_height | number | 否 | 单件包装高度,单位cm。 |
| goods_list[].goods_cbm | number | 否 | 该行总体积,单位m³;API不根据尺寸自动补算,按实际值提交。 |
请求示例(填写实际选项后提交)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"pol": "PVG",
"pod": "LAX",
"goods": "General cargo",
"sender": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"consignee": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"notifier": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"goods_list": [
{
"goods_packing": "CTN",
"goods_pcs": 2,
"goods_weight": 20,
"goods_length": 50,
"goods_width": 50,
"goods_height": 100
}
]
}快递#
/api/openapi/v1/orders/express/create外层 goods_pcs 是包装件数,goods_weight 是整票总重量;goods[] 内是申报商品。此接口仅有收货人和通知人,没有发货人参数,通知人不能当作发货人。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| client_order_no | string | 是 | 客户自己的订单号,1–64位字母、数字或 . _ : -,区分大小写;用于防重与后续查询。 |
| goods_type | string | 是 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| goods_pcs | integer | 是 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| goods_pcs_unit | string | 否 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| goods_weight | number | 是 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| goods_cbm | number | 海运 / FBA 必填 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| custom | object | 否 | 报关服务,可省略;子字段见“附加服务”。 |
| insurance | object | 否 | 保险服务,可省略;子字段见“附加服务”。 |
| collecting | array<object> | 否 | 集货/入仓快递明细,默认[],最多200项;子字段见“附加服务”。 |
| packup | array<object> | 否 | 上门提货安排,默认[],最多200项;子字段见“附加服务”。 |
| note | string | 否 | 客户备注,默认空字符串,最多255字。 |
| place_country | string | 是 | 目的国两位国家码,例如 US;必须存在于国家字典,服务端转大写。 |
| channel | string | 是 | 快递渠道代码,取 orders/options?order_type=express 返回的 channels[].value;须为启用的快递渠道。 |
| consignee | integer | object | 是 | 收货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| notifier | integer | object | 是 | 通知人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| goods_cost | number | 否 | 整票总货值:按 goods[] 每行计算后的 goods_cost 汇总,可省略;传入有效但不一致的金额时以计算结果为准。无明细为0,上限100000000。 |
| cost_currency | string | 否 | 商品申报币种,默认 USD;明细单价、行货值和总货值共用此币种。 |
| fare_declare | number | 否 | 申报运费,非负数,默认0,上限100000000。 |
| goods | array<object> | 否 | 申报商品,默认[],最多200项。每行 goods_pcs × goods_price 计算 goods_cost,保留两位小数后汇总外层总货值。数量或单价省略按0;不据此修改包装件数或重量。 |
goods[] 快递申报商品明细#
以下路径中的 [] 表示数组中的一项。子字段的必填要求仅在提交该明细项时生效;每组最多200项。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| goods[].goods_chs | string | 否 | 商品中文品名,最多255字。 |
| goods[].goods_en | string | 否 | 商品英文品名,最多255字。 |
| goods[].goods_pcs | number | 否 | 本行商品数量,不是箱数。例如1箱装2件商品,此处填2;省略按0计算货值。 |
| goods[].goods_price | number | 否 | 每件商品单价,币种沿用外层 cost_currency;省略按0。 |
| goods[].goods_cost | number | 否 | 本行合计货值,由数量×单价自动计算并保留两位小数,可省略;上限100000000。传入负数或非法值仍会校验失败。 |
| goods[].goods_hscode | string | 否 | 商品 HS 编码,以字符串提交以保留前导零,最多255字。 |
| goods[].goods_use | string | 否 | 商品用途,最多255字。 |
| goods[].goods_material | string | 否 | 商品材质,最多255字。 |
| goods[].goods_thumb | string | 否 | 商品图片地址,最多255字;不是图片二进制或Base64上传字段。 |
请求示例(填写实际选项后提交)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 1,
"goods_pcs_unit": "CTN",
"goods_weight": 5,
"goods_cbm": 0.02,
"goods_cost": 20,
"cost_currency": "USD",
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"place_country": "US",
"channel": "YOUR_EXP_CHANNEL",
"consignee": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"notifier": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"goods": [
{
"goods_chs": "示例商品",
"goods_en": "Sample goods",
"goods_pcs": 2,
"goods_price": 10,
"goods_cost": 20
}
]
}FBA / 专线#
/api/openapi/v1/orders/fba/createFBA仓库订单与专线共用此接口,通过 fba_type 区分。SKU明细与整票汇总需分别提交;API不会套用快递的货值重算规则。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| client_order_no | string | 是 | 客户自己的订单号,1–64位字母、数字或 . _ : -,区分大小写;用于防重与后续查询。 |
| goods_type | string | 是 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| goods_pcs | integer | 是 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| goods_pcs_unit | string | 否 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| goods_weight | number | 是 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| goods_cbm | number | 海运 / FBA 必填 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| custom | object | 否 | 报关服务,可省略;子字段见“附加服务”。 |
| insurance | object | 否 | 保险服务,可省略;子字段见“附加服务”。 |
| collecting | array<object> | 否 | 集货/入仓快递明细,默认[],最多200项;子字段见“附加服务”。 |
| packup | array<object> | 否 | 上门提货安排,默认[],最多200项;子字段见“附加服务”。 |
| note | string | 否 | 客户备注,默认空字符串,最多255字。 |
| pod | string | 是 | 目的国两位国家码,例如 US;必须存在于国家字典,服务端转大写。 |
| channel | string | 是 | FBA/专线渠道代码,取 orders/options?order_type=fba 返回的 channels[].value。 |
| fba_type | integer | 否 | 业务类型:0 FBA仓库订单(默认)、1专线。 |
| transport | integer | 否 | 运输方式:0海运、1空运(默认)、2铁路、3卡车。 |
| fba | string | fba_type = 0 必填 | FBA仓库代码,取 fba_warehouses[].value,须与 pod 目的国一致;仓库收货人自动生成。 |
| shipment_id | string | fba_type = 0 必填 | Amazon Shipment ID,最多255字。 |
| amazon_reference_id | string | fba_type = 0 必填 | Amazon Reference ID,最多255字。 |
| sender | integer | object | 否 | 发货人,可省略:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| consignee | integer | object | fba_type = 1 必填 | 专线收货人;FBA仓库订单由仓库自动生成:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| pot | string | 否 | 中转地,默认空字符串,最多255字。 |
| goods_cost | number | 否 | 整票货值,非负数,默认0,上限100000000;由调用方汇总 goods[].sku_amount 后传入。 |
| goods | array<object> | 否 | SKU明细,默认[],最多200项;子字段见下表。 |
goods[] FBA / 专线 SKU 明细#
以下路径中的 [] 表示数组中的一项。子字段的必填要求仅在提交该明细项时生效;每组最多200项。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| goods[].sku_no | string | 否 | SKU编号,最多255字。 |
| goods[].sku_packing | string | 否 | 包装单位,例如 CTN。 |
| goods[].sku_box_number | string | 否 | 箱号或箱号范围,最多255字。 |
| goods[].sku_nw | number | 否 | 单箱净重,单位kg。 |
| goods[].sku_gw | number | 否 | 单箱毛重,单位kg;该行总毛重=sku_ctns×sku_gw。 |
| goods[].sku_length | number | 否 | 单箱长度,单位cm。 |
| goods[].sku_width | number | 否 | 单箱宽度,单位cm。 |
| goods[].sku_height | number | 否 | 单箱高度,单位cm。 |
| goods[].sku_ctns | number | 否 | 该SKU箱数,非负数。 |
| goods[].sku_pcs | number | 否 | 该SKU商品总数量,不是每箱数量;用于数量×单价计算行货值。 |
| goods[].sku_price | number | 否 | 商品单价,官网口径为USD。 |
| goods[].sku_amount | number | 否 | 该行总货值;调用方计算 sku_pcs×sku_price 后提交,官网口径为USD。 |
| goods[].sku_vol | number | 否 | 该行总体积(m³);调用方计算 sku_ctns×长×宽×高÷1000000 后提交。 |
| goods[].sku_weight | number | 否 | 该行总毛重(kg);调用方计算 sku_ctns×sku_gw 后提交。 |
请求示例(填写实际选项后提交)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"pod": "US",
"channel": "YOUR_FBA_CHANNEL",
"fba_type": 0,
"transport": 0,
"fba": "ONT8",
"shipment_id": "YOUR_SHIPMENT_ID",
"amazon_reference_id": "YOUR_AMAZON_REFERENCE",
"sender": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"goods": [
{
"sku_no": "SKU-001",
"sku_packing": "CTN",
"sku_ctns": 2,
"sku_pcs": 10,
"sku_gw": 10,
"sku_nw": 9
}
]
}联系人对象#
发货人 sender、收货人 consignee、通知人 notifier 的可用范围见各创建表。每项可以传本人联系人ID,或下面的完整对象;对象中的四项必填,提交后保存为本客户联系人。不得使用其它客户的联系人ID。快递只有 consignee 和 notifier;目的国在外层 place_country,省州/城市写进 address,邮编填 post。
联系人对象不接受 id、auth 等内部字段。发送联系人ID时不要再嵌套对象;发送对象时 company、contact、tel、address 缺一不可。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| company | string | 是 | 公司/机构名称,最多255字。 |
| contact | string | 是 | 联系人姓名,最多255字。 |
| tel | string | 是 | 联系电话,建议含国际区号;最多255字。 |
| address | string | 是 | 完整地址,包含省/州、市、街道门牌等,最多4000字;没有独立省市字段。 |
| string | 否 | 邮箱,最多255字。 | |
| post | string | 否 | 邮政编码,以字符串提交以保留前导零,最多255字。 |
| duty | string | 否 | 税号,最多255字。 |
{
"consignee": {
"company": "Example Company",
"contact": "Jane Doe",
"tel": "+1-555-0100",
"address": "123 Example St, Los Angeles, CA, US",
"email": "[email protected]",
"post": "90001",
"duty": "YOUR_TAX_ID"
}
}附加服务#
四类创建均可使用以下对象/列表,子字段均为可选;省略表示不提交该服务。修改时对象或列表整体替换。明细数值可传JSON数字或数字字符串,建议传数字;没有说明自动计算的字段请自行计算后提交。
custom 报关服务#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| custom.custom | integer | string | 否 | 报关类型:0不报关、1一般贸易报关、2买单报关、3客户自报;海运可用逗号组合(如"1,3"),其它类型只能单选。 |
insurance 保险服务#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| insurance.is_buy | integer | 否 | 是否购买:0不购买、1购买。 |
| insurance.money_type | string | 否 | 保险金额币种,例如 USD/CNY。 |
| insurance.amount | number | 否 | 保险金额,非负数,上限100000000。 |
| insurance.beneficiary | string | 否 | 受益人,最多100字。 |
collecting[] 集货明细#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| collecting[].company | string | 否 | 国内集货快递公司,取 express_companies[].value,最多255字。 |
| collecting[].number | string | 否 | 入仓快递单号,最多255字;同一请求中规范化后的单号不能重复,只能绑定本人或未归属且未绑单的入仓记录。 |
| collecting[].note | string | 否 | 该票集货备注,最多255字。 |
packup[] 上门提货#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| packup[].time | string | 否 | 预约提货时间,建议 YYYY-MM-DD HH:mm:ss,最多255字。 |
| packup[].address | string | 否 | 提货详细地址,最多4000字。 |
| packup[].contact | string | 否 | 提货联系人,最多255字。 |
| packup[].tel | string | 否 | 提货联系电话,最多255字。 |
统一订单响应#
data 包含 order_id、order_no、order_type、client_order_no、work_no、status、status_name、replayed。hfs_no 仅快递/FBA返回,海运/空运不返回。首次创建通常 status=0(待确认);已收货的集货绑定可能返回实际更新状态。响应表示平台收单,后续状态以订单详情为准。
响应外层结构#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| code | integer | 始终返回 | 业务码:0成功,其它值见错误码说明。 |
| msg | string | 始终返回 | 结果说明或错误消息。 |
| request_id | string | 始终返回 | 本次请求追踪ID,排查问题时保留。 |
| data | object | 成功时 | 业务结果,下方字段表除特别说明外均相对于 data。 |
| credit_used | integer | 经过计费层时 | 本次消耗积分,订单接口为0;鉴权等前置失败时可能不附带。 |
| credit_balance | integer | 经过计费层时 | 剩余积分,-1表示不限量。 |
| quota | object | 经过计费层时 | 积分信息,与顶层 credit_used / credit_balance 对应。 |
| quota.cost | integer | 存在 quota 时 | 本次消耗积分,订单接口为0。 |
| quota.remain | integer | 存在 quota 时 | 剩余积分,-1表示不限量。 |
响应字段(data 内)#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order_id | integer | 始终返回 | 平台订单ID。 |
| order_no | string | 始终返回 | 系统订单号;即使按物流巴巴单号或工作号查询,此响应字段仍返回系统订单号。 |
| order_type | string | 始终返回 | 订单类型:ocean、air、express、fba。 |
| client_order_no | string | null | 始终返回 | 本次使用的外部订单号;按系统单号操作且未传外部单号时为null。 |
| work_no | string | 始终返回 | 工作号,AW开头,可为空。详情查询时可直接填入 order_no。 |
| hfs_no | string | 仅快递/FBA返回;海运/空运不返回此字段 | 物流巴巴单号:快递EV开头、FBA FV开头,可为空。详情查询时可直接填入 order_no。 |
| status | integer | 始终返回 | 订单状态:0待确认、1预报、2确认订单、4已收货、5已发货、6退件、7作废、8缺货、9待定。 |
| status_name | string | 始终返回 | 当前状态名称,按服务端实际文字返回。 |
| replayed | boolean | 始终返回 | 创建/修改/取消的重复请求命中时为true;详情与轨迹为false。 |
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"order_id": 123,
"order_no": "EXAMPLE_ORDER_NUMBER",
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"work_no": "AW2026111001",
"status": 0,
"status_name": "待确认",
"replayed": false
},
"credit_used": 0
}下单选项(免费)#
/api/openapi/v1/orders/options?order_type=fba&country=USGET 参数 order_type:ocean / air / express / fba,默认 ocean。返回官网同源的 goods_types、pcs_units、container_sizes、transport_types、shipping_modes、bill_types、custom_types、insurance_options、payment_options 等选项,每项含 label/value;空运另有 air_transport_types、air_modes,FBA另有 fba_types、fba_transports。快递/FBA另返回有效 channels(最多30项),可用 keyword 搜索;FBA另返回 fba_warehouses(最多50项),可用 country 两位国家码和 keyword 过滤。
下单不做港口名称匹配:海运请用港口字典 code 或运价响应 resolved.pol.code / resolved.pod.code;空运使用机场 IATA 码。船司、航司从基础字典选取。
URL 查询参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_type | string | 否 | 订单类型:ocean、air、express、fba;默认ocean。 |
| keyword | string | 否 | 搜索渠道代码/名称或FBA仓库代码/地址,最多100字;默认空字符串。 |
| country | string | 否 | FBA仓库目的国过滤,两位国家码,如US;默认不按国家过滤,不用于渠道筛选。 |
选项响应字段(data 内)#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| goods_types | array<object> | 始终返回 | 货物类型,用于 goods_type。 每项 label:string(名称)、value:string(提交值)。 |
| pcs_units | array<object> | 始终返回 | 包装单位,用于 goods_pcs_unit。 每项 label:string(名称)、value:string(提交值)。 |
| container_sizes | array<object> | 始终返回 | 海运柜型,用于 packing[].ctt。 每项 label:string(名称)、value:string(提交值)。 |
| transport_types | array<object> | 始终返回 | 海运运输类型,用于 transport_type。 每项 label:string(名称)、value:string(提交值)。 |
| shipping_modes | array<object> | 始终返回 | 海运运输条款,用于 shipping_mode。 每项 label:string(名称)、value:string(提交值)。 |
| bill_types | array<object> | 始终返回 | 海运提单类型,用于 blt。 每项 label:string(名称)、value:integer(提交值)。 |
| custom_types | array<object> | 始终返回 | 报关类型,用于 custom.custom。 每项 label:string(名称)、value:integer(提交值)。 |
| insurance_options | array<object> | 始终返回 | 是否买保险,用于 insurance.is_buy。 每项 label:string(名称)、value:integer(提交值)。 |
| payment_options | array<object> | 始终返回 | 海运预付/到付,用于 payment。 每项 label:string(名称)、value:integer(提交值)。 |
| express_companies | array<object> | 始终返回 | 国内集货快递公司,用于 collecting[].company。 每项 label:string(名称)、value:string(提交值)。 |
| air_transport_types | array<object> | 始终返回 | 空运运输类型,用于 transport_type。 每项 label:string(名称)、value:string(提交值)。 |
| air_modes | array<object> | 始终返回 | 空运运输条款,用于 air_mode。 每项 label:string(名称)、value:integer(提交值)。 |
| fba_types | array<object> | 始终返回 | FBA/专线类型,用于 fba_type。 每项 label:string(名称)、value:integer(提交值)。 |
| fba_transports | array<object> | 始终返回 | FBA运输方式,用于 transport。 每项 label:string(名称)、value:integer(提交值)。 |
| channels | array<object> | 快递 / FBA | 启用渠道,最多30项,用于 channel。 每项 label:string(名称)、value:string(提交值)。 |
| fba_warehouses | array<object> | FBA | FBA仓库,最多50项,用于 fba;有下表额外字段。 每项 label:string(名称)、value:string(提交值)。 |
选项对象及仓库额外字段#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| label | string | 始终返回 | 选项显示名称;适用于上表所有选项列表。 |
| value | string | integer | 始终返回 | 提交给业务字段的值;具体类型由上表逐项标明,不要提交 label。 |
| fba_warehouses[].id | integer | string | 始终返回 | 仓库记录ID;下单 fba 使用 value/code。 |
| fba_warehouses[].code | string | 始终返回 | 仓库代码,与 value 相同。 |
| fba_warehouses[].country | string | 始终返回 | 仓库所在国两位代码。 |
| fba_warehouses[].address | string | null | 始终返回 | 仓库地址。 |
| fba_warehouses[].zip | string | null | 始终返回 | 仓库邮政编码。 |
本人订单详情(免费)#
/api/openapi/v1/orders/detailPOST 参数 order_type 必填;order_no 可填写系统订单号、物流巴巴单号或工作号,三种号码使用同一个参数,无需分别填写。也可按 client_order_no 查询;同时传入时优先使用 client_order_no,未找到不回退。仅在当前客户、指定订单类型内精确匹配,重号返回1001。返回完整订单信息、联系人、货物和附加服务;海运货物为 packing,其他类型为 goods_list;bills 仅包含开给当前客户的已核应收账单,无符合条件的账单时为 []。
详情查询的 order_no 统一接收三种单号:系统订单号(SEA… / AIR… / EXP… / FBA…)、物流巴巴单号(快递 EV…,FBA FV…)、工作号(AW…)。响应中的 order_no 始终是系统订单号;hfs_no 和 work_no 分别返回物流巴巴单号和工作号。轨迹、修改、取消接口仍使用系统订单号或 client_order_no。
开发者控制台中的订单调用日志展示脱敏摘要,隐藏联系人、货物、附加服务、账单和轨迹明细。请查看客户端实际收到的完整响应核对详情;log_redacted 仅标记日志摘要,不属于接口响应字段。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_type | string | 是 | 订单类型:ocean、air、express、fba。 |
| client_order_no | string | order_no 与 client_order_no 至少填一个 | API创建时的外部订单号,优先级最高。 |
| order_no | string | order_no 与 client_order_no 至少填一个 | 统一查询单号,最多100字:可填系统订单号、物流巴巴单号(快递EV开头、FBA FV开头)或工作号(AW开头);自动去除首尾空白,精确匹配。 |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001"
}{
"order_type": "express",
"order_no": "EV261105001CN"
}{
"order_type": "ocean",
"order_no": "AW2026111001"
}兼容旧调用:独立的 hfs_no、work_no 参数仍可用(string,最多100字);hfs_no 仅快递/FBA。优先级为 client_order_no → order_no → hfs_no → work_no,选中的参数未找到时不回退。新接入只需使用 order_no。以上示例号码均为虚拟数据。
详情响应结构(另含统一订单响应字段)#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order_id | integer | 始终返回 | 平台订单ID。 |
| order_no | string | 始终返回 | 系统订单号;即使按物流巴巴单号或工作号查询,此响应字段仍返回系统订单号。 |
| order_type | string | 始终返回 | 订单类型:ocean、air、express、fba。 |
| client_order_no | string | null | 始终返回 | 本次使用的外部订单号;按系统单号操作且未传外部单号时为null。 |
| work_no | string | 始终返回 | 工作号,AW开头,可为空。详情查询时可直接填入 order_no。 |
| hfs_no | string | 仅快递/FBA返回;海运/空运不返回此字段 | 物流巴巴单号:快递EV开头、FBA FV开头,可为空。详情查询时可直接填入 order_no。 |
| status | integer | 始终返回 | 订单状态:0待确认、1预报、2确认订单、4已收货、5已发货、6退件、7作废、8缺货、9待定。 |
| status_name | string | 始终返回 | 当前状态名称,按服务端实际文字返回。 |
| replayed | boolean | 始终返回 | 创建/修改/取消的重复请求命中时为true;详情与轨迹为false。 |
| order | object | 始终返回 | 当前订单主信息;业务字段沿用对应创建表中的同名标量字段,联系人字段为ID,额外只读字段见下表。 |
| sender_info | object | null | 始终返回 | 发货人详情,字段同联系人表;不存在或不属于当前客户时为null。 |
| consignee_info | object | null | 始终返回 | 收货人详情,字段同联系人表;不存在或不属于当前客户时为null。 |
| notifier_info | object | null | 始终返回 | 通知人详情,字段同联系人表;不存在或不属于当前客户时为null。 |
| custom | object | null | 始终返回 | 报关服务,无记录为null;除请求字段外,还返回报关名称、单号及附件,见只读明细。 |
| insurance | object | null | 始终返回 | 保险服务,字段同 insurance 请求对象;无记录为null。 |
| collecting | array<object> | 始终返回 | 集货记录,字段同 collecting[] 请求项;无记录为[]。 |
| packup | array<object> | 始终返回 | 提货安排,无记录为[];包含请求字段及只读司机trucker。 |
| packing | array<object> | 海运 | 柜型货物明细,字段同海运 packing[];无记录为[]。 |
| goods_list | array<object> | 空运 / 快递 / FBA | 货物明细,字段同该类型创建明细;快递/FBA创建时的 goods[] 在详情中改名为 goods_list[]。 |
| bills | array<object> | 始终返回 | 本人已核应收账单,字段见“订单应收账单”;无可见账单为[]。 |
| files | array<object> | 始终返回 | 当前订单标记为客户可见的附件;隐藏附件不返回,无可见附件为[]。字段见下方只读明细。 |
订单主信息字段#
下表逐项列出 order 的业务字段;按实际订单类型返回已有字段。数据库中的数值可能返回数字字符串,请按业务类型解析。子对象和列表在 data 顶层,见上表;不是嵌套在 order 中。日期/时间沿用原记录,不推断时区。
海运(整箱 / 拼箱)
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order.goods_type | string | null | 海运(整箱 / 拼箱) | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| order.goods_pcs | number | string | null | 海运(整箱 / 拼箱) | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| order.goods_pcs_unit | string | null | 海运(整箱 / 拼箱) | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| order.goods_weight | number | string | null | 海运(整箱 / 拼箱) | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| order.goods_cbm | number | string | null | 海运(整箱 / 拼箱) | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| order.note | string | null | 海运(整箱 / 拼箱) | 客户备注,默认空字符串,最多255字。 |
| order.pol | string | null | 海运(整箱 / 拼箱) | 起运港内部 code,如 CNSHA;取港口字典 code,不要用 locode 替代。 |
| order.pod | string | null | 海运(整箱 / 拼箱) | 目的港内部 code,如 USLSA;必须与 pol 不同。 |
| order.carrier | string | null | 海运(整箱 / 拼箱) | 船公司内部 code,取船公司字典;默认空字符串。 |
| order.etc | string | null | 海运(整箱 / 拼箱) | 预计货好日期,建议 YYYY-MM-DD;默认空字符串。 |
| order.mx | number | string | null | 海运(整箱 / 拼箱) | 进出口:1进口、2出口;默认2。 |
| order.transport_type | string | null | 海运(整箱 / 拼箱) | 运输类型,默认 fcl;拼箱传 lcl,其它可用值取 transport_types[].value。fcl/fob 须填柜型柜量。 |
| order.shipping_mode | string | null | 海运(整箱 / 拼箱) | 运输条款,取 shipping_modes[].value,如 CY-CY。 |
| order.goods_marks | string | null | 海运(整箱 / 拼箱) | 唛头,最多4000字。 |
| order.goods | string | null | 海运(整箱 / 拼箱) | 货物名称/描述,最多4000字;此处是文本。 |
| order.sender | number | string | null | 海运(整箱 / 拼箱) | 发货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.consignee | number | string | null | 海运(整箱 / 拼箱) | 收货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.notifier | number | string | null | 海运(整箱 / 拼箱) | 通知人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.blt | number | string | null | 海运(整箱 / 拼箱) | 提单类型,取 bill_types[].value,范围0–3,默认0。 |
| order.payment | number | string | null | 海运(整箱 / 拼箱) | 运费付款方式:0预付、1到付;默认0。不是账单付款状态。 |
空运
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order.goods_type | string | null | 空运 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| order.goods_pcs | number | string | null | 空运 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| order.goods_pcs_unit | string | null | 空运 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| order.goods_weight | number | string | null | 空运 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| order.goods_cbm | number | string | null | 空运 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| order.note | string | null | 空运 | 客户备注,默认空字符串,最多255字。 |
| order.pol | string | null | 空运 | 起飞机场 IATA 三字码,如 PVG。 |
| order.pod | string | null | 空运 | 目的机场 IATA 三字码,如 LAX;必须与 pol 不同。 |
| order.airline | string | null | 空运 | 航空公司内部 code 或 IATA 码,取航空公司字典;默认空字符串。 |
| order.etc | string | null | 空运 | 预计货好日期,建议 YYYY-MM-DD;默认空字符串。 |
| order.mx | number | string | null | 空运 | 进出口:1进口、2出口;默认2。 |
| order.transport_type | string | null | 空运 | 空运类型:regular普通空运(默认)、consol集中托运、chartered包机。 |
| order.air_mode | number | string | null | 空运 | 运输条款:0机场到机场(默认)、1 DDU、2 DDP、3 DAP、4双清。 |
| order.goods_marks | string | null | 空运 | 唛头,默认空字符串,最多255字。 |
| order.goods | string | null | 空运 | 货物名称/描述,最多255字;此处是文本。 |
| order.sender | number | string | null | 空运 | 发货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.consignee | number | string | null | 空运 | 收货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.notifier | number | string | null | 空运 | 通知人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
快递
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order.goods_type | string | null | 快递 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| order.goods_pcs | number | string | null | 快递 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| order.goods_pcs_unit | string | null | 快递 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| order.goods_weight | number | string | null | 快递 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| order.goods_cbm | number | string | null | 快递 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| order.note | string | null | 快递 | 客户备注,默认空字符串,最多255字。 |
| order.place_country | string | null | 快递 | 目的国两位国家码,例如 US;必须存在于国家字典,服务端转大写。 |
| order.channel | string | null | 快递 | 快递渠道代码,取 orders/options?order_type=express 返回的 channels[].value;须为启用的快递渠道。 |
| order.consignee | number | string | null | 快递 | 收货人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.notifier | number | string | null | 快递 | 通知人:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.goods_cost | number | string | null | 快递 | 整票总货值:按 goods[] 每行计算后的 goods_cost 汇总,可省略;传入有效但不一致的金额时以计算结果为准。无明细为0,上限100000000。 |
| order.cost_currency | string | null | 快递 | 商品申报币种,默认 USD;明细单价、行货值和总货值共用此币种。 |
| order.fare_declare | number | string | null | 快递 | 申报运费,非负数,默认0,上限100000000。 |
FBA / 专线
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order.goods_type | string | null | FBA / 专线 | 货物类型,取下单选项 goods_types[].value;多个值用逗号连接,合计最多50字。 |
| order.goods_pcs | number | string | null | FBA / 专线 | 整票运输包装件数,范围1–100000000,配合 goods_pcs_unit。快递填箱数等包装数量,不等于 goods[] 商品数量。 |
| order.goods_pcs_unit | string | null | FBA / 专线 | 包装单位,默认 CTN;取 pcs_units[].value,例如 CTN 表示箱。 |
| order.goods_weight | number | string | null | FBA / 专线 | 整票总毛重,单位kg,必须大于0且不超过100000000;多件重量相加后填写,系统不会再乘件数。 |
| order.goods_cbm | number | string | null | FBA / 专线 | 整票总体积,单位m³,最高100000000。海运/FBA必须大于0;空运/快递可省略,默认0。 |
| order.note | string | null | FBA / 专线 | 客户备注,默认空字符串,最多255字。 |
| order.pod | string | null | FBA / 专线 | 目的国两位国家码,例如 US;必须存在于国家字典,服务端转大写。 |
| order.channel | string | null | FBA / 专线 | FBA/专线渠道代码,取 orders/options?order_type=fba 返回的 channels[].value。 |
| order.fba_type | number | string | null | FBA / 专线 | 业务类型:0 FBA仓库订单(默认)、1专线。 |
| order.transport | number | string | null | FBA / 专线 | 运输方式:0海运、1空运(默认)、2铁路、3卡车。 |
| order.fba | string | null | FBA / 专线 | FBA仓库代码,取 fba_warehouses[].value,须与 pod 目的国一致;仓库收货人自动生成。 |
| order.shipment_id | string | null | FBA / 专线 | Amazon Shipment ID,最多255字。 |
| order.amazon_reference_id | string | null | FBA / 专线 | Amazon Reference ID,最多255字。 |
| order.sender | number | string | null | FBA / 专线 | 发货人,可省略:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.consignee | number | string | null | FBA / 专线 | 专线收货人;FBA仓库订单由仓库自动生成:本人联系人ID或完整联系人对象,字段见“联系人”。 |
| order.pot | string | null | FBA / 专线 | 中转地,默认空字符串,最多255字。 |
| order.goods_cost | number | string | null | FBA / 专线 | 整票货值,非负数,默认0,上限100000000;由调用方汇总 goods[].sku_amount 后传入。 |
订单主信息的额外只读字段#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| order.etd | integer | string | null | 该类型订单含此字段时 | 历史日期字段,沿用原类型和值;快递为原入仓日期,其他类型为原预计起运日期/时间。 |
| order.eta | string | null | 该类型订单含此字段时 | 预计到达日期或时间,沿用原记录,可为空。 |
| order.vessel | string | null | 该类型订单含此字段时 | 船舶字段,按原订单记录返回。 |
| order.ves_name | string | null | 该类型订单含此字段时 | 船名,按原订单记录返回。 |
| order.ves_no | string | null | 该类型订单含此字段时 | 航次,按原订单记录返回。 |
| order.booking_number | string | null | 该类型订单含此字段时 | 订舱号,由业务录入,未录入时可为空。 |
| order.hbl_no | string | null | 该类型订单含此字段时 | 分单号,未录入时可为空。 |
| order.mbl_no | string | null | 该类型订单含此字段时 | 主单号,未录入时可为空。 |
| order.serve_no | string | null | 该类型订单含此字段时 | 服务商单号,按原订单记录返回。 |
| order.receipt_time | string | null | 仅FBA详情固定返回 | FBA入仓时间,格式 YYYY-MM-DD HH:mm:ss,北京时间(Asia/Shanghai,UTC+08:00);未录入或无效为null。快递不返回此字段。历史数据仅有日期时补00:00:00,不代表真实午夜入仓。 |
| order.transfer_no | string | null | 快递/FBA详情固定返回 | 统一转单号/服务商单号;多个号码以英文逗号分隔,未录入为null。快递原 order.serve_no 保留兼容。 |
| order.created_at | integer | string | null | 该类型订单含此字段时 | 创建时间,可能为Unix秒级时间戳或历史时间文本,沿用原记录。 |
| order.updated_at | integer | string | null | 该类型订单含此字段时 | 最近更新时间,可能为Unix秒级时间戳或历史时间文本,沿用原记录。 |
| order.pol_name | string | 适用订单类型/原记录包含时 | 起运港/机场名称,字典无匹配时回退代码。 |
| order.pod_name | string | 适用订单类型/原记录包含时 | 目的港/机场/国家名称,字典无匹配时回退代码。 |
| order.place_name | string | 适用订单类型/原记录包含时 | 快递目的国家名称,字典无匹配时回退国家码。 |
| order.carrier_name | string | 适用订单类型/原记录包含时 | 船公司/航空公司名称,字典无匹配时回退代码。 |
| order.channel_name | string | 适用订单类型/原记录包含时 | 快递/FBA渠道显示名称,无匹配时回退channel。 |
| order.transport_name | string | 适用订单类型/原记录包含时 | 运输方式显示名称。 |
| order.goods_type_name | string | 适用订单类型/原记录包含时 | 货物类型显示名称,支持多类型组合。 |
| order.air_mode_name | string | 适用订单类型/原记录包含时 | 空运运输条款名称;原air_mode仍返回数值代码。 |
| order.created_time | string | null | 适用订单类型/原记录包含时 | 创建时间,YYYY-MM-DD HH:mm:ss,北京时间;缺失/无效为null。 |
| order.track_status | integer | string | null | 适用订单类型/原记录包含时 | 原订单保存的跟踪状态码,可为空;具体轨迹请使用tracking接口。 |
| order.track_name | string | null | 适用订单类型/原记录包含时 | 原订单保存的跟踪状态名称,存在时返回。 |
| order.cost_currency | string | null | 适用订单类型/原记录包含时 | 申报货值币种,原订单有记录时返回。 |
详情附加只读字段(不作为下单/修改参数)#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| custom.custom_name | string | 父对象/记录存在时 | 报关方式名称。 |
| custom.custom_num | string | null | 父对象/记录存在时 | 报关单号,未录入为null。 |
| custom.custom_file | array<string> | 父对象/记录存在时 | 报关附件路径,单值/JSON历史记录统一为数组;无附件为[]。 |
| custom.name | array<string> | 父对象/记录存在时 | 报关附件名称,与附件路径对应;无名称为[]。 |
| insurance.is_buy_name | string | 父对象/记录存在时 | 是否购买保险的显示文字。 |
| packup[].trucker | string | null | 父对象/记录存在时 | 提货司机信息,未录入为null。 |
| goods_list[].goods_weight | number | string | null | 父对象/记录存在时 | 快递原明细有记录时返回的货物重量(kg),只读;空运对应原goods_list字段。 |
| files[].id | integer | 父对象/记录存在时 | 客户可见附件ID。 |
| files[].title | string | null | 父对象/记录存在时 | 附件标题。 |
| files[].path | string | 父对象/记录存在时 | 原始附件路径,保留兼容;查看或下载请直接使用同一记录的url。相对路径对应https://fms.5688.cn,不是www官网域名。 |
| files[].url | string | null | 父对象/记录存在时 | 可直接查看或下载的完整HTTP(S)链接,无需拼接域名。相对路径自动补https://fms.5688.cn,已有完整链接保留;路径缺失或无法生成链接时为null。图片通常在浏览器预览,可另存为或由程序下载文件内容。 |
| files[].created_at | integer | string | null | 父对象/记录存在时 | 附件创建时间,Unix秒级时间戳或历史时间文本。 |
order.receipt_time(入仓时间)仅FBA详情返回,格式为北京时间 YYYY-MM-DD HH:mm:ss,未录入时为null;快递不返回此字段。快递/FBA均保留 order.transfer_no(转单号),类型为 string | null。下方为FBA局部响应示例。
{
"order_type": "fba",
"order": {
"receipt_time": "2026-11-05 00:00:00",
"transfer_no": "EXAMPLE_CARRIER_NUMBER"
}
}海运详情的 order.booking_number 为业务人员录入的订舱号,order.mbl_no / order.hbl_no 为主单/分单号。未录入时可以为空字符串;平台接单、账单已核或已支付均不保证已取得订舱号。
海运付款方式与付款条件#
海运 payment=0 为预付(Prepaid),payment=1 为到付(Collect),默认 0;详情从 order.payment 返回。此字段表示运费预付/到付方式,不包含订金比例、付款截止时间、月结账期或授信额度。具体付款条件需与业务员确认;账单是否已支付请查看 bills[].pay_status,不能用 payment 判断。
订单应收账单#
沿用官网订单详情口径:订单属于当前客户,账单付款客户也必须是当前客户;仅返回已核单/已核销的应收账单。未核单、反核单、应付、其他客户账单及已拆分母单/中间节点不返回。拆分子单金额以自身split_fee为准,只有同订单、同付款客户的已核应收母单且金额对应时才展示母单费用明细,否则quotes为空。金额按原币种分别汇总,total_cny仅为按官网汇率口径折算的人民币参考金额;FBA按入仓日期,其余按ETD。只返回客户账单及费用字段,不返回内部备注、制单人、供应商或拆分母单标识。
费用确认请查看 bills[].total_by_currency 和费用明细。返回的是当前已核应收,各币种分别汇总;total_cny 为人民币参考折算,不表示实收金额。账单可能随业务调整,接口未提供永久锁定的 final_price;bills=[] 也不表示订单免费。
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| bills[].bill_code | string | 始终返回 | 当前客户账单号。 |
| bills[].pay_status | integer | 始终返回 | 付款状态:0未支付、1已支付。 |
| bills[].pay_status_name | string | 始终返回 | 付款状态说明。 |
| bills[].total_by_currency | object | 始终返回 | 按币种汇总,如 {"USD":100,"CNY":300};无金额时为{}。 |
| bills[].total_by_currency.{currency} | number | 该币种存在时 | 动态键为币种代码,值为该币种金额;不同币种不要直接相加。 |
| bills[].total_cny | number | 始终返回 | 按官网汇率口径折算的人民币参考金额,不代表实际收款金额。 |
| bills[].total_display | string | 始终返回 | 原币汇总显示文字。 |
| bills[].quotes | array<object> | 始终返回 | 费用明细;拆分账单不满足归属/金额匹配条件时为[]。 |
| bills[].quotes[].item | string | 始终返回 | 费用代码。 |
| bills[].quotes[].item_name | string | 始终返回 | 费用名称。 |
| bills[].quotes[].price | number | 始终返回 | 费用单价,币种见 money_type。 |
| bills[].quotes[].num | number | 始终返回 | 计费数量。 |
| bills[].quotes[].unit | string | 始终返回 | 计费单位,如票、箱。 |
| bills[].quotes[].amount | number | 始终返回 | 该项原币金额。 |
| bills[].quotes[].money_type | string | 始终返回 | 该费用币种;原记录为空时按CNY返回。 |
| bills[].quotes[].amount_cny | number | 始终返回 | 该项人民币参考金额。 |
详情响应示例(虚拟数据)#
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"order_id": 123,
"order_no": "EXAMPLE_ORDER_NUMBER",
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"work_no": "AW2026111001",
"status": 0,
"status_name": "待确认",
"replayed": false,
"order": {
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"pol": "CNSHA",
"pol_name": "Shanghai",
"pod": "USLSA",
"pod_name": "Los Angeles",
"transport_type": "fcl",
"transport_name": "整柜",
"goods_type_name": "普货",
"created_time": "2026-11-05 09:00:00",
"booking_number": "",
"mbl_no": "",
"hbl_no": "",
"blt": 0,
"payment": 0
},
"sender_info": {
"company": "Example Shipper",
"contact": "Sender",
"tel": "+86-00000000000",
"email": "",
"address": "Example origin address",
"post": "",
"duty": ""
},
"consignee_info": {
"company": "Example Consignee",
"contact": "Recipient",
"tel": "+1-555-0100",
"email": "",
"address": "Example destination address",
"post": "",
"duty": ""
},
"notifier_info": null,
"custom": null,
"insurance": null,
"collecting": [],
"packup": [],
"files": [
{
"id": 123,
"title": "example-document.pdf",
"path": "/storage/oms/files/example-document.pdf",
"url": "https://fms.5688.cn/storage/oms/files/example-document.pdf",
"created_at": 1793840400
}
],
"packing": [
{
"ctn_no": "",
"ctt": "20GP",
"seal_no": "",
"ctn_num": 1,
"qty": 2,
"qty_unit": "CTN",
"wgt": 20,
"vol": 0.5
}
],
"bills": [
{
"bill_code": "EXAMPLE_BILL_CODE",
"pay_status": 0,
"pay_status_name": "未支付",
"total_by_currency": {
"CNY": 300
},
"total_cny": 300,
"total_display": "CNY 300.00",
"quotes": [
{
"item": "DOC",
"item_name": "文件费",
"price": 300,
"num": 1,
"unit": "票",
"amount": 300,
"money_type": "CNY",
"amount_cny": 300
}
]
}
]
},
"credit_used": 0
}查询本人订单轨迹#
/api/openapi/v1/orders/tracking固定免费0积分。查询参数:order_type为ocean/air/express/fba,client_order_no与order_no至少传一个,同时传时优先client_order_no;order_no为系统订单号,不是工作号或承运商运单号。仍需签名、客户启用与实名认证,并遵循原有限速。仅返回当前客户订单已保存的自动和人工轨迹,不实时访问承运商或触发抓取,不保证每种运输方式或每个单号都有轨迹。没有轨迹时events=[],不代表单号无效或货物未运输。事件按时间倒序,预计节点可能排在最前,不能据此认定已到港或已签收。时间按原记录返回,不附加或推断时区。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_type | string | 是 | 订单类型:ocean、air、express、fba。 |
| client_order_no | string | 与 order_no 至少填一个 | 创建时的外部订单号;同时传 order_no 时优先使用此字段。 |
| order_no | string | 与 client_order_no 至少填一个 | 系统订单号,取创建响应 data.order_no;不能填工作号、物流巴巴单号或承运商运单号。 |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001"
}响应字段(data 内)#
data 除下面的 events 字段外,还包含统一订单响应中的全部字段。
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| events | array<object> | 始终返回 | 已保存轨迹;无数据时为空数组 |
| events[].time | string | 始终返回 | 事件时间,按原记录返回 |
| events[].place | string | 始终返回 | 事件地点,可为空 |
| events[].description | string | 始终返回 | 原始轨迹描述,语言沿用原记录 |
| events[].tracking_no | string | 始终返回 | 关联运单号;人工或历史记录可能为空 |
| events[].is_forecast | boolean | 始终返回 | true表示预计,不能当作已经发生 |
| events[].has_time | boolean | 始终返回 | 是否含有效时分;false按日期展示 |
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"order_id": 123,
"order_no": "EXAMPLE_ORDER_NUMBER",
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"work_no": "AW2026111001",
"status": 0,
"status_name": "待确认",
"replayed": false,
"events": [
{
"time": "2026-01-02 10:30:00",
"place": "EXAMPLE_PORT",
"description": "Loaded on vessel",
"tracking_no": "EXAMPLE_TRACKING_NUMBER",
"is_forecast": false,
"has_time": true
}
]
},
"credit_used": 0
}修改本人订单(免费)#
/api/openapi/v1/orders/updateorder_type 必填,另传 client_order_no 或 order_no;同时传入时按 client_order_no 查询。仅本人 status=0(待确认)或1(预报)的订单可修改,已完结订单仍禁止编辑。changes 为非空对象,只能包含该类型下单文档中的业务字段;未提交的字段和明细保留原值。提交的对象或列表整体替换,可选明细传空对象/数组可清空;整箱 packing 等必填项不能清空。快递提交 goods 或 goods_cost 时,按商品数量×单价重算明细货值并同步总货值;goods=[] 清空明细且总货值归零,只改其它字段不重算历史货值。联系人沿用本人ID或联系人对象规则。不能修改订单号、客户归属、内部状态、订舱号、内部成本或账单。返回当前订单标识及状态;相同内容重复提交不重复创建联系人或记录修改日志,replayed=true。改单不改变原创建请求的防重记录,重新发送原创建请求仅返回当前订单。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_type | string | 是 | 订单类型:ocean、air、express、fba。 |
| client_order_no | string | 与 order_no 至少填一个 | 创建时的外部订单号;同时传 order_no 时优先使用此字段。 |
| order_no | string | 与 client_order_no 至少填一个 | 系统订单号,取创建响应 data.order_no;不能填工作号、物流巴巴单号或承运商运单号。 |
| changes | object | 是 | 非空修改对象,只含该类型创建表中除 client_order_no 以外的业务字段;子对象/列表整体替换,未提交字段保留。 |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"changes": {
"goods_weight": 1200,
"note": "Updated shipping instructions"
}
}响应字段(data 内)#
响应 data 使用“统一订单响应”的全部字段;replayed 表示是否为重复操作,status/status_name 为操作后的实际状态。 统一订单响应
取消本人订单/作废(免费)#
/api/openapi/v1/orders/cancelorder_type 必填,另传 client_order_no 或 order_no;reason 可选,最多200字。仅本人 status=0(待确认)订单可自助取消,取消就是设为 status=7(作废),保留原订单和操作记录。预报、确认、收货、发货等其他状态请联系业务员处理。已作废订单重复取消返回当前结果及 replayed=true,不重复写取消日志。该接口沿用官网作废流程,不执行退款或撤销船公司订舱。
请求参数#
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| order_type | string | 是 | 订单类型:ocean、air、express、fba。 |
| client_order_no | string | 与 order_no 至少填一个 | 创建时的外部订单号;同时传 order_no 时优先使用此字段。 |
| order_no | string | 与 client_order_no 至少填一个 | 系统订单号,取创建响应 data.order_no;不能填工作号、物流巴巴单号或承运商运单号。 |
| reason | string | 否 | 取消原因,最多200字;默认空字符串。 |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"reason": "Shipment no longer needed"
}响应字段(data 内)#
响应 data 使用“统一订单响应”的全部字段;replayed 表示是否为重复操作,status/status_name 为操作后的实际状态。 统一订单响应
错误与处理#
创建时漏填或格式错误返回 HTTP400 / code1001。errors 是完整的问题列表,每项含 field(精确字段路径)、label(中文名称)、message(问题说明)。数组下标从0开始,如 packing.0.ctn_num;msg 汇总所有提示,方便直接展示。认证和签名仍先校验。失败不创建订单、不扣积分,修正本次返回的所有问题后,用原外部订单号重新提交。
字段校验错误结构(响应外层)#
| 字段 | 类型 | 返回条件 | 说明 |
|---|---|---|---|
| errors | array<object> | 字段校验失败时 | 字段校验问题列表,不是所有错误响应都会附带。 |
| errors[].field | string | 始终返回 | 精确字段路径,数组从0开始,如 goods.0.goods_price。 |
| errors[].label | string | 始终返回 | 字段中文名称。 |
| errors[].message | string | 始终返回 | 该字段的问题说明。 |
{
"code": 1001,
"msg": "参数校验失败:起运港/机场(pol)不能为空;目的港/机场或国家(pod)不能为空",
"request_id": "req_example",
"errors": [
{
"field": "pol",
"label": "起运港/机场",
"message": "起运港/机场(pol)不能为空"
},
{
"field": "pod",
"label": "目的港/机场或国家",
"message": "目的港/机场或国家(pod)不能为空"
}
],
"credit_used": 0
}1001 / HTTP400:参数校验失败,创建响应的 errors 列出缺项、格式、基础数据或联系人问题;1003 / HTTP409:外部单号与其他下单内容冲突;2007 / HTTP403:客户不可用或未完成实名认证,请访问 https://www.5688.cn/user/profile;4001 / HTTP429:现有限速。失败不生成残缺订单;详情不存在或不属于本人均返回1001。 1004 / HTTP409:订单状态不允许修改或自助取消,请联系业务员处理。