面向哈萨克斯坦配送伙伴的一套接口，只有两个核心资源 —— Job（揽件任务）和 Package（任务里的每件包裹）。接任务、送货到家（同城 / 跨城）、把包裹交运给合作承运商。用你自己的系统对接，或直接用 delivery.atasuai.com 后台。
每个伙伴做的事都一样：取件、运输、送达。运单记录、面单、以及承运单号都由 Atasuai 统一生成 —— 一个只有手机的骑手今天就能上手。能自己做承运交运处理的伙伴，可作为附加能力解锁。
接揽件任务、整批揽件、逐件更新 Package 状态、提交签收。Scope deliveries:read · deliveries:write
每件 Package 自带单号与面单，只读。Scope tracking:read
预留条码、打印空白运单、生成承运交接单（如 QazPost 103 表）。Scope consolidation:write
卖家把多个包裹打成一个 Job（揽件任务）、选取货时间发布；当前是开放市场 —— 所有在线 Agent 都能看到待接单的 Job，谁先 accept 归谁（独占派单与 10 分钟计时改派仍规划中）。揽件是 Job 级（骑手一次把整批取走），去向是 Package 级 —— 同一个 Job 可混装下面两种，取货后按每件的 destination 分流。
走 Atasuai 自己的配送网络。取货后直接送到买家家门 —— 同城或跨城均可（按 Agent 的服务范围），不经第三方承运商。
首公里取件。取货后交给我们对接的第三方承运商网点（carrier_code：qazpost / filp / …）—— 承运单号由 Atasuai 统一号池签发。
carrier_code 签发Delivery 域只有两个核心资源。Job 是卖家发布、派给一个 Agent 的揽件任务；Package 是任务里的每件包裹，各有去向与状态。学会这两个，你就掌握了整个配送对接。
// 卖家发布；任何在线 Agent 都可抢单（先到先得） { "id": "job_4471", "batch_no": "PB-4471", "status": "pending", "accept_deadline": "2026-07-22T09:18:32Z", // 仅展示，暂不强制 "seller": { "name": "Oscar ЖК" }, "pickup": { "address": "Алматы, Абай 150, оф.3", "window": { "from": "14:00", "to": "16:00" }, "pickup_by": "2026-07-22T16:00:00Z" }, "courier": null, // 可选 "totals": { "package_count": 6, "total_weight_kg": 6.5 }, "packages": [ "pkg_88213", "…" ] }
// Job 里的每件包裹，各有 destination 与 status { "id": "pkg_88213", "job_id": "job_4471", "tracking_number": "AI556489715KZ", "destination": "carrier", // door | carrier "carrier_code": "qazpost", // carrier 时 "status": "pending", "recipient": { "name": "Елена", "phone": "+7 7•• •••" }, "weight_kg": 0.7, "cod": null }
揽件在 Job 级（整批一次取走），派送/交运在 Package 级（取货后逐件更新）。
pending ──accept──▶ accepted │ │ │ pickup（整批） │ ▼ │ picked_up ──▶ completed │ ├─(超时未接自动改派 —— 规划中，暂未强制)─▶ expired └─(卖家取消)────▶ cancelled
pending ▶ picked_up ▶ in_transit ▶ out_for_delivery ▶ verify // OTP 验码 ▶ delivered ✕ failed / returned
pending ▶ picked_up ▶ handed_off // 103 表交接 ── 承运商接管 ── ▶ in_transit ▶ delivered ✕ exception
送货到家（destination=door）的每件 Package 单独送、单独确认 —— 设计上会凭平台下发的一次性验证码确认本人签收，杜绝冒领。以 AI0123423443KZ 为例。标记 规划中 的端点 / 事件 / 规则均尚未实现，仅作为路线图展示，暂不可调用；当前真正可用的送达确认流程见下方「API 一览」中的 out-for-delivery / deliver 等端点。
// ① 骑手到门口，为这件包裹请求验证码 POST …/packages/pkg_88213/delivery-code → 平台向收件人发 SMS / 买家 App 推送 → 验证码只发给收件人，绝不回传给伙伴 // ② 收件人口述验证码，骑手提交校验 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 的 Job 对全部 Agent 公开可见（GET /jobs?status=pending），谁先 accept 归谁 —— 慢了返回 409。accept_deadline 会返回但暂不强制；独占派单、10 分钟计时与 job.expired 自动改派均规划中。destination（door / carrier）与独立状态。一个 Job 可混装两种去向。POST /jobs/{id}/pickup 整批取走）；派送/交运是 Package 级，按包裹逐件推进：POST /packages/{id}/out-for-delivery → /deliver（失败走 /delivery-failed，退回走 /return）；carrier 类交接见 POST /jobs/{id}/handoff。通用的 POST /packages/{id}/status 尚未实现，规划中。/packages/{id}/delivery-code 发码、/packages/{id}/verify 验码即 delivered；这两个端点尚未实现。当前的等价流程：POST /packages/{id}/out-for-delivery 会为 door 包裹签发验证码，POST /packages/{id}/deliver 需要该码（door）才能确认签收，可附带照片与收件人姓名。POST /jobs/{id}/courier 非必需，可不指定配送员直接推进（与后台一致）。POST /jobs/{id}/handoff 生成（如 QazPost 103 表），POST /jobs/{id}/form103 可重新生成；consolidation:write 可自助操作。carrier_code 签发承运单号。Idempotency-Key（Header 已接受）；但 Delivery API 暂未做去重 / 幂等回放，规划中，请勿依赖它防止重复提交。错误用 RFC 7807 problem+json；列表游标分页；per-tenant 限流。jobs:write）+ 查轨迹（tracking:read）；Agent 集成接单履约（deliveries:*、consolidation:write）。Agent 凭证目前暂停颁发（/oauth/token 对 agent 密钥返回 503），卖家凭证不受影响。三步搞定。机器对机器 —— 无需用户登录，没有跳转流程。
在伙伴后台，或入驻时由 Atasuai 提供，拿到 client_id 和 client_secret。密钥只显示一次。Agent（配送伙伴）凭证目前暂停颁发（/oauth/token 对 agent 密钥返回 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"
带上令牌调用接口。写操作需要 Idempotency-Key。
# 接受一个待接单的 Job（先到先得，谁先 accept 归谁） curl -X POST \ …/delivery/v1/jobs/{id}/accept \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)"
每个资源都遵循同一套约定 —— 学会一个端点，你就会用所有端点。
客户端凭证令牌携带租户与一组 scope。你只能看到被授予的部分 —— deliveries:*、tracking:read 等。
写操作请带 Idempotency-Key —— Header 已接受，但 Delivery API 暂未做去重 / 回放，重试可能产生重复记录，请自行防抖。
状态变更主动推送并以 HMAC 签名（sha256={ts}.{body}），带防重放；重试节奏为 5s/30s/2m/10m/30m/2h/6h/12h/24h/48h，共 10 次、约 4 天。
RFC 7807 problem+json，带稳定的 error_code 与用于排障的 request_id —— 解析一次，处处适用。
规划中。目前网关不做限流，也不返回 Retry-After / X-RateLimit-* 头。上线前将按租户令牌桶实现。
完全隔离的环境 sandbox.open.atasuai.com 即将上线（证书尚未就绪，暂未对外提供服务）。契约一致，测试条码，零真实包裹与资金。
订阅一次即可；也可轮询 GET /delivery/v1/jobs?status=pending 获取当前待接单列表。标记 规划中 的事件尚未真正推送。
按域分路径、带版本。标记 规划中 的端点尚未实现，仅供路线图参考。完整的交互式参考文档见文档站。
| 方法 | 端点 | Scope |
|---|---|---|
| Jobs 揽件任务 · /delivery/v1 | ||
| GET | /delivery/v1/jobs?status=pending （全部待接单，公开可见） | deliveries:read |
| GET | /delivery/v1/jobs/{id} （含 packages） | 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 |
| Packages 包裹 · /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 |
| Webhook · /delivery/v1 | ||
| POST | /delivery/v1/webhook-subscriptions | webhooks:manage |