# Collegamento banca (https://docs.getbeel.com/it/api/bank-connections)

Movimenti bancari automatici con Enable Banking, usando l'applicazione Enable Banking della tua azienda.

Getbeel scarica i movimenti dei conti correnti ogni 6 ore e li abbina alle fatture, come se ogni mese arrivasse un estratto conto. Il collegamento passa da [Enable Banking](https://enablebanking.com) con **la tua applicazione Enable Banking**: tu la registri a nome della tua azienda, Getbeel firma le chiamate con la sua chiave privata.

Scope: `bank:read` per leggere, `bank:write` per collegare, ricollegare, sincronizzare e scollegare. La lettura funziona con qualsiasi chiave; le modifiche richiedono una chiave live (`403 livemode_required`). Ogni conto collegato costa 2 € al mese e ogni movimento importato 0,02 €, dal saldo prepagato (`402 insufficient_balance` se non basta).

## Prima di iniziare [#prima-di-iniziare]

1. Crea un account su [Enable Banking](https://enablebanking.com/sign-in/).
2. Nel [pannello di controllo](https://enablebanking.com/cp/applications) registra un'applicazione nell'ambiente **Production** (o **Sandbox** per provare con la banca di prova "Mock ASPSP"). Scegli "Generate in the browser" ed esporta la chiave privata `.pem`.
3. In "Allowed redirect URLs" aggiungi esattamente:

   ```text
   https://getbeel.com/api/open-banking/callback
   ```

4. Attiva l'applicazione con "Activate by linking accounts": in modalità limitata l'applicazione legge solo i conti collegati lì.

<Callout type="warn">
  Enable Banking descrive la modalità limitata come pensata per la valutazione e
  per l'uso "individuale non commerciale". Verifica con Enable Banking che il
  tuo uso rientri nelle condizioni, o firma con loro un contratto.
</Callout>

## Collega una banca [#collega-una-banca]

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-connections \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @- <<EOF
{
  "application_id": "aaaaaaaa-1111-2222-3333-444444444444",
  "private_key": "$(awk '{printf "%s\\n", $0}' private.pem)",
  "bank": { "name": "Intesa Sanpaolo", "country": "IT" },
  "psu_type": "business"
}
EOF
```

Getbeel prova la chiave con una chiamata reale, la salva cifrata (non viene mai restituita) e avvia l'accesso alla banca. Risposta `201`:

```json
{
  "object": "bank_connection",
  "id": "5b0c…",
  "status": "pending",
  "bank": { "name": "Intesa Sanpaolo", "country": "IT" },
  "authorization_url": "https://getbeel.com/bank-login?t=…",
  "redirect_url_registered": true,
  "accounts": []
}
```

Apri `authorization_url` in un browser. È una pagina di Getbeel che mostra il nome del tuo team, così chi accede vede a quale team vanno i suoi conti; **Continua** porta alla banca. Lì autorizza la lettura dei conti (fino a 180 giorni, secondo la banca), poi arriva nell'app Getbeel. La prima sincronizzazione (ultimi 90 giorni) parte subito. Il nome della banca è quello dell'elenco di Enable Banking (`GET /aspsps` con la tua applicazione, oppure il selettore nell'app).

Errori: `422 bank_credentials_invalid` (ID o chiave rifiutati), `422 redirect_url_not_allowed` (manca l'URL del passo 3), `409 bank_connection_limit` (al massimo 10 banche per team).

## Elenco e stato [#elenco-e-stato]

```bash
curl https://www.getbeel.com/api/v1/bank-connections \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

`status`: `pending` (accesso alla banca non completato), `active`, `requires_reconnect` (consenso scaduto o revocato). `consent_expires_at` e `expires_soon` (meno di 7 giorni) dicono quando [ricollegare](#ricollega). Ogni conto ha IBAN, saldo, numero di movimenti sincronizzati e `pending_transactions` (vedi sotto).

## Ricollega [#ricollega]

Le banche chiedono di nuovo il consenso almeno ogni 180 giorni (PSD2; spesso prima, secondo la banca). Sette giorni prima della scadenza Getbeel manda un'email ai proprietari del team, invia il webhook `bank_connection.expiring` e mostra in Riconciliazione un avviso con il pulsante Ricollega; quando il consenso è scaduto (o la banca l'ha revocato) fa lo stesso con `bank_connection.expired`, una volta per consenso. Entrambi i webhook contengono la `BankConnection` e vanno solo agli endpoint live.

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-connections/$ID/reconnect \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "language": "it" }'
```

La risposta è il collegamento con un nuovo `authorization_url` (valido 30 minuti): aprilo in un browser e accedi di nuovo alla banca. Il consenso precedente viene chiuso, i conti vengono ritrovati (stessi IBAN, stessi estratti mensili) e parte subito una sincronizzazione. Il corpo è facoltativo. Errori: `409 bank_connection_conflict` (banca non ancora scelta), gli stessi `422` del collegamento, `402 insufficient_balance` se il saldo non copre il mese del conto.

## Dove finiscono i movimenti [#dove-finiscono-i-movimenti]

Per ogni conto e mese Getbeel crea un estratto conto con `source: "open_banking"` (in `GET /bank-statements`), senza file. Ogni sincronizzazione aggiunge i movimenti contabilizzati nuovi, senza doppioni, e avvia l'abbinamento alle fatture solo per i movimenti nuovi. Arrivano i webhook `bank_statement.parsed` (movimenti aggiunti) e poi `reconciliation.completed`. I movimenti sono in `GET /bank-transactions` e negli abbinamenti, come per gli estratti caricati.

**Movimenti in attesa.** I movimenti che la banca non ha ancora contabilizzato (stato Enable Banking `PDNG`, lo stato ISO 20022 delle registrazioni in attesa) non sono movimenti contabili: sono elencati per conto in `pending_transactions` (gli ultimi 50, importi con segno), non vengono mai abbinati e sono sostituiti a ogni sincronizzazione. Quando la banca ne contabilizza uno, arriva in `GET /bank-transactions` come gli altri.

**Fornitore e autofattura.** Prima dell'abbinamento ogni nuovo movimento in uscita riceve gli stessi campi AI degli estratti caricati: paese del fornitore, partita IVA e indirizzo quando noti, se è estero e se serve un'autofattura (TD17, TD18 o TD19), così i fornitori esteri pagati da una banca collegata compaiono in Autofatture. Il nome inviato dalla banca resta quello.

## Sincronizza ora [#sincronizza-ora]

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-connections/$ID/sync \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Getbeel sincronizza già ogni 6 ore. Le banche consentono circa quattro letture al giorno senza l'utente presente e questa chiamata ne usa una: quando sono finite risponde `429 bank_daily_limit`. Altri errori: `409 sync_in_progress`, `409 bank_connection_inactive`, `409 bank_connection_requires_reconnect`.

## Scollega [#scollega]

```bash
curl -X DELETE https://www.getbeel.com/api/v1/bank-connections/$ID \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Chiude il consenso presso la banca e cancella la chiave. Estratti, movimenti e abbinamenti restano.

## MCP [#mcp]

Gli assistenti AI hanno `list_bank_connections`, `sync_bank_connection` e `reconnect_bank_connection` (restituisce il link che l'utente apre per accedere alla banca). Collegare una nuova banca richiede la chiave privata, che non passa mai da un assistente: si fa nell'app o con l'API.
