Today Express API

Маркетплейстер, онлайн-дүкөндөр, WMS жана ERP үчүн ачык API. Жеткирүү буйрутмаларын өз системаңыздан түзүп, статустарды вебхук аркылуу алыңыз: сервер↔сервер, панелге кирбестен. Бул бет — толук жана жалгыз документация: иштеп чыгуучуга керектин баары ушул жерде.

Базалык URL ({base_url})Аны API-ачкыч менен бирге беребиз. Документациядагы бардык жолдор ага салыштырмалуу көрсөтүлгөн.

Жалпы маалымат

Интеграция бир гана нерсенин — жеткирүү буйрутмасынын (order) айланасында курулат. Кадимки сценарий:

  1. Сатып алуучу сизден буйрутма берди → сиз POST /orders/ чакырып, tracking_code аласыз.
  2. Курьер жөнөтмөнү сиздин кампаңыздан алат, алып кетүүдө анык салмагы жана габариттери боюнча жеткирүү баасын коёт жана алуучуга жеткирет; статус ар өзгөргөн сайын сизге вебхук жөнөтөбүз.
  3. Сатып алуучу жөнөтмөнү биздин сайттан tracking_url боюнча көзөмөлдөйт (шилтемени ага өзүңүз бересиз) — «буйрутмам кайда» деген суроолор азаят.
tracking_code — APIдеги буйрутманын жалгыз идентификатору: ал аркылуу буйрутма суралат, өзгөртүлөт жана жокко чыгарылат, вебхуктарда да ошол келет. Жооптордо ички сандык id жок.
Эки нерсени сиз жөнөтпөйсүз: жөнөтүүчүнүн дарегин (өнөктөш профилиңизден алабыз) жана жеткирүү баасын. Түзүүдө price = null: акыркы бааны курьер алып кетүүдө коёт, ал 2-статус менен order.status_changed вебхугунда жана 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) жана согуштук (live). Ачкычтын өзүнөн чөйрөсү көрүнбөйт — чаташтырбаңыз, өзүнчө сактаңыз.
  • Ачкыч сиздин компанияңызды, чөйрөнү жана укуктарды аныктайт. Укуктар «окуу» (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. Башка өлкөнүн номери — invalid_phone коду менен 400. Телодогу белгисиз талаалар (анын ичинде 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. Курьер алып кетүүдө жөнөтмөнү таразалап, карап чыгып, акыркы бааны коёт. Ал 2-статус («Алып кетти») менен order.status_changed вебхугунун 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 — трек-коддун QR-коду жана Today Express логотиби бар PNG: аны жөнөтмөгө басып чыгарыңыз, кампа жана курьерлер буйрутманы ошол боюнча табат. Шилтеме түзүү жообунда дароо келет, файл өзү ошол шилтеме боюнча бир нече секунданын ичинде пайда болот. Наклейканы өзүңүз түзсөңүз, 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 }

Вебхуктар

Сурап туруунун ордуна — окуяларда сиздин URLге POSTту өзүбүз жөнөтөбүз. Жазылууну каттаңыз, кол тамганы текшериңиз, 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 ичинде

Окуянын телосу жана заголовоктор

Сиздин URLге POST
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= + сиздин secret менен <X-TE-Timestamp>.<чийки тело> сабынын HMAC-SHA256.
  • 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

Кайталоолор жана ишенимдүүлүк

  • 10 секунданын ичинде 2xx коду менен жооп бериңиз — болбосо жөнөтүү ийгиликсиз деп эсептелет.
  • Өсүүчү тыныгуу менен 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)

КодТибиМилдеттүүСүрөттөмө
11 кгга чейин—
25 кгга чейин—
310 кгга чейин—макулдашуу боюнча
415 кгга чейин—макулдашуу боюнча
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 суроо-талап) жана биздин бардык серверлер үчүн жалпы. Ашып кетсе — Retry-After заголовогу менен 429 (кийинки аракетке чейинки секундалар). Ачкычсыз же туура эмес ачкыч менен суроо-талаптар IP боюнча өзүнчө чектелет. Суроо-талаптын телосу — 2 МБга чейин, андан чоң суроо-талап четке кагылат. Жогорураак лимит керекпи — бизге жазыңыз.

Sandbox (тесттик ачкыч)

Тесттик ачкыч ошол эле APIге кайрылат, бирок буйрутмалар is_sandbox: true деп белгиленип, чыныгы курьерлерге жана операторлорго жетпейт. Тесттик буйрутмалардын трек-коддору TEST- менен башталат, ачык трекингде көрүнбөйт, ал эми info_qr_url биздин API тарткан QRге алып барат. Тесттик вебхуктар 6 эмес, 2 жолу кайталанат. Чөйрөлөр бөлүнгөн: тесттик ачкыч согуштук буйрутмаларды көрбөйт жана өзгөртө албайт, согуштук — тесттиктерди. Баарын текшерип бүткөндө бизге «даярбыз» деп жазып, согуштук ачкычка өтөсүз.

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) жана согуштук. Ачкыч сиздин компанияңызды, чөйрөнү жана укуктарды аныктайт; сизден башка эч нерсе керек эмес.
Буйрутмалардын статусун сурап туруу керекпи?
Жок. Вебхук каттаңыз — статус ар өзгөргөн сайын сиздин URLге POSTту өзүбүз жөнөтөбүз. Суроо-талап бизден экенине ынанышыңыз үчүн ар бир вебхукка кол коюлган (HMAC).
Согуштук ишке киргизүүдөн мурун сынап көрсө болобу?
Ооба. Тесттик (sandbox) ачкыч ошол эле APIге кайрылат, бирок буйрутмалар тесттик деп белгиленет (is_sandbox=true) жана чыныгы курьерлерге/операторлорго кетпейт. Sandbox-буйрутманын статустарын POST /orders/{tracking_code}/test/advance/ аркылуу өзүңүз өткөрөсүз — ошентип согуштук ишке киргизүүгө чейин order.status_changed вебхуктарынын келишин текшересиз.
Жөнөтүүчүнүн дарегин ким көрсөтөт?
Биз. Сиздин кампаңыз (шаар, дарек, телефон) өнөктөш профилиңизде сакталат. Буйрутма түзүү суроо-талабында сиз алуучуну жана жөнөтмөнү гана жөнөтөсүз — кайдан алып кетүүнү өзүбүз коёбуз.
Жеткирүү баасын ким коёт?
Курьер, жөнөтмөнү алып кетүүдө, анык салмагы жана габариттери боюнча. Түзүү жообунда price = null; акыркы баа 2-статус менен order.status_changed вебхугунда жана GET /orders/{tracking_code}/ ичинде келет. API аркылуу баа жөнөтүлбөйт.
Сатып алуучу Today Express'тен трекинг билдирүүлөрүн алабы?
Демейки боюнча жок: API аркылуу түзүлгөн буйрутмалар боюнча биз алуучуга трек-шилтеме жөнөтпөйбүз — статустарды өз системаңызда өзүңүз көрсөтөсүз (вебхуктар аркылуу). Бул жөндөлөт: сиздин өтүнүчүңүз боюнча трекинг менен WhatsApp-шилтемени түз алуучуга жөнөтүүнү күйгүзө алабыз. Кадимки буйрутмалар боюнча (API аркылуу эмес) алуучуга билдирүүлөр мурдагыдай иштейт.

Туташууга даярсызбы?

Бизге жазыңыз — сизди өнөктөш кылып, тесттик жана согуштук ачкычтарды беребиз. Sandbox'тон баштаса болот, милдеттенмесиз.

WhatsApp'ка жазуу