Аутентификация

Партнёрские запросы аутентифицируются API-ключом, а не пользовательским токеном. Ключ — это полные учётные данные: кто им владеет, действует от вашего имени, поэтому его место на вашем сервере и в менеджере секретов — никогда в браузере, мобильном приложении или git-репозитории.

Заголовок

Передавайте ключ в каждом запросе в заголовке X-Api-Key. Ключи начинаются с esk_live_ или esk_sandbox_ и содержат ещё 32 символа, поэтому среда видна сразу.

http

X-Api-Key: esk_live_a1b2c3d4e5f60718293a4b5c6d7e8f90

Создание и хранение ключей

Создавайте ключи на странице API-ключей этого портала. Ключ в открытом виде показывается ровно один раз, при создании: мы храним только его SHA-256-хеш и физически не можем показать снова. Потеряли — ротируйте.

/keys · 10 max

Ротация

Ротация сразу выдаёт новый ключ и оставляет старый рабочим на 24 часа. Выкатите новый ключ в этом окне; после него старый отклоняется с ERR_API_KEY_REVOKED. Отзыв, наоборот, действует немедленно.

grace = 24 h

Скоупы

У каждого ключа свой набор скоупов. Запрос вне них отклоняется с ERR_API_KEY_SCOPE — это 403, а не 404, чтобы отличать нехватку прав от отсутствующего заказа.

Скоупы
scope	Значение
`orders:read`	Чтение назначенных вам заказов: позиции, суммы, временное окно, зона и хронология статусов.
`orders:pii`	Дополнительно имя, телефон и адрес доставки клиента. Выдавайте, только если реально доставляете.
`logistics:write`	Отправка событий доставки (PICKED_UP, EN_ROUTE, DELIVERED, FAILED) по своим заказам.
`webhooks:manage`	Создание и изменение вебхук-эндпоинтов для этого ключа.
`payments:read`	Чтение платёжных намерений и их статусов для сверки.

Среды

Каждый ключ принадлежит ровно одной среде. Боевой API принимает только боевые ключи, песочница — только sandbox-ключи; не тот ключ отклоняется с ERR_API_KEY_ENVIRONMENT, даже если сам по себе он валиден.

base urls

live     https://api.turanyol.com
sandbox  http://localhost:3050

Лимиты запросов

У каждого ключа свой лимит запросов в минуту по скользящему окну. При превышении API отвечает 429 с ERR_RATE_LIMITED и заголовком Retry-After в секундах — подождите указанное время, а не повторяйте сразу.

http

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{ "statusCode": 429, "code": "ERR_RATE_LIMITED", "message": "rate limit exceeded" }

Счётчики использования

Мы считаем запросы, 4xx и 5xx по каждому ключу за день и храним 35 дней. Цифры есть на странице API-ключей, а GET /v1/partner/me возвращает скоупы ключа, лимит и трафик за последние семь дней.

Первый запрос

bash

curl -sS "https://api.turanyol.com/v1/partner/orders?status=EN_ROUTE&page=1" \
  -H "X-Api-Key: $ESADARAK_API_KEY" \
  -H "Accept: application/json"

Что может пойти не так

Любая ошибка — JSON-конверт со стабильным кодом. Четыре, с которыми вы столкнётесь первыми:

ERR_API_KEY_INVALID

Заголовок X-Api-Key отсутствует или не совпадает ни с одним ключом.

ERR_API_KEY_SCOPE

Ключ валиден, но не содержит скоуп, который нужен этому эндпоинту.

ERR_API_KEY_ENVIRONMENT

Sandbox-ключ отправлен в боевой API или наоборот.

ERR_RATE_LIMITED

Слишком много запросов по этому ключу. Подождите столько секунд, сколько в Retry-After.

Остальные — в полном каталоге ошибок.