Операции через API-интерфейс

(Раздел: Операции и Управление)

1) Назначение и принципы

API — это «операционный слой» экосистемы: все, что не автоматизировано через контракт, превращается в ручную работу и риски.

• Contract-first: сначала спецификация (OpenAPI/JSON Schema/AsyncAPI), потом реализация.
• Secure-by-default: минимальные скоупы, короткие TTL, мьютуал-TLS/подписи.
• Observable: end-to-end трассировка и метрики SLA.
• Idempotent: повтор безопасен.
• Backwards-compatible: эволюция без «ломающих» изменений.
• Auditable: криптографически подтвержденные факты (квитанции).

2) Контракт и модели (референс)

OpenAPI для sync-запросов; AsyncAPI для событий/вебхуков.
Обязательные поля в каждом ресурсе: `id`, `version`, `created_at`, `updated_at`, `tenant`, `region`, `trace_id`.

Пример фрагмента контракта

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Аутентификация, авторизация, скоупы

OAuth2/OIDC для пользователей/партнеров; client-credentials/JWT для S2S.
Скоупы/ресурсные роли: `payments.write`, `catalog.read`, `audit.export`.
ReBAC: доступ «по владению» (тенант/аккаунт/саб-аккаунт).
JIT-секреты: краткоживущие токены, привязка к устройству/подсети/региону.
Device posture & mTLS для критичных операций (выплаты, ключи).

4) Идемпотентность и «ровно-однажды»

Idempotency-Key (заголовок) + дедуп по `(key, account, route)` на TTL-окне.
Outbox/CDC для публикации событий — гарантированная доставка.
Exactly-once-effects: побочные эффекты фиксируются через транзакционный журнал; повтор приводит к той же «квитанции» (`receipt_hash`).
Retry-политики: экспоненциальный бэк-офф, джиттер, максимальные окна.

5) Лимиты, квоты, приоритезация

Rate limits: per-key/tenant/route/region; «мягкие» (429) и «жесткие» (отсечка).
Квоты/бюджеты: месячные/суточные капы, вебхуки `QuotaCapReached`.
Fair-use: приоритет тенантов по сервисному уровню (Gold/Silver/Bronze).
Burst-буферы: короткие всплески без деградации соседей.

6) Пагинация, фильтры, выборки

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Time-sliced выборки (`from`, `to`, `watermark`) для журналов/транзакций.
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
Consistency hints: `snapshot_at`/`as_of` для репортинговых API.

7) Версионирование и совместимость

SemVer: `v1`, `v1.1` (расширения), `v2` — только по новым путям/неймспейсам.
Правила эволюции: только добавления полей/значений, «deprecate → remove» через окно.
Compatibility tests: «контракты-как-тесты» (consumer-driven).

8) События, вебхуки и квитанции

AsyncAPI описывает темы/payload/подписи.
Подпись: HMAC/EdDSA, заголовки `X-Signature`, `X-Nonce`, `X-Timestamp` (узкое окно).
Квитанции (receipts): `receipt_hash` и DSSE-подпись на критичных событиях (платежи, изменения RTP/лимитов, прайс-листы).
Ретраи и дедуп: идемпотентность по `idempotency_key`/`event_id`.
DLQ/карантин: невалидные/повторные сообщения с причинами.

9) Наблюдаемость и качество

Traces: обязательные `trace_id/span_id` сквозь шлюз/бизнес-события/вебхуки.
Metrics: доступность, p50/p95/p99, error-rate, retry-rate, cost per 1k.
Logs: структурированные, без секретов/PII; метки `tenant/region/version`.
SLO/алерты: SLO-ориентированные условия и авто-руны (pause/re-route/rollback).

10) Ошибки и семантика статусов

2xx — успех (202 для асинхронных операций).
4xx — вина клиента (422 — валидация, 409 — конфликт/идемпотентность, 429 — лимиты).
5xx — временные проблемы.
Тело ошибки: `code`, `message`, `trace_id`, `hint`, `retry_after?`.
UX для партнеров: таблица «что делать» на каждую ошибку.

11) Политики-как-код (OPA/ABAC)

Централизованная авторизация: «кто/что/где/когда/зачем».
Политики в Git, код-ревью, CI-тесты (pre-flight: «разрешит ли политика?»).
SoD-чек: «создать выплату» ≠ «утвердить».

12) Безопасность, приватность, комплаенс

PII-минимизация: токенизация/маски, доступ к первичке только через одобренные джобы.
Секреты: Vault/KMS, короткие TTL, ротации; запрет shared-секретов.
Шифрование: mTLS/TLS 1.3, AES-GCM at-rest, HSTS/PKP где уместно.
Jurisdiction-aware: локализация данных/ключей per region.
Журналы аудита: WORM, Merkle-срезы, DSSE-подписи.

13) Эксплуатация: SLI/SLO и дашборды

• Доступность per-route/region.
• Латентность p95 (read/write).
• Успешность вебхуков (квитанции), лаг доставки.
• Error-rate/Retry-rate.
• Cost per 1k запросов и egress.

SLO (пример): 99.95% доступности; p95 ≤ 120/250 мс; вебхуки ≥ 99.5%/5-мин; P1 MTTR ≤ 60 мин.

14) Управление изменениями (релизы/откаты)

Blue-Green/Canary для шлюзов и критичных маршрутов.
Фичефлаги для поведения без релиза.
Expand→Migrate→Contract для схем и payload.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Артефакты: подписанные образы/манифесты, реестр версий.

15) SDK, клиенты, «песочницы»

Официальные SDK (TS/Java/Python/Go) с одинаковой семантикой ошибок и ретраев.
Sandbox-окружения с тестовыми ключами/сертификатами и симуляторами PSP/KYC/провайдеров контента.
Contract-tests включены в SDK CI, nightly-совместимость.

16) Модель данных (упрощенно)

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

18) Метрики качества

Contract Drift: 0 «ломающих» изменений без депрекейта.
Idempotency Error Rate: ≤ 0.01%.
Webhook Success: ≥ 99.5%, лаг p95 ≤ 60 с.
Auth Fail vs Abuse: доля злонамеренных блоков, шум ≤ целевого уровня.
Cost/1k: контроль по маршрутам и регионам (бюджеты/кап-алерты).
SDK Adoption: доля трафика через официальные SDK.

19) Плейбуки инцидентов

Spike 429/лимиты: поднять кап для Gold, троттлинг «шумных» ключей, связь с партнером.
WebhookLag: увеличить воркеры/батчи, приоритизировать очереди, временно выключить необязательные вебхуки.
PriceMismatch (catalog/FX/Tax): сверка версий, форс-инвалидация кэша, откат артефакта, компенсации.
PSP Outage: переключение маршрута, карантин «серых» транзакций, реплей.
Compromise API-key: немедленный отзыв, ротация, аудит последних 30 дней.

20) Специфика iGaming/финтех

RTP/Limits API: только агрегаты и версии профилей; изменения — с квитанциями.
Платежи/выплаты: 202 + вебхуки с подписями; идемпотентность на ключ заказа.
Аффилиаты: дедуп конверсий, эскроу для споров, подписанные отчеты.
Ответственная игра: экспонируйте «guardrails API» для лимитов и RG-событий.

21) Чек-лист внедрения

• Описан контракт (OpenAPI/AsyncAPI), CI-валидация и consumer-tests.
• Настроены OAuth2/OIDC, скоупы, JIT-секреты и mTLS для критичных маршрутов.
• Введены идемпотентность, ретраи, DLQ и карантин.
• Лимиты/квоты/приоритеты и алерты по капам.
• Пагинация курсорами, консистентные выборки `as_of`.
• Версионирование и Deprecation-политика.
• Вебхуки с подписями/квитанциями, реплей и дедуп.
• Трассировка/метрики/логи, SLO и руны.
• WORM-журналы, DSSE-подписи, Merkle-срезы.
• SDK, sandbox, симуляторы, примеры кода и «how-to».

22) FAQ

Почему 202 для длинных операций?
Чтобы не держать соединение и обеспечить надежный ретрай/квитанцию через вебхук.

Нужны ли оба: OpenAPI и AsyncAPI?
Да: sync для команд/запросов, async для событий/согласования состояний.

Как избежать ломающих изменений?
Правило «только добавления», deprecate → observe → remove, контракт-тесты клиентов.

Где хранить квитанции?
В WORM-зоне с подписями; `receipt_hash` возвращается клиенту и сверяется по запросу.

Резюме: Операции через API — это дисциплина контракта и эксплуатации: строгая модель доступа и идемпотентность, лимиты и версии, наблюдаемость и SLO, подписи и квитанции. Добавьте песочницы и SDK — и партнеры будут интегрироваться быстро, безопасно и предсказуемо, а бизнес — масштабироваться без потерь качества и комплаенса.