iac/apps/transmittal/ENDPOINTS.md

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