Чеклист интеграции 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. Пройдите пункты сверху вниз, автоматизируйте проверку лимитов, идемпотентности и вебхуков, включите наблюдаемость и план отката — и ваш запуск пройдет предсказуемо, без «сюрпризов» в продакшне.