> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Avvio rapido dei dati bancari: collegare una banca di test e leggere le transazioni

> Dall'applicazione sandbox ai conti, saldi e transazioni della Test Bank di Didit: crea una chiave e un link, collega, leggi, sincronizza ed elimina.

I dati bancari sono disponibili per le applicazioni sandbox.
Le chiamate di un'applicazione live ricevono una risposta `404` finché l'accesso live non viene annunciato, e in sandbox non viene addebitato nulla.
Questa guida rapida ti accompagna da un'applicazione sandbox ai conti, ai saldi e alle transazioni della Didit Test Bank, con richieste da copiare e incollare.

> [!NOTE]
>
> Ogni risposta qui sotto è abbreviata ai soli campi rilevanti.
> Conserva la chiave API sul tuo server: non arriva mai a un browser o a un'app.

## Passaggio 1: crea una chiave API con l'autorizzazione Bank data

Bank data non fa parte dell'accesso completo.
Una chiave con accesso completo, inclusa la chiave segreta principale dell'applicazione, viene rifiutata in tutte le chiamate a Bank data con `403 bank_data_access_denied`.

1. Nella [Business Console](https://business.didit.me), apri la tua applicazione sandbox e vai su **Chiavi API**.
2. Crea una chiave con accesso personalizzato e aggiungi **Bank data**: **Read** per le letture, **Write** per le chiamate che creano, modificano o eliminano qualcosa.
3. Copia la chiave ed esportala:

```bash theme={null}
export DIDIT_API_KEY="your-sandbox-key"
```

Consulta [Chiavi API](https://docs.didit.me/it/console/api-keys.md) per l'elenco completo delle risorse.

## Passo 2: crea un link

Un link corrisponde a un percorso attraverso le schermate in cui una persona collega una banca.
Crea un link continuativo per la Test Bank:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/links/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "access": "ongoing",
    "country": "ESP",
    "data": ["accounts", "balances", "transactions"],
    "history_days": 90,
    "vendor_data": "client-7731"
  }'
```

`country` è il paese, in formato di tre lettere, della banca della persona ed è facoltativo.
Invialo quando lo conosci, così la persona vede solo le banche di quel paese; senza di esso sceglie tra tutti i paesi che puoi servire.
Per un accesso una tantum invia `"access": "one_time"` (il valore predefinito).

```json theme={null}
{
  "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40",
  "mode": "connect",
  "access": "ongoing",
  "status": "created",
  "url": "https://verify.didit.me/bank/link/...",
  "expires_at": "2026-11-22T13:00:00Z",
  "connection_id": null
}
```

Conserva l'`id` del link insieme al tuo utente.
`url` e `client_token` vengono restituiti una sola volta, al momento della creazione del link.

## Passaggio 3: apri il link e collega la Didit Test Bank

Apri l'`url` in un browser oppure invialo alla persona via email o chat.
La persona vede la schermata di consenso, sceglie **Didit Test Bank**, accede con uno dei clienti di prova e sceglie i conti da condividere.
La [pagina sandbox](https://docs.didit.me/it/core-technology/bank-verification/sandbox.md) elenca i clienti di prova e ciò che ciascuno ti consente di ottenere.

Per riportare la persona sul tuo sito al termine, consulta [Torna al tuo sito](https://docs.didit.me/it/integration/bank-link/return-to-your-site.md).
Senza un `redirect_url` la persona termina sulla pagina dei risultati di Didit e tu conosci l'esito tramite il webhook o da una lettura.

## Passaggio 4: ricevi i webhook e conferma

Sottoscrivi una destinazione webhook agli eventi `bank.*` nella console, come per qualsiasi [webhook](https://docs.didit.me/it/integration/webhooks.md).
Quando l'utente completa il processo, arriva `bank.link.completed` con il `link_id` e il `connection_id`, poi `bank.connection.created` quando la prima sincronizzazione ha salvato i conti.

Non fidarti mai di un ID del link che ti invia il browser.
Leggi tu stesso il link:

```bash theme={null}
curl https://verification.didit.me/v3/bank/links/$LINK_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{ "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40", "status": "completed", "connection_id": "5e1d2a70-3b4c-4d5e-8f60-71829304a5b6" }
```

Lo `status` è `completed` oppure uno stato finale (`cancelled`, `expired`, `failed`). Un link `failed` riporta un `error.code`; uno `cancelled` riporta `error: null`.

## Passaggio 5: leggere conti, saldi e transazioni

```bash theme={null}
curl https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/accounts/ -H "x-api-key: $DIDIT_API_KEY"
curl https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/balances/ -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/transactions/?date_from=2026-01-01" -H "x-api-key: $DIDIT_API_KEY"
```

Gli importi sono stringhe decimali, negative per le uscite di denaro.
Una pagina di transazioni contiene `next_page_token` finché sono disponibili altri dati da leggere.
Consulta [Conti, saldi e transazioni](https://docs.didit.me/it/core-technology/bank-verification/accounts-balances-transactions.md).

## Passaggio 6: segui il flusso delle modifiche

Il flusso delle modifiche restituisce solo ciò che è cambiato dall'ultima lettura.
La prima lettura, senza cursore, è l'istantanea completa: ogni transazione della connessione, ciascuna come `added`, con `reset: true`.
Una prima pagina può contenere `has_more: true` con un `next_page_token` e nessun `next_cursor` per ora.
Continua a leggere con `page_token` finché `has_more` è `true`, e conserva il `next_cursor` dell'ultima pagina (quella con `has_more: false`) per la lettura successiva:

```bash theme={null}
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/" -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?page_token=$NEXT_PAGE_TOKEN" -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?cursor=$NEXT_CURSOR" -H "x-api-key: $DIDIT_API_KEY"
```

`reset: true` indica che la risposta è un'istantanea completa: sostituisci la tua copia con quella invece di aggiungere dati.
`bank.data.updated` ti avvisa quando una sincronizzazione ha salvato dati nuovi.

## Passaggio 7: sincronizza ora

Una connessione attiva si sincronizza da sola.
Per leggere subito i dati della banca, richiedi una sincronizzazione:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/refresh/ -H "x-api-key: $DIDIT_API_KEY"
```

Una banca consente un numero limitato di letture automatiche al giorno.
`sync.live_syncs_left_today` e `sync.budgets` sulla connessione indicano quante ne restano e quando vengono azzerate. Una chiamata oltre il limite restituisce `429 refresh_limit_reached` con l'orario di reset.
Vedi [Aggiornare i dati bancari su richiesta](https://docs.didit.me/it/use-cases/refresh-bank-data-on-demand.md).

## Passaggio 8: interrompi l'accesso ed elimina

Interrompere l'accesso ed eliminare sono due chiamate diverse.

```bash theme={null}
# Stop access at the bank. The connection keeps its data until you delete it.
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/revoke/ -H "x-api-key: $DIDIT_API_KEY"

# Delete the connection and its data. Irreversible.
curl -X DELETE https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

Una connessione eliminata risponde solo con `id`, `status`, `status_reason`, `created_at` ed `erasure`.
Vedi [Dati, consenso ed eliminazione](https://docs.didit.me/it/core-technology/bank-verification/data-consent-and-deletion.md).

## Prossimi passi

* [Connessioni](https://docs.didit.me/it/core-technology/bank-verification/connections.md): accesso una tantum e continuo, consenso e rinnovo.
* [Webhook bancari](https://docs.didit.me/it/core-technology/bank-verification/webhooks.md)
* [Prezzi](https://docs.didit.me/it/getting-started/bank-verification-pricing.md)
* [Riferimento API](https://docs.didit.me/it/standalone-apis/bank-data.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.