fontvielle
a040f8b07d
- docs/lk-contract/v1/openapi.yaml — OpenAPI 3.0: POST/GET/PATCH /api/v1/back_office/claims, схемы Claim/CreateClaimRequest/StatusCallback/ErrorResponse - docs/lk-contract/v1/examples/claim-request.json — заявка с 3 ЦБ, ИИС T03 - docs/lk-contract/v1/examples/claim-response.json — ответ на создание - docs/lk-contract/v1/examples/callback-confirmed.json — callback подтверждения - docs/lk-contract/v1/examples/callback-rejected.json — callback отказа - docs/lk-contract/v1/examples/error-422.json — ошибка валидации - docs/lk-contract/v1/changelog.md — v1.0.0 Контракт предлагается команде реального ЛК как точка синхронизации. В lk-emulator (отдельный PR) контракт реализуется как «как-будто-ЛК» для проверки сквозного потока. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
657 lines
19 KiB
YAML
657 lines
19 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: lk-gateway API
|
|
version: 1.0.0
|
|
description: |
|
|
REST-контракт между сервисом `lk-gateway` (Bridge-and-Join-s) и ЛК
|
|
инвестора на платформе ESIA Finance. Версия V1 совместима с
|
|
официальным API ESIA Finance (`DOC/API ЛК ЕСИА.pdf`).
|
|
|
|
Контракт обслуживает жизненный цикл заявки M2M-перевода: создание,
|
|
получение, обновление статуса и список заявок.
|
|
|
|
Аутентификация — HTTP Basic. Кодировка — UTF-8. Тело запросов и
|
|
ответов — JSON.
|
|
servers:
|
|
- url: https://lk-gateway.bridge-and-joins.local
|
|
description: Production lk-gateway
|
|
- url: http://localhost:8080
|
|
description: Локальный эмулятор (lk-emulator)
|
|
security:
|
|
- basicAuth: []
|
|
|
|
paths:
|
|
/api/v1/back_office/claims/:
|
|
post:
|
|
operationId: create_claim
|
|
summary: Создать заявку на M2M-перевод
|
|
description: |
|
|
Принимает подписанное (XMLDSig) заявление инвестора. Сервис
|
|
проверяет подпись через crypto-service, валидирует данные,
|
|
создаёт сделку и инициирует отправку в НРД.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateClaimRequest'
|
|
examples:
|
|
full_claim:
|
|
summary: Заявка с тремя ЦБ, ИИС T03
|
|
externalValue: ./examples/claim-request.json
|
|
responses:
|
|
'201':
|
|
description: Заявка создана
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateClaimResponse'
|
|
'400':
|
|
description: Невалидные входные данные
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'401':
|
|
description: Не авторизован
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
'422':
|
|
description: Подпись неверна или данные не прошли бизнес-валидацию
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
|
|
/api/v1/back_office/claims:
|
|
get:
|
|
operationId: list_claims
|
|
summary: Список заявок
|
|
description: Возвращает список заявок с фильтрацией по статусу, периоду и инвестору.
|
|
parameters:
|
|
- name: status
|
|
in: query
|
|
description: Фильтр по статусу.
|
|
required: false
|
|
schema:
|
|
$ref: '#/components/schemas/ClaimStatus'
|
|
- name: investor_id
|
|
in: query
|
|
description: UUID инвестора в ЛК.
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: created_from
|
|
in: query
|
|
description: Нижняя граница периода создания (ISO 8601, UTC).
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: created_to
|
|
in: query
|
|
description: Верхняя граница периода создания (ISO 8601, UTC).
|
|
required: false
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: limit
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 200
|
|
default: 50
|
|
- name: offset
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
minimum: 0
|
|
default: 0
|
|
responses:
|
|
'200':
|
|
description: Страница списка заявок
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ClaimsPage'
|
|
|
|
/api/v1/back_office/claims/{id}:
|
|
get:
|
|
operationId: get_claim
|
|
summary: Получить заявку и её статус
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: UUID заявки.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
'200':
|
|
description: Заявка
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Claim'
|
|
'404':
|
|
description: Заявка не найдена
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
patch:
|
|
operationId: update_claim_status
|
|
summary: Callback обновления статуса (от lk-gateway к ЛК)
|
|
description: |
|
|
Используется лгатвей-ом для уведомления ЛК о смене статуса
|
|
сделки на стороне НРД. Подтверждение, отказ или таймаут.
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
description: UUID заявки.
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/StatusCallback'
|
|
examples:
|
|
confirmed:
|
|
summary: Подтверждение
|
|
externalValue: ./examples/callback-confirmed.json
|
|
rejected:
|
|
summary: Отказ
|
|
externalValue: ./examples/callback-rejected.json
|
|
responses:
|
|
'200':
|
|
description: Callback принят
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CallbackResponse'
|
|
'404':
|
|
description: Заявка не найдена
|
|
|
|
components:
|
|
securitySchemes:
|
|
basicAuth:
|
|
type: http
|
|
scheme: basic
|
|
|
|
schemas:
|
|
ClaimStatus:
|
|
type: string
|
|
description: |
|
|
Жизненный цикл заявки на M2M-перевод.
|
|
- `draft` — черновик, ещё не подписан.
|
|
- `signed` — подписан, но не отправлен.
|
|
- `submitted` — отправлен в НРД.
|
|
- `in_progress` — НРД принял, ждём решение от принимающей стороны.
|
|
- `confirmed` — подтверждён, перевод исполнен.
|
|
- `rejected` — отклонён.
|
|
- `timed_out` — превышен SLA, ручной разбор.
|
|
enum:
|
|
- draft
|
|
- signed
|
|
- submitted
|
|
- in_progress
|
|
- confirmed
|
|
- rejected
|
|
- timed_out
|
|
|
|
SignatureFormat:
|
|
type: string
|
|
description: Тип цифровой подписи заявления.
|
|
enum:
|
|
- XMLDSig-GOST
|
|
- XMLDSig-RSA
|
|
|
|
AgreementType:
|
|
type: string
|
|
description: |
|
|
Тип договора ИИС.
|
|
- `T12` — ИИС-1 или ИИС-2 (старый формат).
|
|
- `T03` — ИИС-3 (новый).
|
|
enum:
|
|
- T12
|
|
- T03
|
|
|
|
SecurityClassification:
|
|
type: string
|
|
description: Тип ценной бумаги.
|
|
enum:
|
|
- BOND
|
|
- SHAR
|
|
- MFUN
|
|
|
|
SecurityCategory:
|
|
type: string
|
|
description: Категория акций.
|
|
enum:
|
|
- ORDN
|
|
- PREF
|
|
- UKWN
|
|
|
|
Investor:
|
|
type: object
|
|
description: Анкета инвестора.
|
|
required:
|
|
- last_name
|
|
- first_name
|
|
- document
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: UUID инвестора в ЛК (если уже известен).
|
|
last_name:
|
|
type: string
|
|
maxLength: 50
|
|
example: Иванов
|
|
first_name:
|
|
type: string
|
|
maxLength: 50
|
|
example: Иван
|
|
middle_name:
|
|
type: string
|
|
maxLength: 50
|
|
example: Иванович
|
|
document:
|
|
$ref: '#/components/schemas/IdentityDocument'
|
|
|
|
IdentityDocument:
|
|
type: object
|
|
description: Документ, удостоверяющий личность.
|
|
required:
|
|
- document_type
|
|
- number
|
|
properties:
|
|
document_type:
|
|
type: string
|
|
pattern: '^(0[1-7]|09|1[0-4]|2[1-37]|26|91)$'
|
|
description: Код документа по справочнику НРД.
|
|
example: '21'
|
|
series:
|
|
type: string
|
|
pattern: '^\S+$'
|
|
example: '4512'
|
|
number:
|
|
type: string
|
|
pattern: '^\S+$'
|
|
example: '654321'
|
|
|
|
Quantity:
|
|
type: object
|
|
description: Количество ценных бумаг — choice (ровно одно поле).
|
|
properties:
|
|
whole:
|
|
type: integer
|
|
format: int64
|
|
minimum: 1
|
|
example: 1500
|
|
fractional:
|
|
type: string
|
|
description: Десятичная строка с не более 16 знаками после точки.
|
|
pattern: '^[0-9]+(\.[0-9]{1,16})?$'
|
|
example: '2500.75'
|
|
|
|
FundShares:
|
|
type: object
|
|
required:
|
|
- reg_number
|
|
properties:
|
|
reg_number:
|
|
type: string
|
|
maxLength: 256
|
|
example: '23-001'
|
|
class:
|
|
type: string
|
|
maxLength: 120
|
|
example: A
|
|
|
|
IdentificationDetails:
|
|
type: object
|
|
description: Идентификация ЦБ — choice (ровно одно поле).
|
|
properties:
|
|
reg_number:
|
|
type: string
|
|
maxLength: 20
|
|
fund_shares:
|
|
$ref: '#/components/schemas/FundShares'
|
|
|
|
SecurityInfo:
|
|
type: object
|
|
description: Описание ЦБ при отсутствии ISIN.
|
|
required:
|
|
- classification
|
|
- category
|
|
- identification_details
|
|
properties:
|
|
classification:
|
|
$ref: '#/components/schemas/SecurityClassification'
|
|
category:
|
|
$ref: '#/components/schemas/SecurityCategory'
|
|
security_type:
|
|
type: string
|
|
maxLength: 256
|
|
security_series:
|
|
type: string
|
|
identification_details:
|
|
$ref: '#/components/schemas/IdentificationDetails'
|
|
|
|
SecurityDetails:
|
|
type: object
|
|
description: Идентификация ЦБ — choice (ровно одно поле).
|
|
properties:
|
|
isin:
|
|
type: string
|
|
pattern: '^[A-Z]{2}[A-Z0-9]{9}[0-9]$'
|
|
example: RU0007661625
|
|
security_info:
|
|
$ref: '#/components/schemas/SecurityInfo'
|
|
|
|
SettlementLocation:
|
|
type: object
|
|
required:
|
|
- deponent_code
|
|
- account_id
|
|
- section_id
|
|
properties:
|
|
deponent_code:
|
|
type: string
|
|
maxLength: 50
|
|
example: DP789456
|
|
account_id:
|
|
type: string
|
|
maxLength: 50
|
|
example: 31MC0021900000F01
|
|
section_id:
|
|
type: string
|
|
maxLength: 50
|
|
example: P001
|
|
|
|
SettlementAccount:
|
|
type: object
|
|
required:
|
|
- settlement_requisites_inn
|
|
- settlement_location
|
|
properties:
|
|
settlement_requisites_inn:
|
|
type: string
|
|
pattern: '^[0-9]{10}$'
|
|
example: '7702070139'
|
|
settlement_location:
|
|
$ref: '#/components/schemas/SettlementLocation'
|
|
|
|
ClaimSecurity:
|
|
type: object
|
|
required:
|
|
- security_code
|
|
- security_details
|
|
- quantity
|
|
- settlement_accounts
|
|
properties:
|
|
security_code:
|
|
type: string
|
|
pattern: '^[0-9A-Z_/-]{12}$'
|
|
example: MM0766162534
|
|
security_details:
|
|
$ref: '#/components/schemas/SecurityDetails'
|
|
quantity:
|
|
$ref: '#/components/schemas/Quantity'
|
|
settlement_accounts:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/SettlementAccount'
|
|
|
|
CostInfo:
|
|
type: object
|
|
description: |
|
|
Информация об учёте стоимости приобретения. Choice: либо
|
|
`yes` (с кодом депонента-источника), либо `no` (учёт не ведётся).
|
|
properties:
|
|
yes:
|
|
type: object
|
|
required: [code]
|
|
properties:
|
|
code:
|
|
type: string
|
|
pattern: '^[A-Z0-9]+$'
|
|
maxLength: 12
|
|
example: MC0010300032
|
|
no:
|
|
type: object
|
|
description: Пустой объект — учёт не ведётся.
|
|
|
|
IIAAgreement:
|
|
type: object
|
|
description: Реквизиты договора ИИС (нужно, если перевод идёт по ИИС).
|
|
required:
|
|
- agreement_type
|
|
- agreement_number
|
|
- agreement_date
|
|
- broker_inn
|
|
properties:
|
|
agreement_type:
|
|
$ref: '#/components/schemas/AgreementType'
|
|
agreement_number:
|
|
type: string
|
|
maxLength: 128
|
|
example: ИИС78/2024
|
|
agreement_date:
|
|
type: string
|
|
format: date
|
|
example: '2026-01-15'
|
|
broker_inn:
|
|
type: string
|
|
pattern: '^[0-9]{10}$'
|
|
example: '0707083893'
|
|
|
|
CreateClaimRequest:
|
|
type: object
|
|
required:
|
|
- investor
|
|
- transferring_depository_inn
|
|
- receiving_depository_inn
|
|
- cost_info
|
|
- securities
|
|
- signed_document
|
|
- signature_format
|
|
properties:
|
|
investor:
|
|
$ref: '#/components/schemas/Investor'
|
|
transferring_depository_inn:
|
|
type: string
|
|
pattern: '^[0-9]{10}$'
|
|
receiving_depository_inn:
|
|
type: string
|
|
pattern: '^[0-9]{10}$'
|
|
cost_info:
|
|
$ref: '#/components/schemas/CostInfo'
|
|
iia_agreement:
|
|
$ref: '#/components/schemas/IIAAgreement'
|
|
securities:
|
|
type: array
|
|
minItems: 1
|
|
items:
|
|
$ref: '#/components/schemas/ClaimSecurity'
|
|
signed_document:
|
|
type: string
|
|
format: byte
|
|
description: Подписанный XML заявления в base64.
|
|
signature_format:
|
|
$ref: '#/components/schemas/SignatureFormat'
|
|
|
|
CreateClaimResponse:
|
|
type: object
|
|
required: [id, status, created_at, success]
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
$ref: '#/components/schemas/ClaimStatus'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
|
|
Claim:
|
|
type: object
|
|
description: Полная сущность заявки.
|
|
required:
|
|
- id
|
|
- status
|
|
- created_at
|
|
- updated_at
|
|
- investor
|
|
- transferring_depository_inn
|
|
- receiving_depository_inn
|
|
- securities
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
$ref: '#/components/schemas/ClaimStatus'
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
investor:
|
|
$ref: '#/components/schemas/Investor'
|
|
transferring_depository_inn:
|
|
type: string
|
|
pattern: '^[0-9]{10}$'
|
|
receiving_depository_inn:
|
|
type: string
|
|
pattern: '^[0-9]{10}$'
|
|
cost_info:
|
|
$ref: '#/components/schemas/CostInfo'
|
|
iia_agreement:
|
|
$ref: '#/components/schemas/IIAAgreement'
|
|
securities:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ClaimSecurity'
|
|
last_callback:
|
|
$ref: '#/components/schemas/StatusCallback'
|
|
|
|
ClaimsPage:
|
|
type: object
|
|
required: [items, total, limit, offset]
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Claim'
|
|
total:
|
|
type: integer
|
|
minimum: 0
|
|
limit:
|
|
type: integer
|
|
offset:
|
|
type: integer
|
|
|
|
StatusCallback:
|
|
type: object
|
|
description: Callback обновления статуса от lk-gateway к ЛК.
|
|
required:
|
|
- claim_id
|
|
- new_status
|
|
- updated_at
|
|
properties:
|
|
claim_id:
|
|
type: string
|
|
format: uuid
|
|
new_status:
|
|
$ref: '#/components/schemas/ClaimStatus'
|
|
reason_code:
|
|
type: string
|
|
maxLength: 6
|
|
description: Код причины (для rejected/timed_out) из M2MTransferResponse или M2MTransferDecision.
|
|
example: '01'
|
|
reason_text:
|
|
type: string
|
|
maxLength: 1024
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
nsd_response:
|
|
type: object
|
|
description: Оригинал ответа НРД (необязательно, для аудита).
|
|
properties:
|
|
guid:
|
|
type: string
|
|
format: uuid
|
|
status_code:
|
|
type: string
|
|
enum: [INFO, ERROR]
|
|
responses:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
reference_id:
|
|
type: string
|
|
pattern: '^M2M[A-Z0-9]{13}$'
|
|
code:
|
|
type: string
|
|
text:
|
|
type: string
|
|
|
|
CallbackResponse:
|
|
type: object
|
|
required: [success]
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
|
|
ErrorResponse:
|
|
type: object
|
|
description: Формат ошибки, идентичный API ESIA Finance V1.
|
|
required: [error, status]
|
|
properties:
|
|
error:
|
|
type: boolean
|
|
example: true
|
|
status:
|
|
type: integer
|
|
example: 422
|
|
code:
|
|
type: string
|
|
example: invalid_signature
|
|
title:
|
|
type: string
|
|
example: Подпись не прошла проверку
|
|
meta:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
errors:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
field:
|
|
type: string
|
|
message:
|
|
type: string
|