# API панели модулей МПФИТ

Панель, в которой сотрудник фулфилмента подключает своим селлерам модули интеграций
(СДЭК, Uzum, Яндекс Доставка). Логика подключения живёт в воркфлоу n8n, панель их вызывает.

Контракт повторяет кабинет `cabinet.mpfit.ru`: префикс `/api/web/v1`, сессионная кука,
ответы `{"data": ...}`, поля в camelCase.

## Авторизация

Вход — API-ключ кабинета ВМС фулфилмента (выпускается в ЛК: Компании → карточка
компании → «API интеграция» → «Сгенерировать ключ»). Ключ и есть доказательство, кто
пришёл: ядро по нему отдаёт компанию с `type: FF` и всех её селлеров.

Ключ селлера не принимается — подключать модули может только фулфилмент.

После входа ставятся две куки: `mpfit_modules_session` (HttpOnly, сессия) и
`mpfit_modules_csrf` (читаемая). Все запросы, меняющие состояние, должны возвращать
значение второй куки в заголовке `X-CSRF-Token`.

Сам ключ наружу не отдаётся никогда — ни в ответах, ни в журнале.

## Методы

| Метод | Путь | Что делает |
|---|---|---|
| POST | `/api/web/v1/auth/login` | `{"token": "..."}` → проверка ключа в ядре, вход |
| POST | `/api/web/v1/auth/logout` | выход, гасит сессию |
| GET | `/api/web/v1/auth/me` | текущее подключение |
| GET | `/api/web/v1/connections/{id}/companies` | селлеры этого ФФ — для выбора, кому подключаем |
| GET | `/api/web/v1/connections/{id}/order-types` | направления отгрузки ФФ, названиями |
| GET | `/api/web/v1/modules` | реестр модулей: что подключаем и какие поля спрашивать |
| GET | `/api/web/v1/connections/{id}/sellers/{sellerId}/integrations` | подключения селлера по всем модулям |
| POST | `/api/web/v1/connections/{id}/sellers/{sellerId}/integrations/{module}/check` | проверка ключей в чужом сервисе, ничего не пишет |
| POST | `/api/web/v1/connections/{id}/sellers/{sellerId}/integrations/{module}` | завести подключение |
| GET | `/healthz` | живость |

### Подключение модуля

`{"credentials": {...}, "mpfitToken": "...", "orderTypeId": 2899}`.

Состав `credentials` описан в `/api/web/v1/modules`: у СДЭК — `client_id` и
`client_secret`, у Uzum — `uzum_token`, у Яндекс Доставки — `yandex_token`.

Перед записью ключи проверяются вживую в самом сервисе (СДЭК — выдача `access_token`,
Uzum — список магазинов, Яндекс — запрос заказов за узкое окно). Не прошло — `422`
с человеческим текстом, в n8n ничего не уходит. У Uzum успешная проверка возвращает
магазины кабинета в `options.shops` — их показываем, чтобы ФФ убедился, что кабинет тот.

`mpfitToken` — API-ключ **селлера**, его присылает сам селлер. Переиспользовать уже
сохранённый нельзя: ручка поиска отдаёт только флаг `hasMpfitToken`, самих ключей она
не показывает. Это осознанно, но неудобно — кандидат на отдельную ручку в n8n.

Селлер из URL всегда сверяется со списком селлеров фулфилмента: чужому подключение
не заведёшь.

### Коды ошибок

- `401` — нет сессии;
- `403` — не совпал `X-CSRF-Token`;
- `409` — сохранённый ключ перестал работать (отозвали в ЛК) или нечитаем;
- `422` — ключ не принят ядром при входе;
- `502` — ядро ВМС недоступно.

## Что где хранится

- Привязанный кабинет ВМС, сессии и журнал — своя SQLite панели. Ключ ВМС лежит
  зашифрованным (AES-256-GCM).
- Сами подключения модулей — в базе n8n, там же, где их видит внутренняя админка
  `tools.mpfit.ru/admin/`. Панель их не дублирует.