Операції через 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 - і партнери будуть інтегруватися швидко, безпечно і передбачувано, а бізнес - масштабуватися без втрат якості і комплаєнсу.