Документация и задачи фронта: auth state (login / register)

Источник правды API (Scribe)#

Ломающие изменения относительно старого плана / старого фронта#

1. 1.
   Один URL больше не используется. Было POST /api/v1/auth/state. Стало:

   • •
     экран /login → POST /api/v1/auth/state/login
   • •
     экран /register → POST /api/v1/auth/state/register

   Сценарий задаётся URL.
2. 2.
   data.status → data.state. Типы, свитчи, Zod/TS, разбор JSON — читать state. То же для ответа регистрации продавца без токена (sms_required на POST /auth/register/user): там тоже state, не status.
3. 3.
   role_mismatch — единственное отличие двух методов. Значение state одно и то же. Меняются message, next_action и actions:

   • •
     /auth/state/register — можно регистрировать новую роль (next_action = register);
   • •
     /auth/state/login — не логинить (next_action = contact_support).

   Остальные state на login и register ведут себя одинаково.
4. 4.
   Регистрацию слать только если проверка была /auth/state/register и state ∈ {account_not_found, role_mismatch}.

1. Зачем эндпоинты#

• •
  data.state
• •
  какой URL вызывали (login vs register) — обязательно для role_mismatch

2. Когда вызывать#

• •
  /register — после валидации формы, до POST /auth/register/user или POST /auth/register/organization → POST /auth/state/register
• •
  /login — после роли / телефона / email, до POST /auth/login → POST /auth/state/login

3. Запрос#

• •
  role (обязательно) — private-person | private-broker | estate-agent | estate-representative | builder | director | supervisor | mentor | realtor | lawyer | administrator
• •
  phone (обязательно, до 25 символов)
• •
  email (обязательно)
• •
  inn (необязательно, до 12 символов)

4. Ответ 200 (/auth/state/*)#

JSON
Копировать
{
  "success": true,
  "data": {
    "state": "account_not_found",
    "next_action": "register",
    "message": "Учётная запись не найдена — пройдите регистрацию.",
    "actions": [{ "code": "register", "label": "Пройти регистрацию" }]
  },
  "error": null,
  "message": "Success"
}

• •
  Показать data.message.
• •
  Первая кнопка = data.next_action = data.actions[0].code. label не хардкодить.
• •
  «Изменить данные» — локально на форме, бэкенд не присылает.

5. Flow#

Trigger zoom image

Mermaid
Копировать
flowchart TD
  form[Форма логина или регистрации]
  which{Какой экран?}
  loginCall["POST /auth/state/login"]
  registerCall["POST /auth/state/register"]
  v422[422: починить поля]
  loginState{data.state}
  registerState{data.state}

  form --> which
  which -->|/login| loginCall
  which -->|/register| registerCall
  loginCall -->|422| v422
  registerCall -->|422| v422
  loginCall -->|200| loginState
  registerCall -->|200| registerState

  loginState -->|account_not_found| goRegLogin["Увести на /register"]
  loginState -->|role_mismatch| mailLogin["mailto поддержки, не логинить"]
  loginState -->|account_active / employee_already_exists| doLogin["POST /auth/login"]
  loginState -->|credentials_mismatch| goReset["/login/reset"]
  loginState -->|sms_required| goSms[Модалка SMS]
  loginState -->|pending_admin| wait[Сообщение, ждать]
  loginState -->|blocked / deleted / company / org_inactive| mailLogin

  registerState -->|account_not_found| doReg["POST /auth/register/user или organization"]
  registerState -->|role_mismatch| doRegNewRole["Регистрация новой роли"]
  registerState -->|остальное| panel["Панель, next_action, не слать register"]

• •
  /auth/state/register + role_mismatch → можно регистрировать новую роль (next_action = register).
• •
  /auth/state/login + role_mismatch → не логинить (next_action = contact_support).

• •
  account_not_found после /auth/state/register
• •
  role_mismatch после /auth/state/register

6. Состояния: что делать фронту#

• •
  account_active — «Такая учётная запись уже есть — войдите или восстановите пароль.»
• •
  employee_already_exists — «Такой сотрудник уже добавлен — войдите или восстановите пароль.»
• •
  pending_admin — «Заявка уже отправлена и ждёт подтверждения администратора.»
• •
  account_deleted — «Учётная запись удалена — для восстановления обратитесь в поддержку ETTE.»
• •
  account_blocked — «Учётная запись заблокирована — обратитесь в поддержку ETTE.»
• •
  company_already_registered — «Компания с этим ИНН уже зарегистрирована — обратитесь в поддержку ETTE.»
• •
  organization_inactive — «Доступ организации временно ограничен — обратитесь в поддержку ETTE.»
• •
  role_mismatch + register — «Учётная запись найдена — продолжаем регистрацию новой роли.»
• •
  role_mismatch + login — «Для этой роли учётная запись не найдена — обратитесь в поддержку ETTE.»
• •
  credentials_mismatch — «Введённые данные не совпадают — восстановите пароль или обратитесь в поддержку.»
• •
  account_not_found — «Учётная запись не найдена — пройдите регистрацию.»
• •
  sms_required — «Введите код из SMS для подтверждения телефона.»

7. cURL (Postman)#

Bash
Копировать
curl --request POST 'https://staging-api.ette.ru/api/v1/auth/state/register' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Accept-Language: ru' \
  --data '{
    "role": "private-person",
    "phone": "+79120000001",
    "email": "new-user@example.com"
  }'

8. Чеклист фронта#

• •
  Вызовы: login-экран → /auth/state/login, register-экран → /auth/state/register. Удалить POST /auth/state.
• •
  Везде data.state, не data.status (включая ответ sms_required с /auth/register/user).
• •
  Для role_mismatch смотреть, какой метод вызывали: register — слать регистрацию новой роли; login — не логинить, взять кнопку из actions.
• •
  Register API только после /auth/state/register и account_not_found | role_mismatch.
• •
  Кнопки и подписи из actions.
• •
  Сверить примеры с staging docs после выката.
• •
  Обновить ette_frontend/docs/ (отдельным шагом после кода).