Аутентификация
API-ключ организации в заголовке Authorization — тестовый и боевой, области доступа, allowlist IP и ротация.
Каждый запрос несёт API-ключ организации:
GET /v1/orders HTTP/1.1
Host: partner.sapamoto.kz
Authorization: Bearer sk_live_2Hq8…В Partner API нет сессий, cookie и пользовательских токенов — токены кабинета и бэк-офиса отклоняются с 401.
Принимается только TLS 1.2+.
Тестовые и боевые ключи
| Префикс | Среда | Хост | Когда |
|---|---|---|---|
sk_test_ | песочница | https://partner-sandbox.sapamoto.kz | сразу после создания организации, до договора |
sk_live_ | боевая | https://partner.sapamoto.kz | после чек-листа интеграции; боевой режим включает аккаунт-менеджер |
Среда ключа решает всё: заказы, адреса вебхуков и журнал запросов тестовых и боевых ключей никогда не смешиваются.
Боевой заказ организации, которая ещё не активна (нет подписанного договора), отклоняется с
403 organization_not_active; тестовый ключ продолжает работать.
Как создать ключ
В кабинете, раздел «Интеграция», создайте ключ: выберите среду, название (например, erp-prod), области доступа и
при желании allowlist IP. Секрет показывается один раз и хранится у нас только хешем — если потеряли, создайте
новый ключ и отзовите старый.
Храните ключи только на своих серверах. Никогда не кладите ключ в мобильное приложение, веб-страницу или публичный репозиторий. Утёкший ключ может создавать заказы от вашего имени.
Области доступа
| Область | Разрешает |
|---|---|
orders.read | GET /v1/orders, /orders/{id}, /track, /proof, /slots |
orders.write | POST /v1/quotes, /orders, /orders/batch, PATCH /orders/{id}, /ready, /cancel, /payment |
points.read | GET /v1/pickup-points |
finance.read | GET /v1/balance |
webhooks.manage | GET/POST /v1/webhooks, PUT /v1/webhooks/{id} |
Новый ключ по умолчанию получает все области. Запрос вне областей ключа — 403 forbidden. Дашборду только для
чтения выдайте один orders.read.
Allowlist IP
У ключа может быть список адресов или CIDR-диапазонов (203.0.113.10, 198.51.100.0/24). Запросы с других адресов
отклоняются с 403 api_key_ip_not_allowed.
Ротация и отзыв
В каждой среде можно держать два активных ключа — так ключ меняется без простоя:
- создайте второй ключ;
- разверните его на всех своих серверах;
- отзовите старый ключ в кабинете.
Отозванный ключ перестаёт работать везде не позже чем через 60 секунд и получает 401 unauthorized. Отзыв
записывается в аудит.
Ошибки
| Статус | Код | Почему |
|---|---|---|
| 401 | unauthorized | нет Authorization: Bearer, ключ неизвестен или отозван |
| 403 | forbidden | у ключа нет нужной области |
| 403 | api_key_ip_not_allowed | запрос пришёл не с адреса из allowlist ключа |
| 403 | feature_disabled | Partner API ещё не включён для вашей организации |
| 403 | organization_not_active | боевой заказ организации без активного договора |