iac/apps/stamp-verification/ENDPOINTS.md

Эндпоинты, с которыми взаимодействует 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-домен потребует правки кода.