Connessione API#

Le API consentono ai sistemi reali dell’intermediario di sostituire progressivamente il Client fornito. La WebUI è una specifica eseguibile; il contratto ufficiale è contracts/openapi-v1.json insieme agli schemi runtime.

Credenziali#

Un client API è emesso dal Core o da CLI. Il segreto viene mostrato una sola volta e deve essere conservato nel secret store del partecipante. La pagina del Client non deve visualizzarlo.

Intestazioni tipiche:

X-Client-Id: <client-id>
X-Client-Secret: <secret>
Idempotency-Key: <uuid-univoco>
X-Request-Timestamp: <ISO-8601>
X-Request-Nonce: <valore-univoco>
Content-Type: application/json

Usare HTTPS. Non inserire il segreto in URL, log, ticket o screenshot.

Idempotenza e replay#

Riutilizzare la stessa Idempotency-Key solo per ritentare la stessa richiesta identica.
Se cambia il payload, usare una nuova chiave.
Il nonce deve essere unico nella finestra prevista.
Il timestamp deve rientrare nella tolleranza configurata.
Una risposta di replay coerente non indica una seconda esecuzione.

Famiglie principali#

Endpoint	Uso
`catalogue.php`	Catalogo Composer e componenti
`onboarding.php`	Pratiche e presentazioni
`dossiers.php`	Dossier cristallizzati
`issuer_intermediary_mandates.php`	Mandati e capability
`premarket.php`	Interesse, Q&A e consultazioni
`issuance.php`	Sottoscrizioni e allocazioni
`rfqs.php`	RFQ, quote, match e OTC
`asset_lots.php`	Lotti statici e servicing post-cessione
`availability.php`	Attestazioni di disponibilità
`registration_positions.php`	Posizioni aggregate
`servicing.php`	Obbligazioni e attestazioni
`events.php`	Feed degli eventi del partecipante

Procedura di integrazione#

Errori HTTP#

Classe	Interpretazione
400	Payload o transizione non valida
401	Credenziali mancanti/non valide
403	Scope o ruolo insufficiente
404	Oggetto non visibile o inesistente
409	Conflitto di stato/idempotenza
422	Validazione di dominio fallita
429	Rate limit
500/503	Errore interno o provider indisponibile; verificare esito prima del retry

Riconciliazione#

Non considerare completata un’operazione perché la chiamata ha restituito 200. Conservare identificativo, stato e receipt; verificare successivamente il feed eventi o l’oggetto di dominio.

Versionamento#

Il Client deve registrare la versione del contratto usato. Una nuova release applicativa può mantenere la stessa famiglia API ma cambiare schemi o capability. Testare sempre contro il pacchetto consegnato.