Сотрудники и PIN

Сотрудник организации — пользователь с ролью клиента в ней: на всю организацию или на один филиал. Кроме того, сотрудниками считаются все, у кого роль на весь клиент, — например, «Владелец». На кассе сотрудник входит по короткому PIN.

1. Роль. GET /v1/orgs/{id}/roles — роли клиента с рангами; нужен id одной из них.

2. Добавление. POST /v1/orgs/{id}/members с телефоном, именем и roleId. Если аккаунта с этим номером нет, он создаётся, и сотрудник входит по SMS-коду.

3. PIN. PUT /v1/orgs/{id}/members/{userId}/pin — 6 цифр для входа на кассе.

4. Изменения. PATCH меняет роль в организации, DELETE убирает сотрудника из неё.

Роли для сотрудников

GET/v1/orgs/{id}/roles

Роли клиента, которые можно выдать в этой организации: системные («Владелец», «Директор», «Управляющий», «Главный бухгалтер», «Кассир») и собственные роли клиента. Сначала старшие по рангу. Нужен доступ users.read в организации. Выдать можно только роль ниже своего ранга — см. ниже.

[
  {
    "id": "7d0f3a9e-1c2b-4e5f-8a6d-2b9c0e1f4a37",
    "code": "client.cashier",
    "name": "Кассир",
    "rank": 10,
    "isSystem": true,
    "permissions": ["orgs.read"]
  }
]

Кто кем управляет

Правила те же, что у ролей платформы, но ранги сравниваются по ролям клиента:

• Добавлять, менять роль и удалять сотрудников может тот, у кого в организации есть доступы users.manage и roles.assign. Из ролей клиента они есть у «Владельца» и «Директора».
• Выдать можно только роль клиента ниже своего ранга — кроме «Владельца» (100): он выдаёт любую роль. У выдаваемой роли не должно быть доступов, которых нет у вас.
• Менять роль, удалять и задавать PIN можно только сотруднику ниже вас рангом — кроме «Владельца», — и только если у вас есть все его доступы в этой организации. Учитываются и роли сотрудника в филиалах.
• Себя изменить или удалить нельзя — 422 cannot_manage_self. Свой PIN задать можно.
• Сотрудники reKassa с доступами платформы стоят выше лестницы рангов клиента: ранги для них не проверяются, проверяются только доступы.

Нарушение ранга даёт 403 insufficient_rank, лишние доступы — 403 permission_not_held со списком в details.missing.

Список сотрудников

GET/v1/orgs/{id}/members

Нужен доступ users.read в организации. Массив без пагинации: сначала старшие по рангу, затем по фамилии и имени.

curl

curl https://api.rekassa.uz/v1/orgs/8c1e4a27-5d3b-4f60-9a82-1b7e0c3d9f45/members \
  -H 'Authorization: Bearer <accessToken>'

JavaScript

const response = await fetch(`https://api.rekassa.uz/v1/orgs/${organizationId}/members`, {
  headers: { Authorization: `Bearer ${accessToken}` },
})
const members = await response.json()

[
  {
    "userId": "0d3f5b8e-2c41-4a7e-9f10-6c8b2a7d4e11",
    "phone": "+998901234567",
    "firstName": "Азиз",
    "lastName": "Каримов",
    "status": "active",
    "hasPin": true,
    "roles": [
      {
        "assignmentId": "c4e81f2a-6b93-4d05-8a7e-3f1d9b2c6e70",
        "scope": { "type": "client", "clientId": "e2b7c915-0a4d-4e38-b6f1-7d9a2c5e8b03" },
        "role": {
          "id": "1a7d3e90-4c2b-4f68-b5e1-9d0c8a6f2b34",
          "code": "client.owner",
          "name": "Владелец",
          "rank": 100
        }
      }
    ]
  },
  {
    "userId": "6b2e9d14-7a3c-4e81-9f50-2d8c1a4b7e63",
    "phone": "+998935551122",
    "firstName": "Нодира",
    "lastName": "Юсупова",
    "status": "active",
    "hasPin": false,
    "roles": [
      {
        "assignmentId": "f07a2c58-3e1d-4b96-a8c4-6d2e9b1f5a07",
        "scope": {
          "type": "branch",
          "clientId": "e2b7c915-0a4d-4e38-b6f1-7d9a2c5e8b03",
          "organizationId": "8c1e4a27-5d3b-4f60-9a82-1b7e0c3d9f45",
          "branchId": "5f2a9c61-8e3d-4b07-a4c9-0d6b1e7f3a28"
        },
        "role": {
          "id": "9e4b7a12-0d5c-4f83-b2e6-7a1c3d9f0b58",
          "code": "client.cashier",
          "name": "Кассир",
          "rank": 10
        }
      }
    ]
  }
]

Поле	Описание
userId	идентификатор пользователя — он же в путях /members/{userId}
status	статус аккаунта: active, blocked или pending
hasPin	задан ли PIN для кассы в этой организации
roles	роли в этой организации: на весь клиент, на организацию и на её филиалы
roles[].scope	где действует роль: client, organization или branch с идентификаторами

Добавить сотрудника

POST/v1/orgs/{id}/members

Поле	Тип	Обязательное	Описание
phone	string	да	телефон сотрудника, см. Телефоны
firstName	string	да	1–100 символов
lastName	string	да	1–100 символов
roleId	string (UUID)	да	роль клиента
branchId	string (UUID)	нет	филиал этой организации; без него роль действует на всю организацию

curl

curl -X POST https://api.rekassa.uz/v1/orgs/8c1e4a27-5d3b-4f60-9a82-1b7e0c3d9f45/members \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone": "93 555 11 22",
    "firstName": "Нодира",
    "lastName": "Юсупова",
    "roleId": "9e4b7a12-0d5c-4f83-b2e6-7a1c3d9f0b58",
    "branchId": "5f2a9c61-8e3d-4b07-a4c9-0d6b1e7f3a28"
  }'

JavaScript

const response = await fetch(`https://api.rekassa.uz/v1/orgs/${organizationId}/members`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone: '93 555 11 22',
    firstName: 'Нодира',
    lastName: 'Юсупова',
    roleId: cashierRoleId,
    branchId,
  }),
})
const member = await response.json()

Ответ 201 — сотрудник в том же виде, что в списке.

Аккаунт по номеру телефона

Если пользователь с этим номером уже есть, он становится сотрудником, а его имя и фамилия не меняются. Если нет — создаётся активный аккаунт со входом по SMS-коду и без пароля: сотрудник сразу может войти по номеру телефона. Роли «Пользователь» у такого аккаунта нет, поэтому добавить свою организацию он не сможет.

Статус	Код	Когда
400	validation_failed	неверный телефон, пустое имя, roleId или branchId не UUID
403	forbidden	нет доступа users.manage или roles.assign (в details.permission)
403	insufficient_rank	ранг роли не ниже вашего
403	permission_not_held	у роли есть доступы, которых нет у вас (details.missing)
404	organization_not_found	организации нет
404	branch_not_found	в этой организации нет филиала с таким branchId
404	role_not_found	роли с таким roleId нет
409	member_exists	пользователь уже сотрудник: у него есть роль в организации или на весь клиент
422	role_scope_mismatch	роль не клиентская или принадлежит другому клиенту

Сменить роль

PATCH/v1/orgs/{id}/members/{userId}

Заменяет все роли сотрудника в этой организации и её филиалах одной новой. Роли на весь клиент, например «Владелец», не затрагиваются.

Поле	Тип	Обязательное	Описание
roleId	string (UUID)	да	новая роль клиента
branchId	string (UUID)	нет	ограничить роль филиалом; без него — на всю организацию

curl -X PATCH https://api.rekassa.uz/v1/orgs/8c1e4a27-5d3b-4f60-9a82-1b7e0c3d9f45/members/6b2e9d14-7a3c-4e81-9f50-2d8c1a4b7e63 \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"roleId": "3c8f1b27-9a4e-4d60-b7c2-5e0a9d4f1c86"}'

Ответ 200 — сотрудник с новой ролью. Ошибки — как у добавления (кроме member_exists), а также:

Статус	Код	Когда
403	insufficient_rank	ранг сотрудника не ниже вашего
404	member_not_found	пользователь не сотрудник этой организации
422	cannot_manage_self	попытка сменить собственную роль

Убрать сотрудника

DELETE/v1/orgs/{id}/members/{userId}

Снимает роли сотрудника в этой организации и её филиалах и удаляет его PIN в ней. Аккаунт пользователя остаётся, роли в других организациях и роли на весь клиент не затрагиваются — поэтому «Владельца» так убрать нельзя. Ответ — 204 No Content.

curl -X DELETE https://api.rekassa.uz/v1/orgs/8c1e4a27-5d3b-4f60-9a82-1b7e0c3d9f45/members/6b2e9d14-7a3c-4e81-9f50-2d8c1a4b7e63 \
  -H 'Authorization: Bearer <accessToken>'

Статус	Код	Когда
403	forbidden	нет доступа users.manage в организации
403	insufficient_rank	ранг сотрудника не ниже вашего
403	permission_not_held	у сотрудника есть доступы, которых нет у вас (details.missing)
404	member_not_found	у пользователя нет ролей в этой организации и её филиалах
422	cannot_manage_self	попытка убрать самого себя

PIN для кассы

PUT/v1/orgs/{id}/members/{userId}/pin

На кассе сотрудник входит по PIN: касса находит его по PIN среди сотрудников организации. Поэтому PIN — ровно 6 цифр и уникален в пределах организации. В каждой организации у сотрудника свой PIN.

• Свой PIN может задать любой сотрудник, включая кассира.
• Чужой — только тот, у кого есть users.manage в организации и кто выше сотрудника по рангу (см. Кто кем управляет).

curl

curl -X PUT https://api.rekassa.uz/v1/orgs/8c1e4a27-5d3b-4f60-9a82-1b7e0c3d9f45/members/6b2e9d14-7a3c-4e81-9f50-2d8c1a4b7e63/pin \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'Content-Type: application/json' \
  -d '{"pin": "418263"}'

JavaScript

const response = await fetch(
  `https://api.rekassa.uz/v1/orgs/${organizationId}/members/${userId}/pin`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ pin: '418263' }),
  },
)
if (response.status === 409) {
  // pin_taken: попросите придумать другой PIN
}

Ответ — 204 No Content. Повторный вызов заменяет PIN. Узнать, задан ли PIN, можно по полю hasPin в списке сотрудников; сам PIN API не возвращает.

Осторожно

Код 409 pin_taken сообщает, что такой PIN уже у кого-то в организации. Не показывайте пользователю, у кого именно, и не предлагайте перебирать варианты — просите придумать другой.

Статус	Код	Когда
400	validation_failed	PIN не из 6 цифр
403	forbidden	чужой PIN без доступа users.manage в организации
403	insufficient_rank	чужой PIN сотрудника не ниже вас рангом
403	permission_not_held	у сотрудника есть доступы, которых нет у вас
404	member_not_found	пользователь не сотрудник этой организации
409	pin_taken	такой PIN уже задан другому сотруднику организации