Bridge-and-Join-s/docs/tasks/PR-3-lk-openapi.md

PR-3: OpenAPI контракт lk-gateway (ESIA Finance API V1)

Цель

Зафиксировать REST-контракт между lk-gateway (наш сервис) и ЛК клиента на платформе ESIA Finance. Контракт — отправная точка для:

• собственного эмулятора ЛК (lk-emulator, PR будет позже);
• интеграции с командой реального ЛК (когда формы документа на стороне ЛК будут готовы).

Источники правды

• DOC/API ЛК ЕСИА.pdf — официальное описание API V1 платформы ESIA Finance (/api/v1/back_office/..., Basic HTTP, JSON, UTF-8).
• DOC/M2MSchemas_260408/*.xsd — поля заявления должны быть достаточны для формирования M2MTransferRequest.

Состав PR

1. docs/lk-contract/v1/openapi.yaml

Спецификация OpenAPI 3.0. Покрывает следующие операции:

• POST /api/v1/back_office/claims/ — создание заявки на M2M-перевод.
  • Тело: подписанное заявление инвестора (XML или JSON, согласовать с командой ЛК; XML с XMLDSig — предпочтительнее, проще верифицировать на нашей стороне через crypto-service).
  • Ответ: { id, status, created_at, success: true }.
• GET /api/v1/back_office/claims/{id} — получение заявки и её статуса.
• PATCH /api/v1/back_office/claims/{id} — обновление статуса от нашей стороны (callback).
• GET /api/v1/back_office/claims — список заявок (фильтры по статусу, периоду, инвестору).
• Аутентификация: Basic HTTP (как в API V1 ESIA Finance).
• Формат ошибок — как в API ЛК ЕСИА.pdf: { error: true, status, code, title, meta: { message, errors } }.

2. Состав модели «Заявка»

Минимальный набор полей, нужный для формирования M2MTransferRequest:

• id (uuid),
• created_at, updated_at,
• status — enum (draft|signed|submitted|in_progress|confirmed|rejected|timed_out),
• investor — ссылка на пользователя в ЛК (или встроенные ФИО+документ);
• transferring_depository_inn, receiving_depository_inn,
• securities[] — список с security_code, isin (или security_info), quantity_whole|fractional, settlement_accounts[],
• cost_info — yes { code } | no,
• iia_agreement (опц., для ИИС) — agreement_type T12|T03, agreement_number, agreement_date, broker_inn,
• signed_document (base64) — подписанный XML заявления,
• signature_format — XMLDSig-GOST или XMLDSig-RSA.

3. Состав модели «Callback статуса»

Что мы отправляем обратно в ЛК:

• claim_id,
• new_status (по тому же enum),
• reason_code (для отказов — код причины из M2MTransferResponse),
• reason_text,
• updated_at,
• nsd_response — оригинал ответа НРД (опц., для аудита).

4. docs/lk-contract/v1/examples/

• examples/claim-request.json — пример заявки на перевод (3 ЦБ, ИИС, заполненные реквизиты).
• examples/claim-response.json — пример ответа.
• examples/callback-confirmed.json — пример callback подтверждения.
• examples/callback-rejected.json — пример callback отказа.
• examples/error-422.json — пример ошибки валидации.

5. docs/lk-contract/v1/changelog.md

Версионирование контракта. Первая запись — v1.0.0.

6. Обновить docs/lk-contract/v1/README.md

Описать состав, способ работы и порядок согласования с командой ЛК.

Требования к коду

• OpenAPI 3.0.x, валидный по spectral или openapi-cli.
• Имена операций (operationId) — snake_case.
• Описания (description) — на русском.
• Все поля с description и примерами.
• Без эмодзи.

Коммит

feat(lk-contract): OpenAPI контракт lk-gateway по ESIA Finance API V1

- docs/lk-contract/v1/openapi.yaml — спецификация
- docs/lk-contract/v1/examples/ — примеры запросов/ответов/callback
- docs/lk-contract/v1/changelog.md — v1.0.0

Контракт предлагается команде реального ЛК как точка синхронизации.
В lk-emulator (отдельный PR) контракт реализуется как «как-будто-ЛК»
для проверки сквозного потока.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

После коммита

1. Обновить docs/tasks/README.md: PR-3 — «выполнено».
2. Сообщить заказчику, что OpenAPI готов и можно отправлять команде ЛК.