# Эндпоинты внешних сервисов, с которыми взаимодействует documentations-api

Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается сервис документаций (оба бинарника — `cmd/api` и `cmd/filestreamer`). В отличие от фронтенда, единого декларативного реестра эндпоинтов здесь нет — каждый внешний сервис инкапсулирован в собственном клиенте в каталогах `clients/` и `pkg/`.

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

Клиенты создаются при старте (`cmd/api/routes_api.go`, `cmd/filestreamer/*`) и используют базовый URL из соответствующей переменной окружения (см. `config/config.go`). Большинство клиентов построены на `go-resty/resty` (метод `SetHostURL`/`SetBaseURL`), часть — на внутренних http-обёртках `gitlab.sarex.io/platform/gotools`. Итоговый URL = `<базовый URL сервиса>` + путь из клиента.

Аутентификация исходящих запросов:

- к Sarex backend (Django) — HTTP Basic (`DJANGO_BASIC_AUTH`, а для получения пользователей — `DJANGO_BASIC_AUTH_FOR_GET_USER`); для части ручек проксируется заголовок `Identity`/`Bearer`;
- к остальным сервисам — по внутренней сети кластера, как правило без внешней авторизации.

## Базовые URL по сервисам

| Сервис | Переменная окружения | Клиент (каталог) |
| --- | --- | --- |
| Sarex backend (Django) | `DJANGO_HOST` | `clients/django`, `pkg/django`, `pkg/users`, `pkg/sarex_backend`, `clients/accounts` |
| Flows | `FLOWS_URL` | `pkg/flows` |
| Workflows | `WORKFLOW_URL` | `clients/workflow`, `pkg/workflows` |
| Workspaces | `WORKSPACE_URL` | `clients/workspace` |
| Transmittals | `TRANSMITTALS_BASE_URL` (опц.) | `pkg/transmittal` |
| Automation | `AUTOMATION_URL` | `pkg/automation` |
| Marks (штампы, HTTP) | `MARKS_PROCESSING_URL` | `pkg/marks/base` |
| Marks (штампы, RabbitMQ) | `MARKS_RABBITMQ_*` | `pkg/marks/rpc` |
| BIM-API v1 | `BIM_API_URL` | `clients/bim-api` |
| BIM-API v2 (bim-core-api) | `BIM_API_V2_URL` | `clients/bim-api-v2` |
| System log | `SYSTEM_LOG_URL` | `pkg/system_log` |

Дополнительно сервис работает с S3 (объектное хранилище, креды из `S3_SERVICE_ACCOUNT`/`S3_SERVICE_ACCOUNT_STR`) и PostgreSQL — это не HTTP-сервисы и в таблицах ниже не приводятся.

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

### Sarex backend (Django) — `DJANGO_HOST`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| GET | `/api/core/users/` | `clients/django/users.go` | Список пользователей |
| GET | `/api/core/users/{id}/` | `clients/django/users.go`, `pkg/users/client.go` | Пользователь по id |
| GET | `/api/core/users/{id}/introspect` | `clients/django/users.go` | Интроспекция пользователя |
| GET | `/api/core/users/{id}` | `pkg/django/client.go` | Пользователь по id (внутренний клиент) |
| GET | `/api/client/settings/` | `clients/django/settings.go` | Клиентские настройки |
| GET | `/api/core/service-accounts/personalized/` | `clients/django/settings.go` | Персонализированные сервисные аккаунты |
| GET | `/api/core/service_accounts/` | `clients/django/service_accounts.go`, `clients/accounts` | Сервисные аккаунты |
| GET | `/api/core/companies/` | `clients/django/companies.go` | Список компаний |
| GET | `/api/core/mrpa/{id}/` | `pkg/sarex_backend/client.go` | MRPA по id (прокидывается заголовок `Identity`) |

### Flows — `FLOWS_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| GET | `internal/v1/documents/?full=true&document_ids={id}` | `pkg/flows/client.go` | Документы в процессах (flows) по id |
| GET/POST | `internal/v1/documents/` | `pkg/flows/client.go` | Документы процессов |

### Workflows — `WORKFLOW_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `internal/v1/companies/{company_id}/workflows` | `clients/workflow/client.go` | Создать workflow обработки (BIM/PDF/DWG/DEM/DOCX и т. д.); образы задач — из `CONTAINER_REGISTRY` + `WORKFLOWS_IMAGES_VERSION` |
| GET | `v1/workflows/{id}` | `pkg/workflows/client.go` | Прочитать workflow по id |

### Workspaces — `WORKSPACE_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `internal/v2/workspaces` | `clients/workspace/client.go` | Создать воркспейс |
| DELETE | `internal/v2/documents/{ids}` | `clients/workspace/client.go` | Удалить документы воркспейса |
| PATCH | `internal/v2/documents/restore` | `clients/workspace/client.go` | Восстановить документы воркспейса |

### Transmittals — `TRANSMITTALS_BASE_URL`

Клиент создаётся только если переменная задана.

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `/internal/v1/transmittals/by_bundle_ids` | `pkg/transmittal/client.go` | Трансмитталы по списку bundle-id |

### Automation — `AUTOMATION_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| — | `/internal/v1/automations/{process_name}` | `pkg/automation/client.go` | Запуск/получение автоматизации по имени процесса |

### Marks (штампы/маркировки)

Режим выбирается флагом `USE_MARKS_RABBITMQ`.

| Метод | Путь / транспорт | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `/api/v1/marks/{bundle_id}` (HTTP, `MARKS_PROCESSING_URL`) | `pkg/marks/base/client.go` | Наложение штампов на бандл (HTTP-режим) |
| — | RabbitMQ (`MARKS_RABBITMQ_*`) | `pkg/marks/rpc` | Наложение штампов через очередь (RPC-режим, не HTTP) |

### BIM-API v1 — `BIM_API_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `/internal/v1/targets/{target_id}/bims-pdm` | `clients/bim-api/client.go` | Создать BIM для target (PDM) |
| POST | `/internal/v1/targets/{target_id}/bims-v2-pdm` | `clients/bim-api/client.go` | Создать BIM v2 для target (PDM) |

### BIM-API v2 (bim-core-api) — `BIM_API_V2_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `/internal/v1/projects/{project_id}/bims` | `clients/bim-api-v2/client.go` | Создать BIM для проекта |

### System log — `SYSTEM_LOG_URL`

| Метод | Путь | Клиент | Назначение |
| --- | --- | --- | --- |
| POST | `/api/v0/system_log` | `pkg/system_log/client.go` | Отправить запись в системный лог |

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

Клиенты, как правило, проверяют код ответа и оборачивают ошибку через `github.com/rotisserie/eris` (напр. «invalid response code %d expected 200»). Для случая недоступности исходного сервиса в самом API определён нестандартный статус `523` (`network/consts.go`, `StatusOriginIsUnreachable`).