Operazioni tramite API

(Sezione Operazioni e Gestione)

1) Assegnazione e principi

L'API è uno strato operativo dell'ecosistema: tutto ciò che non è automatizzato tramite contratto si trasforma in manuale e rischi.

• Contract-first: prima specifica ( ), poi implementazione.
• Secure-by-default: scorciatoie minime, TTL brevi, mutual-TLS/firme.
• Osservabile: tracciatura end-to-end e metriche SLA.
• Idempotent: ripetizione sicura.
• Backwards-compatibile: evoluzione senza alterazioni «distruttive».
• Verifiche crittograficamente confermate (ricevute).

2) Contratto e modelli (arbitro)

OpenAPI per le query sync AsyncAPI per eventi/webhoop.
I campi obbligatori di ogni risorsa sono «id», «variante», «created _ at», «updated _ at», «tenant», «region», «trace _ id».

Esempio di un frammento di contratto

yaml paths:
/payments/payouts:
post:
operationId: createPayout requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PayoutRequest'
responses:
"202": { $ref: '#/components/responses/AcceptedWithReceipt' }
headers:
Idempotency-Key:
schema: { type: string }
required: true components:
responses:
AcceptedWithReceipt:
description: Accepted, processing asynchronously headers:
Receipt-Hash: { schema: { type: string } }

3) Autenticazione, autorizzazione, scorciatoie

OAuth2/OIDC per utenti/partner; client-credentials/JWT для S2S.
Scoop/ruoli di risorse: 'payments. write`, `catalog. read`, `audit. export`.
ReBAC: accesso «di proprietà» (tenente/account/sito).
I segreti JIT includono i token a breve vita, il riferimento al dispositivo/subnet/regione.
Device posture & mTLS per operazioni critiche (pagamenti, chiavi).

4) Idampotenza e «un giorno esatto»

Idempotency-Key (titolo) + deadup per '(key, account, route)' nella finestra TTL.
Outbox/CDC per la pubblicazione degli eventi - consegna garantita.
Exactly-once-effects: gli effetti collaterali vengono registrati tramite un registro transazionale; La ripetizione porta alla stessa «ricevuta» («receipt _ hash»).
Regole Retry: back-off esponenziale, jitter, finestre massime.

5) Limiti, quote, priorità

Rate limits: per-key/tenant/route/region; «morbido» (429) e «rigido» (rifilo).
Quote/budget: cappe mensili/giornaliere, webhook' QuotaCapReached '.
Fair-use: priorità dei tenenti per livello di servizio (Gold/Silver/Bronze).
Buffer burst: picchi brevi senza degrado dei vicini.

6) Paginazione, filtri, campionamento

Cursor-based (stable ordering по `created_at,id`), `page_size` ≤ 1000.
Time-sliced campionamento («from», «to», «watermark») per i registri/transazioni.
Filtering DSL: whitelisted поля, `?status=...&tenant=...&region=...`.
«Snapshot _ at »/« as _ of» per le API di reportage.

7) Versioning e compatibilità

SemVer: `v1`, `v1. 1 '(estensioni),' v2 '- solo attraverso nuove vie/neimspace.
Regole di evoluzione: solo l'aggiunta di campi/valori, «deprecate → remove» attraverso la finestra.
Compatibility test - Contratti-come-test (consumer-driven).

8) Eventi, webhook e ricevute

AsyncAPI descrive i temi/payload/firma.
Firma: HMAC/EdDSA, intestazioni X-Firma, X-Nonce, X-Timestamp (finestra ristretta).
Ricevute (receipts): «receipt _ hash» e firma DSSE su eventi critici (pagamenti, modifiche RTP/limiti, fogli di pregio).
Retrai e deadup: idempotenza per «idempotency _ key »/« event _ id».
DLQ/quarantena: messaggi non caldi/ripetuti con cause.

9) Osservabilità e qualità

Traces: obbligatori dì trace _ id/span _ id "attraverso gateway/eventi aziendali/webhoop.
Metrics: disponibilità, p50/p95/p99, errato-rate, retry-rate, cost per 1k.
Logs: strutturati, senza segreti/PII; etichette «tenant/region/variante».
SLO/alert - Condizioni di riferimento SLO e run auto (pausa/re-route/rollback).

10) Errori e semantica degli stati

2xx - Successo (202 per le operazioni asincrone).
4xx - vini del cliente (422 - validazione, 409 - conflitto/idampotenza, 429 - limiti).
5xx - problemi temporanei.
Il corpo dell'errore è «code», «messaggino», «trace _ id», «hint», «retry _ after?».
X per i partner: tabella «cosa fare» per ogni errore.

11) Criteri-come-codice (OPA/ABAC)

Autorizzazioni centralizzate: «chi/cosa/dove/quando/perché».
Criteri in Git, codice-review, test CI (pre-flight: "risolverà il criterio? »).
Assegno SoD: «Crea un pagamento».

12) Sicurezza, privacy, compliance

Riduzioni PII: tornitura/maschera, accesso al primogenito solo tramite jobs approvati.
Segreti: Vault/KMS, TTL brevi, rotazioni; proibire i segreti shared.
Crittografia: mTLS/TLS 1. 3, AES-GCM at-rest, HSTS/PKP se necessario.
Giurisdiction-aware - Localizzazione dei dati/chiavi per region.
Registri di controllo: WORM, tagli Merkle, firme DSSE.

13) Utilizzo: SLI/SLO e dashboard

• Disponibilità per-route/region.
• Latenza p95 (read/write).
• Successo dei webhoop (ricevute), la linea di consegna.
• Error-rate/Retry-rate.
• Cost per 1k richieste e egress.

SLO (esempio): 99. 95% di disponibilità p95 ≤ 120/250 ms; I webhook sono stati 99. 5 %/5-min; P1 MTTR da 60 min.

14) Gestione delle modifiche (rilasci/rimborsi)

Blue-Green/Canary per gateway e percorsi critici.
Ficheflagi per il comportamento senza rilascio.
Expand→Migrate→Contract per diagrammi e payload.
Руны: Rollback Release, Disable Flag, Re-route, Flush Cache.
Artefatti - immagini/manifesti firmati, registro delle versioni.

15) SDK, clienti, «cassette di sabbia»

SDK ufficiali (TS/Java/Python/Go) con la stessa semantica di errori e retrai.
Ambienti Sandbox con chiavi di prova/certificati e simulatori PSP/KYC/provider di contenuti.
Contract-test sono inclusi in SDK CI, nightly-compatibilità.

16) Modello di dati (semplificato)

`api_key` `{id, tenant, scopes[], ttl, created_by}`

`rate_plan` `{tenant, quotas{route→cap}, burst, priority}`

`request_log` `{trace_id, route, actor, idempotency_key?, status, latency_ms, region, cost_unit}`

`webhook_receipt` `{event_id, endpoint, status, attempts, receipt_hash, signature}`

`policy` `{version, rules, signer, dsse}`

17) RACI

18) Metriche di qualità

Contract Drift: 0 modifiche «spezzanti» senza deprecazione.
Idempotency Error Rate: ≤ 0. 01%.
Webhook Success: ≥ 99. 5%, p95 a 60.
Auth Fail vs Abuse: percentuale di blocchi malevoli, rumore di livello ≤.
Cost/1k - Controllo delle rotte e delle regioni (budget/cap-alert).
SDK Adoption: quota di traffico tramite SDK ufficiali.

19) Playbook incidenti

Spike 429/limiti - Sollevare la cappa per Gold, trottling chiavi «rumorose», collegamento con il partner.
WebhookLag: ingrandire i worker/batch, dare priorità alle code, spegnere temporaneamente i webhoop facoltativi.
PriceMismatch (catalog/FX/Tax) - Verifica delle versioni, forza-invalidità della cache, reimpostazione dell'artefatto, compensi.
PSP Outage - Transizione della rotta, quarantena di transazioni grigie, repliche.
Compromise API-key: recensione immediata, rotazione, revisione degli ultimi 30 giorni.

20) Specificità iGaming/Fintech

API RTP/Limits: solo unità e versioni di profili; modifiche - con ricevute.
Pagamenti/pagamenti: 202 + webhoop con iscrizioni; Idipotenza a chiave d'ordine.
Gli affiliati sono il dedotto delle conversioni, gli escrow per le controversie, i rapporti firmati.
Gioco responsabile: espone le API di guardia per i limiti e gli eventi RG.

21) Assegno foglio di implementazione

• È stato descritto il contratto (OpenAPI/AsyncAPI), la validazione CI e i consumer-test.
• Sono configurati OAuth2/OIDC, insetti, segreti JIT e mTLS per percorsi critici.
• Idampotenza, retrai, DLQ e quarantena.
• Limiti/quote/priorità e alert per gap.
• Paginazione con puntatori, campionamenti consistenti «as _ of».
• Versioning e Criteri di deprecazione.
• Webhook con firme/ricevute, repliche e deduzioni.
• Traccia/metriche/fogli, SLO e rune.
• registri WORM, firme DSSE, tagli Merkle.
• SDK, sandbox, simulatori, esempi di codice e «how-to».

22) FAQ

Perché 202 per operazioni lunghe?
Per non mantenere la connessione e fornire un sicuro retro/ricevuta tramite webhook.

Abbiamo bisogno di entrambi, OpenAPI e AsyncAPI?
Sì: sync per comandi/interrogazioni, async per eventi/corrispondenza di stati.

Come evitare cambiamenti distruttivi?
Regola «solo aggiunte», deprecate, observe e remove, test del contratto client.

Dove conservare le ricevute?
Nella zona WORM con le firme, 'receipt _ hash' viene restituito al client e verificato su richiesta.

Riepilogo: Le transazioni tramite API sono una disciplina del contratto e del funzionamento: un rigoroso modello di accesso e idermotazione, limiti e versioni, osservabilità e SLO, firme e ricevute. Aggiungete arenaria e SDK - e i partner si integreranno in modo rapido, sicuro e prevedibile, mentre il business sarà scalabile senza perdita di qualità e compliance.