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 синхрондау
• SemVer және нұсқа матрицасы бойынша SDK/клиенттердің үйлесімділігі тексерілді

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: белсенді/келесі кілт, rollover жоспары
• Анти-абьюз: капча/кілттерді жасау жылдамдығы/тіркеуді шектеу

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; enqueue кейін жылдам ACK
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Ретра саясаты: backoff + jitter, 24-72 сағатқа дейін
• DLQ + Replay: қол жетімді және тексерілген
• Қабылдағыштың дедуп-сақтау орны, TTL ≥ Ретра терезелері

9) Бақылау және трассалау

• Клиент/SDK OpenTelemetry хакі қосылды
• Бүкіл тізбек бойынша '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/playbook: «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 интеграциясының техникалық, операциялық және комплаенс-аспектілерін жабады. Жоғарыдан төмен пункттерді басып өтіңіз, лимиттерді, демпотенттілікті және веб-хуктерді тексеруді автоматтандырыңыз, бақылау мен кері қайтару жоспарын қосыңыз - және сіздің іске қосылуыңыз болжамды түрде, өнімде «күтпеген жерден» өтеді.