Справочник собран из OpenAPI 3.1. Секретные ключи не вводятся в браузере: пробуйте запросы из curl или Postman с тестовым ключом. Скачать OpenAPI
Загружаем справочник…
POST /v1/quotes — Рассчитать доставкуРассчитывает цену доставки и ETA без создания заказа. quote_id держит цену 10 минут (valid_until): заказ по нему получит ровно эту цену, даже если тариф изменился. Позже заказ отклоняется с quote_expired. Адреса вне зон отклоняются с out_of_zone.
Нужна область доступа orders.write.
GET /v1/orders — Список заказовВаши заказы в среде ключа, новые сверху, с фильтрами. Курсорная пагинация: передайте next_cursor страницы как cursor, чтобы получить следующую; на последней странице next_cursor равен null.
Нужна область доступа orders.read.
POST /v1/orders — Создать заказСоздаёт заказ доставки. С quote_id цена берётся из расчёта (действует 10 минут, иначе quote_expired); без него заказ считается по текущему тарифу.
Идемпотентность. Передавайте уникальный Idempotency-Key (рекомендуем UUID). Повтор с тем же ключом и тем же телом в течение 24 часов возвращает первый ответ без изменений — таймаут никогда не создаст два заказа. Тот же ключ с другим телом отклоняется с 409 idempotency_conflict.
`external_id` — ваш номер заказа; он уникален в пределах организации и среды. Второй заказ с тем же external_id (даже другим ключом) отклоняется с 409 duplicate_external_id и ссылкой на существующий заказ.
В ответе — tracking_url для получателя и delivery_code, который получатель называет курьеру при вручении. Тестовые ключи создают заказы песочницы, их везёт виртуальный курьер.
Нужна область доступа orders.write.
POST /v1/orders/batch — Создать заказы пакетомСоздаёт до 100 заказов одним запросом. Каждый заказ обрабатывается отдельно: в результате по каждому элементу — created с заказом или error с кодом ошибки, в порядке запроса. Пакет целиком идемпотентен с Idempotency-Key.
Нужна область доступа orders.write.
GET /v1/orders/{id} — Получить заказЗаказ со статусом, версией, курьером (имя, телефон через маску, транспорт), ETA, историей статусов и ценой. {id} — наш id заказа или ваш external_id. Заказы других организаций — 404.
Нужна область доступа orders.read.
PATCH /v1/orders/{id} — Изменить заказИзменяет заказ. До picked_up можно менять адрес доставки, получателя, время и сумму наложенного платежа. После забора — только comment и recipient_phone; остальные поля отклоняются с 422 order_not_editable и details[].field. Передавайте только изменяемые поля.
Нужна область доступа orders.write.
POST /v1/orders/{id}/cancel — Отменить заказОтменяет заказ с кодом причины. Бесплатно, пока курьер не назначен; дальше действует плата за отмену по тарифу, она возвращается в cancellation_fee (курьеру начисляется компенсация). После забора отмена превращается в возврат на точку (returning). Завершённые, недоставленные и возвращаемые заказы отменить нельзя.
Нужна область доступа orders.write.
POST /v1/orders/{id}/payment — Сообщить об оплате Kaspi QRПередаёт статус оплаты через Kaspi QR магазина для заказа с наложенным платежом method: kaspi_qr. Курьер может вручить заказ только после paid.
Нужна область доступа orders.write.
POST /v1/orders/{id}/ready — Отметить заказ собраннымСигнал «заказ собран и готов для курьера». Без него поиск курьера стартует по нормативу сборки точки забора.
Нужна область доступа orders.write.
GET /v1/orders/{id}/proof — Получить доказательства врученияДоказательства вручения: способ, проверен ли код получателя, геоточка и время, принятые наличные и временная ссылка на фото (действует 15 минут — когда истечёт, запросите новую). Доступно после вручения; до этого — 404.
Нужна область доступа orders.read.
GET /v1/orders/{id}/track — Отследить курьераПоследняя позиция курьера и ETA. Не чаще одного раза в 10 секунд на заказ (иначе 429). Позиция видна, пока курьер везёт заказ; до этого — только статус и ETA. Позиция курьера никогда не отправляется вебхуками — опрашивайте этот метод или дайте получателю tracking_url.
Нужна область доступа orders.read.
GET /v1/pickup-points — Список точек забораТочки забора вашей организации (ведутся в кабинете). Используйте id как pickup.point_id.
Нужна область доступа points.read.
GET /v1/slots — Список слотов доставкиСлоты доставки точки забора на дату. Используйте from свободного слота как scheduled_at с type: slot. В песочнице — двухчасовые слоты каждые два часа с 10:00 до 22:00.
Нужна область доступа orders.read.
GET /v1/balance — Получить балансБаланс депозита (предоплата) или остаток кредитного лимита (постоплата) вашей организации. В песочнице — постоянный тестовый баланс 1 000 000 ₸. Подпишитесь на вебхук balance.low, чтобы пополнять вовремя.
Нужна область доступа finance.read.
GET /v1/statements — Получить выписку начислений и наложенного платежаВыписка за период: начисления за доставки и каждый заказ с наложенным платежом, завершённый в местные дни [from, to] (Алматы, не больше 92 дней), — сумма к получению, что принял курьер, способ оплаты и как заказ участвует в расчёте. Наличные зачитываются в счёт ваших доставок при закрытии периода (to_offset → offset); деньги Kaspi QR приходят вам напрямую (kaspi_direct). Если наличных больше, чем стоят доставки, Sapa Moto перечисляет разницу вам (payable_to_client). Те же данные, что «Сверка наложенного платежа» в кабинете. В песочнице выписка пустая.
Нужна область finance.read.
GET /v1/webhooks — Список адресов вебхуковАдреса вебхуков среды ключа. Тестовые и боевые адреса раздельные.
Нужна область доступа webhooks.manage.
POST /v1/webhooks — Добавить адрес вебхукаДобавляет адрес. Секрет подписи (whsec_…) возвращается один раз — сохраните его для проверки X-Sapa-Signature. Пустой event_types — подписка на все события. Адрес — только https на публичном хосте. До 10 адресов на среду.
Нужна область доступа webhooks.manage.
PUT /v1/webhooks/{endpointId} — Изменить адрес вебхукаМеняет URL, подписки или статус адреса. status: active включает приостановленный адрес: события, накопленные за время приостановки (до 7 дней), отправляются по порядку. status: disabled останавливает отправку.
Нужна область доступа webhooks.manage.
balance.low — Баланс ниже порогаДепозит или остаток кредитного лимита опустился ниже вашего порога.
claim.updated — Претензия обновленаИзменился статус претензии (повреждение, утеря, жалоба).
order.courier_assigned — Курьер назначенКурьер назначен или заменён (включая передачу заказа другому курьеру).
order.created — Заказ созданЗаказ создан — через API, в кабинете, импортом или диспетчером.
order.delivered — ВручёнЗаказ вручён — с доказательствами, а для наложенного платежа — с суммой и способом. Это сигнал отправить покупателю электронный фискальный чек.
order.eta_changed — ETA изменилосьETA сдвинулось больше вашего порога (по умолчанию 5 минут, настраивает аккаунт-менеджер).
order.failed — Не доставленЗаказ не удалось вручить; он едет обратно на точку забора.
order.price_changed — Цена измениласьИзменилась итоговая цена (ожидание, возврат, смена адреса).
order.returned — ВозвращёнЗаказ возвращён на точку забора.
order.status_changed — Статус изменилсяЛюбой переход статуса — с прежним и новым статусом и кодом причины. Отправляется на каждый переход в порядке версии.
ping — ПингТестовое событие от кнопки «Пинг» в кабинете. На него не подписываются; доставляется всегда.