Справочник API¶

Вся HTTP-поверхность бэкенда в одном месте. Бизнес-эндпоинты имеют префикс /api/v1/*; OIDC-провайдер и инфраструктурные эндпоинты живут в корне.

Браузер не обращается к ним напрямую

Frontend построен по модели BFF: браузер общается только с same-origin-маршрутами /api/* в Next.js, а те проксируют запросы на бэкенд на стороне сервера. Токены никогда не попадают в клиентский JS. Ниже приведены пути бэкенда.

Swagger: GET /swagger/doc.json (в production требуется bearer-токен).

Инфраструктура¶

Метод	Путь	Доступ
`GET`	`/health`	открыто
`GET`	`/ready`	открыто
`GET`	`/metrics`	в production — `OBSERVABILITY_TOKEN` (иначе 404)
`GET`	`/swagger/doc.json`	так же

OIDC-провайдер¶

Включается при заданных OAUTH_ISSUER + SSO_STATE_KEY. Пути закреплены спецификацией OIDC.

Метод	Путь
`GET`	`/.well-known/openid-configuration`
`GET`	`/.well-known/jwks.json`
`GET`	`/oauth2/auth`
`POST`	`/oauth2/token`
`POST`	`/oauth2/introspect`
`POST`	`/oauth2/revoke`
`GET`	`/oauth2/sessions/logout`
`GET` `POST`	`/userinfo`

Внутренний API login/consent: /api/v1/provider/login · /consent · /login/accept · /login/reject · /consent/accept · /consent/reject · /logout/accept.

Аутентификация — `/api/v1/auth`¶

Метод	Путь	Лимит
`POST`	`/eid/start`	auth (5/мин)
`POST`	`/eid/start-id`	auth
`POST`	`/eid/poll`	poll (1/сек, burst 30)
`POST`	`/google`	auth
`DELETE`	`/google/link`	вход выполнен
`POST`	`/refresh` · `/logout`	auth
`POST`	`/initiate`	auth (мобильные)
`GET`	`/status/{sid}`	poll (мобильные)

Суперадмин: /api/v1/auth/superadmin/mfa · /onboard/{google,eid/start,eid/start-id,eid/poll,email/send,email/verify,totp/init,totp/verify}.

Gerege SSO (сторона RP): /api/v1/sso/start · /callback · /native · /logout.

Пользователи и организации¶

Метод	Путь	Что
`GET`	`/api/v1/users/me`	Свой профиль
`GET`	`/api/v1/users/me/eid/summary` · `/certificates` · `/devices` · `/activity`	PKI-профиль eID
`GET` `POST` `DELETE`	`/api/v1/users/me/eid/organizations…`	Связанные организации
`GET` `POST` `DELETE`	`/api/v1/users/me/eid/organizations/{regNo}/signers…`	Уполномоченные подписанты
`POST` `GET`	`/api/v1/org`	Создание / мои организации
`GET`	`/api/v1/org/lookup/{regNo}`	Поиск в государственном реестре
`GET` `POST` `PUT` `DELETE`	`/api/v1/org/{id}/members…`	Участники и роли
`GET`	`/api/v1/core/users` · `/organizations`	Поиск для админа (`users.manage`)

Прокси сервисов eID¶

Метод	Путь	Грант
`GET`	`/api/v1/eid/summary` · `/certificates` · `/devices` · `/activity`	`svc:eid-proxy`
`GET`	`/api/v1/eid-org/organizations` · `/organizations/{regNo}/signers`	`svc:eid-org-proxy`
`*`	`/rp/sign/*`	`svc:eid-sign`

Услуги для граждан — `/api/v1/gov`¶

Полностью перечислены на странице Услуги для граждан. Публичный каталог: /api/v1/catalog/services · /services/{id} · /life-events.

Реестр и Relay¶

Полностью перечислены на странице Реестр и Relay (/api/v1/registry/*, /api/v1/relay/*).

Шлюз и реестр приложений¶

Метод	Путь	Право
`GET`	`/api/v1/gateway/overview` · `/logs`	`gateway.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/gateway/services…`	`gateway.manage`
`GET` `POST`	`/api/v1/applications`	`gateway.manage`
`GET` `PUT` `DELETE`	`/api/v1/applications/{id}`	`gateway.manage`
`POST`	`/api/v1/applications/{id}/rotate-secret`	`gateway.manage`
`PUT`	`/api/v1/applications/{id}/secret` · `/services`	`gateway.manage`

Подпись, активы, файлы¶

Метод	Путь
`POST`	`/api/v1/sign/initiate` · `/init`
`GET`	`/api/v1/sign/status/{sid}` · `/{id}` · `/{id}/download`
`GET` `PUT` `DELETE`	`/api/v1/me/signature`
`PUT`	`/api/v1/me/latin-name` · `/org-name-latin/{regNo}`
`GET` `PUT` `DELETE`	`/api/v1/me/orgstamp/{regNo}`
`GET` `POST` `DELETE`	`/api/v1/gspace` · `/upload` · `/download`
`GET` `POST` `DELETE`	`/api/v1/integrations…`

Подробнее: Документы, подпись, файлы.

AI¶

Метод	Путь	Лимит
`POST`	`/api/v1/ai/chat` · `/stt` · `/tts` · `/translate`	20/мин, burst 10
`POST`	`/api/v1/public/ai/chat` · `/chat/stream`	6/мин, burst 3
`POST`	`/api/v1/public/ai/tts`	20/мин, burst 8

Подробнее: AI-конвейер.

Админ, RBAC, аудит¶

Метод	Путь	Право
`GET`	`/api/v1/rbac/me`	вход выполнен
`GET` `POST` `PUT` `DELETE`	`/api/v1/rbac/roles…` · `/permissions`	`roles.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/admin/users…`	`users.manage`
`GET` `PUT`	`/api/v1/admin/ai/prompts…`	`settings.manage`
`POST`	`/api/v1/admin/ai/knowledge/reindex`	`settings.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/superadmin/…`	superadmin
`GET`	`/api/v1/audit` · `/audit/verify`	admin
`POST`	`/api/v1/security/events`	вход выполнен
`GET`	`/api/v1/security/events`	admin
`GET` `PUT`	`/api/v1/site/appearance`	открыто / `settings.manage`
`GET` `POST` `PUT` `DELETE`	`/api/v1/themes…`	открыто (`/active`) / admin

Подробнее: Админ, RBAC, аудит.

Модель ошибок¶

Обработчики имеют вид func(w, r) error и оборачиваются в v1.Wrap. Слой usecase возвращает apperror.*, который в одном месте отображается в HTTP-статус. Внутренние причины оборачиваются apperror.InternalCause, поэтому ошибки библиотек никогда не утекают клиенту.