https://hopla.deliveryОт нуля до страницы отслеживания за три запроса
В примерах используются две переменные оболочки. Задайте их один раз:
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" } }'Откройте страницу
Страница заказа и страница каждой посылки доступны сразу, на четырех языках. Остается отправить ссылку покупателю.
Посмотреть страницу демо-заказа/ru/order/HP-1042
Авторизация
Для записи нужен API-ключ в заголовке Authorization. Поиск посылок открыт для всех.
Authorization: Bearer hopla_dev_keyЗаголовок X-Api-Key тоже принимается. Если ключа нет или он неверный, вернется 401 unauthorized. Чтение заказов и посылок возвращает персональные данные, поэтому для него тоже нужен ключ.
| Открытые эндпоинты | Описание |
|---|---|
| GET /v1/track/:ref | Находит посылку по трек-номеру или весь заказ по номеру либо идентификатору заказа. Из этого ответа строится каждая страница отслеживания. |
| 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/ordersAPI-ключ
/v1/ordersAPI-ключСоздает заказ с товарами и посылками одной транзакцией. Если хотя бы одна часть неверна, не записывается ничего.
| Имя | Тип | Описание |
|---|---|---|
| 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/ordersAPI-ключ
/v1/ordersAPI-ключСписок заказов, сначала новые, с фильтрами и курсорной пагинацией.
| Имя | Тип | Описание |
|---|---|---|
| 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/:refAPI-ключ
/v1/orders/:refAPI-ключВозвращает заказ целиком, включая персональные данные.
| Имя | Тип | Описание |
|---|---|---|
| refпутьобязательно | string | Идентификатор или номер заказа. |
| 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/:refAPI-ключ
/v1/orders/:refAPI-ключОбновляет заказ: этапы сборки, сообщение покупателю, товары. Номер заказа не меняется никогда.
| Имя | Тип | Описание |
|---|---|---|
| refпутьобязательно | string | Идентификатор или номер заказа. |
| 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/:refAPI-ключ
/v1/orders/:refAPI-ключУдаляет заказ вместе с посылками, товарами и событиями.
| Имя | Тип | Описание |
|---|---|---|
| refпутьобязательно | string | Идентификатор или номер заказа. |
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/eventsAPI-ключ
/v1/shipments/:id/eventsAPI-ключДобавляет одно событие или до 50 в массиве events. События можно присылать в любом порядке: статус всегда берется из самого позднего.
| Имя | Тип | Описание |
|---|---|---|
| idпутьобязательно | string | Идентификатор посылки или ее трек-номер. |
| substatusтелообязательно | string | Что произошло — код из модели статусов. |
| occurredAtтело | ISO 8601 | Когда это произошло, с местным смещением. По умолчанию — сейчас. |
| locationтело | { place } | { city, country, … } | Код места или свободные поля с необязательными координатами. |
| message · messageLangтело | string | Исходный текст службы доставки и его язык. Возвращается без изменений. |
| detailsтело | object | Дополнения для некоторых кодов: signedBy, window, deadline, reason. |
| externalIdтело | string | Ваш идентификатор события: отправленное дважды, оно запишется один раз. |
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-ключ
/v1/shipments/:id/events/:eventIdAPI-ключУдаляет ошибочное событие. Статус пересчитывается.
| Имя | Тип | Описание |
|---|---|---|
| idпутьобязательно | string | Идентификатор посылки или ее трек-номер. |
| 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/shipmentsAPI-ключ
/v1/shipmentsAPI-ключСоздает посылку отдельно или привязывает ее к существующему заказу. Обязателен только трек-номер.
| Имя | Тип | Описание |
|---|---|---|
| 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/shipmentsAPI-ключ
/v1/shipmentsAPI-ключСписок посылок, сначала новые, с фильтрами и курсорной пагинацией.
| Имя | Тип | Описание |
|---|---|---|
| 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/:idAPI-ключ
/v1/shipments/:idAPI-ключВозвращает посылку со всеми событиями, сначала новые. Вместо идентификатора можно указать трек-номер.
| Имя | Тип | Описание |
|---|---|---|
| idпутьобязательно | string | Идентификатор посылки или ее трек-номер. |
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-ключ
/v1/shipments/:idAPI-ключМеняет ожидаемую дату, службу доставки, последний этап, пункт выдачи или сценарий симулятора. Статус меняется только через события.
| Имя | Тип | Описание |
|---|---|---|
| idпутьобязательно | string | Идентификатор посылки или ее трек-номер. |
| 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/:idAPI-ключ
/v1/shipments/:idAPI-ключУдаляет посылку и ее события.
| Имя | Тип | Описание |
|---|---|---|
| idпутьобязательно | string | Идентификатор посылки или ее трек-номер. |
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ОткрытНаходит посылку по трек-номеру или весь заказ по номеру либо идентификатору заказа. Из этого ответа строится каждая страница отслеживания.
| Имя | Тип | Описание |
|---|---|---|
| refпутьобязательно | string | Трек-номер, номер последнего этапа, номер заказа, идентификатор заказа или посылки. |
| 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=ru&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=ruGET/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=ruGET/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=ruGET/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=ru&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/advanceAPI-ключ
/v1/simulator/shipments/:id/advanceAPI-ключДобавляет следующие запланированные события смоделированной посылки.
| Имя | Тип | Описание |
|---|---|---|
| idпутьобязательно | string | Идентификатор посылки или ее трек-номер. |
| 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/resetAPI-ключ
/v1/simulator/resetAPI-ключУдаляет демо-заказы и создает их заново со свежими датами. Заказы, которые создали вы, сохраняются.
| Имя | Тип | Описание |
|---|---|---|
| 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 | Такого идентификатора или номера нет. Для поиска в 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" } ]
}
}Идемпотентность
- При создании заказа или посылки передавайте заголовок
Idempotency-Keyдлиной до 100 символов. - Первый успешный ответ хранится 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 | YunExpress | Иу → Портленд | Доставлена |
| 7700 1111 8888 | Нью-Йорк → Денвер | Проблема с доставкой | |
| 4810 0020 26 | Гонконг → Лондон | Возврат отправителю | |
| SF 1000 0000 02026 | Шэньчжэнь → Ханчжоу | Доставлена | |
| H00V AD00 0000 0001 | Evri | Манчестер → Лондон | Нет обновлений |
| 2500 0000 0020 26 | Париж → Лилль | Ожидает отправки |