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

Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается фронтенд публичных ссылок (`document-link-frontend`).

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

Фронтенд загружает карточку документа по `uuid` из URL (`/<uuid>`). Запрос выполняется хуком `useSWR` в `src/app/[uuid]/components/modal.tsx` через нативный `fetch`. Базовый хост API выбирается в рантайме по `window.location.hostname`, итоговый URL = `https://<apiBaseUrl>` + путь эндпоинта. Скачивание файлов выполняется переходом браузера по ссылкам, которые возвращает сам API (`download_link`, `download_mrpas_link`).

Авторизация: заголовок `Authorization: Bearer <jwt>` (сейчас — зашитая константа `fixedToken`; целевое — `NEXT_PUBLIC_API_TOKEN` из секрета `documentations-publiclink-jwt-secret`). Запрос идёт с `credentials: "include"`.

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

Значения из `switch` по `window.location.hostname` в `modal.tsx`:

| Hostname фронтенда | `apiBaseUrl` (базовый хост API) |
| --- | --- |
| `localhost` | `https://stage-api.sarex.io` |
| `document-link.stage.sarex.io` | `https://stage-api.sarex.io` |
| `document-link.sarex.io` | `https://api.sarex.io` |
| прочее | не определён (fallback `https://stage-api.sarex.io`) |

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

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

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| Публичная ссылка | GET | `/documentations/api/v1/public/documents/public_link/{uuid}` | Метаданные документа по публичной ссылке (`uuid`) |

Пример итогового URL: `https://stage-api.sarex.io/documentations/api/v1/public/documents/public_link/e602b98d-58a1-4ba3-8a89-84e5617b5aac`.

Ожидаемые поля ответа (используются во фронтенде):

| Поле ответа | Тип | Использование |
| --- | --- | --- |
| `name` | string | Название документа |
| `document_type` | string | Тип (иконка): `bim`/`bimv2`/`cloud`/`surface`/`workspace`/`pdf`/`deviation`/`c2s`/`c2c`/`abap`/`ksg`/`docx`/`xlsx`/`dxf`/`dwg`/… |
| `author` | string | Автор |
| `version` | string | Версия документа (скрывается для `workspace`/`folder`/`project`) |
| `size` | number | Размер в байтах (форматируется библиотекой `bytes`) |
| `download_token` | string | Токен скачивания |
| `download_link` | string (URL) | Прямая ссылка на скачивание файла |
| `download_mrpas_link` | string (URL) \| null | Ссылка на скачивание МЧД (опционально) |
| `expires_at` | string (datetime) \| null | Срок действия ссылки; `null` → «Неограничено» |
| `is_connector` | bool | Признак «файл > 5 Гб, требуется Sarex-коннектор» |

### Скачивание файлов (динамические ссылки)

Не отдельные эндпоинты реестра, а переход браузера по URL из ответа:

| Действие | Источник URL |
| --- | --- |
| Скачать файл/папку | `download_link` из ответа `public_link` |
| Скачать МЧД | `download_mrpas_link` из ответа `public_link` (если не `null`) |

При `is_connector = true` вместо прямого скачивания показывается предупреждение со ссылкой на [Sarex-коннектор](https://support.sarex.io/knowledge_base/item/347946).

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

Статус ответа маппится в человекочитаемое сообщение (`modal.tsx`):

| Статус | Сообщение |
| --- | --- |
| `400`, `404` | «Ссылка не найдена» |
| `410` | «Время действия вашей ссылки истекло» |
| `500`, `503` | «Что-то пошло не так» |