Chequlist di integrazione API

0) Panoramica rapida (chi fa cosa)

• Proprietario dell'integrazione assegnato
• Contatti on-call (24 x 7/schiavo. orologio) prescritto
• SLO/SLA accettati e finestra di supporto per i rilasci
• Stato pagina e canale di incidenti (email/Slack/Webhook)

1) Accessibilità, ambiente, versione

• Accesso a sandbox/staging/production ottenuto
• API confermata: '/v1 '/titolo 'X-API-Version'
• Allowlist IP e regole di rete configurate
• Orologio e TZ: tutte le volte in UTC, NTP sincronizzazione
• Verifica della compatibilità SDK/client per la SemVer e la matrice di versione

2) Autenticazione e token

• Meccanismo concordato: OAuth2 Client Credentials/Auth Code + PKCE/API Key/ mTLS
• La durata di Access Token e la rotazione di Refresh Token sono configurate
• Per API Key: il segreto viene visualizzato una volta, memorizzato nel gestore dei segreti
• JWKS/JTI/« kid »sono controllati, clock skew abilitato © 5 min
• 'Authorization', le intestazioni non sono logiche (redazione)

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

3) Sicurezza e privacy

• TLS 1. 2 +/HSTS, opzionale
• Minimizzazione PII - Invia solo la maschera desiderata, le maschere nei fogli
• Criteri di conservazione ed eliminazione (GDPR/DSAR) documentati
• Secret rotation: chiave attiva/successiva, piano rollover
• Anti-abuse: goccia/velocità di creazione chiavi/limitazioni di registrazione

4) Limiti, quote e bacoff

• Dichiarato' X-RateLimit '/' X-Quota'
• Il client rispetta 429 e Retry-After
• Retrai solo per 5xx/408/429, backoff esponenziale + jitter
• Limite di tentativi/tempo impostato (ad esempio, 5 tentativi, 60s totali)

5) Idampotenza e conflitti

• Tutte le operazioni write vengono inviate con «Idempotency-Key» (TTL-24-72 ore)
• Conflitto di duplicati → 409 IDAMP _ REPLAY
• ETag/' If-Match 'per gli aggiornamenti competitivi è abilitato (se disponibile)

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

6) Paginazione e delta incrementale

• Utilizza cursor/keyset pagination ('next _ cursor', 'ha _ more')
• Ordinamento stabile '(updated _ at, id)' documentato
• Scarichi incrementali: watermark o change token
• Finestre sovrapposte (overlap 1-2 min) e deducibilità dì (id, variante/seq) '

7) Formato degli errori e diagnostica

• Formato unico'application/perfem + json '(RFC 7807)
• Supporto dei campi: 'error _ code', 'trace _ id', 'retriable', 'detail'
• La mappa degli errori e le azioni del client sono descritte (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) Webhook: ricevute e ripetizioni

• Conferma del successo: qualsiasi 2xx; ACK veloce dopo enceue
• Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`
• Policy retraes: backoff + jitter, fino a 24-72 ore
• DLQ + Replay: disponibili e convalidati
• Archivio di deducibilità del ricevitore, TTL della finestra dei retrai

9) Osservabilità e tracciabilità

• Accesi gancio nel client/SDK
• Correlazione «trace _ id »/« X-Sollest-ID» su tutta la catena
• Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`
• Alarms: picco 5xx/429, crescita p95, caduta success rate, abbondanza webhook

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

10) Prestazioni e sostenibilità

• Pool di connessioni, keep-alive, HTTP/2/3 dove possibile
• Parallelismo limitato (backpressure), coda client non gonfia
• I criteri del circuito-breaker/timeout/fallback sono configurati
• Test di carico: burst 10 x, lunghe connessioni, inizio freddo

11) Dati, valute, tempo

• Formati: ISO-8601 UTC, denaro - righe decimali/minor units, locali indipendenti dall'ambiente
• Codifiche/lingue concordate (ad esempio, «Accept-Language» per i messaggi, ma «error _ code» è automatico)
• Il criterio di arrotondamento/commissione è documentato

12) Incrociatura e reporting

• Incroci giornalieri/orari con importi di controllo
• API/caricamento per fistole testate (CSV/JSON, manifesti/hash)
• Soluzioni temporanee - Ticket con riferimenti a «trace _ id»

13) Complaens e aspetti legali

• Condizioni di utilizzo API accettate (fair use/export control)
• PEI/titolari di dati - ruoli e aree di storage definite
• Legale Hold/controllo-controllo-attività attivati in caso di incidenti

14) Documentazione e portale degli sviluppatori

• sono aggiornati, gli esempi «copia-incolla» sono disponibili
• SDK (TS/PY/Java/Go/.NET) - versioni concordate, cookbook disponibile
• Try-it playground funziona, chiavi di sabbia attive
• Changelog/deprecazioni/roadmap visibili nel portale

15) Test: funzionali, negativi, caos

Funzionali

• CRUD/script chiave completati (happy path)
• Paginazione/cursore/delta incrementale

Negativi

• 401/403/404/409/422/429/5xx ed elaborazione dì Retry-After '
• Firma webhook errata, token scaduti, corpi grandi

Caos

• Drop 10-30% eventi, reorder, ritardo 1-10 min
• Disattivare le dipendenze (PSP/KYC) con fallback/errori corretti

16) Ricezione e avvio (go-live)

• PRR finale completato
• Accensione canaria: 10% → 25% → 50% → 100%
• Reimpostazione automatica SLO (errori/latitanza/429)
• La matrice di contatto degli incidenti e il percorso di escalation pubblicati
• Backlog CAPA dopo il pilota formato

17) Utilizzo e supporto

• Runbook/playbook: «5xx spike», «429 storm», «webhook backlog», «timeout»
• Report regolari SLO/Errore Budget
• Rotazione di segreti e chiavi pianificate
• Piano di deprecazione/migrazione versione concordato (data sunset)

18) Modelli di manufatti

Modello env-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

Policy retraes (pseudo)

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

19) Foglio di assegno «a firma»

• Ambienti/versioni/chiavi/allowlist pronti
• configurati e testati
• Limiti/quote/retrai/idampotenza implementati
• Paginazione/cursore/delta funzionano sui dati
• Web hook firme, ripetizioni, DLQ/Replay convalidati
• Gli errori 'problem + json', 'trace _ id', si attaccano a tutti i loghi
• Dashboard/alert assemblati, OTel abilitato
• Test di carico/negativi/caos superati
• Incroci e report convergono, runbooks sono stati compilati
• PRR/canarino/piano rollback pronto, contatti on-call specificati

Totale

Questo checklist chiude gli aspetti tecnici, operativi e complessi dell'integrazione API. Passate dall'alto verso il basso, automatizzate il controllo dei limiti, dell'idipotenza e dei webhoop, attivate l'osservazione e il piano di recupero e il vostro avvio sarà prevedibile, senza «sorprese» nella produzione.