Подключение

Все запросы идут на https://api.rekassa.uz по HTTPS. Тела запросов и ответов — JSON в UTF-8, поэтому для запросов с телом передавайте Content-Type: application/json.

Заголовки

Заголовок	Обязательность	Назначение
`Authorization: Bearer <jwt>`	да, кроме `/v1/auth/*` и `/health`	access-токен, см. Аутентификация
`Content-Type: application/json`	для запросов с телом	формат тела
`Accept-Language`	нет	язык текстов в ответе: `ru`, `uz` или `oz`; по умолчанию `ru`
`X-Request-Id`	нет	идентификатор запроса для трассировки; возвращается в ответе
`X-Client: web`	только для браузерных клиентов	refresh-токен приходит в `httpOnly`-куке, а не в теле ответа

Authorization

Методы /v1/auth/* и служебные /health, /health/ready публичные. Все остальные (/v1/me/*, /v1/portal/*) требуют access-токен:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Без токена, с просроченным токеном или с токеном завершённой сессии API отвечает 401 с кодом unauthorized. Токен проверяется вместе с сессией на каждом запросе, поэтому выход и блокировка пользователя действуют сразу, не дожидаясь истечения токена.

Accept-Language

От языка зависят поле message в ошибках и текст SMS с кодом подтверждения.

Значение	Язык
`ru`	русский (по умолчанию)
`uz`	узбекский, латиница
`oz` или `uz-Cyrl`	узбекский, кириллица

Заголовок разбирается по стандарту: берётся первый поддерживаемый язык из списка, региональные варианты сводятся к базовому (ru-RU → ru). Неизвестные языки дают ru.

Accept-Language: uz-Cyrl, ru;q=0.8

X-Request-Id

У каждого ответа есть заголовок X-Request-Id, и то же значение приходит в error.requestId у ошибок. Сообщайте его в поддержку — по нему находится запрос в логах.

Можно передать свой идентификатор: API примет его, если это от 1 до 128 символов из латинских букв, цифр, _ и -. Иначе API сгенерирует UUID.

X-Request-Id: checkout-7f3a9c

X-Client

Браузерные клиенты (кабинет, редактор чеков, портал) передают X-Client: web во все запросы /v1/auth/*. Тогда refresh-токен ставится в куку rk_refresh, недоступную скриптам страницы, и в теле ответа его нет. Мобильные клиенты заголовок не передают и получают refresh-токен в теле. Подробнее — в разделе Аутентификация.

curl https://api.rekassa.uz/v1/me \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Accept-Language: ru' \
  -H 'X-Request-Id: profile-1'

const response = await fetch('https://api.rekassa.uz/v1/me', {
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Accept-Language': 'ru',
  },
})
const requestId = response.headers.get('X-Request-Id')

CORS

Из браузера API доступен только с доверенных доменов продуктов reKassa — список разрешённых источников задаётся на сервере. Запросы с других источников браузер заблокирует.

Ответы разрешают передачу кук (Access-Control-Allow-Credentials: true). Чтобы кука rk_refresh ушла на сервер, вызывайте fetch с credentials: 'include'.
Скрипту страницы доступны заголовки ответа X-Request-Id и Retry-After.