# docs/lk-contract/v1 — контракт с ЛК клиента (ESIA Finance API V1)

ЛК клиента работает на платформе **ESIA Finance**, контракт описан в
`DOC/API ЛК ЕСИА.pdf` (`/api/v1/back_office/...`, Basic HTTP, JSON,
UTF-8).

На этапе M1 в `lk-emulator` (отдельный PR) мы реализуем этот контракт
как «как-будто-ЛК» для запуска сквозного потока. Реальный ЛК
подключится по тому же контракту без правок на нашей стороне.

## Состав каталога

- **`openapi.yaml`** — OpenAPI 3.0 контракт lk-gateway. Описывает
  четыре операции: создание, чтение, callback статуса и список заявок.
  Модель `Claim` включает все поля, нужные m2m-core для формирования
  `M2MTransferRequest`.
- **`examples/`**:
  - `claim-request.json` — пример заявки на перевод (3 ЦБ, ИИС T03).
  - `claim-response.json` — пример ответа на создание.
  - `callback-confirmed.json` — callback подтверждения (status_code
    INFO, 3 коды 01).
  - `callback-rejected.json` — callback отказа (status_code ERROR).
  - `error-422.json` — ошибка валидации подписи.
- **`changelog.md`** — версионирование контракта.

## Что входит в модель заявки

- Идентификация инвестора (UUID в ЛК, ФИО, документ).
- Реквизиты передающего и принимающего депозитариев (ИНН).
- Информация об учёте стоимости (`cost_info: yes | no`).
- Опциональный блок ИИС (тип T12/T03, номер договора, дата, ИНН брокера).
- Массив ценных бумаг (1..N), каждая с:
  - `security_code` (НРД-код, 12 символов),
  - идентификацией (`isin` или развёрнутый `security_info`),
  - количеством (целое `whole` или дробное `fractional` до 16 знаков),
  - списком счетов депо (`settlement_accounts[]`).
- Подписанный XML заявления (base64) и формат подписи
  (XMLDSig-GOST или XMLDSig-RSA).

## Что входит в callback статуса

- `claim_id`, `new_status`, `updated_at`.
- Для `rejected`/`timed_out`: код и текст причины из ответа НРД.
- Полное `nsd_response` (опц., для аудита).

## Порядок согласования

1. Передать команде ЛК ссылку на эту папку (тег `lk-contract-v1`).
2. Обсудить базовый URL, авторизацию (Basic, через VPN), окна.
3. Запустить `lk-emulator` на нашей стороне как опорную реализацию.
4. После приёмки — поднимать реальную интеграцию.

## Принципы

- OpenAPI 3.0, валидный по spectral / openapi-cli.
- Operation IDs в snake_case.
- Описания на русском, имена полей на английском.
- Enum'ы значений M2M — буквально как в XSD НРД (T12/T03, BOND/SHAR/MFUN, ...).