🏛️ Юридический профиль продавца (LegalProfiles API)

Контроллер: Api::V1::LegalProfilesController
Версия: v1
Слой: Аутентифицированный API
Все методы требуют access-токен. Некоторые действия доступны только администраторам.

---

📘 Общая логика

• Каждый SellerProfile может иметь до двух юридических профилей (LegalProfile)
• Профиль используется при создании магазина
• Юр. лица подтверждаются администратором вручную (is_verified)
• Только владелец SellerProfile или администратор может редактировать или просматривать юр. профиль

---

📄 Методы

🆕 POST /api/v1/legal_profiles

Создание юридического профиля

🔹 Входные параметры

Поле	Тип	Обязательный	Пример
company_name	string	✅	ИП Иванов И.И.
tax_id	string	✅	123456789012
country_code	string	✅	KZ
legal_address	string	✅	г. Алматы, ул. Абая, д. 10
legal_form	string	✅	Индивидуальный предприниматель
seller_profile_id	UUID	✅	UUID seller-профиля

---

✅ Ответ (201 Created)

{
  "id": "lp-uuid",
  "company_name": "ИП Иванов И.И.",
  "is_verified": false
}

---

✅ Чек-лист

Пункт	Значение
🔒 Требуется access token	✅ Да
🔐 Политики доступа	Только владелец SellerProfile
🔗 Зависимости	Продавец должен иметь SellerProfileИметь < 2 юридических профилей

---

📋 Валидации

• Только страны KZ и RU
• tax_id — уникален
• Максимум два юридических профиля на один SellerProfile
• Все поля обязательны, кроме верификации
• Если профиль был верифицирован is_verified: true, то пользователь не может редактировать профиль. Он должен сначала сбросить верификацию при помощи метода /unverify
• Пользователь может редактировать профиль только при is_verified: false
• Пользователь не может сам себе установить is_verified: true

---

💼 Бизнес-логика

• Проверка уникальности ИНН
• Проверка количества существующих юридических профилей
• Новый профиль автоматически is_verified: false
• Может быть использован при создании магазина

---

📚 Кейсы использования

🏢 Кейс 1: Продавец добавляет юр. лицо

После создания профиля продавца он добавляет данные юр. лица для использования в магазине.

🚫 Кейс 2: Превышен лимит в 2 профиля

При попытке создать 3-й юридический профиль — ошибка 422.

---

📂 GET /api/v1/legal_profiles

Получение всех юр. профилей текущего пользователя

✅ Ответ

[
  {
    "id": "lp-uuid",
    "company_name": "ИП Иванов И.И.",
    "is_verified": false
  }
]

---

🔍 GET /api/v1/legal_profiles/:id

Получение одного юр. профиля

✅ Ответ

{
  "id": "lp-uuid",
  "company_name": "ИП Иванов И.И.",
  "tax_id": "123456789012",
  "country_code": "KZ",
  "legal_form": "ИП",
  "is_verified": true
}

---

✏️ PATCH /api/v1/legal_profiles/:id

Редактирование профиля (если is_verified = false)

🔹 Поля для редактирования:

• company_name
• tax_id
• country_code
• legal_address
• legal_form

✅ Ответ

{
  "id": "lp-uuid",
  "company_name": "ИП Обновлённый"
}

---

✅ Чек-лист

Пункт	Значение
🔒 Требуется access token	✅ Да
🔐 Политики доступа	Только владелец
🔗 Зависимости	Только если не подтверждён

---

📚 Кейсы использования

• Продавец исправляет адрес юр. лица до верификации
• Админ вручную верифицирует через админку

---

🔁 PATCH /api/v1/legal_profiles/:id/unverify

Сброс верификации админом

✅ Ответ

{
  "id": "lp-uuid",
  "is_verified": false
}

---

📚 Кейсы использования

• Админ снимает верификацию перед повторной проверкой
• Продавец вновь получает возможность редактирования

---

🧩 Связанные сущности

Сущность	Назначение
LegalProfile	Юр. лицо продавца
SellerProfile	Продавец-владелец
User	Через SellerProfile
Shop	Связан с LegalProfile при создании

---

📄 TODO / Идеи

• Интеграция с базой налоговых для автоподтверждения
• Визуальный статус верификации
• Уведомление администратора о новых заявках
• Загрузка PDF документов
• Поддержка юр. форм по странам