Чеклист інтеграції API

0) Швидкий огляд (хто що робить)

• Власник інтеграції призначений
• Контакти on-call (24 × 7/раб. годинник) прописані
• Погоджена SLO/SLA та вікно підтримки релізів
• Статус-сторінка і канал інцидентів (email/Slack/Webhook)

1) Доступи, оточення, версії

• Доступ до sandbox/staging/production отримано
• Версія API підтверджена: '/v1 '/заголовок'X-API-Version '
• Allowlist IP і мережеві правила налаштовані
• Годинник і TZ: всі часи в UTC, NTP синхронізація
• Перевірена сумісність SDK/клієнтів по SemVer і матриці версій

2) Автентифікація та токени

• Механізм узгоджений: OAuth2 Client Credentials / Auth Code + PKCE / API Key / mTLS
• Термін життя Access Token і ротація Refresh Token налаштовані
• Для API Key: секрет показується один раз, зберігається в менеджері секретів
• JWKS/JTI/' kid'перевіряються, включений clock skew ± 5 хв
• 'Authorization'заголовки не логуються (редакція)

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3) Безпека і приватність

• TLS 1. 2 +/HSTS, опціонально mTLS
• PII-мінімізація: відправляємо тільки потрібне, маски в логах
• Політика зберігання та видалення (GDPR/DSAR) задокументована
• Secret rotation: активний/наступний ключ, план ролловера
• Анти-аб'юз: капча/швидкість створення ключів/обмеження реєстрацій

4) Ліміти, квоти і бекофф

• Оголошені'X-RateLimit- '/' X-Quota-'заголовки
• Клієнт поважає 429 і'Retry-After '
• Ретраї тільки для 5xx/408/429, експоненціальний backoff + jitter
• Межа спроб/часу заданий (наприклад, ≤ 5 спроб, ≤ 60с сумарно)

5) Ідемпотентність і конфлікти

• Всі write-операції відправляються з'Idempotency-Key'( TTL ≥ 24-72 год)
• Конфлікт дублікатів → 409 IDEMP_REPLAY обробляється
• ETag/' If-Match'для конкурентних оновлень включений (за наявності)

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6) Пагінація та інкрементальні дельти

• Використовується cursor/keyset пагінація ('next _ cursor','has _ more')
• Стабільне сортування'( updated_at, id)'документовано
• Інкрементальні вивантаження: watermark или change token
• Перекриваючі вікна (overlap 1-2 хв) і дедуп по'( id, version/seq) '

7) Формат помилок і діагностика

• Єдиний формат'application/problem + json'( RFC 7807)
• Підтримка полів: `error_code`, `trace_id`, `retriable`, `detail`
• Карта помилок і дії клієнта описані (runbook)

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8) Вебхукі: квітування та повтори

• Підтвердження успіху - будь-який 2xx; швидкий ACK після enqueue
• Підпис HMAC ('X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Політика ретраїв: backoff + jitter, до 24-72 годин
• DLQ + Replay: доступні та перевірені
• Дедуп-сховище у приймача, TTL ≥ вікна ретраїв

9) Спостережуваність і трасування

• Включені OpenTelemetry хуки в клієнті/SDK
• Кореляція'trace _ id '/' X-Request-ID'по всьому ланцюжку
• Дашборди: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: сплеск 5xx/429, зростання p95, падіння success rate, лаг вебхуків

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10) Продуктивність і стійкість

• Пули з'єднань, keep-alive, HTTP/2/3 де можливо
• Паралелізм обмежений (backpressure), черга клієнта не «роздувається»
• Політики circuit-breaker/timeout/fallback налаштовані
• Тести навантаження: burst 10 ×, довгі з'єднання, холодний старт

11) Дані, валюти, час

• Формати: ISO-8601 UTC, гроші - десяткові рядки/minor units, локалі не залежать від оточення
• Кодування/мови узгоджені (наприклад,'Accept-Language'для повідомлень, але'error _ code'- машинний)
• Політика округлення/комісій документована

12) Звірки та звітність (reconciliation)

• Щоденні/годинні звірки з контрольними сумами
• API/вивантаження для звірок протестовані (CSV/JSON, маніфести/хеші)
• Розбіжності - в тікети з посиланнями на'trace _ id '

13) Комплаєнс і правові аспекти

• Умови використання API прийняті (fair use/export control)
• PII/тримачі даних - ролі та зони зберігання визначені
• Legal Hold/аудит-лог дій включені при інцидентах

14) Документація та портал розробників

• OpenAPI/AsyncAPI актуальні, приклади «копіювати-вставити» є
• SDK (TS/Py/Java/Go/.NET) - версії узгоджені, Cookbook доступний
• Try-it playground працює, пісочні ключі активні
• Changelog/депрекації/roadmap видно в порталі

15) Тестування: функціональні, негативні, хаос

Функціональні

• CRUD/ключові сценарії пройдені (happy path)
• Пагінація/курсор/інкрементальні дельти

Негативні

• 401/403/404/409/422/429/5xx і обробка'Retry-After '
• Невірний підпис вебхука, прострочені токени, великі тіла

Хаос

• Drop 10-30% подій, reorder, затримки 1-10 хв
• Відключення залежностей (PSP/KYC) → коректний fallback/помилки

16) Приймання та запуск (go-live)

• Фінальний PRR (Production Readiness Review) пройдено
• Канарське включення: 10% → 25% → 50% → 100%
• Авто-відкат по SLO сигналам (помилки/латентність/429)
• Контактна матриця інцидентів і шлях ескалації опубліковані
• Беклоґ CAPA після пілота сформований

17) Експлуатація та підтримка

• Runbook/плейбуки: «5xx spike», «429 storm», «webhook backlog», «timeout»
• Регулярні звіти по SLO/Error Budget
• Ротація секретів і ключів за розкладом
• План депрекацій/міграцій версій узгоджений (дата sunset)

18) Шаблони артефактів

Шаблон env-конфіга

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

Політика ретраїв (псевдо)

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19) Підсумковий чек-лист «на підпис»

• Оточення/версії/ключі/allowlist готові
• Auth/JWT/keys/mTLS налаштовані і протестовані
• Ліміти/квоти/ретраї/ідемпотентність реалізовані
• Пагінація/курсор/дельти працюють на даних
• Вебхукі: підписи, повтори, DLQ/Replay перевірені
• Помилки'problem + json','trace _ id'прилипає в усі логи
• Дашборди/алерти зібрані, OTel включений
• Навантажувальні/негативні/хаос-тести пройдені
• Звірки і звіти сходяться, runbooks оформлені
• PRR/канарка/rollback-план готові, контакти on-call вказані

Підсумок

Цей чекліст закриває технічні, операційні та комплаєнс-аспекти інтеграції API. Пройдіть пункти зверху вниз, автоматизуйте перевірку лімітів, ідемпотентності і вебхуків, увімкніть спостережуваність і план відкату - і ваш запуск пройде передбачувано, без «сюрпризів» в продакшні.