https://hopla.delivery三次调用,生成一个物流页面
示例中用到两个 shell 变量,请先设置:
API=https://hopla.delivery
KEY=hopla_dev_key创建订单及其商品和包裹
一次调用即可写入订单、商品和包裹。不填写快递公司时,系统会根据运单号自动识别。
POST /v1/orders curl -X POST "$API/v1/orders" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: demo-2001" \ -d '{ "orderNumber": "HP-2001", "store": { "name": "Atelier Nord" }, "customer": { "name": "Camille Durand", "email": "camille.durand@example.com" }, "destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" }, "items": [ { "ref": "a", "title": "Linen overshirt", "variant": "Sand / M", "quantity": 1, "unitPriceCents": 8900, "imageUrl": "https://cdn.example/overshirt.jpg" } ], "shipments": [ { "trackingNumber": "6A20001118001", "carrier": "la-poste", "origin": { "city": "Lille", "country": "FR" }, "items": [ "a" ], "simulate": { "scenario": "domestic_home", "autoStart": true } } ] }'添加一条轨迹
发送状态代码和地点;如果有快递公司的原始信息,也可以一并发送。包裹状态以最新一条轨迹为准。
POST /v1/shipments/:id/events curl -X POST "$API/v1/shipments/6A20001118001/events" \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{ "substatus": "out_for_delivery", "location": { "place": "LYS" }, "message": "Votre colis est en cours de livraison.", "messageLang": "fr", "details": { "window": "14:00-18:00" } }'打开页面
订单页面和每个包裹的页面会立即生成,支持四种语言。把链接发给您的顾客即可。
查看演示订单页面/zh/order/HP-1042
身份验证
写入类接口需要在请求头 Authorization 中携带 API 密钥,查询类接口无需密钥。
Authorization: Bearer hopla_dev_key也可以使用 X-Api-Key。密钥缺失或错误时返回 401 unauthorized。读取订单和包裹会返回个人信息,因此同样需要密钥。
| 公开接口 | 说明 |
|---|---|
| GET /v1/track/:ref | 按运单号查询一个包裹,或按订单号、订单 ID 查询整个订单。每个物流页面都是根据这个响应生成的。 |
| POST /v1/track/batch | 一次查询最多40个单号。每个单号都有各自的结果,无论是否查到。 |
| POST /v1/detect | 从任意文本中提取单号,并为每个单号列出可能的快递公司。 |
| GET /v1/carriers | 快递公司目录,以及用于识别单号的格式规则。 |
| GET /v1/carriers/:slug | 按标识读取一家快递公司。 |
| GET /v1/statuses | 状态模型,可返回一种语言或全部四种语言的名称和说明。 |
| GET /v1/places | 轨迹可引用的地点:本地化名称、坐标和时区。 |
| GET /health | 服务状态和数据量。 |
| GET /v1/simulator/scenarios | 模拟器可以运行的运输场景。 |
状态模型
九种状态用于筛选和配色,52个子状态用于具体描述。
| 状态 | 代码 | 含义 |
|---|---|---|
| 待发货 | pending | 寄件人已登记该包裹,快递公司尚未揽收。 |
| 运输中 | in_transit | 包裹正在运往目的地的途中。 |
| 派送中 | out_for_delivery | 快递员正在派送,预计今天送达。 |
| 待取件 | available_for_pickup | 包裹已到达驿站或快递柜,请凭取件码或有效证件领取。 |
| 已签收 | delivered终态 | 包裹已送达并签收。 |
| 派送失败 | failed_attempt | 快递员曾尝试派送但未成功,通常会再次派送或转为自提。 |
| 异常 | exception | 包裹运输出现异常,请查看最新一条物流信息了解后续处理。 |
| 退回寄件人 | returned | 包裹正在退回或已退回寄件人。 |
| 长时间未更新 | expired | 物流信息已长时间没有更新,如仍未收到包裹,请联系寄件人。 |
商家处理 · 3个代码
order_placed已下单 → pendingorder_processing备货中 → pendingorder_ready已打包 → pending
揽收 · 5个代码
info_received已生成运单 → pendingawaiting_carrier_pickup待揽收 → pendingpicked_up已揽收 → in_transitdropped_off已交寄 → in_transitaccepted_origin已到达始发网点 → in_transit
运输途中 · 4个代码
arrived_hub到达分拣中心 → in_transitsorted已分拣 → in_transitdeparted_hub已离开分拣中心 → in_transitin_transit运输途中 → in_transit
出口 · 4个代码
export_hub_arrived到达出口处理中心 → in_transitexport_customs出口清关中 → in_transitdeparted_origin_country已离开始发国 → in_transittransit_country到达中转国 → in_transit
清关与进口 · 7个代码
arrived_destination_country已抵达目的地国家 → in_transitcustoms_processing清关中 → in_transitcustoms_cleared已清关 → in_transitcustoms_held海关扣留 → exceptioncustoms_duties_due待缴纳关税 → exceptioncustoms_info_required清关资料待补充 → exceptionhanded_to_local_carrier已交由当地快递派送 → in_transit
末端派送 · 8个代码
arrived_delivery_depot到达派件网点 → in_transitout_for_delivery派送中 → out_for_deliverydelivery_rescheduled已改期派送 → in_transitdelivered已签收 → delivereddelivered_mailbox已投入信箱 → delivereddelivered_signed已当面签收 → delivereddelivered_third_party他人代签 → delivereddelivered_safe_place已放至指定位置 → delivered
自提点 · 4个代码
arrived_pickup_point已到驿站或快递柜 → available_for_pickuppickup_reminder取件提醒 → available_for_pickuppicked_up_by_recipient已取件 → deliveredpickup_expired超时未取 → returned
派送尝试 · 6个代码
attempt_absent无人签收 → failed_attemptattempt_closed收件单位休息 → failed_attemptaddress_issue地址有误 → exceptionrecipient_refused收件人拒收 → exceptionrecipient_unreachable无法联系收件人 → exceptionawaiting_recipient_action待收件人确认 → exception
异常情况 · 9个代码
delayed延误 → exceptionmisrouted错分,正在转回 → exceptiondamaged包裹破损 → exceptionlost包裹丢失 → exceptionon_hold滞留 → exceptionsecurity_check安全查验中 → exceptionredirected已转寄 → in_transitcancelled已取消寄送 → exceptionno_updates超时未更新 → expired
退回 · 2个代码
return_in_transit退回途中 → returnedreturn_delivered已退回寄件人 → returned
接口参考
所有响应的格式均为 { "data": … }(列表另带 meta),出错时为 { "error": … }。字段名采用 camelCase,时间戳为带时区偏移的 ISO 8601 格式。
订单
POST/v1/orders需要密钥
/v1/orders需要密钥在一个事务中创建订单及其商品和包裹。只要有一处无效,就不会写入任何数据。
| 名称 | 类型 | 说明 |
|---|---|---|
| Idempotency-Key请求头 | string | 让重试变得安全:相同的键加相同的请求体,会返回第一次的响应。 |
| orderNumber请求体必填 | string | 您自己的订单号,1至40个字符,不可重复。 |
| store请求体必填 | object | name 必填;url 和 supportEmail 可选。 |
| customer请求体必填 | object | name 必填,在公开页面上会脱敏显示。 |
| destination请求体必填 | object | city 和 country 必填。街道地址不会出现在公开页面上。 |
| items请求体必填 | Item[] | 1至100件商品:title、quantity,以及可选的 variant、unitPriceCents、imageUrl。ref 用于把商品关联到包裹。 |
| shipments请求体 | Shipment[] | 0至20个包裹。可以在发货之前先创建订单。 |
| locale请求体 | en | fr | zh | ru | 顾客使用的语言。 |
curl -X POST "$API/v1/orders" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: demo-2001" \
-d '{
"orderNumber": "HP-2001",
"store": { "name": "Atelier Nord" },
"customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
"destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" },
"items": [
{
"ref": "a",
"title": "Linen overshirt",
"variant": "Sand / M",
"quantity": 1,
"unitPriceCents": 8900,
"imageUrl": "https://cdn.example/overshirt.jpg"
}
],
"shipments": [
{
"trackingNumber": "6A20001118001",
"carrier": "la-poste",
"origin": { "city": "Lille", "country": "FR" },
"items": [ "a" ],
"simulate": { "scenario": "domestic_home", "autoStart": true }
}
]
}'const res = await fetch(`${API}/v1/orders`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': 'demo-2001' },
body: JSON.stringify({
"orderNumber": "HP-2001",
"store": { "name": "Atelier Nord" },
"customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
"destination": { "city": "Lyon", "postalCode": "69002", "country": "FR" },
"items": [
{
"ref": "a",
"title": "Linen overshirt",
"variant": "Sand / M",
"quantity": 1,
"unitPriceCents": 8900,
"imageUrl": "https://cdn.example/overshirt.jpg"
}
],
"shipments": [
{
"trackingNumber": "6A20001118001",
"carrier": "la-poste",
"origin": { "city": "Lille", "country": "FR" },
"items": [ "a" ],
"simulate": { "scenario": "domestic_home", "autoStart": true }
}
]
}),
});
const { data } = await res.json();{
"data": {
"id": "ord_4h7k2m9x3pqa",
"orderNumber": "HP-2001",
"status": "pending",
"items": [ { "id": "itm_5c7n2w8h3dfa", "title": "Linen overshirt", "quantity": 1 } ],
"shipments": [ { "id": "shp_3v9x7b2m6kq4", "trackingNumber": "6A20001118001", "carrier": "la-poste", "status": "pending", "substatus": "info_received" } ]
},
"meta": { "trackUrl": "/v1/track/ord_4h7k2m9x3pqa", "publicPath": "/order/ord_4h7k2m9x3pqa" }
}GET/v1/orders需要密钥
/v1/orders需要密钥列出订单,最新的在前,支持筛选和游标分页。
| 名称 | 类型 | 说明 |
|---|---|---|
| q查询参数 | string | 匹配订单号、顾客姓名或邮箱,或运单号。 |
| status查询参数 | string | 一个或多个状态代码,用逗号分隔。 |
| demo查询参数 | 0 | 1 | 只返回演示订单,或只返回您自己的订单。 |
| expand查询参数 | shipments | events | 同时返回每个包裹的轨迹。 |
| limit查询参数 | integer | 每页数量,默认20,最多100。 |
| cursor查询参数 | string | 上一页返回的 meta.nextCursor。 |
curl "$API/v1/orders?status=exception,failed_attempt&limit=10" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/orders?status=exception,failed_attempt&limit=10`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": [ /* Order, Order, … */ ],
"meta": { "limit": 10, "nextCursor": null, "total": 3 }
}GET/v1/orders/:ref需要密钥
/v1/orders/:ref需要密钥读取一个完整的订单,包含个人信息。
| 名称 | 类型 | 说明 |
|---|---|---|
| ref路径必填 | string | 订单 ID 或订单号。 |
| expand查询参数 | events | 同时返回每个包裹的轨迹。 |
curl "$API/v1/orders/HP-1042?expand=events" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/orders/HP-1042?expand=events`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": {
"id": "ord_8k2m4x9p1qrt",
"orderNumber": "HP-1042",
"store": { "name": "Atelier Nord" },
"customer": { "name": "Camille Durand", "email": "camille.durand@example.com" },
"destination": { "line1": "12 rue de la République", "city": "Lyon", "postalCode": "69002", "country": "FR" },
"status": "in_transit",
"items": [ /* Item */ ],
"shipments": [ /* Shipment, with events */ ]
}
}PATCH/v1/orders/:ref需要密钥
/v1/orders/:ref需要密钥更新订单:商家处理进度、给顾客的留言、商品。订单号不可更改。
| 名称 | 类型 | 说明 |
|---|---|---|
| ref路径必填 | string | 订单 ID 或订单号。 |
| processingAt · readyAt · cancelledAt请求体 | ISO 8601 | 商家开始备货、完成打包或取消订单的时间。 |
| notice请求体 | string | null | 商家的简短留言,显示在订单页面上。 |
| items请求体 | { add, update, remove } | 要添加、修改或移除的商品。 |
curl -X PATCH "$API/v1/orders/HP-2001" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"processingAt": "2026-11-18T11:00:00+01:00",
"notice": "Packed with care — ships tomorrow."
}'const res = await fetch(`${API}/v1/orders/HP-2001`, {
method: 'PATCH',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"processingAt": "2026-11-18T11:00:00+01:00",
"notice": "Packed with care — ships tomorrow."
}),
});
const { data } = await res.json();{ "data": { /* the full order */ } }DELETE/v1/orders/:ref需要密钥
/v1/orders/:ref需要密钥删除订单及其包裹、商品和轨迹。
| 名称 | 类型 | 说明 |
|---|---|---|
| ref路径必填 | string | 订单 ID 或订单号。 |
curl -X DELETE "$API/v1/orders/HP-2001" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/orders/HP-2001`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${KEY}` },
});
// res.status === 204HTTP/1.1 204 No Content轨迹
POST/v1/shipments/:id/events需要密钥
/v1/shipments/:id/events需要密钥添加一条轨迹,或通过 events 数组一次添加最多50条。轨迹可以按任意顺序提交:状态始终取时间最新的一条。
| 名称 | 类型 | 说明 |
|---|---|---|
| id路径必填 | string | 包裹 ID 或其运单号。 |
| substatus请求体必填 | string | 发生了什么,用状态模型中的代码表示。 |
| occurredAt请求体 | ISO 8601 | 发生时间,带当地时区偏移。默认为当前时间。 |
| location请求体 | { place } | { city, country, … } | 地点代码,或自由填写的字段(可附带坐标)。 |
| message · messageLang请求体 | string | 快递公司的原始信息及其语言,会原样返回。 |
| details请求体 | object | 部分代码的附加信息:signedBy、window、deadline、reason。 |
| externalId请求体 | string | 您为这条轨迹指定的 ID:重复提交只会写入一次。 |
curl -X POST "$API/v1/shipments/6A20001118001/events" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"substatus": "out_for_delivery",
"location": { "place": "LYS" },
"message": "Votre colis est en cours de livraison.",
"messageLang": "fr",
"details": { "window": "14:00-18:00" }
}'const res = await fetch(`${API}/v1/shipments/6A20001118001/events`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"substatus": "out_for_delivery",
"location": { "place": "LYS" },
"message": "Votre colis est en cours de livraison.",
"messageLang": "fr",
"details": { "window": "14:00-18:00" }
}),
});
const { data } = await res.json();{
"data": {
"created": [ { "id": "evt_9t4r6y1n8zc2", "status": "out_for_delivery", "substatus": "out_for_delivery", "occurredAt": "2026-11-18T09:12:00+01:00" } ],
"duplicates": [],
"shipment": { "id": "shp_3v9x7b2m6kq4", "status": "out_for_delivery", "substatus": "out_for_delivery", "lastEventAt": "2026-11-18T09:12:00+01:00" }
}
}DELETE/v1/shipments/:id/events/:eventId需要密钥
/v1/shipments/:id/events/:eventId需要密钥删除一条错误的轨迹,状态会重新计算。
| 名称 | 类型 | 说明 |
|---|---|---|
| id路径必填 | string | 包裹 ID 或其运单号。 |
| eventId路径必填 | string | 要删除的轨迹。 |
curl -X DELETE "$API/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${KEY}` },
});
// res.status === 204HTTP/1.1 204 No Content包裹
POST/v1/shipments需要密钥
/v1/shipments需要密钥单独创建包裹,或关联到已有订单。只有运单号是必填项。
| 名称 | 类型 | 说明 |
|---|---|---|
| Idempotency-Key请求头 | string | 让重试变得安全:相同的键加相同的请求体,会返回第一次的响应。 |
| trackingNumber请求体必填 | string | 以大写、无空格的形式保存,不可重复。 |
| carrier请求体 | slug | 当单号格式只对应一家快递公司时可以省略。 |
| lastMile请求体 | { trackingNumber, carrier } | 在目的地国家接手派送的快递公司及其单号。 |
| origin · destination请求体 | object | 城市和国家,或地点代码。目的地默认取订单的目的地。 |
| deliveryType请求体 | home | pickup_point | locker | mailbox | 包裹的交付方式。 |
| eta请求体 | { from, to, window, source } | 预计送达时间:一个日期或一个区间,以及由谁给出。 |
| orderId · orderNumber请求体 | string | 把包裹关联到已有订单。 |
| simulate请求体 | { scenario, autoStart } | 关联一个模拟场景;autoStart 会立即执行第一步。 |
curl -X POST "$API/v1/shipments" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"trackingNumber": "1Z999AA10123456784",
"label": "Desk lamp",
"origin": { "city": "Chicago", "country": "US" },
"destination": { "city": "Austin", "region": "TX", "country": "US" },
"simulate": { "scenario": "us_domestic" }
}'const res = await fetch(`${API}/v1/shipments`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"trackingNumber": "1Z999AA10123456784",
"label": "Desk lamp",
"origin": { "city": "Chicago", "country": "US" },
"destination": { "city": "Austin", "region": "TX", "country": "US" },
"simulate": { "scenario": "us_domestic" }
}),
});
const { data } = await res.json();{
"data": {
"id": "shp_7d2k9m4x1qpa",
"orderId": null,
"trackingNumber": "1Z999AA10123456784",
"carrier": "ups",
"status": "pending",
"substatus": "info_received",
"simulation": { "scenario": "us_domestic", "step": 1, "remaining": 8 },
"events": [ /* one automatic "label created" checkpoint */ ]
}
}GET/v1/shipments需要密钥
/v1/shipments需要密钥列出包裹,最新的在前,支持筛选和游标分页。
| 名称 | 类型 | 说明 |
|---|---|---|
| q查询参数 | string | 匹配运单号、备注名或订单号。 |
| status · substatus · carrier查询参数 | string | 按状态、子状态或快递公司筛选。 |
| expand查询参数 | events | 同时返回每个包裹的轨迹。 |
| limit查询参数 | integer | 每页数量,默认20,最多100。 |
| cursor查询参数 | string | 上一页返回的 meta.nextCursor。 |
curl "$API/v1/shipments?status=in_transit&carrier=china-post" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments?status=in_transit&carrier=china-post`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": [ /* Shipment, Shipment, … */ ],
"meta": { "limit": 20, "nextCursor": null, "total": 2 }
}GET/v1/shipments/:id需要密钥
/v1/shipments/:id需要密钥读取一个包裹及其全部轨迹,最新的在前。可以用运单号代替 ID。
| 名称 | 类型 | 说明 |
|---|---|---|
| id路径必填 | string | 包裹 ID 或其运单号。 |
curl "$API/v1/shipments/6A20001118001" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments/6A20001118001`, {
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{
"data": {
"id": "shp_3v9x7b2m6kq4",
"trackingNumber": "6A20001118001",
"carrier": "la-poste",
"status": "in_transit",
"substatus": "arrived_hub",
"eta": { "from": "2026-11-21", "to": "2026-11-22", "window": null, "source": "store" },
"simulation": { "scenario": "domestic_home", "step": 3, "remaining": 4 },
"events": [ /* Event, newest first */ ]
}
}PATCH/v1/shipments/:id需要密钥
/v1/shipments/:id需要密钥修改预计送达时间、快递公司、末端派送信息、自提点或模拟场景。状态只能通过轨迹改变。
| 名称 | 类型 | 说明 |
|---|---|---|
| id路径必填 | string | 包裹 ID 或其运单号。 |
| eta请求体 | object | null | 预计送达时间:一个日期或一个区间,以及由谁给出。 |
| carrier · lastMile请求体 | slug · object | 在目的地国家接手派送的快递公司及其单号。 |
| simulate请求体 | { scenario } | null | 关联一个模拟场景;autoStart 会立即执行第一步。 |
curl -X PATCH "$API/v1/shipments/6A20001118001" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{
"eta": { "from": "2026-11-20", "to": "2026-11-21", "source": "carrier" }
}'const res = await fetch(`${API}/v1/shipments/6A20001118001`, {
method: 'PATCH',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({
"eta": { "from": "2026-11-20", "to": "2026-11-21", "source": "carrier" }
}),
});
const { data } = await res.json();{ "data": { /* the shipment */ } }DELETE/v1/shipments/:id需要密钥
/v1/shipments/:id需要密钥删除包裹及其轨迹。
| 名称 | 类型 | 说明 |
|---|---|---|
| id路径必填 | string | 包裹 ID 或其运单号。 |
curl -X DELETE "$API/v1/shipments/6A20001118001" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/shipments/6A20001118001`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${KEY}` },
});
// res.status === 204HTTP/1.1 204 No Content查询(公开)
GET/v1/track/:ref公开
/v1/track/:ref公开按运单号查询一个包裹,或按订单号、订单 ID 查询整个订单。每个物流页面都是根据这个响应生成的。
| 名称 | 类型 | 说明 |
|---|---|---|
| ref路径必填 | string | 运单号、末端派送单号、订单号、订单 ID 或包裹 ID。 |
| lang查询参数 | en | fr | zh | ru | 名称、说明和地名所用的语言,默认为 en。 |
| events查询参数 | all | latest | latest 只返回每个包裹最新的一条轨迹(适用于列表)。 |
| verify查询参数 | string | 顾客邮箱或邮政编码,在服务器要求验证订单查询时使用。 |
curl "$API/v1/track/LV202611181CN?lang=fr"const res = await fetch(`${API}/v1/track/LV202611181CN?lang=fr`);
const { data } = await res.json();{
"data": {
"kind": "shipment",
"query": "LV202611181CN",
"lang": "fr",
"shipment": {
"trackingNumber": "LV202611181CN",
"status": { "code": "in_transit", "label": "En transit", "tone": "info" },
"substatus": { "code": "arrived_hub", "label": "Arrivé au centre de tri" },
"eta": { "from": "2026-11-19", "to": "2026-11-19", "source": "carrier" },
"milestones": [ /* key, label, state, at */ ],
"progress": { "percent": 68, "from": "import", "to": "out_for_delivery", "legFraction": 0.4, "direction": "forward", "halted": false },
"events": [ /* newest first */ ]
},
"siblings": [ /* the other parcels of the same order */ ]
}
}GET /v1/track/LV202611181CN?lang=zh&events=latestPOST/v1/track/batch公开
/v1/track/batch公开一次查询最多40个单号。每个单号都有各自的结果,无论是否查到。
| 名称 | 类型 | 说明 |
|---|---|---|
| refs请求体必填 | string[] | 1至40个单号,重复的会合并。 |
| lang请求体 | en | fr | zh | ru | 名称、说明和地名所用的语言,默认为 en。 |
| events请求体 | latest | all | latest 只返回每个包裹最新的一条轨迹(适用于列表)。 |
curl -X POST "$API/v1/track/batch" \
-H "Content-Type: application/json" \
-d '{
"refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
"lang": "en"
}'const res = await fetch(`${API}/v1/track/batch`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
"lang": "en"
}),
});
const { data } = await res.json();{
"data": {
"lang": "en",
"results": [
{ "query": "LV202611181CN", "found": true, "kind": "shipment", "shipment": { /* … */ } },
{ "query": "HP-1042", "found": true, "kind": "order", "order": { /* … */ } },
{ "query": "ABC", "found": false, "notFound": { "kind": "unknown", "plausible": false, "candidates": [] } }
],
"counts": { "total": 4, "found": 3, "notFound": 1, "byStatus": { "in_transit": 2, "out_for_delivery": 1, "pending": 1 } }
}
}快递公司与识别
POST/v1/detect公开
/v1/detect公开从任意文本中提取单号,并为每个单号列出可能的快递公司。
| 名称 | 类型 | 说明 |
|---|---|---|
| input请求体必填 | string | 任意文本,最多5000个字符。 |
| lang请求体 | en | fr | zh | ru | 名称、说明和地名所用的语言,默认为 en。 |
curl -X POST "$API/v1/detect" \
-H "Content-Type: application/json" \
-d '{
"input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
}'const res = await fetch(`${API}/v1/detect`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
"input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
}),
});
const { data } = await res.json();{
"data": {
"items": [
{ "raw": "1ZVAD0DEMO00000001", "normalized": "1ZVAD0DEMO00000001", "kind": "tracking", "known": true, "checkDigit": "na",
"candidates": [ { "carrier": { "slug": "ups", "displayName": "UPS" }, "confidence": 1, "reason": "known" } ] },
{ "raw": "rr123456785gb", "normalized": "RR123456785GB", "kind": "tracking", "known": false, "checkDigit": "ok",
"candidates": [ { "carrier": { "slug": "royal-mail", "displayName": "Royal Mail" }, "confidence": 0.9, "reason": "s10_country" } ] },
{ "raw": "HP-1042", "normalized": "HP-1042", "kind": "order", "known": true, "checkDigit": "na", "candidates": [] }
],
"duplicatesRemoved": 0
}
}GET/v1/carriers公开
/v1/carriers公开快递公司目录,以及用于识别单号的格式规则。
| 名称 | 类型 | 说明 |
|---|---|---|
| q查询参数 | string | 匹配名称、当地名称或标识。 |
| country查询参数 | ISO 3166-1 alpha-2 | 两位字母的国家代码。 |
| kind查询参数 | postal | express | ecommerce | regional | 快递公司类型。 |
| popular查询参数 | 1 | 只返回优先展示的快递公司。 |
| lang查询参数 | en | fr | zh | ru | 名称、说明和地名所用的语言,默认为 en。 |
curl "$API/v1/carriers?popular=1&lang=ru"const res = await fetch(`${API}/v1/carriers?popular=1&lang=ru`);
const { data } = await res.json();{
"data": [
{ "slug": "cdek", "name": "CDEK", "nameLocal": "СДЭК", "displayName": "СДЭК", "country": "RU", "countryName": "Россия", "kind": "express",
"monogram": "СД", "color": "#1AB248", "logoUrl": null, "website": "https://www.cdek.ru",
"patterns": [ { "regex": "^\\d{10,11}$", "weight": 0.4 } ], "example": "1500042017", "popularRank": 11 }
],
"meta": { "total": 12 }
}GET /v1/carriers?popular=1&lang=zhGET/v1/carriers/:slug公开
/v1/carriers/:slug公开按标识读取一家快递公司。
| 名称 | 类型 | 说明 |
|---|---|---|
| slug路径必填 | string | 快递公司的标识,例如 la-poste。 |
| lang查询参数 | en | fr | zh | ru | 名称、说明和地名所用的语言,默认为 en。 |
curl "$API/v1/carriers/la-poste"const res = await fetch(`${API}/v1/carriers/la-poste`);
const { data } = await res.json();{ "data": { "slug": "la-poste", "name": "La Poste (Colissimo)", "country": "FR", "kind": "postal", "example": "6A12345678901", "patterns": [ /* … */ ] } }GET /v1/carriers/la-poste?lang=zhGET/v1/statuses公开
/v1/statuses公开状态模型,可返回一种语言或全部四种语言的名称和说明。
| 名称 | 类型 | 说明 |
|---|---|---|
| lang查询参数 | en | fr | zh | ru | all | all 同时返回四种语言。 |
curl "$API/v1/statuses?lang=zh"const res = await fetch(`${API}/v1/statuses?lang=zh`);
const { data } = await res.json();{
"data": {
"version": "1.0.0",
"lang": "zh",
"statuses": [ { "code": "in_transit", "label": "运输中", "description": "包裹正在运往目的地的途中。", "tone": "info", "terminal": false } ],
"substatuses": [ { "code": "arrived_hub", "status": "in_transit", "group": "hub", "severity": "info", "actor": "none", "label": "到达分拣中心" } ],
"milestones": [ { "key": "shipped", "label": "已发货", "crossBorderOnly": false } ],
"defaultSubstatus": { "in_transit": "in_transit", "delivered": "delivered" }
}
}GET /v1/statuses?lang=zhGET/v1/places公开
/v1/places公开轨迹可引用的地点:本地化名称、坐标和时区。
| 名称 | 类型 | 说明 |
|---|---|---|
| country查询参数 | ISO 3166-1 alpha-2 | 两位字母的国家代码。 |
| lang查询参数 | en | fr | zh | ru | 名称、说明和地名所用的语言,默认为 en。 |
curl "$API/v1/places?lang=en&country=FR"const res = await fetch(`${API}/v1/places?lang=en&country=FR`);
const { data } = await res.json();{ "data": [ { "code": "LYS", "name": "Lyon", "region": null, "country": "FR", "countryName": "France", "lat": 45.76, "lon": 4.84, "tz": "Europe/Paris" } ] }GET /v1/places?lang=zh&country=FRGET/health公开
/health公开服务状态和数据量。
curl "$API/health"const res = await fetch(`${API}/health`);
const { data } = await res.json();{ "data": { "status": "ok", "version": "1.0.0", "time": "2026-11-18T10:00:00.000Z", "db": { "orders": 9, "shipments": 14, "events": 94 }, "simulator": { "auto": false, "intervalSeconds": 45 } } }GET /health模拟器
GET/v1/simulator/scenarios公开
/v1/simulator/scenarios公开模拟器可以运行的运输场景。
curl "$API/v1/simulator/scenarios"const res = await fetch(`${API}/v1/simulator/scenarios`);
const { data } = await res.json();{
"data": [
{ "key": "cn_eu", "title": "China → EU, postal hand-off", "steps": 14, "ends": "delivered", "crossBorder": true,
"defaultCarrier": "china-post", "defaultLastMile": "la-poste", "defaultOrigin": "SZX", "defaultDestination": "LYS",
"stepsPreview": [ "info_received", "picked_up", "arrived_hub", "…" ] }
]
}GET /v1/simulator/scenariosPOST/v1/simulator/shipments/:id/advance需要密钥
/v1/simulator/shipments/:id/advance需要密钥为模拟包裹添加接下来的计划轨迹。
| 名称 | 类型 | 说明 |
|---|---|---|
| id路径必填 | string | 包裹 ID 或其运单号。 |
| steps请求体 | 1–20 | 要添加的计划轨迹数量,默认为1。 |
| to请求体 | substatus | "end" | 一直推进到出现该代码,或推进到场景结束。 |
| at请求体 | now | spaced | spaced 会按真实间隔回溯各条轨迹的时间,使最后一条落在当前时刻。 |
curl -X POST "$API/v1/simulator/shipments/6A20001118001/advance" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{ "steps": 1 }'const res = await fetch(`${API}/v1/simulator/shipments/6A20001118001/advance`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify({ "steps": 1 }),
});
const { data } = await res.json();{
"data": {
"created": [ /* Event */ ],
"finished": false,
"shipment": { "id": "shp_3v9x7b2m6kq4", "status": "in_transit", "substatus": "arrived_delivery_depot",
"simulation": { "scenario": "domestic_home", "step": 5, "remaining": 2 } }
}
}POST/v1/simulator/reset需要密钥
/v1/simulator/reset需要密钥删除演示订单,并以新的日期重新创建。您自己创建的订单会保留。
| 名称 | 类型 | 说明 |
|---|---|---|
| all请求体 | boolean | 同时删除手动创建的订单。 |
curl -X POST "$API/v1/simulator/reset" \
-H "Authorization: Bearer $KEY"const res = await fetch(`${API}/v1/simulator/reset`, {
method: 'POST',
headers: { Authorization: `Bearer ${KEY}` },
});
const { data } = await res.json();{ "data": { "orders": 9, "shipments": 14, "events": 94 } }错误
所有错误的结构都相同:一个固定的 code、一条面向开发者的说明,必要时附带 details。
| HTTP | 代码 | 出现的情况 |
|---|---|---|
| 400 | bad_request | JSON 格式有误,或内容类型不正确。 |
| 401 | unauthorized | API 密钥缺失或错误。 |
| 403 | verification_required | 服务器要求验证订单查询,而 verify 缺失或不正确。 |
| 404 | not_found | ID 或单号不存在。查询类接口会在 details 中说明该单号的格式特征。 |
| 409 | order_exists | 该订单号已被使用,details.existingId 指向已有订单。 |
| 409 | tracking_exists | 该运单号已登记。 |
| 409 | idempotency_conflict | 同一个幂等键对应了不同的请求体。 |
| 413 | too_many | 一次调用中超过40个单号、50条轨迹或100件商品。 |
| 422 | validation_error | 请求体未通过校验,details 列出每个字段路径及其问题。 |
| 429 | rate_limited | 同一地址对公开接口的调用过于频繁,请按 Retry-After 等待。 |
| 500 | internal | 其他所有情况。返回的说明是通用的,具体原因记录在服务器日志中。 |
{
"error": {
"code": "validation_error",
"message": "Request body is invalid.",
"details": [ { "path": "items[0].quantity", "message": "Must be an integer ≥ 1" } ]
}
}幂等性
- 创建订单或包裹时,可发送不超过100个字符的
Idempotency-Key请求头。 - 第一次成功的响应会保留24小时;相同的键加相同的请求体将重放该响应,并带有响应头
Idempotent-Replay: true。 - 相同的键加不同的请求体,返回
409 idempotency_conflict。 - 即使不发送该请求头,订单号也是唯一的:重复提交会返回
409 order_exists。
Idempotency-Key: demo-2001语言
?lang=en|fr|zh|ru 会改变名称、说明以及地名和国家名。快递公司的原始信息会原样返回。
curl "$API/v1/track/LV202611181CN?lang=fr"
curl "$API/v1/track/LV202611181CN?lang=zh"
curl "$API/v1/track/LV202611181CN?lang=ru"演示数据
十四个演示包裹覆盖了所有状态。它们由模拟器推动,因此“状态”一栏显示的是每个包裹此刻的位置。
| 运单号 | 快递公司 | 路线 | 状态 |
|---|---|---|---|
| LV 2026 1118 1CN | 深圳 → 里昂 | 运输中 | |
| LP 0042 0000 0000 17 | 深圳 → 里昂 | 待发货 | |
| 1ZVA D0DE MO00 0000 01 | 芝加哥 → 奥斯汀 | 派送中 | |
| 6A10 0000 00011 | 里尔 → 波尔多 | 已签收 | |
| XW 1234 5678 5FR | 巴黎 → 马赛 | 派送失败 | |
| 24680135 | 南特 → 图卢兹 | 待取件 | |
| RV 1042 0001 9CN | 义乌 → 喀山 | 异常 | |
| 1500 0420 17 | 莫斯科 → 新西伯利亚 | 运输中 | |
| YT 2611 1800 0000 0042 | 云途物流 | 义乌 → 波特兰 | 已签收 |
| 7700 1111 8888 | 纽约 → 丹佛 | 异常 | |
| 4810 0020 26 | 香港 → 伦敦 | 退回寄件人 | |
| SF 1000 0000 02026 | 深圳 → 杭州 | 已签收 | |
| H00V AD00 0000 0001 | Evri | 曼彻斯特 → 伦敦 | 长时间未更新 |
| 2500 0000 0020 26 | 巴黎 → 里尔 | 待发货 |