Единый набор API для партнёров по доставке в Казахстане, всего с двумя основными сущностями — Задание (задание на забор) и Посылка (каждое место внутри Задания). Принимайте задания, доставляйте до двери (по городу и между городами) и передавайте посылки партнёрским перевозчикам. Интегрируйте свою систему или используйте delivery.atasuai.com панели.
Все партнёры делают одно и то же: забрать, перевезти, доставить. Накладные, этикетки и трек-номера перевозчиков формирует централизованно Atasuai — курьер, у которого есть только телефон, может начать сегодня. Партнёры, способные сами передавать грузы перевозчику, подключают это как дополнительную возможность.
Принимайте задания на забор, забирайте партию целиком, обновляйте статус каждой Посылки и отправляйте подтверждение доставки. Scope deliveries:read · deliveries:write
У каждой Посылки есть трек-номер и этикетка, только для чтения. Scope tracking:read
Бронируйте штрих-коды, печатайте пустые накладные и формируйте опись передачи перевозчику (например, Форма 103 QazPost). Scope consolidation:write
Продавец объединяет несколько посылок в одно Задание, выбирает интервал забора и публикует его; сегодня это открытый маркетплейс — каждый Агент в сети видит ожидающие Задания, и кто первым вызовет accept , тот и получает (эксклюзивное распределение и 10-минутный таймер переназначения пока Запланировано). Забор — на уровне Задания (курьер забирает партию целиком), а направление — на уровне Посылки — в одном Задании могут быть оба типа ниже, и после забора каждое место идёт по своему destination.
Работает в собственной сети доставки Atasuai. После забора посылка идёт прямо до двери покупателя — по городу или между городами (в зависимости от зоны обслуживания Агента), без участия сторонних перевозчиков.
Первая миля — забор. После забора посылка передаётся в отделение одного из интегрированных сторонних перевозчиков (carrier_code: qazpost / filp / …) — трек-номер перевозчика выдаётся из централизованного пула номеров Atasuai.
carrier_codeВ домене Доставки всего две основные сущности. Задание — задание на забор, опубликованное продавцом и назначенное одному Агенту; Посылка — каждое место внутри Задания, со своим направлением и статусом. Освойте эти две сущности — и вы освоили всю интеграцию доставки.
// Published by the seller; any online Agent can claim it (first to accept wins) { "id": "job_4471", "batch_no": "PB-4471", "status": "pending", "accept_deadline": "2026-07-22T09:18:32Z", // informational only, not enforced yet "seller": { "name": "Oscar ЖК" }, "pickup": { "address": "Алматы, Абай 150, оф.3", "window": { "from": "14:00", "to": "16:00" }, "pickup_by": "2026-07-22T16:00:00Z" }, "courier": null, // optional "totals": { "package_count": 6, "total_weight_kg": 6.5 }, "packages": [ "pkg_88213", "…" ] }
// Each item within a Job, with its own destination and status { "id": "pkg_88213", "job_id": "job_4471", "tracking_number": "AI556489715KZ", "destination": "carrier", // door | carrier "carrier_code": "qazpost", // when carrier "status": "pending", "recipient": { "name": "Елена", "phone": "+7 7•• •••" }, "weight_kg": 0.7, "cod": null }
Забор — на уровне Задания (партия забирается целиком); доставка/передача — на уровне Посылки (обновляется по каждому месту после забора).
pending ──accept──▶ accepted │ │ │ pickup (whole batch) │ ▼ │ picked_up ──▶ completed │ ├─(auto-reassign on timeout — planned, not enforced)─▶ expired └─(seller cancels)────▶ cancelled
pending ▶ picked_up ▶ in_transit ▶ out_for_delivery ▶ verify // OTP verification ▶ delivered ✕ failed / returned
pending ▶ picked_up ▶ handed_off // Form 103 handoff ── carrier takes over ── ▶ in_transit ▶ delivered ✕ exception
Каждая Посылка с доставкой до двери (destination=door) рассчитана на индивидуальную доставку и подтверждение — получатель подтверждает лично одноразовым кодом от платформы, что исключает получение посторонним. Например: AI0123423443KZ . Всё, что помечено Запланировано — эндпоинт, событие или правило — пока не реализовано и показано только как план; реально работающий сегодня процесс подтверждения доставки — это out-for-delivery / deliver эндпоинты в справочнике API ниже.
// ① The rider arrives at the door and requests a code for this package POST …/packages/pkg_88213/delivery-code → The platform sends an SMS to the recipient / a push to the buyer's app → The code goes only to the recipient and is never returned to the partner // ② The recipient reads out the code and the rider submits it for verification POST …/packages/pkg_88213/verify { "code": "4821" } → 200 { "status": "delivered", "delivered_at": "2026-07-22T15:12Z" }
delivered и служит подтверждением доставки (POD) для этого места./packages/{id}/proof.Это жёсткие контракты. Соблюдайте их при интеграции своей системы; если не хотите строить своё — используйте delivery.atasuai.com панель напрямую — возможности идентичны.
pending Задание видно всем Агентам (GET /jobs?status=pending), и кто первым вызовет accept , тот и получает — опоздавшие получают 409. accept_deadline возвращается, но не применяется; эксклюзивное распределение, 10-минутный таймер и автопереназначение через job.expired — всё это Запланировано.destination (door / carrier) и независимый статус. В одном Задании могут быть оба направления.POST /jobs/{id}/pickup забирает партию целиком); delivery/handoff is at the Посылка level, по каждому месту: POST /packages/{id}/out-for-delivery → /deliver (неудачные попытки идут через /delivery-failed, возвраты через /return); carrier handoff is POST /jobs/{id}/handoff. Универсальный POST /packages/{id}/status пока не реализован, Запланировано./packages/{id}/delivery-code отправляет код, /packages/{id}/verify verifies it as delivered; ни один из эндпоинтов пока не реализован. Сегодняшний аналогичный процесс: POST /packages/{id}/out-for-delivery выдаёт код для посылок door , а POST /packages/{id}/deliver требует этот код (для door) для подтверждения доставки, фото и имя получателя — по желанию.POST /jobs/{id}/courier не обязателен — можно продолжить, не назначая курьера (как и в панели).POST /jobs/{id}/handoff формирует её (например, QazPost Form 103), and POST /jobs/{id}/form103 rebuilds it; consolidation:write разрешает самостоятельное использование.carrier_code.Idempotency-Key (заголовок принимается); однако API Доставки пока не обеспечивает идемпотентный повтор, Запланировано — не полагайтесь на это для защиты от дублей. Ошибки в формате RFC 7807 problem+json; списки используют курсорную пагинацию; ограничение частоты — по tenant.jobs:write) + проверять отслеживание (tracking:read); Агенты интегрируются, чтобы принимать и выполнять (deliveries:*, consolidation:write). Ключи агента временно отключены (/oauth/token returns 503 для ключей агента); ключи продавца не затронуты.Три шага. Machine-to-machine — без входа пользователя и без редиректов.
Получите client_id and client_secret в партнёрской панели или у Atasuai при подключении. Секрет показывается только один раз. Ключи агента (партнёра по доставке) временно отключены (/oauth/token returns 503 для ключей агента); ключи продавца работают штатно.
Обменяйте ключи на bearer-токен с ограниченными scope, действующий 15 минут (900 секунд).
# POST /oauth/token curl -u $ID:$SECRET \ https://open.atasuai.com/oauth/token \ -d grant_type=client_credentials \ -d scope="deliveries:write"
Вызовите API со своим токеном. Операции записи требуют Idempotency-Key.
# Accept a pending Job (first come, first served — first to accept wins) curl -X POST \ …/delivery/v1/jobs/{id}/accept \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)"
Все сущности следуют одним соглашениям — освоив один эндпоинт, вы знаете их все.
Токены client-credentials несут tenant и набор scope. Вы видите только то, что вам выдано — deliveries:*, tracking:read, and so on.
Операции записи должны передавать Idempotency-Key — заголовок принимается, но API Доставки пока не выполняет дедупликацию / повтор , поэтому повторы могут создать дубликаты; пока ограничивайте их на своей стороне.
Изменения статуса отправляются заранее и подписываются HMAC (sha256={ts}.{body}), с защитой от повторов; повторы идут по схеме 5s, 30s, 2m, 10m, 30m, 2h, 6h, 12h, 24h, 48h — 10 попыток примерно за 4 дня.
RFC 7807 problem+json, со стабильным error_code and a request_id для диагностики — разберите один раз, применяйте везде.
Запланировано. Шлюз сегодня не ограничивает частоту и не возвращает заголовки Retry-After / X-RateLimit-* . Ограничение по tenant появится до запуска.
Полностью изолированная среда: sandbox.open.atasuai.com is скоро (сертификат пока не готов, внешне не обслуживает). Тот же контракт, тестовые штрих-коды, никаких реальных посылок и денег.
Подпишитесь один раз; можно также опрашивать GET /delivery/v1/jobs?status=pending для текущего списка ожидающих. События с пометкой Запланировано пока фактически не отправляются.
Пути разделены по домену и версионированы. Эндпоинты с пометкой Запланировано пока не реализованы и показаны только как план. Полный интерактивный справочник — на сайте документации.
| Метод | Эндпоинт | Scope |
|---|---|---|
| Задания · /delivery/v1 | ||
| GET | /delivery/v1/jobs?status=pending (все ожидающие задания, видны всем) | deliveries:read |
| GET | /delivery/v1/jobs/{id} (с посылками) | deliveries:read |
| POST | /delivery/v1/jobs/{id}/accept (кто первый — того и задание; возвращает 409, если уже принято) | deliveries:write |
| POST | /delivery/v1/jobs/{id}/decline | deliveries:write |
| POST | /delivery/v1/jobs/{id}/courier (необязательно) | deliveries:write |
| POST | /delivery/v1/jobs/{id}/pickup (забрать партию целиком) | deliveries:write |
| POST | /delivery/v1/jobs/{id}/complete (picked_up → completed) | deliveries:write |
| POST | /delivery/v1/jobs/{id}/handoff (Форма 103 / опись передачи) | consolidation:write |
| POST | /delivery/v1/jobs/{id}/form103 (пересобрать Форму 103 QazPost) | consolidation:write |
| POST | /delivery/v1/jobs (продавец создаёт задание) Запланировано | jobs:write |
| POST | /delivery/v1/jobs/{id}/cancel (продавец отменяет) Запланировано | jobs:write |
| Посылки · /delivery/v1 | ||
| GET | /delivery/v1/jobs/{id}/packages | deliveries:read |
| GET | /delivery/v1/packages/{id} | deliveries:read |
| GET | /delivery/v1/packages/{id}/delivery (состояние последней мили, код никогда не возвращается) | deliveries:read |
| POST | /delivery/v1/packages/{id}/out-for-delivery (начать/повторить последнюю милю; для door отправляет код) | deliveries:write |
| POST | /delivery/v1/packages/{id}/deliver (подтвердить доставку; для door нужен код, фото/имя получателя необязательны) | deliveries:write |
| POST | /delivery/v1/packages/{id}/delivery-failed (зафиксировать неудачную попытку, можно повторить) | deliveries:write |
| POST | /delivery/v1/packages/{id}/return (отметить как возврат) | deliveries:write |
| POST | /delivery/v1/packages/{id}/status (статус по каждому месту) Запланировано | deliveries:write |
| POST | /delivery/v1/packages/{id}/delivery-code (отправить одноразовый код) Запланировано | deliveries:write |
| POST | /delivery/v1/packages/{id}/verify (проверить код и подтвердить) Запланировано | deliveries:write |
| POST | /delivery/v1/packages/{id}/proof (резервное подтверждение / COD) Запланировано | deliveries:write |
| GET | /delivery/v1/packages/{id}/label Запланировано | tracking:read |
| GET | /delivery/v1/tracking/{tracking_number} Запланировано | tracking:read |
| POST | /delivery/v1/packages/{id}/location (не включено) Запланировано | deliveries:write |
| Вебхук · /delivery/v1 | ||
| POST | /delivery/v1/webhook-subscriptions | webhooks:manage |
Создайте ключи API в партнёрской панели или получите их у менеджера Atasuai при подключении (Ключи агента временно отключены; ключи продавца работают штатно). Нет своей системы? Ведите весь автопарк в панели Atasuai — те же возможности, ничего разрабатывать не нужно.