Reti aperte e integrazioni esterne

(Sezione Ecosistema e Rete)

1) Perché una rete aperta

Una rete aperta riduce i costi transazionali delle integrazioni e accelera l'innovazione. Contratti standardizzati, arenili e portali self-service trasformano l'ecosistema in una piattaforma di sviluppo, dove i partecipanti creano rapidamente valore senza negoziazioni su ogni passo.

2) Principi openness

Open by design - Specifiche API/Ivent pubbliche, esempi, SDK.
Sicurezza & privacy first: dati minimi necessari, firme, localizzazione PII.
Backward/forward compatibilità: criteri di versioning e migrazione.
Osservabilità by default - trace-id end, logi strutturati, metriche.
Self-service - Chiavi, webhook, quote e report tramite il portale.
Cost-aware - limiti egress, cache, guardia-rail economici.

3) Contratti di integrazione

3. 1 API (RQ/RS)

Formato: REST/gRPC + specifica (OpenAPI/Protobuf).
Le intestazioni obbligatorie sono «x-sollest-id», «x-idempotency-key», «traceparent».
Errori: codici definiti, suggerimenti sui retrai, riferimento «status _ url» per l'asincronica.

3. 2 Eventi (Pub/Sub)

Поля: `event_id`, `occurred_at`, `producer`, `subject_id`, `schema_version`, `region`, `tenant`.
Garanzie: at-least-once, partizionamento in chiave (user _ id/tenant _ id), retention per replay.

3. 3 Webhook

I titoli sono «firma», «timestamp», «nonce», «delivery-id».
Anti-replay: TTL finestre, monouso «nonce», elenco dei delivery-id usati.
Comportamento: 2xx = accettazione; ritrai esponenziali con jitter; Idopotenza sul ricevitore.

4) Sicurezza e fiducia

Autenticazione: OAuth2/OIDC per le integrazioni client mTLS per S2S.
Firme: HMAC/Ed25519; directory centralizzata delle chiavi, rotazione e pinning.
Regole di accesso: RBAC/ABAC, scorciatoie «minime», token temporanei.
Chiavi e segreti: KMS per-region, separazione dei compiti (M-of-N per le operazioni critiche).
Controllo: registri invariati (WORM) + tagli e ricevute Merkle (receipts).

5) Versioning e migrazione

SemVer per API e diagrammi di eventi.
Strategia: expand migrate contract (aggiungiamo campi, trasferiamo i consumatori, rimuoviamo quelli vecchi).
Rilasci breaking in calendario, pre-GA e GA finestre, fidi di prova.
Automezzi di compatibilità CI; assegno verde per le integrazioni certificate.

6) Sabbia, SDK e DevEx

Ambiente completo con chiavi di prova, ficstour, pagamenti mock, generatori di eventi.
SDK/CLI: integrazione rapida, generazione di client per specifiche, esempi di copia-incolla.
Elenco dei contratti: ricerca per domini, versioni, regioni; changelog e esempi di payload.
Correzione automatica: pacchetto di test di firma, idempotenza, schemi; I badge sono compatibili.

7) SLO/SLA, quote e fair-usa

SLO per-canale: p95/p99 latency, errato-rate, successo delle consegne di eventi.
SLA per i partner: finestre di accesso mirate, crediti-note/multe come codice.
Quote/limiti: per-chiave/tenante/regione, parametri burst, priorità per livello.
Rate-limits e protezione: circuito-breakers, backpressure, pulsante rosso (kill-switch).
Routing cost-aware: con lo stesso ritardo è un percorso più economico.

8) Osservabilità e verifica

Traceability: passante «trace _ id »/« span _ id» in tutti i canali (RPC, eventi, webhook).
Metriche: latency p50/p95/p99, error-rate, fila, cash hit, egress/ingress.
Logi: strutturati, con «tenant _ id», «partner _ id», versione del contratto e regione.
Ricevute e registri Merkle: spedizione/inclusione provata; Incrociature automatiche (differf).
I dashboard del partner sono consumo, stato delle consegne, quote, incidenti, billing.

9) Complaence e privacy

Data minimization - Gli eventi contengono ID/prove e non un PII superfluo.
Localizzazione dei dati: PII/Find - nelle «zone di fiducia» della regione; fuori, token/hash.
Diritto all'oblio: rimozione dei PII primari senza perdita di prova (le ricevute rimangono).
Regole come codice: controlli di privacy/sicurezza in CHI che bloccano i gate di rilascio.

10) Onboording partner (flusso arbitrale)

1. Due Diligence: sicurezza/compilazione, allineamento SLA/economia.
2. Fornitura delle chiavi: scoop, quote, disponibilità temporanea.
3. Integrazione in sabbia: esempi di payload, correzione automatica.
4. Il pilota sotto il phicheflag, traffico limitato, guardrail e dashboard.
5. Avvio GA - Pubblicazione nella directory, condizioni SLA/Bollo.
6. Utilizzo: monitoraggio, report, gelosia regolare; Gestione delle versioni/migrazioni.
7. EOL/Disconnessione: ritiro delle chiavi, migrazione del traffico, archivio degli artefatti.

11) Marketplace estensioni

Formato: plugin/adattatori/bot con vetrina, classifica e condizioni.
Modello di reddito: royalties/commissione di utilizzo, sconti tier per grandi integratori.
Qualità: certificazione, SLO-badge, automezzi di compatibilità per update.
Sicurezza - Firma artefatti (SBOM), criteri di aggiornamento e ripristino.

12) Economia delle interazioni

RevShare/CPA/CPL/Marketplace-Commission - trasparenti e formalizzati nei circuiti di reporting.
Shared-savings: condividiamo il risparmio (ad esempio, riduzione egress/marceback).
Budget-cap: limiti per promo/intenti, auto-downscale moltiplicatori.
Dispute & escrow - Arbitraggio automatico per le ricevute firmate, skrow temporaneo.

13) Rischi e anti-pattern

Il caos versionale è che la mancanza di politiche migratorie sta distruggendo i consumatori.
Scarsa sicurezza dei webhoop: nessuna firma/TTL/nonce/ripetizioni.
Nessuna idipotenza: ripresa del pagamento/addebito.
Rieletto PII, violazione della privacy e aumento dei costi della compilazione.
Nessun kill-switch e quote: un partner «brucia» la capacità e i costi aumentano.
Bollo opaco, discussioni e perdita di fiducia.

14) Metriche di successo di una rete aperta

DevEx: TTFI (key-to-first-success), tempo di certificazione, NPS integratori.
Qualità: p95/p99 attraverso i canali, successo delle consegne Web e della replica.
Economia: costo 1k eventi, egress/ingress per partner, programmi di incentivi REI.
Affidabilità: MTTR, percentuale di riprese elaborate in modo idipotente, percentuale coperta da ricevute di transazioni.
Effetti di rete: numero di integrazioni attive, quota di traffico tramite bus standardizzato.

15) Assegno-foglio di implementazione

• Pubblica le specifiche API/Ivent e la directory delle versioni.
• Abilita cassetta di sabbia, SDK/CLI e correzione automatica.
• Configura OAuth2/OIDC e mTLS, firme web (HMAC/Ed25519), TTL/nonce.
• Immettere «x-idempotency-key», «traceparent», «x-sollest-id» ovunque.
• Eseguire i registri Merkle e le ricevute; i dashboard del partner e il billing.
• Definire SLO/SLA, quote, rate-limits, cost-aware routing e kill-switch.
• Accettare il criterio di versioning (expand → migrate → contract) e il calendario di modifiche breaking.
• Formalizzare l'economia (RevShare/CPA/Marketplace/Shared-savings) e le regole delle controversie/escrow.
• Localizzare PII/find; Gli assegni di privacy/sicurezza CI.
• Eseguire regolari GameDays di integrazioni (tempesta di retrai, perdita di firma, diagramma di drift).

16) FAQ

Come si fa ad accelerare l'onboard?
Sabbia + SDK pronti, autosufficienza dei contratti e status-endpoint.

Come evitare i discorsi?
rigorosa, modalità di compatibilità e «expand migrate» con finestre pre-GA.

C'è bisogno di una telemetria firmata?
Per le attività critiche aziendali, sì (ricevute/firme). Per le metriche basta la correlazione e l'hash.

Cosa facciamo con le riprese?
Chiavi idipotenti, deduplicazione sul ricevitore e elaboratori repeat-safe.

Riassunto: La rete aperta è una combinazione di standard e disciplina: specifiche e sabbia, firme e idemoticità, quote e politica cost-aware, osservabilità e verifiche dimostrabili, migrazioni chiare e un'economia onesta. Seguendo questa lista di assegni, l'ecosistema ottiene una rapida integrazione, una qualità prevedibile e una crescita sostenibile.