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

Документ описывает HTTP-эндпоинты внешних сервисов, к которым обращается Go-сервис **documentation-api-v2** (`pdm/documentation-api-v2`).

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

Внешние вызовы выполняются типизированными клиентами в `pkg/clients/*` и `pkg/django`. Каждый клиент строится на [`github.com/go-resty/resty/v2`](https://github.com/go-resty/resty) с `SetBaseURL(<URL>)`, ретраями и (опционально) OTEL-трассировкой. Базовый URL берётся из переменной окружения (см. `api-v2.CONFIGURATION.md`); итоговый URL = `<базовый URL>` + путь, указанный в коде метода клиента.

Клиенты создаются в `internal/api/httpserver/server.go` (`App.Run`) и передаются в репозитории/юзкейсы. Аутентификация к внешним сервисам:

- **Django** и **flows** используют Basic-auth из `DJANGO_BASIC_AUTH`;
- **workspace** (`Archive`) пробрасывает пользовательский Bearer-токен (`SetAuthToken`);
- прочие внутренние сервисы вызываются по кластерным адресам без явной авторизации на уровне клиента.

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

| Клиент (`pkg/...`) | Переменная базового URL | Назначение |
| --- | --- | --- |
| `django` | `DJANGO_HOST` | Монолит/IAM: пользователи, компании, сервис-аккаунты, настройки |
| `clients/workspace` | `WORKSPACE_URL` | Сервис рабочих областей |
| `clients/workflows` | `WORKFLOW_URL` | Запуск workflow-обработки |
| `clients/bimv1` | `BIM_API_URL` | BIM API v1 |
| `clients/bimv2` | `BIM_API_V2_URL` | BIM API v2 (bim-core) |
| `clients/flows` | `FLOWS_URL` | Сервис flows (процессы) |
| `clients/marks` | `MARKS_PROCESSING_URL` | Сервис PDF-маркировок |
| `clients/system_log` | `SYSTEM_LOG_URL` | Сервис журналирования |

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

### `django` — монолит/IAM (`pkg/django`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| GET | `api/client/settings/` | Клиентские настройки |
| GET | `/api/core/companies/` | Список компаний |
| GET | `/api/core/users/` | Список пользователей |
| GET | `api/core/users/{user_id}/introspect` | Интроспекция пользователя |
| GET | `/api/core/service_accounts/` | Сервис-аккаунты |
| GET | `/api/core/service-accounts/personalized/` | Персонализированные сервис-аккаунты |

### `workspace` — рабочие области (`pkg/clients/workspace`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `internal/v2/workspaces` | Создать рабочую область |
| DELETE | `internal/v2/documents/{document_ids}` | Удалить документы из рабочих областей; возвращает id опустевших областей |
| POST | `api/v1/workspaces/{workspace_id}/archive` | Архивировать рабочую область (с пользовательским Bearer-токеном) |

### `workflows` — workflow-обработка (`pkg/clients/workflows`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `internal/v1/companies/{company_id}/workflows` | Создать/запустить workflow для компании |

### `bimv1` — BIM API v1 (`pkg/clients/bimv1`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `/internal/v1/targets/{target_id}/bims-pdm` | Зарегистрировать новый BIM (v1) |
| POST | `/internal/v1/targets/{target_id}/bims-v2-pdm` | Зарегистрировать новый BIM (v2) |

### `bimv2` — BIM API v2 (`pkg/clients/bimv2`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `/internal/v1/projects/{project_id}/bims` | Создать BIM в проекте |

### `flows` — процессы (`pkg/clients/flows`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| GET | `api/v1/documents/?full=true&document_ids={id}` | Документы процессов по id |

### `marks` — PDF-маркировки (`pkg/clients/marks`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `/api/v1/marks/{bundle_id}` | Массовое создание маркировок для бандла |

### `system_log` — журналирование (`pkg/clients/system_log`)

| Метод | Путь | Назначение |
| --- | --- | --- |
| POST | `/api/v0/system_log` | Отправка пакета записей журнала |

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

Клиенты проверяют HTTP-статус ответа и при коде, отличном от ожидаемого (обычно `200`), оборачивают ошибку через `github.com/rotisserie/eris` с указанием имени метода клиента (напр. `bimapi.addNewBim: invalid response code %d expected 200`). Транспортные ошибки resty также оборачиваются `eris.Wrap`. Настроены ретраи (напр. клиент workspace — 5 попыток с паузой 1 c, таймаут 10 c).