API Today Express
Публичный API для маркетплейсов, интернет-магазинов, WMS и ERP. Создавайте заявки на доставку из своей системы и получайте статусы вебхуками: сервер↔сервер, без входа в панель. Эта страница — полная и единственная документация: всё, что нужно разработчику, здесь.
{base_url})Мы выдаём его вместе с API-ключом. Все пути в этой документации указаны относительно него.Обзор
Интеграция строится вокруг одной сущности — заявки на доставку (order). Типичный сценарий:
- Покупатель оформил заказ у вас → вы вызываете
POST /orders/и получаетеtracking_code. - Курьер забирает посылку с вашего склада, при заборе ставит цену доставки по факту веса и габаритов и везёт получателю; на каждой смене статуса шлём вам вебхук.
- Покупатель отслеживает посылку по
tracking_urlна нашем сайте (ссылку вы передаёте ему сами) — вопросов «где заказ» меньше.
tracking_code — единственный идентификатор заявки в API: по нему она запрашивается, меняется и отменяется, он же приходит в вебхуках. Внутренних числовых id в ответах нет.price = null: финальную цену ставит курьер при заборе, она приходит в вебхуке order.status_changed со статусом 2 и в GET /orders/{tracking_code}/. Расчёты за доставку — по договору, вне API.Быстрый старт
Два запроса от нуля до созданной заявки. Начинайте с тестового ключа.
# 1. Узнать id города получателя
curl -s {base_url}/reference/locations/ \
-H "X-Api-Key: ВАШ_ТЕСТОВЫЙ_КЛЮЧ"
# 2. Создать заявку (сохраните tracking_code — это идентификатор заявки,
# и info_qr_url — готовый QR для печати на посылку)
curl -s -X POST {base_url}/orders/ \
-H "X-Api-Key: ВАШ_ТЕСТОВЫЙ_КЛЮЧ" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-5567" \
-d '{
"external_id": "order-5567",
"to_location_id": 2,
"to_full_name": "Айбек Асанов",
"to_contact": "996700123456",
"to_address": "мкр Восток-5, д. 12, кв. 3"
}'Авторизация
Каждый запрос требует заголовок:
X-Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx- Ключ выдаёт Today Express. Есть два вида: тестовый (sandbox) и боевой. По самому ключу среду не видно — не перепутайте, храните их раздельно.
- Ключ определяет вашу компанию, среду и права. Права бывают «чтение» (только
GET) и «чтение и запись». - В БД хранится только хэш ключа. Полный ключ показывается один раз при выдаче — сохраните его.
- Вы видите только свои заявки и только своей среды: тестовый ключ не видит боевые заявки, боевой — тестовые.
- Отзыв и перевыпуск ключа и ваш профиль-отправитель меняются через Today Express — напишите нам, сделаем.
Соглашения
| Правило | Тип | Обяз. | Описание |
|---|---|---|---|
| Слеш в конце | — | да | Все пути оканчиваются на /. Без него — 404. |
| Content-Type | — | да | Для POST/PATCH — application/json, тело в UTF-8. |
| Idempotency-Key | header | нет | Заголовок при POST /orders/, до 128 символов: повтор с тем же значением и тем же телом вернёт ту же заявку, а не создаст дубль. Тот же ключ с другим телом → 409 idempotency_mismatch. |
| Телефоны | — | да | Только номера +996. На вход принимаем 996700123456, +996 700 123 456, 0700123456; храним и отдаём как 996XXXXXXXXX. Другая страна → 400 invalid_phone. |
| Идентификатор | — | — | Заявка адресуется по tracking_code, напр. /orders/TEKG-202610-3A5361D1ARDW/. |
| Длины полей | — | — | Адрес до 256 символов, ФИО и компания до 128, комментарий до 1000, external_id до 128. Длиннее → 400. |
| Цена | — | — | Не передаётся: поле price во входных данных игнорируется. При создании price = null, финальную цену ставит курьер при заборе. |
| Даты | — | — | В ответах — ISO-8601 с таймзоной. В фильтрах — YYYY-MM-DD. |
Справочники
Города и коды значений. Кэшируйте у себя — они меняются редко.
Список городов
/reference/locations/Возвращает массив городов компании. id используется в to_location_id.
[
{ "id": 2, "name": "Ош", "name_en": "Osh", "latitude": 40.53, "longitude": 72.80 }
]Справочник значений
/reference/enums/Коды типов упаковки, веса и статусов (см. разделы ниже).
Заявки
Создать заявку
/orders/Создаёт заявку в статусе «Ожидание» без цены. Передавайте заголовок Idempotency-Key.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
external_id | string | нет | ваш id заказа — вернётся в ответах и вебхуках |
to_location_id | integer | да | id города получателя (/reference/locations/) |
to_contact | string | да | телефон получателя +996, напр. 996700123456 или +996 700 123 456 |
to_full_name | string | нет | ФИО получателя |
to_address | string | да | адрес получателя |
to_company | string | нет | компания получателя |
view | integer | нет | тип упаковки 1–5 (по умолч. 5 — Другое) |
weight | integer | нет | градация веса 1–5 (по умолч. 5) |
amount | integer | нет | количество посылок в заявке (по умолч. 1) |
comment | string | нет | комментарий к заявке |
+996. Пробелы, скобки, плюс и ведущий 0 уберём сами; в ответах и вебхуках номер всегда 996XXXXXXXXX. Номер другой страны — 400 с кодом invalid_phone. Неизвестные поля в теле (в т.ч. price) игнорируются.Ответ (201 Created; при повторе с тем же Idempotency-Key — 200 OK и та же заявка):
HTTP 201 Created
{
"tracking_code": "TEKG-202610-3A5361D1ARDW",
"external_id": "order-5567",
"status": 1,
"status_name": "Ожидание",
"from_location": "Бишкек",
"from_address": "Дордой, проход 2, ангар 6",
"from_contact": "996999666777",
"to_location": "Ош",
"to_address": "мкр Восток-5, д. 12, кв. 3",
"to_full_name": "Айбек Асанов",
"to_contact": "996700123456",
"view": 5,
"weight": 2,
"amount": 1,
"price": null,
"comment": null,
"is_sandbox": true,
"info_qr_url": "https://aircore.fra1.cdn.digitaloceanspaces.com/qr/TEKG-202610-3A5361D1ARDW.png",
"label_data_url": "{base_url}/orders/TEKG-202610-3A5361D1ARDW/label/",
"tracking_url": "https://todayexpress.kg/track/TEKG-202610-3A5361D1ARDW/",
"created_date": "2026-10-16T11:31:12+06:00",
"last_status_date": null
}price всегда null. Курьер при заборе взвешивает и осматривает посылку и ставит финальную цену. Она приходит в вебхуке order.status_changed со статусом 2 («Забрал») в поле data.price и дальше отдаётся в GET /orders/{tracking_code}/. До этого момента цена заявки не определена.Пакетного эндпоинта нет: создавайте заявки по одной, каждую со своим Idempotency-Key. Так у каждой заявки свой ответ и своя ошибка, а повтор после сбоя безопасен.
Список заявок
/orders/Пагинация. Фильтры (query): status (1–9), external_id, from_date, to_date (YYYY-MM-DD), page. Неверное значение фильтра → 400.
GET /orders/?status=1&from_date=2026-10-01&page=1
{
"count": 42,
"next": "{base_url}/orders/?page=2",
"previous": null,
"results": [ { /* объект заявки, как в ответе создания */ } ]
}Заявка по трек-коду
/orders/{tracking_code}/Возвращает тот же объект заявки, что и создание. Чужая или не своей среды заявка — 404.
Изменить заявку (до назначения курьера)
/orders/{tracking_code}/Пока оператор не назначил курьера, можно поправить получателя и параметры посылки. Изменяемые поля: to_address, to_full_name, to_contact, comment, view, weight, amount.
Отменить заявку
/orders/{tracking_code}/cancel/Возможно только пока оператор не назначил курьера: после назначения курьер может уже ехать к вам. Статус станет «Отмена» (9). Если нужно отменить позже — напишите нам.
Данные для наклейки
/orders/{tracking_code}/label/Возвращает поля в JSON и ссылку на готовый QR. info_qr_url — PNG с QR-кодом трек-кода и логотипом Today Express: печатайте его на посылку, по нему склад и курьеры находят заявку. Ссылка приходит сразу в ответе на создание, сам файл появляется по ней в течение нескольких секунд. Если верстаете наклейку сами, qr_value = tracking_code — закодируйте его в QR. Ссылка на этот эндпоинт приходит в ответе создания как label_data_url.
{ "tracking_code": "TEKG-202610-3A5361D1ARDW", "qr_value": "TEKG-202610-3A5361D1ARDW",
"info_qr_url": "https://aircore.fra1.cdn.digitaloceanspaces.com/qr/TEKG-202610-3A5361D1ARDW.png",
"to_location": "Ош", "to_address": "…", "to_full_name": "…",
"to_contact": "996700123456", "from_location": "Бишкек",
"weight": 2, "amount": 1 }Вебхуки
Вместо опроса — мы сами шлём POST на ваш URL при событиях. Зарегистрируйте подписку, проверяйте подпись, отвечайте 2xx.
Зарегистрировать подписку
/webhooks/POST /webhooks/
{
"url": "https://ваш-магазин.kg/api/te-webhook",
"secret": "случайная_строка_которую_знаете_только_вы",
"events": [] // [] = все события; можно ["order.status_changed"]
}
// url — только https:// и только публичный адрес (не localhost, не 10.x/192.168.x)
// secret — от 16 символов; неизвестное событие в events → 400
HTTP 201 Created
{ "id": 3, "url": "...", "events": [], "is_active": true, "created_date": "..." }Управление: GET /webhooks/ — список, PATCH /webhooks/{id}/ — сменить url, secret или events без пересоздания, DELETE /webhooks/{id}/ — отключить (журнал доставок сохраняется), GET /webhooks/deliveries/?status=failed — журнал доставок (трек-код, статус pending / success / failed / dead, попытки, код ответа, ошибка, время следующего повтора).
Какие события мы шлём
| Событие | Тип | Обяз. | Описание |
|---|---|---|---|
order.created | — | — | заявка создана |
order.status_changed | — | — | статус изменился; конкретный статус — в data.status (1–9) и data.status_name. Со статусом 2 («Забрал») приходит финальная data.price |
order.price_changed | — | — | цена изменилась без смены статуса (например, оператор поправил её после забора); новая — в data.price, прежняя — в data.previous_price |
Тело события и заголовки
POST на ваш URL
Content-Type: application/json
X-TE-Event: order.status_changed
X-TE-Delivery: 445e217b-d052-4ac2-a75c-f5161b0af563
X-TE-Timestamp: 1760602930
X-TE-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b...
{
"event_id": "445e217b-d052-4ac2-a75c-f5161b0af563",
"type": "order.status_changed",
"created_at": "2026-10-16T14:22:10+06:00",
"data": {
"tracking_code": "TEKG-202610-3A5361D1ARDW",
"external_id": "order-5567",
"status": 2,
"status_name": "Забрал",
"price": 350.0,
"from_location": "Бишкек",
"to_location": "Ош",
"info_qr_url": "https://aircore.fra1.cdn.digitaloceanspaces.com/qr/TEKG-202610-3A5361D1ARDW.png",
"last_status_date": "2026-10-16T14:22:09+06:00"
}
}X-TE-Signature—sha256=+ HMAC-SHA256 вашимsecretот строки<X-TE-Timestamp>.<сырое тело>.X-TE-Timestamp— время отправки, Unix-секунды. Отклоняйте запросы старше 5 минут: так перехваченный вебхук нельзя повторить позже.X-TE-Event— тип события,X-TE-Delivery— он жеevent_id.- Дедуплицируйте по
event_id: при ретраях одно событие может прийти повторно.
Проверка подписи
// Node.js (Express). Важно: подпись считается по СЫРОМУ телу запроса.
const crypto = require("crypto");
const SECRET = process.env.TE_WEBHOOK_SECRET;
app.post("/api/te-webhook",
express.raw({ type: "application/json" }), // получаем Buffer, не парсим заранее
(req, res) => {
const ts = req.header("X-TE-Timestamp") || "";
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end();
const expected = "sha256=" +
crypto.createHmac("sha256", SECRET).update(ts + ".").update(req.body).digest("hex");
const got = req.header("X-TE-Signature") || "";
const ok = expected.length === got.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
if (!ok) return res.status(401).end();
const event = JSON.parse(req.body.toString("utf8"));
// TODO: дедуп по event.event_id, затем обработка
res.status(200).json({ ok: true });
});<?php // PHP
$secret = getenv('TE_WEBHOOK_SECRET');
$raw = file_get_contents('php://input'); // сырое тело
$ts = $_SERVER['HTTP_X_TE_TIMESTAMP'] ?? '';
if (abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $secret);
$got = $_SERVER['HTTP_X_TE_SIGNATURE'] ?? '';
if (!hash_equals($expected, $got)) { http_response_code(401); exit; }
$event = json_decode($raw, true);
// TODO: дедуп по $event['event_id'], затем обработка
http_response_code(200);
echo json_encode(['ok' => true]);# Python (Flask). Считаем HMAC по request.get_data() — сырому телу.
import hmac, hashlib, os, time
from flask import request, abort
SECRET = os.environ["TE_WEBHOOK_SECRET"].encode()
@app.post("/api/te-webhook")
def te_webhook():
raw = request.get_data()
ts = request.headers.get("X-TE-Timestamp", "")
if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
abort(401)
expected = "sha256=" + hmac.new(SECRET, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-TE-Signature", "")):
abort(401)
event = request.get_json()
# TODO: дедуп по event["event_id"], затем обработка
return {"ok": True}, 200Ретраи и надёжность
- Ответьте кодом
2xxв течение 10 секунд — иначе доставка считается неуспешной. - До 6 попыток с нарастающей паузой:
1м → 5м → 30м → 2ч → 6ч. После — статусdead, дальше не шлём. - Событие записывается в журнал в той же транзакции, что и смена статуса: если очередь или сеть легли, доставка останется
pending, и фоновый процесс дошлёт её в течение пары минут. Если ваш приёмник не отвечает все 6 попыток (около 9,5 часов), событие получит статусdeadи больше не придёт — его видно в журнале доставок. Порядок между близкими событиями не гарантирован — ориентируйтесь наdata.status, а не на порядок прихода. - Обработку делайте идемпотентной (по
event_id) и быстрой; тяжёлое — в фоновую очередь у себя. - История попыток видна в
GET /webhooks/deliveries/. - Пропустили событие (приёмник лежал)? Отдельной ленты событий и повторной доставки по запросу пока нет — актуальное состояние восстановите опросом
GET /orders/(фильтрыstatus,from_date).
Статусы заявки
Приходят в status (код) и status_name. Ориентируйтесь на код — названия для отображения.
| Код | Тип | Обяз. | Описание |
|---|---|---|---|
| 1 | Ожидание | — | заявка создана, ждёт курьера |
| 2 | Забрал | — | курьер забрал у отправителя и поставил цену доставки |
| 3 | На складе | — | принято на склад |
| 4 | Отправлено | — | отправлено в город назначения |
| 5 | Получено | — | прибыло / получено в городе назначения |
| 6 | Готов к доставке | — | готово к вручению получателю |
| 7 | Завершено | — | вручено, заявка закрыта |
| 8 | Возврат | — | посылка вернулась на ваш склад. Промежуточные статусы обратного пути не присылаем: до этого заявка остаётся в последнем статусе перед возвратом, затем сразу 8 с итоговой ценой |
| 9 | Отмена | — | отменено вами, оператором или системой: заявка, не забранная за день, отменяется в 05:00 следующего дня (по Бишкеку) |
Справочные значения
Тип упаковки (view)
| Код | Тип | Обяз. | Описание |
|---|---|---|---|
| 1 | Документ | — | |
| 2 | Конверт | — | |
| 3 | Коробка | — | |
| 4 | Пакет | — | |
| 5 | Другое | — |
Вес (weight)
| Код | Тип | Обяз. | Описание |
|---|---|---|---|
| 1 | до 1 кг | — | |
| 2 | до 5 кг | — | |
| 3 | до 10 кг | — | по договор. |
| 4 | до 15 кг | — | по договор. |
| 5 | Другое | — | по договор. |
Градация веса нужна курьеру и складу как ориентир. Цену доставки курьер ставит при заборе по фактическому весу и габаритам посылки.
Ошибки
Любая ошибка — один и тот же конверт. code — машинный код для ветвления в вашем коде, message — текст для логов, fields — ошибки по полям (только при 400).
HTTP 400 Bad Request
{
"error": {
"code": "invalid_phone",
"message": "Нужен номер в формате +996XXXXXXXXX",
"fields": { "to_contact": ["Нужен номер в формате +996XXXXXXXXX"] }
}
}
// Несколько разных ошибок сразу → code: "validation_error", все поля в fields.
// 401 / 403 / 404 / 429 приходят без fields.| HTTP | Тип | Обяз. | Описание |
|---|---|---|---|
| 400 | validation_error | — | тело или фильтр не прошёл проверку; подробности в fields |
| 400 | invalid_phone | — | телефон не +996 — в fields.to_contact |
| 400 | unknown_location | — | нет такого to_location_id; актуальный список — /reference/locations/ |
| 401 | missing_api_key | — | нет заголовка X-Api-Key |
| 401 | invalid_api_key | — | ключ неверный или отозван |
| 403 | permission_denied | — | у ключа нет права записи |
| 404 | not_found | — | заявка, подписка или путь не найдены (в т.ч. чужая заявка и заявка другой среды) |
| 409 | idempotency_mismatch | — | этот Idempotency-Key уже использован для заявки с другими данными |
| 429 | rate_limited | — | превышен лимит; подождите Retry-After секунд |
| 500 | internal_error | — | наша ошибка; повторите позже, мы уже видим её в логах |
Лимиты и тестовый режим
Rate limiting
Лимит запросов считается на ключ (по умолчанию 120 запросов в минуту) и общий для всех наших серверов. При превышении — 429 с заголовком Retry-After (секунды до следующей попытки). Запросы без ключа или с неверным ключом ограничены отдельно по IP. Тело запроса — до 2 МБ, запрос больше отклоняется. Нужен лимит выше — напишите нам.
Sandbox (тестовый ключ)
Тестовый ключ ходит в тот же API, но заявки помечаются is_sandbox: true и не попадают реальным курьерам и операторам. Трек-коды тестовых заявок начинаются с TEST-, на публичном трекинге их нет, а info_qr_url ведёт на QR, который рисует наш API. Вебхуки тестовых заявок повторяются 2 раза, а не 6. Среды изолированы: тестовый ключ не видит боевые заявки и не может их менять, боевой — тестовые. Проверили всё — присылаете нам «готовы», переключаетесь на боевой ключ.
Так как sandbox-заявки не двигают операторы, статусы у них меняете вы сами — тест-эндпоинтом, чтобы проверить приход вебхука order.status_changed:
/orders/{tracking_code}/test/advance/POST /orders/TEKG-202610-3A5361D1ARDW/test/advance/ { "status": 2, "price": 350 }
→ статус «Забрал» с ценой 350, прилетает вебхук order.status_changedРаботает только для тестовых заявок; на боевом ключе вернёт 400. Прогоните заявку по статусам (2 → 3 → 4 → 5 → 6 → 7) и убедитесь, что вебхуки приходят и подпись сходится. Курьера в sandbox нет: чтобы проверить цену, передайте её вместе со статусом 2, как в примере.
Получить ключ и поддержка
- Как получить доступ к API?
- Напишите нам в WhatsApp — мы заведём вас как партнёра и выдадим два ключа: тестовый (sandbox) и боевой. Ключ определяет вашу компанию, среду и права; больше от вас ничего не нужно.
- Нужно ли опрашивать статусы заказов?
- Нет. Зарегистрируйте вебхук — мы сами шлём POST на ваш URL при каждом изменении статуса. Каждый вебхук подписан (HMAC), чтобы вы убедились, что запрос от нас.
- Можно ли протестировать перед боевым запуском?
- Да. Тестовый (sandbox) ключ ходит в тот же API, но заявки помечаются как тестовые (is_sandbox=true) и не уходят реальным курьерам/операторам. Статусы sandbox-заявки вы прогоняете сами через POST /orders/{tracking_code}/test/advance/ — так проверяете приход вебхуков order.status_changed до боевого запуска.
- Кто указывает адрес отправителя?
- Мы. Ваш склад (город, адрес, телефон) хранится в вашем профиле партнёра. В запросе на создание заявки вы передаёте только получателя и посылку — откуда забрать подставляем сами.
- Кто ставит цену доставки?
- Курьер при заборе посылки, по фактическому весу и габаритам. В ответе на создание price = null; финальная цена приходит в вебхуке order.status_changed со статусом 2 и в GET /orders/{tracking_code}/. Через API цена не передаётся.
- Получит ли покупатель уведомления с трекингом от Today Express?
- По умолчанию нет: по заявкам через API мы не шлём получателю трек-ссылку — статусы вы показываете сами в своей системе (через вебхуки). Это настраивается: по вашей просьбе мы можем включить отправку WhatsApp-ссылки с трекингом напрямую получателю. По обычным заявкам (не через API) уведомления получателю работают как раньше.
Готовы подключиться?
Напишите нам — заведём вас партнёром и выдадим тестовый и боевой ключи. Начать можно с sandbox, без обязательств.
Написать в WhatsApp
