Manuale simulatori e sistemi esterni

Dal simulatore al provider reale

Dal simulatore al provider reale#

Sostituire un simulatore con un endpoint non significa avere un’integrazione produttiva. La qualificazione deve coprire contratto operativo, sicurezza, semantica degli stati, riconciliazione, responsabilità e continuità.

Le fasi#

simulatore locale
→ stub contrattuale
→ sandbox del provider
→ test integrato con dati sintetici
→ collaudo con operatori reali
→ pilot controllato
→ produzione

Ogni passaggio deve chiudere criteri espliciti. Non usare il pilot per scoprire la semantica base degli errori.

Scheda del provider#

Per ogni sistema compilare:

Nome e soggetto responsabile:
Funzione:
Provider ID:
Ambiente e base URL:
Owner CertiExch:
Owner del provider:
Dati scambiati:
Protocollo e schema:
Autenticazione:
Idempotenza:
Stati e codici errore:
Finalità o valore della ricevuta:
SLA e cut-off:
Riconciliazione:
Retention:
Subfornitori:
RPO/RTO:
Exit e portabilità:

Contratto funzionale#

Concordare:

operazioni supportate;
campi obbligatori;
unità e arrotondamenti;
macchina a stati;
codici di eccezione;
retry e lookup;
idempotenza;
cancellazione e irrevocabilità;
ricezione parziale;
correzioni;
timestamp e timezone;
versioning dello schema.

Le descrizioni testuali non bastano: servono esempi di payload, test vectors e casi negativi.

Sicurezza#

Verificare:

TLS e certificati;
autenticazione server e client;
secret management;
rotazione credenziali;
allowlist di rete;
firma dei messaggi quando necessaria;
anti-replay;
segregazione delle chiavi;
logging privo di segreti;
vulnerability management;
incident notification;
audit e penetration test.

Privacy e dati#

Definire:

categorie di dati;
base giuridica;
minimizzazione;
pseudonimizzazione;
localizzazione;
retention;
accessi;
data breach process;
cancellazione o anonimizzazione;
subprocessor.

Il fatto che il canale sia cifrato non rende lecito inviare dati non necessari.

Prestazioni e capacità#

Misurare:

throughput sostenuto e di picco;
latenza mediana e percentile elevato;
dimensione massima payload/file;
numero di connessioni;
finestra batch;
timeout;
rate limit;
comportamento sotto retry;
recupero dopo indisponibilità;
backlog massimo.

Per Asset Lots o servicing massivo, testare volumi realistici e non soltanto una singola istruzione.

Resilienza#

Il provider deve documentare:

health per capability;
circuit breaker e backoff;
code e persistenza;
deduplica;
replica;
disaster recovery;
RPO/RTO;
manutenzioni programmate;
failover;
modalità manuale controllata;
procedure di rientro.

Riconciliazione indipendente#

Una vera integrazione deve poter verificare lo stato anche fuori dal canale primario:

lookup distinto dall’invio;
statement periodico;
file di quadratura;
explorer/RPC alternativo per rail;
ricevuta firmata;
report di fine giornata.

Senza una fonte di riconciliazione, un timeout può restare irrisolvibile.

Test di accettazione minimi#

Happy path.
Duplicato identico.
Stessa idempotency key con payload diverso.
Campo mancante.
Importo/quantità fuori limite.
Timeout prima e dopo l’accettazione.
Risposta tardiva.
Provider degradato/offline.
Errore business.
Partial execution.
Correzione.
Replay e firma errata.
Riconciliazione dopo recovery.
Rotazione credenziali.
Continuità/exit.

Passaggio di configurazione#

Prima di attivare il provider reale:

disabilitare il simulatore;
configurare endpoint e provider ID;
caricare credenziali nel secret store;
verificare health e certificati;
validare il profilo di capability;
creare allarmi;
eseguire test non distruttivi;
approvare il change;
predisporre rollback.

Go/no-go#

Il go-live richiede approvazione congiunta di:

owner di dominio;
responsabile del registro/operazioni;
sicurezza;
compliance/privacy;
infrastruttura;
provider;
business continuity;
controllo o audit, quando previsto.