跳至正文

Hopla API

创建订单、关联包裹、添加物流轨迹。Hopla 物流页面上显示的一切,都来自这些接口。

基础地址https://hopla.delivery
JSON/v1Bearer

三次调用,生成一个物流页面

示例中用到两个 shell 变量,请先设置:

shell
API=https://hopla.delivery
KEY=hopla_dev_key
  1. 创建订单及其商品和包裹

    一次调用即可写入订单、商品和包裹。不填写快递公司时,系统会根据运单号自动识别。

    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 }
          }
        ]
      }'
  2. 添加一条轨迹

    发送状态代码和地点;如果有快递公司的原始信息,也可以一并发送。包裹状态以最新一条轨迹为准。

    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" }
      }'
  3. 打开页面

    订单页面和每个包裹的页面会立即生成,支持四种语言。把链接发给您的顾客即可。

    查看演示订单页面/zh/order/HP-1042

身份验证

写入类接口需要在请求头 Authorization 中携带 API 密钥,查询类接口无需密钥。

header
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已下单 → pending
  • order_processing备货中 → pending
  • order_ready已打包 → pending
揽收 · 5个代码
  • info_received已生成运单 → pending
  • awaiting_carrier_pickup待揽收 → pending
  • picked_up已揽收 → in_transit
  • dropped_off已交寄 → in_transit
  • accepted_origin已到达始发网点 → in_transit
运输途中 · 4个代码
  • arrived_hub到达分拣中心 → in_transit
  • sorted已分拣 → in_transit
  • departed_hub已离开分拣中心 → in_transit
  • in_transit运输途中 → in_transit
出口 · 4个代码
  • export_hub_arrived到达出口处理中心 → in_transit
  • export_customs出口清关中 → in_transit
  • departed_origin_country已离开始发国 → in_transit
  • transit_country到达中转国 → in_transit
清关与进口 · 7个代码
  • arrived_destination_country已抵达目的地国家 → in_transit
  • customs_processing清关中 → in_transit
  • customs_cleared已清关 → in_transit
  • customs_held海关扣留 → exception
  • customs_duties_due待缴纳关税 → exception
  • customs_info_required清关资料待补充 → exception
  • handed_to_local_carrier已交由当地快递派送 → in_transit
末端派送 · 8个代码
  • arrived_delivery_depot到达派件网点 → in_transit
  • out_for_delivery派送中 → out_for_delivery
  • delivery_rescheduled已改期派送 → in_transit
  • delivered已签收 → delivered
  • delivered_mailbox已投入信箱 → delivered
  • delivered_signed已当面签收 → delivered
  • delivered_third_party他人代签 → delivered
  • delivered_safe_place已放至指定位置 → delivered
自提点 · 4个代码
  • arrived_pickup_point已到驿站或快递柜 → available_for_pickup
  • pickup_reminder取件提醒 → available_for_pickup
  • picked_up_by_recipient已取件 → delivered
  • pickup_expired超时未取 → returned
派送尝试 · 6个代码
  • attempt_absent无人签收 → failed_attempt
  • attempt_closed收件单位休息 → failed_attempt
  • address_issue地址有误 → exception
  • recipient_refused收件人拒收 → exception
  • recipient_unreachable无法联系收件人 → exception
  • awaiting_recipient_action待收件人确认 → exception
异常情况 · 9个代码
  • delayed延误 → exception
  • misrouted错分,正在转回 → exception
  • damaged包裹破损 → exception
  • lost包裹丢失 → exception
  • on_hold滞留 → exception
  • security_check安全查验中 → exception
  • redirected已转寄 → in_transit
  • cancelled已取消寄送 → exception
  • no_updates超时未更新 → expired
退回 · 2个代码
  • return_in_transit退回途中 → returned
  • return_delivered已退回寄件人 → returned
请发送代码,而不是句子:Hopla 会用读者的语言生成文字。

接口参考

所有响应的格式均为 { "data": … }(列表另带 meta),出错时为 { "error": … }。字段名采用 camelCase,时间戳为带时区偏移的 ISO 8601 格式。

订单

POST/v1/orders需要密钥

在一个事务中创建订单及其商品和包裹。只要有一处无效,就不会写入任何数据。

名称类型说明
Idempotency-Key请求头string让重试变得安全:相同的键加相同的请求体,会返回第一次的响应。
orderNumber请求体必填string您自己的订单号,1至40个字符,不可重复。
store请求体必填objectname 必填;url 和 supportEmail 可选。
customer请求体必填objectname 必填,在公开页面上会脱敏显示。
destination请求体必填objectcity 和 country 必填。街道地址不会出现在公开页面上。
items请求体必填Item[]1至100件商品:title、quantity,以及可选的 variant、unitPriceCents、imageUrl。ref 用于把商品关联到包裹。
shipments请求体Shipment[]0至20个包裹。可以在发货之前先创建订单。
locale请求体en | fr | zh | ru顾客使用的语言。
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 }
      }
    ]
  }'

GET/v1/orders需要密钥

列出订单,最新的在前,支持筛选和游标分页。

名称类型说明
q查询参数string匹配订单号、顾客姓名或邮箱,或运单号。
status查询参数string一个或多个状态代码,用逗号分隔。
demo查询参数0 | 1只返回演示订单,或只返回您自己的订单。
expand查询参数shipments | events同时返回每个包裹的轨迹。
limit查询参数integer每页数量,默认20,最多100。
cursor查询参数string上一页返回的 meta.nextCursor。
GET /v1/orders
curl "$API/v1/orders?status=exception,failed_attempt&limit=10" \
  -H "Authorization: Bearer $KEY"

GET/v1/orders/:ref需要密钥

读取一个完整的订单,包含个人信息。

名称类型说明
ref路径必填string订单 ID 或订单号。
expand查询参数events同时返回每个包裹的轨迹。
GET /v1/orders/:ref
curl "$API/v1/orders/HP-1042?expand=events" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/orders/:ref需要密钥

更新订单:商家处理进度、给顾客的留言、商品。订单号不可更改。

名称类型说明
ref路径必填string订单 ID 或订单号。
processingAt · readyAt · cancelledAt请求体ISO 8601商家开始备货、完成打包或取消订单的时间。
notice请求体string | null商家的简短留言,显示在订单页面上。
items请求体{ add, update, remove }要添加、修改或移除的商品。
PATCH /v1/orders/:ref
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."
  }'

DELETE/v1/orders/:ref需要密钥

删除订单及其包裹、商品和轨迹。

名称类型说明
ref路径必填string订单 ID 或订单号。
DELETE /v1/orders/:ref
curl -X DELETE "$API/v1/orders/HP-2001" \
  -H "Authorization: Bearer $KEY"

轨迹

POST/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:重复提交只会写入一次。
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" }
  }'

DELETE/v1/shipments/:id/events/:eventId需要密钥

删除一条错误的轨迹,状态会重新计算。

名称类型说明
id路径必填string包裹 ID 或其运单号。
eventId路径必填string要删除的轨迹。
DELETE /v1/shipments/:id/events/:eventId
curl -X DELETE "$API/v1/shipments/6A20001118001/events/evt_9t4r6y1n8zc2" \
  -H "Authorization: Bearer $KEY"

包裹

POST/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 会立即执行第一步。
POST /v1/shipments
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" }
  }'

GET/v1/shipments需要密钥

列出包裹,最新的在前,支持筛选和游标分页。

名称类型说明
q查询参数string匹配运单号、备注名或订单号。
status · substatus · carrier查询参数string按状态、子状态或快递公司筛选。
expand查询参数events同时返回每个包裹的轨迹。
limit查询参数integer每页数量,默认20,最多100。
cursor查询参数string上一页返回的 meta.nextCursor。
GET /v1/shipments
curl "$API/v1/shipments?status=in_transit&carrier=china-post" \
  -H "Authorization: Bearer $KEY"

GET/v1/shipments/:id需要密钥

读取一个包裹及其全部轨迹,最新的在前。可以用运单号代替 ID。

名称类型说明
id路径必填string包裹 ID 或其运单号。
GET /v1/shipments/:id
curl "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY"

PATCH/v1/shipments/:id需要密钥

修改预计送达时间、快递公司、末端派送信息、自提点或模拟场景。状态只能通过轨迹改变。

名称类型说明
id路径必填string包裹 ID 或其运单号。
eta请求体object | null预计送达时间:一个日期或一个区间,以及由谁给出。
carrier · lastMile请求体slug · object在目的地国家接手派送的快递公司及其单号。
simulate请求体{ scenario } | null关联一个模拟场景;autoStart 会立即执行第一步。
PATCH /v1/shipments/:id
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" }
  }'

DELETE/v1/shipments/:id需要密钥

删除包裹及其轨迹。

名称类型说明
id路径必填string包裹 ID 或其运单号。
DELETE /v1/shipments/:id
curl -X DELETE "$API/v1/shipments/6A20001118001" \
  -H "Authorization: Bearer $KEY"

查询(公开)

GET/v1/track/:ref公开

按运单号查询一个包裹,或按订单号、订单 ID 查询整个订单。每个物流页面都是根据这个响应生成的。

名称类型说明
ref路径必填string运单号、末端派送单号、订单号、订单 ID 或包裹 ID。
lang查询参数en | fr | zh | ru名称、说明和地名所用的语言,默认为 en。
events查询参数all | latestlatest 只返回每个包裹最新的一条轨迹(适用于列表)。
verify查询参数string顾客邮箱或邮政编码,在服务器要求验证订单查询时使用。
GET /v1/track/:ref
curl "$API/v1/track/LV202611181CN?lang=fr"
GET /v1/track/LV202611181CN?lang=zh&events=latest

POST/v1/track/batch公开

一次查询最多40个单号。每个单号都有各自的结果,无论是否查到。

名称类型说明
refs请求体必填string[]1至40个单号,重复的会合并。
lang请求体en | fr | zh | ru名称、说明和地名所用的语言,默认为 en。
events请求体latest | alllatest 只返回每个包裹最新的一条轨迹(适用于列表)。
POST /v1/track/batch
curl -X POST "$API/v1/track/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "refs": [ "LV202611181CN", "1ZVAD0DEMO00000001", "HP-1042", "ABC" ],
    "lang": "en"
  }'

快递公司与识别

POST/v1/detect公开

从任意文本中提取单号,并为每个单号列出可能的快递公司。

名称类型说明
input请求体必填string任意文本,最多5000个字符。
lang请求体en | fr | zh | ru名称、说明和地名所用的语言,默认为 en。
POST /v1/detect
curl -X POST "$API/v1/detect" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Hi! your parcels: 1ZVAD0DEMO00000001 and rr123456785gb, order HP-1042"
  }'

GET/v1/carriers公开

快递公司目录,以及用于识别单号的格式规则。

名称类型说明
q查询参数string匹配名称、当地名称或标识。
country查询参数ISO 3166-1 alpha-2两位字母的国家代码。
kind查询参数postal | express | ecommerce | regional快递公司类型。
popular查询参数1只返回优先展示的快递公司。
lang查询参数en | fr | zh | ru名称、说明和地名所用的语言,默认为 en。
GET /v1/carriers
curl "$API/v1/carriers?popular=1&lang=ru"
GET /v1/carriers?popular=1&lang=zh

GET/v1/carriers/:slug公开

按标识读取一家快递公司。

名称类型说明
slug路径必填string快递公司的标识,例如 la-poste。
lang查询参数en | fr | zh | ru名称、说明和地名所用的语言,默认为 en。
GET /v1/carriers/:slug
curl "$API/v1/carriers/la-poste"
GET /v1/carriers/la-poste?lang=zh

GET/v1/statuses公开

状态模型,可返回一种语言或全部四种语言的名称和说明。

名称类型说明
lang查询参数en | fr | zh | ru | allall 同时返回四种语言。
GET /v1/statuses
curl "$API/v1/statuses?lang=zh"
GET /v1/statuses?lang=zh

GET/v1/places公开

轨迹可引用的地点:本地化名称、坐标和时区。

名称类型说明
country查询参数ISO 3166-1 alpha-2两位字母的国家代码。
lang查询参数en | fr | zh | ru名称、说明和地名所用的语言,默认为 en。
GET /v1/places
curl "$API/v1/places?lang=en&country=FR"
GET /v1/places?lang=zh&country=FR

GET/health公开

服务状态和数据量。

GET /health
curl "$API/health"
GET /health

模拟器

GET/v1/simulator/scenarios公开

模拟器可以运行的运输场景。

GET /v1/simulator/scenarios
curl "$API/v1/simulator/scenarios"
GET /v1/simulator/scenarios

POST/v1/simulator/shipments/:id/advance需要密钥

为模拟包裹添加接下来的计划轨迹。

名称类型说明
id路径必填string包裹 ID 或其运单号。
steps请求体1–20要添加的计划轨迹数量,默认为1。
to请求体substatus | "end"一直推进到出现该代码,或推进到场景结束。
at请求体now | spacedspaced 会按真实间隔回溯各条轨迹的时间,使最后一条落在当前时刻。
POST /v1/simulator/shipments/:id/advance
curl -X POST "$API/v1/simulator/shipments/6A20001118001/advance" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "steps": 1 }'

POST/v1/simulator/reset需要密钥

删除演示订单,并以新的日期重新创建。您自己创建的订单会保留。

名称类型说明
all请求体boolean同时删除手动创建的订单。
POST /v1/simulator/reset
curl -X POST "$API/v1/simulator/reset" \
  -H "Authorization: Bearer $KEY"

错误

所有错误的结构都相同:一个固定的 code、一条面向开发者的说明,必要时附带 details。

HTTP代码出现的情况
400bad_requestJSON 格式有误,或内容类型不正确。
401unauthorizedAPI 密钥缺失或错误。
403verification_required服务器要求验证订单查询,而 verify 缺失或不正确。
404not_foundID 或单号不存在。查询类接口会在 details 中说明该单号的格式特征。
409order_exists该订单号已被使用,details.existingId 指向已有订单。
409tracking_exists该运单号已登记。
409idempotency_conflict同一个幂等键对应了不同的请求体。
413too_many一次调用中超过40个单号、50条轨迹或100件商品。
422validation_error请求体未通过校验,details 列出每个字段路径及其问题。
429rate_limited同一地址对公开接口的调用过于频繁,请按 Retry-After 等待。
500internal其他所有情况。返回的说明是通用的,具体原因记录在服务器日志中。
422
{
  "error": {
    "code": "validation_error",
    "message": "Request body is invalid.",
    "details": [ { "path": "items[0].quantity", "message": "Must be an integer ≥ 1" } ]
  }
}

幂等性

  1. 创建订单或包裹时,可发送不超过100个字符的 Idempotency-Key 请求头。
  2. 第一次成功的响应会保留24小时;相同的键加相同的请求体将重放该响应,并带有响应头 Idempotent-Replay: true。
  3. 相同的键加不同的请求体,返回 409 idempotency_conflict。
  4. 即使不发送该请求头,订单号也是唯一的:重复提交会返回 409 order_exists。
header
Idempotency-Key: demo-2001

语言

?lang=en|fr|zh|ru 会改变名称、说明以及地名和国家名。快递公司的原始信息会原样返回。

GET /v1/track/:ref
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 01UPS芝加哥 → 奥斯汀派送中
6A10 0000 00011La Poste (Colissimo)里尔 → 波尔多已签收
XW 1234 5678 5FRChronopost巴黎 → 马赛派送失败
24680135Mondial Relay南特 → 图卢兹待取件
RV 1042 0001 9CN中国邮政义乌 → 喀山异常
1500 0420 17CDEK莫斯科 → 新西伯利亚运输中
YT 2611 1800 0000 0042云途物流义乌 → 波特兰已签收
7700 1111 8888FedEx纽约 → 丹佛异常
4810 0020 26DHL Express香港 → 伦敦退回寄件人
SF 1000 0000 02026顺丰速运深圳 → 杭州已签收
H00V AD00 0000 0001Evri曼彻斯特 → 伦敦长时间未更新
2500 0000 0020 26DPD France巴黎 → 里尔待发货