Қазақстандағы жеткізу серіктестері үшін бірыңғай API жинағы, тек екі негізгі нысанмен — Тапсырма (алып кету тапсырмасы) және Сәлемдеме (Тапсырма ішіндегі әрбір жүк). Тапсырмаларды қабылдаңыз, есікке жеткізіңіз (қала ішінде / қалалар арасында) және сәлемдемелерді серіктес тасымалдаушыға тапсырыңыз. Өз жүйеңізді кіріктіріңіз немесе мынаны пайдаланыңыз: delivery.atasuai.com панелінен басқарыңыз.
Әрбір серіктес бір істі істейді: алады, тасымалдайды, жеткізеді. Жүкқұжаттар, жапсырмалар және тасымалдаушының бақылау нөмірлері — бәрін Atasuai орталықтан жасайды: қолында тек телефоны бар курьер бүгін бастай алады. Тасымалдаушыға өзі тапсыра алатын серіктестер бұл мүмкіндікті қосымша ретінде қоса алады.
Алып кету тапсырмаларын қабылдау, партияны толық алу, әрбір Сәлемдеменің күйін жаңарту және жеткізу дәлелін жіберу. Scope deliveries:read · deliveries:write
Әрбір Сәлемдеменің бақылау нөмірі мен жапсырмасы болады, тек оқуға. Scope tracking:read
Штрих-кодтарды брондау, бос жүкқұжаттарды басып шығару және тасымалдаушыға тапсыру тізімдемесін жасау (мысалы, QazPost Форма 103). 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 агент кілттері үшін); сатушы кілттеріне әсер етпейді.Үш қадамда. Машинадан машинаға — пайдаланушы кірмейді, қайта бағыттау жоқ.
Серіктес панелінен немесе қосылу кезінде Atasuai арқылы client_id and client_secret алыңыз. Құпия кілт бір рет қана көрсетіледі. Агент (жеткізу серіктесі) кілттері уақытша өшірілген (/oauth/token returns 503 агент кілттері үшін); сатушы кілттері қалыпты жұмыс істейді.
Кілттеріңізді scope-пен шектелген bearer токенге айырбастаңыз, жарамдылығы 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 тәртібімен — шамамен 4 күнде 10 әрекет.
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 (QazPost Форма 103-ті қайта жасау) | 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 панелінде жүргізіңіз — мүмкіндіктер бірдей, ештеңе жасау қажет емес.