# Интеграция по API — обзор

Этот раздел описывает как backend-сервисы (Альтум, геопортал, BI и т.д.)
читают и пишут справочники Ordinis НСИ ЦУОД.

**Owner:** Ordinis team — `zimin.an@nstart.space`.

## С чего начать

1. [Получи Keycloak service account](auth.md) — нужен для всех API вызовов.
2. [Прочитай read-side endpoints](read-endpoints.md) — как получить данные.
3. [Выбери стратегию обновления](caching.md) — TTL, webhooks, либо Kafka events.

## Что Ordinis даёт

- **Bitemporal CRUD** для справочников — `validFrom` / `validTo` + revision
  history через Hibernate Envers.
- **Multi-locale** — каждое поле может иметь `{ru-RU, en-US, ...}` варианты.
  Flatten через `?lang=` параметр.
- **Cross-dictionary FK** через `x-references` schema extension. Server-side
  валидация на CRUD + orphan scanner periodic.
- **Geometry support** — PostGIS для bbox/polygon фильтров (`spacecraft.aoi`,
  `mission.coverage_area`).
- **Audit log** — все изменения через `/api/v1/admin/audit` (UI: `/audit`).
- **Outbox + Kafka** — at-least-once delivery всех изменений в 3 топика.
- **Webhooks** — push-уведомления HTTP к зарегистрированным URLs (для
  consumers без Kafka access).
- **Bulk operations** — multi-select close + CSV export.
- **Schema workflow** — maker-checker approval для изменения schemas
  (drafts + review + publish). См. [Schema workflow API](schema-workflow.md).
- **Full changelog timeline** — `/dictionaries/{name}/changelog` объединяет
  definition CRUD + draft workflow events с `kind` field для UI rendering.

## Что Ordinis НЕ делает

- Не хранит "снимок на момент заказа" — для этого consumer должен сделать
  snapshot rough copy в свою БД (см. [Caching → Snapshot strategy](caching.md#snapshot-at-order-time)).
- Не enforce'ит FK на уровне DB — это NoSQL-style references поверх JSONB.
  Cascade rules в roadmap (см. design `dict-relationships-v2`).
- Не обеспечивает realtime sync — TTL = 5 мин минимум либо event-driven invalidation.

## Версионирование

- **API** — `/api/v1/...` стабилен. Breaking changes только через major (`v2`).
- **Bundle** (cuod-bundle) — semver. Minor bump при schema изменении, major
  при удалении справочника. См. [Bundle cuod](bundle-cuod.md).

## Глоссарий

| Термин | Значение |
|---|---|
| Dictionary | Справочник (например `spacecraft`, `satellite_type`). |
| Record | Запись в справочнике с уникальным `businessKey`. |
| businessKey | Стабильный идентификатор (string). Не меняется при update. |
| Bundle | Maven module с schemas + seed data. ЦУОД bundle = 40 справочников. |
| Scope | Уровень доступа: `PUBLIC` / `INTERNAL` / `RESTRICTED`. |
| Bitemporal | Запись имеет `validFrom`/`validTo` + revision history (transaction time). |
| x-references | JSON Schema extension для cross-dictionary FK. |