API Today Express

Публичный API для маркетплейсов, интернет-магазинов, WMS и ERP. Создавайте заявки на доставку из своей системы и получайте статусы вебхуками: сервер↔сервер, без входа в панель. Эта страница — полная и единственная документация: всё, что нужно разработчику, здесь.

Базовый URL ({base_url})Мы выдаём его вместе с API-ключом. Все пути в этой документации указаны относительно него.

Обзор

Интеграция строится вокруг одной сущности — заявки на доставку (order). Типичный сценарий:

  1. Покупатель оформил заказ у вас → вы вызываете POST /orders/ и получаете tracking_code.
  2. Курьер забирает посылку с вашего склада, при заборе ставит цену доставки по факту веса и габаритов и везёт получателю; на каждой смене статуса шлём вам вебхук.
  3. Покупатель отслеживает посылку по 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-KeyheaderнетЗаголовок при 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.

Справочники

Города и коды значений. Кэшируйте у себя — они меняются редко.

Список городов

GET/reference/locations/

Возвращает массив городов компании. id используется в to_location_id.

[
  { "id": 2, "name": "Ош", "name_en": "Osh", "latitude": 40.53, "longitude": 72.80 }
]

Справочник значений

GET/reference/enums/

Коды типов упаковки, веса и статусов (см. разделы ниже).

Заявки

Создать заявку

POST/orders/

Создаёт заявку в статусе «Ожидание» без цены. Передавайте заголовок Idempotency-Key.

ПолеТипОбяз.Описание
external_idstringнетваш id заказа — вернётся в ответах и вебхуках
to_location_idintegerдаid города получателя (/reference/locations/)
to_contactstringдателефон получателя +996, напр. 996700123456 или +996 700 123 456
to_full_namestringнетФИО получателя
to_addressstringдаадрес получателя
to_companystringнеткомпания получателя
viewintegerнеттип упаковки 1–5 (по умолч. 5 — Другое)
weightintegerнетградация веса 1–5 (по умолч. 5)
amountintegerнетколичество посылок в заявке (по умолч. 1)
commentstringнеткомментарий к заявке
Телефон получателя. Принимаем только номера +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. Так у каждой заявки свой ответ и своя ошибка, а повтор после сбоя безопасен.

Список заявок

GET/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": [ { /* объект заявки, как в ответе создания */ } ]
}

Заявка по трек-коду

GET/orders/{tracking_code}/

Возвращает тот же объект заявки, что и создание. Чужая или не своей среды заявка — 404.

Изменить заявку (до назначения курьера)

PATCH/orders/{tracking_code}/

Пока оператор не назначил курьера, можно поправить получателя и параметры посылки. Изменяемые поля: to_address, to_full_name, to_contact, comment, view, weight, amount.

Отменить заявку

POST/orders/{tracking_code}/cancel/

Возможно только пока оператор не назначил курьера: после назначения курьер может уже ехать к вам. Статус станет «Отмена» (9). Если нужно отменить позже — напишите нам.

Данные для наклейки

GET/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.

Зарегистрировать подписку

POST/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: при ретраях одно событие может прийти повторно.

Проверка подписи

Считайте HMAC по сырому телу запроса (bytes), до любого парсинга/переформатирования JSON. Если распарсить и заново сериализовать — подпись не сойдётся.
// 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ТипОбяз.Описание
400validation_error—тело или фильтр не прошёл проверку; подробности в fields
400invalid_phone—телефон не +996 — в fields.to_contact
400unknown_location—нет такого to_location_id; актуальный список — /reference/locations/
401missing_api_key—нет заголовка X-Api-Key
401invalid_api_key—ключ неверный или отозван
403permission_denied—у ключа нет права записи
404not_found—заявка, подписка или путь не найдены (в т.ч. чужая заявка и заявка другой среды)
409idempotency_mismatch—этот Idempotency-Key уже использован для заявки с другими данными
429rate_limited—превышен лимит; подождите Retry-After секунд
500internal_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:

POST/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