Песочница и эмуляция курьера
Тот же API с тестовыми ключами и виртуальным курьером, который проводит заказ по всем статусам примерно за две минуты.
Песочница (https://partner-sandbox.sapamoto.kz, ключи sk_test_…) — те же пути, форматы и ошибки, что в боевой среде,
но со своими независимыми данными. Она доступна сразу после создания организации — до договора и активации.
- Виртуальный курьер проводит каждый заказ по статусам —
created → searching → assigned → to_pickup → at_pickup → picked_up → to_dropoff → at_dropoff → delivered— один шаг примерно каждые 15 секунд, около двух минут на заказ. - Он двигается по карте от точки забора к получателю (
/track), делает фото вручения и проверяет код (/proof). - Он отправляет настоящие подписанные вебхуки на ваши тестовые адреса.
- Тестовые заказы никогда не попадают в счета, отчёты, выплаты и данные, на которых учатся наши модели.
- Баланс — постоянный тестовый 1 000 000 ₸; точки забора можно задавать просто адресом с координатами.
Сценарии
Сценарий выбирается маркером в комментарии заказа — [sandbox:<сценарий>] — или кнопками кабинета:
| Маркер | Что происходит | Какие вебхуки ждать |
|---|---|---|
(нет) или [sandbox:success] | доставлен | order.created, order.status_changed ×8, order.courier_assigned, order.delivered |
[sandbox:cash] | доставлен с оплатой наличными | … order.delivered с cod.settlement: to_offset |
[sandbox:no_answer] | получатель не отвечает: at_dropoff → failed (recipient_unreachable) → returning → returned | order.failed, order.returned |
[sandbox:courier_change] | после to_pickup курьера снимают (battery): снова searching, другой курьер, ETA +12 мин | order.courier_assigned с replaced: true, order.eta_changed |
[sandbox:cancel_after_assign] | отмена после назначения курьера, с платой | order.status_changed → cancelled с 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]"
}'Заказы песочницы можно отменять, менять и отмечать собранными через API на любом шаге — как в боевой среде.
Чек-лист интеграции
Боевые ключи включает аккаунт-менеджер, когда в песочнице выполнен чек-лист (его видно в кабинете и в нашем бэк-офисе):
- заказ создан через API;
- вебхук принят (2xx), подпись проверена;
- обработан повтор — ваш адрес один раз ответил ошибкой и принял повтор, или вы использовали повторную отправку;
- заказ отменён;
- обработана недоставка (
[sandbox:no_answer]).
Затем поменяйте хост на https://partner.sapamoto.kz, а ключ — на sk_live_…. Создайте боевые адреса вебхуков — они
отдельные от тестовых.