Авторизация

Для работы с купонами и балансом партнер должен получить клиентский JWT. Токен выдается после проверки логина и пароля и определяет, к данным какого клиента разрешен доступ.

Данные для входа

Логин и пароль предоставляет менеджер. Храните их на серверной стороне и не передавайте в браузер, мобильное приложение или сторонние сервисы.

В примерах используется условный адрес:

BASE_URL="https://coupon-api.example.com"

Замените его базовым URL, который предоставил менеджер.

Получение JWT

Используйте:

POST /api/partner/login

Авторизация для самого запроса входа не требуется.

В старом API для авторизации использовался POST /api/v2/login. Маршрут продолжает поддерживаться, но для новой интеграции используйте POST /api/partner/login. Все отличия собраны в руководстве «Переход со старого API».

Пример:

curl --request POST \
  --url "$BASE_URL/api/partner/login" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{
    "username": "partner-demo",
    "password": "strong-password"
  }'

Поля запроса

Передавайте только одно поле имени: username или login.

Успешный ответ

{
  "code": 1,
  "body": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "username": "partner-demo"
  },
  "error_code": null,
  "error_message": null,
  "date": 1784970000000,
  "time_ms": 35,
  "path": "/api/partner/login"
}

Поля body

Использование токена

Сохраните body.token и передавайте его во всех защищенных запросах:

Authorization: Bearer <client_token>

Пример:

curl --request GET \
  --url "$BASE_URL/api/partner/coupons/active" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <client_token>"

Важно:

• перед словом Bearer и токеном должен быть один пробел;
• используйте JWT, полученный через клиентский /api/partner/login;
• JWT администратора не подходит;
• заголовок X-Client-Id не используется и не позволяет переключиться на другого клиента;

Срок действия и повторный вход

JWT нужно считать непрозрачным токеном доступа: клиенту не требуется разбирать его содержимое или самостоятельно проверять подпись.

Используйте токен до тех пор, пока API его принимает. Если защищенный метод возвращает HTTP 401, выполните вход повторно и повторите запрос уже с новым JWT.

Отдельного метода обновления токена в клиентском API нет.

Не выполняйте повторный вход при каждой операции без необходимости. Полученный JWT можно безопасно переиспользовать между запросами до его истечения или отзыва.

Ошибка входа

Если учетные данные не приняты, API обычно возвращает HTTP 200 и бизнес-ошибку:

{
  "code": 0,
  "body": null,
  "error_code": 1003,
  "error_message": "Wrong login or password",
  "date": 1784970000000,
  "time_ms": 5,
  "path": "/api/partner/login"
}

Возможные ответы:

Все перечисленные error_code являются бизнес-ошибками: они возвращаются с HTTP 200 и code = 0.

Неизвестный логин и неверный пароль намеренно не различаются и возвращают одинаковую ошибку 1003. Состояния аккаунта теперь различаются: при 1004, 1006 или 1007 повтор запроса с теми же данными не поможет — необходимо обратиться к менеджеру для включения аккаунта, продления доступа или пополнения клиентского баланса.

1007 возвращается при входе, если баланс равен нулю или отрицательный. Если баланс положительный, вход разрешен даже тогда, когда его недостаточно для конкретного запроса создания. В такой ситуации POST /api/partner/coupons/place возвращает 507, Insufficient balance.

Совместимый POST /api/v2/login сохраняет прежнее поведение: любой отказ входа возвращается как error_code = 99 и Wrong login or password.

Проверяйте одновременно HTTP-код и поле code в JSON.

Ошибки защищенных запросов

После успешного входа возможны два основных ответа авторизации:

Не запускайте бесконечный цикл повторной авторизации. Если новый JWT сразу получает 401 или 403, остановите повторы и проверьте учетные данные и состояние аккаунта.

Безопасное хранение

• Используйте HTTPS.
• Храните логин, пароль и JWT только на серверной стороне.
• Не записывайте пароль или полный токен в логи.
• Не добавляйте JWT в URL или query-параметры.
• Не передавайте один клиентский токен другому партнеру.
• Ограничьте доступ к учетным данным только тем компонентам, которым нужен клиентский API.

Следующий шаг: изучить общие правила запросов и ответов.