# КриптоАРМ Документы API

> Корпоративный сервис хранения, обмена и подписания электронных документов.
> Управление папками, версиями, доступом, электронной подписью и шифрованием через REST API.

**Текущая версия API: v1.** Все эндпоинты доступны по **`/api/v1/*`** (рекомендуется для агентов)
и **`/api/*`** (совместимость с SPA). Пути `/api/v1/...` — алиасы к `/api/...`. Авторизация: `X-API-KEY`,
`Authorization: Bearer <JWT>` (OIDC или внутренний токен) или cookie-сессия после `GET /api/login`.
Интерактивная документация — `/api` (Swagger UI).

## API
- [OpenAPI spec (JSON)](/openapi.json): машиночитаемый контракт всех эндпоинтов
- [OpenAPI well-known](/.well-known/openapi.json): тот же контракт для discovery
- [Интерактивная документация (Swagger UI)](/api): Try it out с Bearer / API Key / OIDC
- [Health](/api/health) / [Readiness](/api/ready) / [Version](/api/version) — также `/api/v1/health`, `/api/v1/ready`, `/api/v1/version`

## Auth
- OIDC-провайдер: `https://id.kloud.one`
- **API Key**: заголовок `X-API-KEY` (глобальный или привязанный к документу)
- **Bearer JWT**: OIDC ID Token от `https://id.kloud.one` или внутренний JWT
- **Сессия (OIDC)**: `GET /api/v1/login` (или `/api/login`) — редирект на IdP `https://id.kloud.one`, cookie после callback
- `POST /api/login` недоступен при `OAUTH2_ENABLED=true` (503)

## Основные сценарии
1. **Документы**: `GET/POST /api/v1/documents`, загрузка `POST /api/v1/documents/upload`
2. **Подпись**: `POST /api/v1/signatures`, проверка `POST /api/v1/documents/:id/verify`
3. **КриптоАРМ (десктоп)**: `POST /api/v1/operations/start` → poll `GET /api/v1/operations/result?operationId=`
4. **События (аудит)**: `GET /api/v1/events`
5. **Пользователи**: `GET/POST /api/v1/users` (админ)

## Conventions
- **Пагинация (списки)**: query `range=[from,to]`, `sort`, `filter` (react-admin); в ответе заголовки `X-Total-Count`, `Content-Range`
- **Идемпотентность**: мутирующие `POST` принимают заголовок `Idempotency-Key`; повтор с тем же ключом и телом возвращает исходный ответ (`Idempotency-Replayed: true`)
- **Ошибки**: JSON `{ "error": { "code", "message", "field?", "hint?", "details?" } }`; корректные HTTP-статусы (не 200 при ошибке)
- **Трассировка**: каждый ответ содержит `X-Request-Id` (можно передать входящий)
- **Rate limit**: при `429` смотрите `Retry-After`, `RateLimit-Limit`, `RateLimit-Remaining`
- **Доступ**: данные владельца; чужие ресурсы → `403` / `404`

## MCP
- [MCP-LINK](https://mcp-link.kloud.one) — OpenAPI → MCP
- [MCP SSE](https://mcp-link.kloud.one/sse?s=https%3A%2F%2Fkloud-sign-api%3A3000%2Fopenapi.json&u=https%3A%2F%2Fkloud-sign-api%3A3000&f=%2B%2F**)