Primi passi

Flusso di integrazione

Percorso corretto di un’integrazione iframe. Il callback viene inviato prima che il frontend venga notificato.

sequenceDiagram
participant Utente
participant Web
participant Widget as Wealth Reader Widget
participant API as Wealth Reader API
participant Banca as Istituto finanziario
Utente->>Web: Apre l'applicazione
Web->>Widget: Carica l'iframe con operation_id
Utente->>Widget: Sceglie un istituto e dà il consenso
Widget->>API: Richiede i dati con operation_id
API->>Banca: Interrogazione
Banca-->>API: Risponde
API-->>Widget: Restituisce i dati normalizzati
Widget->>Web: POST al callback (operation_id + token + payload)
Web-->>Widget: HTTP 200 e status ok
Widget-->>Web: postMessage flow completed
Web-->>Utente: Mostra il completamento con successo

Chi fa che cosa

Attore	Responsabilità
Il vostro frontend	Genera un `operation_id` univoco, carica il widget e ascolta `postMessage`.
Il widget	Mostra banche, login, 2FA ed errori all’utente.
L’API di Wealth Reader	Comunica con l’istituto e normalizza la risposta.
Il vostro backend	Espone l’URL di callback, risponde `{"status":"ok"}` e memorizza `operation_id`, `token` e payload.

Se qualcosa fallisce

Password errata, 2FA o errore dell’istituto: il widget lo gestisce con l’utente. Il vostro frontend può ricevere un JSON di errore via postMessage; il callback non viene chiamato finché la lettura non termina con successo.
Il vostro callback non restituisce 200 + {"status":"ok"}: l’utente non vede il successo e il frontend non riceve flow completed.
Un token smette di funzionare (cambio password, nuovo 2FA): riaprite il widget passando quel token così l’utente può riautenticarsi.

Il dettaglio dei messaggi e del corpo del callback è nelle pagine iframe.

Passo successivo

Se integrate via iframe, proseguite con frontend e poi backend. Se non potete incorporare un iframe, andate a OAuth.

Ultimo aggiornamento 2026-08-15