Checklist d'intégration API

0) Examen rapide (qui fait quoi)

• Le propriétaire de l'intégration est désigné
• Contact on-call (24 × 7/esclave. l'horloge) est prescrite
• SLO/SLA acceptés et fenêtre de support de sortie
• Page de statut et flux d'incidents (email/Slack/Webhook)

1) Accès, environnement, versions

• Accès à sandbox/staging/production
• Version de l'API confirmée : '/v1 '/en-tête 'X-API-Version'
• Allowlist IP et les règles réseau sont configurés
• Horloge et TZ : tous les temps en UTC, synchronisation NTP
• Compatibilité SDK/clients testée avec BouVer et la matrice de version

2) Authentification et jetons

• Mécanisme convenu : OAuth2 Client Credentials/Auth Code + PKCE/API Key/mTLS
• Durée de vie Access Token et rotation Refresh Token personnalisés
• Pour l'API Clé : un secret est affiché une fois, stocké dans le gestionnaire de secrets
• JWKS/JTI/' kid 'sont vérifiés, clock skew inclus ± 5 min
• « Autorisation » les titres ne sont pas logés (révision)

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

3) Sécurité et vie privée

• TLS 1. 2 +/HSTS, option mTLS
• Minimisation des PII : nous n'envoyons que le bon, les masques dans les logs
• Politique de stockage et d'élimination (RGPD/DSAR) documentée
• Rotation secrète : clé active/suivante, plan de rollover
• Anti-abyse : captcha/vitesse de création des clés/limitation des inscriptions

4) Limites, quotas et bakoff

• Les titres « X-RateLimit- »/« X-Quota- » sont annoncés
• Le client respecte 429 et 'Retry-After'
• Retraits uniquement pour 5xx/408/429, exponentiel backoff + jitter
• Limite de tentative/temps spécifiée (par exemple, 5 tentatives ≤ ≤ 60s total)

5) Idempotence et conflits

• Toutes les opérations d'écriture sont envoyées avec 'Idempotency-Key' (TTL ≥ 24-72 h)
• Conflit de doublons → 409 IDEMP_REPLAY en cours de traitement
• ETag/' If-Match 'pour les mises à jour concurrentielles incluses (si disponible)

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

6) Pagination et delta incrémental

• Utilisation de la pagination cursor/keyset ('next _ cursor', 'has _ more')
• Le tri stable '(updated_at, id)' est documenté
• Décharges incrémentales : watermark ou changement token
• Fenêtres superposées (overlap 1-2 min) et dedup par '(id, version/seq)'

7) Format d'erreur et diagnostic

• Format unique 'application/problème + json' (RFC 7807)
• Prise en charge des champs : 'error _ code', 'trace _ id', 'retriable', 'detail'
• La carte des erreurs et les actions du client sont décrites (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) Webhooks : Fortification et répétitions

• Preuve de succès - n'importe quel 2xx ; un ACK rapide après l'affaire
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Politique des retraits : backoff + jitter, jusqu'à 24-72 heures
• DLQ + Replay : disponible et vérifié
• Stockage de déduplication au récepteur, TTL ≥ fenêtres de retraits

9) Observation et traçage

• Inclus OpenTelemetry hooks dans le client/SDK
• Corrélation 'trace _ id '/' X-Request-ID' sur toute la chaîne
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms : sursaut de 5xx/429, augmentation de p95, baisse de taux de réussite, lag webhooks

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

10) Performance et durabilité

• Pools de composés, keep-alive, HTTP/2/3 si possible
• Le parallélisme est limité (backpressure), la file d'attente du client n'est pas « gonflée »
• Les politiques de circuit-breaker/timeout/fallback sont configurées
• Tests de charge : burst 10 ×, jonctions longues, démarrage à froid

11) Données, devises, heure

• Formats : ISO-8601 UTC, argent - lignes décimales/unités mineures, locales indépendantes de l'environnement
• Les encodages/langues sont cohérents (par exemple, 'Accept-Language' pour les messages, mais 'error _ code' est une machine)
• La politique d'arrondi/commission est documentée

12) Rapprochement et établissement de rapports (reconnaissance)

• Rapprochement quotidien/horaire avec les montants de contrôle
• API/déchargement pour sverok testés (CSV/JSON, manifestes/hash)
• Différences - en tiquets avec des références à 'trace _ id'

13) Conformité et aspects juridiques

• Conditions d'utilisation de l'API acceptées (fair use/export control)
• PII/détenteurs de données - rôles et zones de stockage définis
• Legal Hold/audit-journal des actions inclus dans les incidents

14) Documentation et portail des développeurs

• OpenAPI/AsyncAPI sont à jour, il ya des exemples de « copier-coller »
• SDK (TS/Py/Java/Go/.NET) - versions harmonisées, Cookbook disponible
• Try-it playground fonctionne, les clés de sable sont actives
• Changelog/Dépressions/roadmap sont visibles dans le portail

15) Test : Fonctionnel, négatif, chaos

Fonctionnalité

• CRUD/scénarios clés passés (chemin happy)
• Pagination/curseur/delta incrémental

Négatifs

• 401/403/404/409/422/429/5xx et traitement « Retry-After »
• Signature incorrecte du webhook, tokens périmés, gros corps

Chaos

• Drop 10-30 % des événements, reorder, retards 1-10 min
• Désactivation des dépendances (PSP/KYC) → fallback/erreurs correctes

16) Acceptation et lancement (go-live)

• Le PRR final (Production Read....Review) est passé
• Inclusion canarienne : 10 % → 25 % → 50 % → 100 %
• Auto-retour sur les signaux SLO (erreurs/latence/429)
• Tableau de contact des incidents et chemin d'escalade publié
• Le backlog CAPA après le pilote est formé

17) Exploitation et soutien

• Runbook/playbooks : « 5xx spike », « 429 storm », « webhook backlog », « timeout »
• Rapports réguliers sur le budget SLO/Error
• Rotation des secrets et des clés selon un calendrier
• Plan de dépréciation/migration des versions harmonisé (date sunset)

18) Modèles d'artefacts

Gabarit de bou-config

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

Politique des retraits (pseudo)

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

19) Chèque final « à signer »

• Les environnements/versions/clés/allowlist sont prêts
• Auth/JWT/keys/mTLS configurés et testés
• Limites/quotas/Retrai/Idempotence mis en œuvre
• Pagination/curseur/delta fonctionne sur les données
• Webhooks : signatures, répétitions, DLQ/Replay vérifiés
• Les erreurs 'problème + json', 'trace _ id' sont collées dans toutes les logs
• Dashboards/alerts assemblés, OTel inclus
• Tests de charge/négatifs/chaos passés
• Les rapprochements et les rapports convergent, les runbooks sont formalisés
• PRR/canari/plan de rollback sont prêts, les contacts sont indiqués

Résultat

Ce checklist clôture les aspects techniques, opérationnels et de conformité de l'intégration de l'API. Passez les points de haut en bas, automatisez la vérification des limites, de l'idempotence et des webhooks, activez l'observation et le plan de retour - et votre lancement se déroulera de manière prévisible, sans « surprises » dans la production.