https://hopla.deliveryFrom zero to a tracking page in three calls
The examples use two shell variables. Set them once:
API=https://hopla.delivery
KEY=hopla_dev_keyCreate an order with its items and parcels
One call writes the order, its items and its parcels. Leave the carrier out and it is detected from the tracking number.
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 } } ] }'Append a checkpoint
Send a code, a place and, if you have it, the carrier’s own message. The parcel’s status follows its latest event.
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" } }'Open the page
The order page and a page per parcel are live at once, in four languages. Give your customer the link.
See a demo order page/en/order/HP-1042
Authentication
Write endpoints need an API key in the Authorization header. Lookups are public.
Authorization: Bearer hopla_dev_keyX-Api-Key is accepted too. A missing or wrong key answers 401 unauthorized. Order and shipment reads return personal data, so they need the key as well.
| Public endpoints | Description |
|---|---|
| GET /v1/track/:ref | Look up a parcel by tracking number, or a whole order by order number or order id. This is the answer every tracking page is drawn from. |
| POST /v1/track/batch | Look up as many as 40 references in one call. Each one gets its own result, found or not. |
| POST /v1/detect | Pull references out of free text and rank the carriers each one could belong to. |
| GET /v1/carriers | The carrier directory, with the patterns used to recognise numbers. |
| GET /v1/carriers/:slug | One carrier by its slug. |
| GET /v1/statuses | The status model with labels and descriptions in one language, or in all four. |
| GET /v1/places | The places events can point to: localised names, coordinates and time zones. |
| GET /health | Liveness and row counts. |
| GET /v1/simulator/scenarios | The journeys the simulator can play. |
The status model
Nine statuses for filters and colours, 52 sub-statuses for wording.
| Status | Code | What it means |
|---|---|---|
| Awaiting shipment | pending | The sender has registered this parcel, but the carrier doesn't have it yet. |
| In transit | in_transit | The parcel is moving through the carrier's network toward its destination. |
| Out for delivery | out_for_delivery | The parcel is with the courier and should be delivered today. |
| Ready for pickup | available_for_pickup | The parcel is waiting at a pickup point or locker. Bring an ID or your pickup code. |
| Delivered | deliveredfinal | The parcel has been delivered. |
| Delivery attempted | failed_attempt | The courier tried to deliver the parcel but couldn't. Another attempt or a pickup option usually follows. |
| Delivery issue | exception | Something is holding this parcel up. Check the latest update for what happens next. |
| Return to sender | returned | The parcel is going back, or has gone back, to the sender. |
| No recent updates | expired | The carrier hasn't reported anything for a long time. Contact the sender if the parcel hasn't arrived. |
At the store · 3 codes
order_placedOrder placed → pendingorder_processingBeing prepared → pendingorder_readyReady to ship → pending
First mile · 5 codes
info_receivedLabel created → pendingawaiting_carrier_pickupWaiting for carrier pickup → pendingpicked_upPicked up by carrier → in_transitdropped_offDropped off → in_transitaccepted_originAccepted at origin facility → in_transit
On the way · 4 codes
arrived_hubArrived at sorting facility → in_transitsortedSorted → in_transitdeparted_hubDeparted sorting facility → in_transitin_transitIn transit → in_transit
Export · 4 codes
export_hub_arrivedArrived at export hub → in_transitexport_customsExport customs clearance → in_transitdeparted_origin_countryDeparted country of origin → in_transittransit_countryArrived in transit country → in_transit
Customs and import · 7 codes
arrived_destination_countryArrived in destination country → in_transitcustoms_processingCustoms clearance in progress → in_transitcustoms_clearedCleared customs → in_transitcustoms_heldHeld at customs → exceptioncustoms_duties_dueDuties and taxes to pay → exceptioncustoms_info_requiredCustoms needs more information → exceptionhanded_to_local_carrierHanded to local carrier → in_transit
Last mile · 8 codes
arrived_delivery_depotArrived at delivery depot → in_transitout_for_deliveryOut for delivery → out_for_deliverydelivery_rescheduledDelivery rescheduled → in_transitdeliveredDelivered → delivereddelivered_mailboxDelivered to mailbox → delivereddelivered_signedDelivered and signed for → delivereddelivered_third_partyDelivered to neighbor or reception → delivereddelivered_safe_placeLeft in a safe place → delivered
Pickup points · 4 codes
arrived_pickup_pointArrived at pickup point → available_for_pickuppickup_reminderPickup reminder → available_for_pickuppicked_up_by_recipientCollected → deliveredpickup_expiredNot collected → returned
Delivery attempts · 6 codes
attempt_absentNobody home → failed_attemptattempt_closedPremises closed → failed_attemptaddress_issueAddress problem → exceptionrecipient_refusedRefused by recipient → exceptionrecipient_unreachableRecipient unreachable → exceptionawaiting_recipient_actionWaiting for the recipient → exception
Problems · 9 codes
delayedDelayed → exceptionmisroutedSent to the wrong facility → exceptiondamagedDamaged → exceptionlostLost → exceptionon_holdOn hold → exceptionsecurity_checkHeld for inspection → exceptionredirectedRedirected → in_transitcancelledShipment cancelled → exceptionno_updatesNo updates → expired
Returns · 2 codes
return_in_transitBeing returned to sender → returnedreturn_deliveredReturned to sender → returned
Reference
Every answer is { "data": … }, plus meta on lists, or { "error": … }. Field names are camelCase, timestamps are ISO 8601 with an offset.
Orders
POST/v1/ordersAPI key
/v1/ordersAPI keyCreate an order with its items and parcels in one transaction. If any part is invalid, nothing is written.
| Name | Type | Description |
|---|---|---|
| Idempotency-Keyheader | string | Makes a retry safe: the same key with the same body returns the first answer. |
| orderNumberbodyrequired | string | Your own number, 1 to 40 characters, unique. |
| storebodyrequired | object | name is required; url and supportEmail are optional. |
| customerbodyrequired | object | name is required. Public pages show it masked. |
| destinationbodyrequired | object | city and country are required. Street lines never appear on public pages. |
| itemsbodyrequired | Item[] | 1 to 100 items: title, quantity, and optionally variant, unitPriceCents, imageUrl. ref ties an item to a parcel. |
| shipmentsbody | Shipment[] | 0 to 20 parcels. An order can be created before anything ships. |
| localebody | en | fr | zh | ru | The customer’s language. |
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/ordersAPI key
/v1/ordersAPI keyList orders, newest first, with filters and cursor pagination.
| Name | Type | Description |
|---|---|---|
| qquery | string | Matches the order number, the customer’s name or email, or a tracking number. |
| statusquery | string | One or several status codes, separated by commas. |
| demoquery | 0 | 1 | Only demo orders, or only your own. |
| expandquery | shipments | events | Include each parcel’s events. |
| limitquery | integer | Page size. Default 20, at most 100. |
| cursorquery | string | meta.nextCursor of the previous page. |
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/:refAPI key
/v1/orders/:refAPI keyRead one order in full, personal data included.
| Name | Type | Description |
|---|---|---|
| refpathrequired | string | The order id or the order number. |
| expandquery | events | Include each parcel’s 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/:refAPI key
/v1/orders/:refAPI keyUpdate an order: store stages, a notice for the customer, items. The order number never changes.
| Name | Type | Description |
|---|---|---|
| refpathrequired | string | The order id or the order number. |
| processingAt · readyAt · cancelledAtbody | ISO 8601 | When the store started preparing, finished packing, or cancelled. |
| noticebody | string | null | A short message from the store, shown on the order page. |
| itemsbody | { add, update, remove } | Items to add, update or 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/:refAPI key
/v1/orders/:refAPI keyDelete an order with its parcels, items and events.
| Name | Type | Description |
|---|---|---|
| refpathrequired | string | The order id or the order number. |
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 ContentEvents
POST/v1/shipments/:id/eventsAPI key
/v1/shipments/:id/eventsAPI keyAppend one checkpoint, or as many as 50 in an events array. Events may arrive in any order: the status is always that of the latest one.
| Name | Type | Description |
|---|---|---|
| idpathrequired | string | The shipment id or its tracking number. |
| substatusbodyrequired | string | What happened, as a code from the status model. |
| occurredAtbody | ISO 8601 | When it happened, with the local offset. Default: now. |
| locationbody | { place } | { city, country, … } | A place code, or free fields with optional coordinates. |
| message · messageLangbody | string | The carrier’s own text and its language. Returned untouched. |
| detailsbody | object | Extras for some codes: signedBy, window, deadline, reason. |
| externalIdbody | string | Your own id for the event: sending it twice inserts it once. |
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/:eventIdAPI key
/v1/shipments/:id/events/:eventIdAPI keyRemove a wrong checkpoint. The status is recomputed.
| Name | Type | Description |
|---|---|---|
| idpathrequired | string | The shipment id or its tracking number. |
| eventIdpathrequired | string | The event to remove. |
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 ContentShipments
POST/v1/shipmentsAPI key
/v1/shipmentsAPI keyCreate a parcel on its own or attach it to an existing order. Only the tracking number is required.
| Name | Type | Description |
|---|---|---|
| Idempotency-Keyheader | string | Makes a retry safe: the same key with the same body returns the first answer. |
| trackingNumberbodyrequired | string | Stored upper-case, without spaces. Unique. |
| carrierbody | slug | Optional when the number’s shape names exactly one carrier. |
| lastMilebody | { trackingNumber, carrier } | The carrier that takes over in the destination country, and its number. |
| origin · destinationbody | object | City and country, or a place code. The destination defaults to the order’s. |
| deliveryTypebody | home | pickup_point | locker | mailbox | Where the parcel is handed over. |
| etabody | { from, to, window, source } | Estimated arrival: one date or a range, and who says so. |
| orderId · orderNumberbody | string | Attach the parcel to an existing order. |
| simulatebody | { scenario, autoStart } | Attach a simulator scenario; autoStart plays its first step at once. |
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/shipmentsAPI key
/v1/shipmentsAPI keyList parcels, newest first, with filters and cursor pagination.
| Name | Type | Description |
|---|---|---|
| qquery | string | Matches the tracking number, the label or the order number. |
| status · substatus · carrierquery | string | Filter by status, sub-status or carrier slug. |
| expandquery | events | Include each parcel’s events. |
| limitquery | integer | Page size. Default 20, at most 100. |
| cursorquery | string | meta.nextCursor of the previous page. |
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/:idAPI key
/v1/shipments/:idAPI keyRead one parcel with all its events, newest first. The tracking number works in place of the id.
| Name | Type | Description |
|---|---|---|
| idpathrequired | string | The shipment id or its tracking number. |
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/:idAPI key
/v1/shipments/:idAPI keyChange the estimate, the carrier, the last-mile leg, the pickup point or the simulator scenario. The status only changes through events.
| Name | Type | Description |
|---|---|---|
| idpathrequired | string | The shipment id or its tracking number. |
| etabody | object | null | Estimated arrival: one date or a range, and who says so. |
| carrier · lastMilebody | slug · object | The carrier that takes over in the destination country, and its number. |
| simulatebody | { scenario } | null | Attach a simulator scenario; autoStart plays its first step at once. |
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/:idAPI key
/v1/shipments/:idAPI keyDelete a parcel and its events.
| Name | Type | Description |
|---|---|---|
| idpathrequired | string | The shipment id or its tracking number. |
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 ContentTracking (public)
GET/v1/track/:refPublic
/v1/track/:refPublicLook up a parcel by tracking number, or a whole order by order number or order id. This is the answer every tracking page is drawn from.
| Name | Type | Description |
|---|---|---|
| refpathrequired | string | A tracking number, a last-mile number, an order number, an order id or a shipment id. |
| langquery | en | fr | zh | ru | Language of labels, descriptions and place names. Default en. |
| eventsquery | all | latest | latest returns only the newest event of each parcel (for lists). |
| verifyquery | string | Customer email or postal code, when the server asks to confirm order lookups. |
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=en&events=latestPOST/v1/track/batchPublic
/v1/track/batchPublicLook up as many as 40 references in one call. Each one gets its own result, found or not.
| Name | Type | Description |
|---|---|---|
| refsbodyrequired | string[] | 1 to 40 references. Duplicates are merged. |
| langbody | en | fr | zh | ru | Language of labels, descriptions and place names. Default en. |
| eventsbody | latest | all | latest returns only the newest event of each parcel (for lists). |
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 } }
}
}Carriers and detection
POST/v1/detectPublic
/v1/detectPublicPull references out of free text and rank the carriers each one could belong to.
| Name | Type | Description |
|---|---|---|
| inputbodyrequired | string | Free text, at most 5,000 characters. |
| langbody | en | fr | zh | ru | Language of labels, descriptions and place names. Default 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/carriersPublic
/v1/carriersPublicThe carrier directory, with the patterns used to recognise numbers.
| Name | Type | Description |
|---|---|---|
| qquery | string | Matches the name, the local name or the slug. |
| countryquery | ISO 3166-1 alpha-2 | Two-letter country code. |
| kindquery | postal | express | ecommerce | regional | Type of carrier. |
| popularquery | 1 | Only the carriers shown first. |
| langquery | en | fr | zh | ru | Language of labels, descriptions and place names. Default 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=enGET/v1/carriers/:slugPublic
/v1/carriers/:slugPublicOne carrier by its slug.
| Name | Type | Description |
|---|---|---|
| slugpathrequired | string | The carrier’s slug, such as la-poste. |
| langquery | en | fr | zh | ru | Language of labels, descriptions and place names. Default 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=enGET/v1/statusesPublic
/v1/statusesPublicThe status model with labels and descriptions in one language, or in all four.
| Name | Type | Description |
|---|---|---|
| langquery | en | fr | zh | ru | all | all returns the four languages side by side. |
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=enGET/v1/placesPublic
/v1/placesPublicThe places events can point to: localised names, coordinates and time zones.
| Name | Type | Description |
|---|---|---|
| countryquery | ISO 3166-1 alpha-2 | Two-letter country code. |
| langquery | en | fr | zh | ru | Language of labels, descriptions and place names. Default 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=en&country=FRGET/healthPublic
/healthPublicLiveness and row counts.
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 /healthSimulator
GET/v1/simulator/scenariosPublic
/v1/simulator/scenariosPublicThe journeys the simulator can play.
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/advanceAPI key
/v1/simulator/shipments/:id/advanceAPI keyAppend the next planned events of a simulated parcel.
| Name | Type | Description |
|---|---|---|
| idpathrequired | string | The shipment id or its tracking number. |
| stepsbody | 1–20 | How many planned events to append. Default 1. |
| tobody | substatus | "end" | Advance until this code has been emitted, or to the end. |
| atbody | now | spaced | spaced back-dates the events with realistic gaps so the last one is now. |
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/resetAPI key
/v1/simulator/resetAPI keyDelete the demo orders and create them again with fresh dates. Orders you created yourself are kept.
| Name | Type | Description |
|---|---|---|
| allbody | boolean | Also delete the orders created by hand. |
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 } }Errors
Errors share one envelope: a stable code, a message for developers and, when it helps, details.
| HTTP | Code | When |
|---|---|---|
| 400 | bad_request | The JSON is malformed or the content type is wrong. |
| 401 | unauthorized | The API key is missing or wrong. |
| 403 | verification_required | The server asks to confirm an order lookup and verify is missing or wrong. |
| 404 | not_found | No such id or reference. For lookups, details says what the number looks like. |
| 409 | order_exists | The order number is already taken. details.existingId names the order. |
| 409 | tracking_exists | The tracking number is already registered. |
| 409 | idempotency_conflict | The same idempotency key came with a different body. |
| 413 | too_many | More than 40 references, 50 events or 100 items in one call. |
| 422 | validation_error | The body failed validation. details lists each path and its problem. |
| 429 | rate_limited | Too many public calls from one address. Wait for Retry-After. |
| 500 | internal | Anything else. The message is generic; the cause is in the server log. |
{
"error": {
"code": "validation_error",
"message": "Request body is invalid.",
"details": [ { "path": "items[0].quantity", "message": "Must be an integer ≥ 1" } ]
}
}Idempotency
- Send an
Idempotency-Keyheader of up to 100 characters when you create an order or a shipment. - The first successful answer is kept for 24 hours and replayed for the same key and body, with the header
Idempotent-Replay: true. - The same key with a different body answers
409 idempotency_conflict. - Even without the header, an order number is unique: posting it again answers
409 order_exists.
Idempotency-Key: demo-2001Languages
?lang=en|fr|zh|ru changes labels, descriptions, place and country names. Raw carrier messages are returned untouched.
curl "$API/v1/track/LV202611181CN?lang=fr"
curl "$API/v1/track/LV202611181CN?lang=zh"
curl "$API/v1/track/LV202611181CN?lang=ru"Demo data
Fourteen demo parcels cover every status. A simulator moves them, so the status column shows where each one is right now.
| Tracking number | Carrier | Route | Status |
|---|---|---|---|
| LV 2026 1118 1CN | Shenzhen → Lyon | In transit | |
| LP 0042 0000 0000 17 | Shenzhen → Lyon | Awaiting shipment | |
| 1ZVA D0DE MO00 0000 01 | Chicago → Austin | Out for delivery | |
| 6A10 0000 00011 | Lille → Bordeaux | Delivered | |
| XW 1234 5678 5FR | Paris → Marseille | Delivery attempted | |
| 24680135 | Nantes → Toulouse | Ready for pickup | |
| RV 1042 0001 9CN | Yiwu → Kazan | Delivery issue | |
| 1500 0420 17 | Moscow → Novosibirsk | In transit | |
| YT 2611 1800 0000 0042 | YunExpress | Yiwu → Portland | Delivered |
| 7700 1111 8888 | New York → Denver | Delivery issue | |
| 4810 0020 26 | Hong Kong → London | Return to sender | |
| SF 1000 0000 02026 | Shenzhen → Hangzhou | Delivered | |
| H00V AD00 0000 0001 | Evri | Manchester → London | No recent updates |
| 2500 0000 0020 26 | Paris → Lille | Awaiting shipment |