Integrazione dei partner nell'ecosistema

1) Ruoli e modelli di partecipazione

Operatori/marchi: vetrine, calcoli, KYC/AML, responsabilità per l'esperienza utente.
Studi/RGS/Aggregatori di contenuti: giochi/striam, cataloghi, promozioni.
Fornitori di pagamenti/portafogli: PSP, APM, cripto, charjbeek.
KYC/AML/Antifrode - Verifica, slot list, rischio-scorrimento.
Affiliati/reti di marketing: traffico, postback, assegnazione.
ISV/integratori: moduli aggiuntivi, applicazioni di marketing.

Modelli: referral/resell, white-label/OEM, marketplace/app-store, hub & spoke (federazione).

2) «Passaporto partner» e pacchetto iniziale

Perché: un'unica fonte di verità su diritti, zone, versioni, SLO, chiavi e processi.

yaml partner_passport. v1:
partner_id: "kyc-omega"
type: "KYC/AML"
regions: ["EU","TR","LATAM"]
contracts: { msa: "2025-01-10", dpa: "2025-01-10", sla: "99. 9/30d" }
api_versions: ["identity. v1","events. v1","webhook. v1"]
auth: { oidc_client_id: "p_omega", scopes: ["kyc:read","kyc:write"] }
webhooks: { signature: "Ed25519", retry: "exp", dedupe: true, ttl_s: 300 }
rate_limits: { rps: 100, burst: 300 }
pii_policy: { minimization: true, retention: "180d", geo_pinning: ["EU"] }
recon: { window_days: 7, epsilon: 0. 002 }
owners: { biz: "ecosystem-biz", tech: "integrations" }
status: "sandbox"

3) Processo da richiesta a produzione

1. Screening: questionario, partner KYC, sorgenti dati/traffico, assegno sunk.
2. Contratti: MSA/DPA/SLA/OLA, commercio (CPA/RevShare/Hybrid/net-basis).
3. I punti di partenza sono il rilascio delle chiavi/client OIDC, l'accesso alla cassetta di sabbia, un set di test.
4. Test di Conformance: schemi di eventi, webhook, limiti, idampotenza.
5. Sicurezza review firma gli artefatti, SBOM/SLSA (se SDK/client).
6. Pilota/canarino: volume limitato/geo, monitoraggio rafforzato.
7. Go-live: traduzione dello stato, SLO-Dashboard, piano di risposta.
8. QBR/MBR - recensioni regolari di KPI, incidenti, mappe stradali.

4) Contratti dati e schemi di eventi

Principi: minimizzazione, versioni (semver), compatibilità «vN/vN+1», firme.

yaml event. common. v1:
id: uuid occurred_at_utc: timestamp source_partner_id: string trace_id: uuid type: enum        # e. g., "kyc. approved. v1"
payload: object signature: ed25519 version: "1. 0. x"

Cartelle e report: JSON Schema/Avro, Controllo campi obbligatori, TTL/Retenschen, Legale Hold.
Stabilità: modifiche breaking solo attraverso i nuovi tipi/versioni con la finestra deprecation.

5) Autenticazione, autorizzazione, segreti

OAuth2/OIDC: token a vita corta, se possibile.
mTLS per server-server.
Webhoop firmati: Ed25519/HMAC; anti-replay ('X-Timestamp', finestra 5 minuti).
PoLP/ABAC: schemi/attributi: «partner», «region», «dataset», «env».
Rotazione delle chiavi: bidirezionale, con finestra di compatibilità e registro di revisione.

python def verify(req):
if abs(now()-req. h["X-Timestamp"])>300: return 401 if not sig_ok(req. body, req. h["X-Signature"], partner_pubkey): return 401 if seen(req. json["event_id"]): return 200 store(req. json); mark_seen(req. json["event_id"]); return 200

6) Idempotenza, limiti, stabilità

Idempotency-Key: `partner_id + external_id + op_type`.
Rate limiting/quotas: RPS, burst, «partenza calda» che riducono i tassi di degrado.
Regole Retry: esposizione + jitter, deadup in ricezione.
Pattern outbox/inbox: consegna garantita, deadup, controllo.
Backpressure: code, DLQ con retensen separato.

7) Osservabilità e SLO

Метки: `partner`, `region`, `api_version`, `route`, `env`.
SLI: disponibilità, p95/99 latency, error-rate, delivery-within-window, recon-differf.
SLO & burn rate: per partner/sito; alert per eccesso.
Tracciabili: trace _ id; samplicazione di code e errori (tail sampling).
Sintetica: controlli esterni endpoint/firme/TTL.

rego package partner. release deny["SLO at risk"] { input. slo_forecast. error_burn > 1. 0 }
deny["Missing schema tests"] { input. tests. schemas_passed == false }

8) Complaence e privacy

Geo-pinning: i dati dei domini sensibili non lasciano le regioni autorizzate.
Minimizzazione e alias PII: 'user _ pseudo _ id', invece di un DD diretto.
Tempo di conservazione: TTL/ILM; crypto-erasure chiave (per-partner/per-regione).
Diritti soggetto: instradamento DSAR all'origine, registro di esecuzione.
Registri di accesso e controllo: chi ha visto quando, perché; fogli immutabili.

9) Calcolo, attribuzione e ripartizione

Base di calcolo: net vs gross, tassi di cambio, tasse, bonus.
Assegnazione: finestre (click/view), priorità canali, deduplicazione dì event _ id/click _ id ".
Reconciliation: rapporti bilaterali, tolleranza e chiusura SLA (≤5 pd).

sql
SELECT a. event_id
FROM partner_report a
LEFT JOIN internal_events b ON a. event_id=b. event_id
WHERE a. date BETWEEN:from AND:to AND b. event_id IS NULL;

10) Versioning API e gestione delle modifiche

Semver: «v1» è un ramo stabile; breaking dì v2 "con supporto doppio per giorni.
Processo di deprecazione: l'annuncio di una bandiera sul passaporto di un sintetico/alert è stato disattivato.
SDK/connettori: firma di release, SBOM, compatibilità, gate migratorie.

11) Routing e federazione (se più partner dello stesso tipo)

SOR (Smart Order Routing) - prezzo/qualità/latitanza/completamento/reputazione.
Fairness: limitazione della quota di fatturato, tie-break SLA/reputazione.
Delradation: fallback onesto, peggioramento trasparente (notifiche/banner).

12) Playbook incidenti

12. 1 «Draif schema webhook»

yaml detect: "schema_validation_error_rate>0. 5%"
steps:
- "auto-pause partner webhooks"
- "fallback to cached/default behavior"
- "notify partner; open war-room"
- "provide diff & test vectors; hotfix window 24h"
kpi: ["RTA<=1h","residual_errors<0. 1%"]

12. 2 «SLO fallito da PSP/KYC»

1. Ridistribuisci tramite SOR

2. Attiva graceful-degradation nel flusso di →

3. Applica limiti/quote

4. Ottenere un prestito SLA e post-incidente.

12. 3 «Soluzione di calcolo»

1. Pagamenti Freeze per intervallo di →

2. Eventi re-drive da outbox →

3. Scorciatoia/ →-correzione

4. Atto congiunto e disgelo.

13) Marketplace/portale dei partner

Certificazione integrazioni: scontrini, badge di qualità (Gold/Silver/Bronze).
Catalogo connettori: ricerca/filtri per mercato/tipo/versione API.
Auto-SDK/speck: OpenAPI/AsyncAPI, esempi, raccolte Postman.
Self-service - Chiavi, webhooks, limiti, registri, cornici di prova.

14) Metriche di maturità delle integrazioni

Time-to-Integrate (TTI) - Mediana di giorni prima della prod.
Coverage: quota di mercato/funzionalità supportate dal partner.
SLO pass-rate: mese per mese per partner/regione.
Recon-health: velocità di chiusura delle discrepanze, residuo.
Sicurezza posture: frequenza di rotazione delle chiavi, SBOM coverage.
Cost/egress: $/req e $/GB per partner, efficienza SOR.

15) Anti-pattern

«Prima connettiamo gli standard, poi».
Schemi unici per ogni partner.
Solo i cookie senza S2S contengono perdite e controversie.
Nessuna idampotenza/limite di duplicazione/tempesta di →.
Il PII nei loghi/webhoop è un rischio regolatorio.
Una «super integrazione» senza alternative è un rischio concentrativo.
Modifiche API senza la finestra di deprecazione e sintetici di incidente in vendita.

16) Assegno-foglio dell'architetto delle integrazioni

1. Il passaporto del partner è compilato (contratti, regioni, versioni, chiavi, SLO)?
2. I diagrammi di eventi e report sono validi da un test-pacchetto, c'è una cassetta di sabbia?
3. OAuth/OIDC, la firma del mandato webhook e anti-replay sono inclusi?
4. Idampotenza, limiti, outbox/inbox e DLQ sono implementati?
5. I dashboard SLO/SLA, le tracce, gli alert burn-rate sono configurati?
6. Le finestre di calcolo/assegnazione sono formalizzate?
7. Geo-pinning/TTL/crypto-erasure e routing DSAR in loco?
8. Semver, processo di deprecazione e doppia versione sono documentati?
9. I playbook degli incidenti sono stati verificati (deriva dei circuiti, SLO-fallimento, recon-diff)?
10. Piano exit: disattivazione delle chiavi, esportazione dei dati, migrazione alla seconda-source?

Conclusione

L'integrazione dei partner è una catena di montaggio di produzione, standard di verifica, osservazione e miglioramento. Quando il passaporto del partner è pieno, gli eventi e i contratti sono tipizzati, l'autenticazione e le firme sono obbligatorie, lo SLO viene misurato, i calcoli vengono controllati e le modifiche vengono gestite attraverso versioni e gate - l'ecosistema cresce in modo rapido e sicuro e ogni nuovo partner rafforza il valore della rete.