Sandbox & courier emulation
The same API with test keys and a virtual courier that takes an order through every status in about two minutes.
The sandbox (https://partner-sandbox.sapamoto.kz, keys sk_test_…) has the same paths, payloads and errors as
production, with its own independent data. It is available right after your organization is created — before the
contract and activation.
- A virtual courier takes every order through the statuses —
created → searching → assigned → to_pickup → at_pickup → picked_up → to_dropoff → at_dropoff → delivered— one step every ~15 seconds, about two minutes for the whole order. - It moves on the map from the pickup to the drop-off (
/track), makes a handover photo and checks the code (/proof). - It sends real signed webhooks to your test endpoints.
- Test orders never reach invoices, reports, payouts or the data our models learn from.
- The balance is a fixed test balance of 1 000 000 ₸; pickup points can be plain addresses with coordinates.
Scenarios
Pick a scenario with a marker in the order comment — [sandbox:<scenario>] — or with the buttons of the cabinet:
| Marker | What happens | Webhooks to expect |
|---|---|---|
(none) or [sandbox:success] | delivered | order.created, order.status_changed ×8, order.courier_assigned, order.delivered |
[sandbox:cash] | delivered with cash on delivery | … order.delivered with cod.settlement: to_offset |
[sandbox:no_answer] | the recipient does not answer: at_dropoff → failed (recipient_unreachable) → returning → returned | order.failed, order.returned |
[sandbox:courier_change] | after to_pickup the courier is taken off (battery): back to searching, another courier, ETA +12 min | order.courier_assigned with replaced: true, order.eta_changed |
[sandbox:cancel_after_assign] | cancelled after the courier was assigned, with a fee | order.status_changed → cancelled with cancellation_fee |
curl https://partner-sandbox.sapamoto.kz/v1/orders \
-H "Authorization: Bearer $SAPA_TEST_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"external_id": "TEST-NOANSWER-1",
"pickup": {"address": "Алматы, Абая 10", "latitude": 43.2389, "longitude": 76.9286},
"dropoff": {"address": "Алматы, Жандосова 58", "latitude": 43.214, "longitude": 76.88},
"recipient": {"phone": "+77011234567"},
"comment": "[sandbox:no_answer]"
}'You can also cancel, change or mark sandbox orders ready with the API at any step, exactly as in production.
Integration checklist
Live keys are enabled by your account manager after the checklist (visible in the cabinet and to our back-office) is complete in the sandbox:
- an order was created through the API;
- a webhook was accepted (2xx) and its signature verified;
- a repeated delivery was handled — your endpoint answered an error once and accepted the retry, or you used replay;
- an order was cancelled;
- a failed delivery was processed (
[sandbox:no_answer]).
Then switch the host to https://partner.sapamoto.kz and the key to sk_live_…. Create live webhook endpoints — they are
separate from the test ones.