# Эндпоинты, с которыми взаимодействует stamp-verification-frontend

Документ описывает все внешние HTTP-вызовы, которые выполняет статическая страница проверки штампа (`stamp-verification-frontend`).

## Как устроено взаимодействие

В отличие от микрофронтендов с декларативным реестром эндпоинтов, здесь весь сетевой код сосредоточен в одном файле — `static/js/index.js`. Страница обычным `fetch` обращается к **одному** публичному эндпоинту backend-сервиса `documentations`, а также подгружает сторонние ресурсы аналитики и статику.

Логика вызова:

1. из query-строки берутся параметры `id` (идентификатор QR) и `page_number`; запрос выполняется только если оба заданы;
2. базовый хост API выбирается по `window.location.host`;
3. выполняется `GET`-запрос с `mode: "cors"`, `credentials: "include"`, `cache: "no-cache"`;
4. ответ (JSON) маппится на поля страницы.

## Базовые хосты по окружениям

Значение определяется в `index.js` по хосту страницы. Итоговый URL = `https://<базовый хост>` + путь эндпоинта.

| Хост страницы (`window.location.host`) | Базовый хост API | Окружение |
| --- | --- | --- |
| `stamp-verification.sarex.io` | `api.sarex.io` | prod |
| любой другой (напр. `stamp-verification.stage.sarex.io`) | `stage-api.sarex.io` | stage |

> Промежуточных окружений (preprod/local) в коде не предусмотрено: всё, что не prod-домен, трактуется как stage.

## Эндпоинты по сервисам

### `documentations` — Сервис документации

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getQrDocumentInfo` | GET | `/documentations/api/v1/public/qr/{qrId}/document_info?number_page={pageNumber}` | Публичная информация о документе по QR-коду штампа: название, версия, автор, дата загрузки, актуальность/аннулирование версии, статус согласования, changelog и ссылка на документ в Sarex |

Параметры запроса:

| Параметр | Расположение | Обязателен | Назначение |
| --- | --- | --- | --- |
| `qrId` | path (`{qrId}`) | да | Идентификатор QR-кода (из query `?id=`) |
| `number_page` | query | да | Номер страницы документа (из query `?page_number=`) |

Заголовки запроса (как в текущем коде): `Content-Type: application/json` и `Authorization: Bearer <jwt>`. **Токен захардкожен и истёк** — см. раздел «Замечания». Запрос идёт с `credentials: "include"` (куки/учётные данные), `redirect: "follow"`, `referrerPolicy: "no-referrer"`.

Используемые поля ответа (по `index.js`): `document_name`, `version_number`, `page_number`, `author`, `upload_date`, `is_actual_version`, `is_canceled`, `does_bundle_have_flows`, `is_actual_version_approved`, `document_review_status`, `document_url`, `is_latest_changelog`, `changelog` (`no`, `description`, `author` и др.). Полная схема — в `openapi.yaml`.

Формирование ссылки на документ: при наличии `document_url` ссылка на странице собирается как `${data.document_url}&page_number=${data.page_number}` и открывается в Sarex.

## Внешние (сторонние) ресурсы

Не относятся к API Sarex, но выполняются страницей:

| Ресурс | Метод | URL | Назначение |
| --- | --- | --- | --- |
| Яндекс.Метрика (tag.js) | GET | `https://mc.yandex.ru/metrika/tag.js` | Загрузка счётчика аналитики (id `93441026`) |
| Яндекс.Метрика (noscript) | GET | `https://mc.yandex.ru/watch/93441026` | Пиксель для окружения без JS |
| Статика приложения | GET | `static/css/*`, `static/js/*`, `static/icons/*`, `static/fonts/*`, `static/img/*` | CSS, `moment-with-locales.min.js`, иконки, шрифты, фон — раздаются самим nginx |

Health-check (со стороны инфраструктуры, не самой страницы): `GET /ping` → `200 {"result": "ok"}` (отдаётся nginx).

## Обработка ошибок

Специализированного маппинга кодов ошибок в человекочитаемые сообщения (как в backend-сервисах) в коде нет. Ошибки обрабатываются минимально: `fetch` обёрнут в `.catch(...)`, ошибки логируются в консоль (`console.error`). При пустом/отсутствующем ответе поля страницы заполняются плейсхолдером `–––` (`PLACEHOLDER_STR`). Пользовательских уведомлений об ошибке нет.

## Замечания

- **Захардкоженный JWT.** В заголовке `Authorization` в `index.js` вшит истёкший (2023 г.) Bearer-токен. Эндпоинт публичный (`/public/qr/...`) — заголовок с токеном следует удалить; хранить токены в статике недопустимо.
- **`credentials: "include"`** при кросс-доменном запросе к `*-api.sarex.io` требует корректной CORS-конфигурации на стороне `documentations` (`Access-Control-Allow-Credentials` + конкретный `Access-Control-Allow-Origin`).
- **Параметр `v`** (версия) читается из query, но пока не используется.
- **Выбор окружения только по домену** — новый prod-домен потребует правки кода.