Bridge-and-Join-s/internal/lkgateway/web/templates/admin_help_lk.html

{{define "content"}}
<p style="margin-bottom:16px"><a href="/admin/help">← все инструкции</a></p>

<div class="card">
  <h2>API личного кабинета (ESIA Finance V1)</h2>
  <p class="muted">Bridge-and-Join-s реализует контракт ESIA Finance V1 на стороне back-office. ЛК клиента отправляет нам заявку, мы возвращаем подтверждение и потом колбэк со статусом. Полная спецификация: <code>docs/lk-contract/v1/openapi.yaml</code>.</p>
</div>

<div class="card">
  <h2>1. Аутентификация</h2>
  <p>HTTP <strong>Basic</strong>. Учётные записи и пароли согласуются с командой ЛК.</p>
  <pre>curl -u "lk-user:lk-password" \
  -H "Content-Type: application/json" \
  http://10.10.10.22:8080/api/v1/back_office/claims/</pre>
  <p class="muted">На M2 (дев-стенд) аутентификация отключена; включится на M3 — параллельно с подключением реального ЛК.</p>
</div>

<div class="card">
  <h2>2. Создание заявки M2M</h2>
  <p><code>POST /api/v1/back_office/claims/</code></p>
  <p>Тело — JSON, кодировка UTF-8. Минимально нужно: анкета инвестора, ИНН передающего и принимающего депозитария, информация о стоимости, массив ценных бумаг с количеством и счетами, подписанный XML заявления (base64).</p>
  <pre>curl -X POST http://10.10.10.22:8080/api/v1/back_office/claims/ \
  -H "Content-Type: application/json" \
  -d @docs/lk-contract/v1/examples/claim-request.json</pre>
  <p>Ответ <code>201 Created</code>:</p>
  <pre>{
  "id": "c02a1d5e-c2af-4799-bab4-953f133c5133",
  "status": "submitted_to_nsd",
  "created_at": "2026-03-02T14:30:45Z",
  "success": true
}</pre>
</div>

<div class="card">
  <h2>3. Получение заявки и её статуса</h2>
  <p><code>GET /api/v1/back_office/claims/{id}</code></p>
  <pre>curl http://10.10.10.22:8080/api/v1/back_office/claims/c02a1d5e-c2af-4799-bab4-953f133c5133</pre>
  <p>Возвращает полную карточку с историей FSM, ответом НРД и решением принимающей стороны (когда оно пришло).</p>
</div>

<div class="card">
  <h2>4. Список заявок</h2>
  <p><code>GET /api/v1/back_office/claims</code> с query-фильтрами: <code>status</code>, <code>investor_id</code>, <code>created_from</code>, <code>created_to</code>, <code>limit</code>, <code>offset</code>.</p>
  <pre>curl "http://10.10.10.22:8080/api/v1/back_office/claims?status=confirmed&limit=20"</pre>
</div>

<div class="card">
  <h2>5. Callback статуса (мы → ЛК)</h2>
  <p>Когда сделка меняет статус (подтверждена принимающей стороной, отклонена, или произошёл таймаут), bj-server делает <code>PATCH {LK_BASE}/api/v1/back_office/claims/{id}</code>:</p>
  <pre>{
  "claim_id": "c02a1d5e-c2af-4799-bab4-953f133c5133",
  "new_status": "confirmed",
  "updated_at": "2026-03-02T14:38:12Z",
  "nsd_response": {
    "guid": "...",
    "status_code": "INFO",
    "responses": [{"reference_id": "M2M2026...", "code": "01", "text": "..."}]
  }
}</pre>
  <p>Адрес ЛК указывается в <a href="/admin/setup">Настройка → Callback в ЛК</a> или через переменную <code>BJ_LK_CALLBACK_URL</code>.</p>
</div>

<div class="card">
  <h2>6. Формат ошибок</h2>
  <p>Любая ошибка возвращается в формате, идентичном ESIA Finance V1:</p>
  <pre>{
  "error": true,
  "status": 422,
  "code": "invalid_signature",
  "title": "Подпись заявления не прошла проверку",
  "meta": {
    "message": "Сертификат подписанта недействителен или цепочка доверия не построена.",
    "errors": [{"field": "signed_document", "message": "..."}]
  }
}</pre>
</div>

<div class="card">
  <h2>7. Эмулятор ЛК для тестов</h2>
  <p>На дев-стенде доступен <strong>lk-emulator</strong> на порту 8083 — имитация ЛК. Он сам регистрирует свой URL в bj-server как callback-приёмник.</p>
  <ul>
    <li><code>http://10.10.10.22:8083/</code> — журнал моих заявок (автообновление 3 сек)</li>
    <li><code>http://10.10.10.22:8083/new</code> — форма «подать заявку» с предустановленными инвесторами из seed-данных</li>
    <li>При запуске реального ЛК эмулятор остаётся как QA-инструмент</li>
  </ul>
</div>

<div class="card">
  <h2>8. Подписание заявления</h2>
  <p>ЛК должен подписать заявление XMLDSig (ГОСТ или RSA) и положить в поле <code>signed_document</code> (base64). Мы проверяем подпись через crypto-service — см. <a href="/admin/help/crypto">инструкцию по криптографии</a>.</p>
  <p class="muted">На M2 проверка подписи отключена (stub). На M3-M4 включится после подключения СКЗИ.</p>
</div>
{{end}}