Формат данных

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

Данные возвращаются напрямую, без обёртки вроде { "data": ... }:

{
  "id": "0d3f5b8e-2c41-4a7e-9f10-6c8b2a7d4e11",
  "phone": "+998901234567",
  "firstName": "Азиз",
  "lastName": "Каримов",
  "authMethod": "password",
  "status": "active",
  "hasPassword": true,
  "lastLoginAt": "2026-09-24T08:30:12.000Z",
  "createdAt": "2026-09-01T10:00:00.000Z",
  "roleAssignments": []
}

Идентификаторы — UUID.
Дата и время — строки ISO 8601 в UTC: 2026-09-24T08:30:12.000Z.
Телефоны — в формате E.164: +998901234567, см. Телефоны.
Отсутствующее значение — null, а необязательные поля, которых нет, в ответе не приходят.
Методы без результата отвечают 204 No Content без тела.

Списки и пагинация

Списки разбиты на страницы. Номер страницы и размер передаются в query-параметрах:

Параметр	По умолчанию	Ограничения
`page`	`1`	целое, от 1
`size`	`50`	целое, от 1 до 5000

curl 'https://api.rekassa.uz/v1/portal/users?page=2&size=20' \
  -H 'Authorization: Bearer <accessToken>'

{
  "items": [{ "id": "0d3f5b8e-...", "firstName": "Азиз", "...": "..." }],
  "page": 2,
  "size": 20,
  "total": 57,
  "hasMore": true
}

Поле	Описание
`items`	элементы текущей страницы
`page`	номер страницы из запроса
`size`	размер страницы из запроса
`total`	сколько всего элементов подходит под условия
`hasMore`	`true`, если после этой страницы есть ещё элементы

Листайте, пока hasMore не станет false.

Ошибки

Любая ошибка приходит в одной и той же структуре:

{
  "error": {
    "code": "validation_failed",
    "message": "Проверьте правильность заполнения полей",
    "details": {
      "errors": [{ "path": "phone", "message": "Invalid phone number" }]
    },
    "requestId": "b6a1f0c2-8d3e-4b7a-9c5f-2e1d0a9b8c7d"
  }
}

Поле	Описание
`code`	машиночитаемый код, стабильный. Ветвите логику клиента по нему
`message`	текст для пользователя на языке из `Accept-Language`
`details`	необязательные подробности; состав зависит от кода
`requestId`	идентификатор запроса, совпадает с заголовком `X-Request-Id`

Что бывает в `details`

Когда	Содержимое
`validation_failed` (400)	`errors` — список `{ path, message }`: путь к полю через точку и причина
`forbidden` (403)	`permission` — доступ, которого не хватило, например `users.manage`
`permission_not_held` (403)	`missing` — доступы, которых нет у вас
`requisites_incomplete` (422)	`missing` — незаполненные реквизиты организации
ошибки SMS-кодов (429)	`retryAfter` — через сколько секунд можно повторить

Тексты в details.errors[].message — технические и не переводятся. Например, несовпадение пароля и подтверждения приходит как { "path": "passwordConfirmation", "message": "password_mismatch" }.

HTTP-статусы

Статус	Когда
`200`	успех
`201`	создано: пользователь, организация, филиал, сотрудник, назначенная роль
`204`	успех без тела: выход, смена пароля, завершение сессии, PIN, удаление сотрудника
`400`	запрос составлен неправильно: не прошла валидация тела, query или параметра пути
`401`	не аутентифицирован: нет токена, он истёк, неверный пароль или SMS-код
`403`	аутентифицирован, но нельзя: нет доступа, недостаточный ранг, пользователь заблокирован
`404`	не найдено
`409`	конфликт с текущим состоянием: номер или ИНН уже зарегистрирован, PIN занят
`422`	запрос корректен, но бизнес-правило не позволяет выполнить действие
`429`	превышен лимит; смотрите заголовок `Retry-After`, см. Лимиты
`500`	внутренняя ошибка сервера (`internal_error`)

400 или 422

Различие намеренное, и клиент реагирует на них по-разному.

400 validation_failed — запрос составлен неправильно: не хватает поля, неверный формат телефона, пароль короче 8 символов. Это ошибка ввода — подсветите поля из details.errors.
422 — запрос корректен, но действие сейчас невозможно. Например, в профиле нельзя переключить способ входа на пароль, пока пароль не задан (password_required), или сменить пароль с неверным текущим (current_password_invalid). Покажите message пользователю — поля исправлять не нужно, нужно другое действие.

Полный список кодов — в разделе Коды ошибок.