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

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

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

Все запросы описаны декларативно в реестре `module/api/endpoints.ts` (объект `endpoints`). Каждый эндпоинт задаётся структурой `Endpoint`:

- `service` — логическое имя сервиса (см. таблицу хостов ниже);
- `method` — HTTP-метод (`GET`/`POST`/`PUT`/`PATCH`/`DELETE`);
- `path(args)` — функция, возвращающая путь запроса (с подстановкой параметров/query);
- `body(args)` — опционально, формирование тела запроса;
- `cache`, `queryOptions`, `responseType`, `axiosConfig` — опции кеширования, повторов и типа ответа.

Запрос выполняется единой функцией `fetch(endpoint, params, controller)`, которая через `httpService` (`module/api/http-service.ts`, поверх `@sarex-team/sdk-js` + `axios`) отправляет запрос на базовый хост сервиса. Базовый хост подставляется `resolveHost(service)` из `module/api/hosts.ts` в зависимости от `BUILD_ENV`. Ошибки маппируются в человекочитаемые сообщения в `module/api/errors.ts`.

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

Значения из `module/api/hosts.ts`. Итоговый URL = `<базовый хост сервиса>` + `path` эндпоинта.

| Сервис (`service`) | Назначение | `stage` | `prod` |
| --- | --- | --- | --- |
| `transmittals` | Сервис передачи документации (трансмитталы, шаблоны) | `https://stage-api.sarex.io/transmittals` | `https://api.sarex.io/transmittals` |
| `documentations` | Сервис документации (документы, бандлы, файлы) | `https://stage-api.sarex.io/documentations` | `https://api.sarex.io/documentations` |
| `sarexApi` | Gateway/API Sarex (`/gateway`, `/eav`, `/cde`) | `https://stage-api.sarex.io` | `https://api.sarex.io` |
| `sarex` | Локальный сервис данных (`/api/core`, `/api/client`) | `""` (относительные пути) | `""` |
| `processes` | Сервис рабочих процессов (flows, reviews) | `https://stage-api.sarex.io/flows` | `https://api.sarex.io/flows` |
| `workflows` | Сервис обработки документов | `https://stage-api.sarex.io/workflows` | `https://api.sarex.io/workflows` |
| `workspaces` | Сервис рабочих областей | `https://stage-api.sarex.io/workspaces` | `https://api.sarex.io/workspaces` |
| `remarks` | Сервис замечаний | `https://stage-api.sarex.io/remarks` | `https://api.sarex.io/remarks` |
| `files` | Сервис файлов | `https://stage-api.sarex.io/files` | `https://api.sarex.io/files` |
| `google` | Временное хранилище (GCS) | `https://storage.googleapis.com/srx-tmp` | `https://storage.googleapis.com/srx-tmp` |
| `bim` | BIM-API | `https://stage-bim-api.sarex.io` | `https://bim-api.sarex.io` |
| `zitadel` | IdP (аутентификация) | `https://idp.dev.stage.sarex.io` | `https://login.sarex.io` |

> Также определены окружения `local`, `preprod` и `contour` (относительные пути для изолированного контура). В `local` сервис `sarex` проксируется на `/sarex-backend`. Подключаемый удалённый модуль documentations описан отдельно в `module/api/module-hosts.ts`.

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

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

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getTransmittals` | POST | `api/v1/transmittals` | Список трансмитталов (пагинация по `bookmark`, фильтр по `resource_id`) |
| `getTransmittalStatuses` | POST | `api/v1/transmittals/global_statuses` | Глобальные статусы по набору `resource_ids` |
| `getTransmittalById` | GET | `api/v1/transmittals/{transmittalId}` | Трансмиттал по id |
| `getAct` | GET | `api/v1/transmittals/{transmittalId}/act_available` | Доступность акта для трансмиттала |
| `downloadAct` | GET | `api/v1/transmittals/{transmittalId}/download_act` | Скачивание акта |
| `createTransmittal` | POST | `api/v1/transmittals/create` | Создание трансмиттала |
| `approveTransmittal` | PUT | `api/v1/transmittals/{transmittalId}/approve` | Принять трансмиттал (с комментарием) |
| `declineTransmittal` | PUT | `api/v1/transmittals/{transmittalId}/decline` | Отклонить трансмиттал (с комментарием) |
| `deleteTransmittal` | DELETE | `api/v1/transmittals/{transmittalId}` | Удалить трансмиттал |
| `linkReviewToTransmittal` | POST | `api/v1/transmittals/{transmittalId}/link_review` | Привязать review к трансмитталу |
| `getStatusTypes` | GET | `api/v1/transmittals/status` | Справочник типов статусов |
| `getSearchProject` | POST | `api/v1/transmittals/search` | Поиск/фильтрация трансмитталов в проекте |
| `getSearchProjects` | POST | `api/v1/transmittals/search/resources` | Поиск/фильтрация по нескольким ресурсам |
| `getSteps` | GET | `api/v1/steps` | Список шагов |
| `getStep` | GET | `api/v1/steps/{id}` | Шаг по id |
| `getSearchTemplates` | POST | `/api/v1/transmittal_templates` | Поиск шаблонов трансмитталов |
| `createTemplate` | POST | `/api/v1/transmittal_templates/create` | Создать шаблон |
| `updateTemplate` | PATCH | `/api/v1/transmittal_templates/{templateId}` | Обновить шаблон |
| `deleteTemplate` | DELETE | `/api/v1/transmittal_templates/{templateId}` | Удалить шаблон |
| `getTemplateListForSelect` | GET | `/api/v1/transmittal_templates/select?resource={resourceId}` | Список шаблонов для выбора |
| `getSingleTemplate` | GET | `/api/v1/transmittal_templates/{templateId}?resource={resourceId}` | Шаблон по id |

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

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getDisks` | GET | `api/v1/disks` | Список дисков |
| `getAllPermmission` | GET | `api/v1/permissions` | Все права доступа |
| `getDocPermission` | GET | `api/v1/documents/{id}/permissions` | Права доступа документа |
| `postPermission` | POST | `api/v1/documents/{id}/permissions` | Выдать права сервисному аккаунту |
| `postBundle` | POST | `api/v1/bundles` | Создать бандл |
| `postFile` | POST | `api/v1/bundles/{bundleId}/{fileKey}?single_upload=1` | Загрузить файл (single upload) |
| `uploadFolderStart` | POST | `api/v1/bundles/{bundleId}/{key}/upload_multipart?upload_path={folderPath}` | Начать multipart-загрузку |
| `uploadPart` | PUT | `api/v1/bundles/{bundleId}/{bundleKey}?part_number={partNumber}` | Загрузить часть файла |
| `bundleComplite` | POST | `api/v1/bundles/{bundleId}/upload_finish` | Завершить загрузку бандла |
| `getFile` | GET | `api/v1/bundles/{bundleId}/{bundleKey}` | Получить файл бандла |
| `getBundles` | GET | `api/v1/documents/{id}/bundles` | Бандлы документа |
| `addBundle` | POST | `api/v1/documents/{documentId}/add_bundle` | Привязать бандл к документу |
| `moveBundles` | PATCH | `api/v1/documents/{documentId}/move_bundles` | Переместить бандлы |
| `removeBundle` | DELETE | `api/v1/bundles/{id}` | Удалить бандл |
| `postWorkspace` | POST | `api/v1/workspaces` | Создать рабочую область |
| `getDocumentById` | GET | `api/v1/documents/{id}` | Документ по id |
| `getDocumentWithBundles` | GET | `api/v1/documents/{id}?extend=bundles` | Документ с бандлами |
| `fetchBatchDocuments` | POST | `/api/v1/documents/batch` | Пакетное получение документов |
| `changeDocument` | PATCH | `api/v1/documents/{id}` | Переименовать документ |
| `updatePath` | PATCH | `api/v1/documents/{id}/update-path` | Сменить родителя документа |
| `updateDocumentsPaths` | PATCH | `api/v1/documents/update-path` | Массовая смена родителя |
| `deleteDocument` | DELETE | `api/v1/documents/{id}` | Удалить документ |
| `deleteDocuments` | DELETE | `api/v1/documents?document_ids={ids}` | Удалить несколько документов |
| `downloadFile` | GET | `api/v1/bundles/{lastBundleId}/{key}/download` | Скачать файл |
| `downloadAllFiles` | GET | `api/v1/bundles/{lastBundleId}/download` | Скачать все файлы бандла |
| `downloadFolder` | GET | `api/v1/documents/{docId}/download?depth={depth}` | Скачать папку |
| `getFolderChildrenWithActiveProcesses` | POST | `/api/v1/documents/flows` | Дети папки с активными процессами |
| `conversionFile` | POST | `api/v1/conversion` | Конвертация документа (в IFC) |
| `addMarks` | PUT | `api/v1/bundles/{bundleId}/marks` | Добавить штампы/QR/подписи |
| `sign` | POST | `api/v1/bundles/{bundleId}/sign` | Подписать бандл |
| `cancelQrCode` | PATCH | `api/v1/bundles/{bundleId}/cancel_qr` | Отменить QR-код |
| `restartWorkflow` | POST | `api/v1/bundles/{bundleId}/restart` | Перезапустить workflow бандла |
| `getPublicLink` | GET | `api/v1/public/documents/public_link/{public_link_id}` | Получить публичную ссылку |
| `deletePublicLink` | DELETE | `api/v1/documents/public_link/{public_link_id}` | Удалить публичную ссылку |
| `removeDoc` | DELETE | `api/v1/documents/bin?parent_id={id}` | Переместить в корзину |
| `recoveryDocument` | PATCH | `api/v1/documents/bin/restore?parent_id={id}` | Восстановить из корзины |
| `copyFolderStructure` | POST | `api/v1/documents/copy_structure` | Копировать структуру папок |

### `sarexApi` — Gateway/API Sarex

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getUsersWithTransmittalProjectPermissions` | GET | `/gateway/api/v2/users/?...&resource_id={projectId}&permissions=...` | Пользователи с правами в проекте |
| `getDocuments` | GET | `/gateway/api/v1/disks/{id}/documents?...` | Документы диска (с фильтрами/поиском) |
| `filterByAttributes` | GET | `/gateway/api/v1/disks/{diskId}/documents?parent_id={rootDocumentId}&{params}` | Фильтрация документов по атрибутам |
| `getResources` | GET | `/gateway/api/v1/resources` | Список ресурсов |
| `createDocument` | POST | `/gateway/api/v1/documents` | Создать документ/папку/проект |
| `fetchDocumentAncestors` | POST | `/gateway/api/v1/documents/ancestors` | Предки документов |
| `fetchDocumentsBundleVersions` | POST | `/gateway/api/v1/documents/bundle_versions` | Версии бандлов документов |
| `getAttributesByDocumet` | GET | `/gateway/api/v1/documents/{id}/attributes` | Атрибуты документа |
| `updateAttributes` | PUT | `/gateway/api/v1/documents/{id}/attributes` | Обновить атрибуты документа |
| `addAttributes` | POST | `/gateway/eav/api/v0/entity/` | Создать сущность атрибутов (EAV) |
| `getDefaultAttributes` | GET | `/eav/api/v0/schema/?model=document&company_id=...&type_identifier=...` | Схема атрибутов по типу |
| `getAttributes` | GET | `/eav/api/v0/attribute/?company_id={params}` | Атрибуты компании |
| `getAttributesWithParams` | GET | `/eav/api/v0/schema/?model=document&{params}` | Схема атрибутов с параметрами |
| `updateSubscription` | POST | `/gateway/api/v1/subscription/` | Создать/обновить подписку |
| `deleteSubscription` | DELETE | `/gateway/api/v1/documents/{documentId}/subscription/` | Удалить подписку |
| `getActivityLog` | GET | `/gateway/api/v1/system_log/?...` | Журнал активности документа |
| `fetchDocumentByResourceId` | GET | `/gateway/api/v1/resources-rpc/parent-document-by-resource-id/{resourceId}/` | Родительский документ по resource id |
| `getRemovedDocuments` | GET | `/gateway/api/v1/documents/bin?parent_id={id}{params}` | Удалённые документы в папке |
| `getRemovedFilteredDocuments` | GET | `/gateway/api/v1/documents/bin{params}` | Удалённые документы (фильтр) |
| `getBindings` | GET | `/cde/app/v1/bundles/{bundleId}/bindings` | Привязки бандла |
| `completeUpload` | POST | `{uploadUrl}/complete` | Завершение загрузки (по переданному URL) |

### `sarex` — Локальный сервис данных

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getSettings` | GET | `/api/client/settings/` | Клиентские настройки (кешируется) |
| `getUser` | GET | `/api/core/users/{userId}/` | Пользователь по id |
| `getUsersByCompanyIds` | GET | `/api/core/users/?company={ids}&limit=&offset=&show_inactive=true` | Пользователи компаний |
| `getTargets` | GET | `/api/core/targets/` | Список таргетов |
| `getCompanies` | GET | `/api/core/companies/` | Список компаний |
| `getDepartmentById` | GET | `/api/core/admin/departments?company={companyId}` | Отделы компании |
| `getUsersPositionById` | GET | `/api/core/admin/positions/?company={companyId}` | Должности компании |
| `getByFullUrl` | GET | `{url}` | Запрос по произвольному URL |

### `processes` — Сервис рабочих процессов (flows)

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getProcesses` | GET | `api/v1/flows/?{query}` | Список процессов (flows) |
| `createReview` | POST | `api/v1/reviews/` | Создать review |
| `deleteReview` | DELETE | `api/v1/reviews/{id}/` | Удалить review |
| `activateReview` | PATCH | `api/v1/reviews/{id}/approve/` | Активировать/утвердить review |
| `createReviewDocuments` | POST | `api/v1/documents/` | Добавить документы в review |

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

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getWorkflow` | GET | `api/v1/workflows/{workflowId}` | Workflow по id |
| `getWorkflows` | POST | `api/v1/workflows/batch` | Пакетное получение workflow |

### `workspaces` — Сервис рабочих областей

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getWorkspaces` | GET | `api/v1/workspaces/{uuid}` | Рабочая область по uuid |

### `remarks` — Сервис замечаний

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `getRemarksTotalCount` | GET | `api/v1/total_count` | Общее число замечаний |

### `files` — Сервис файлов

| Ключ | Метод | Путь | Назначение |
| --- | --- | --- | --- |
| `downloadFiles` | GET | `/api/v1/documents/{documentIds}` | Скачать документы по id |
| `downloadFileBundles` | POST | `/api/v1/documents/` | Скачать бандлы (ответ `blob`) |

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

Коды ответов маппируются в сообщения (`module/api/errors.ts`): `400` — некорректный запрос, `404` — ресурс не найден, `500` (и прочие) — ошибка сервера. Для каждого сервиса задано человекочитаемое имя (напр. `transmittals` → «Сервис передачи документации»), которое подставляется в текст ошибки. По умолчанию у запросов включён показ уведомления об ошибке (`showErrorNotification: true`).