# Banca e riconciliazione (https://docs.getbeel.com/it/api/bank-reconciliation)

Carica un estratto conto, lascia che l'AI abbini i pagamenti alle fatture ricevute e poi verifica gli abbinamenti.

La stessa riconciliazione della pagina **Riconciliazioni** dell'app: Getbeel legge un estratto conto, salva un movimento per riga e abbina ogni pagamento a una fattura ricevuta (fornitore). Poi tu confermi gli abbinamenti, correggi quelli sbagliati e vedi cosa manca.

<Callout title="Le modifiche solo con chiavi live">
  I dati bancari sono reali: non c'è una sandbox. Le chiavi di test
  (`gb_test_…`) possono leggere estratti conto, movimenti e abbinamenti;
  caricare e verificare richiede una chiave live (`gb_live_…`), altrimenti `403
  livemode_required`. Ogni movimento nuovo di un estratto caricato costa
  0,02 € dal saldo prepagato (`402 insufficient_balance` se non basta).
</Callout>

Scope: `bank:read` per leggere, `bank:write` per caricare e verificare.

## 1. Carica un estratto conto [#1-carica-un-estratto-conto]

PDF, CSV o TXT, oppure un file della banca: CBI (rendicontazione RH), CAMT.053 (XML ISO 20022) o MT940; fino a 50 MB (esporta prima un foglio di calcolo in CSV). I file CBI, CAMT.053 e MT940 vengono riconosciuti dal contenuto e letti in modo esatto, senza IA; PDF e CSV vengono letti con l'IA. Invia il file in multipart:

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-statements \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@estratto-ottobre.csv" \
  -F "currency=EUR"
```

Le richieste sono limitate a circa 4 MB. Per file più grandi (fino a 50 MB) metti il file online e invia JSON con `file_url` (`https` pubblico, senza redirect):

```bash
curl -X POST https://www.getbeel.com/api/v1/bank-statements \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_url": "https://example.com/estratto-ottobre.pdf" }'
```

La risposta è `202` con l'estratto conto in stato `pending`. L'elaborazione prosegue in background:

| Stato        | Significato                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| `pending`    | In coda                                                                           |
| `processing` | Lettura del file                                                                  |
| `parsed`     | Movimenti salvati (webhook `bank_statement.parsed`)                               |
| `matching`   | Abbinamento AI alle fatture ricevute                                              |
| `review`     | Fatto: gli abbinamenti aspettano la verifica (webhook `reconciliation.completed`) |
| `completed`  | Segnato come concluso nell'app                                                    |
| `failed`     | Non leggibile: riprova con `POST /reconciliations`                                |

`GET /bank-statements/{id}` restituisce anche la banca, il periodo e il saldo iniziale e finale (quando l'estratto conto riporta il saldo progressivo).

## 2. Verifica gli abbinamenti [#2-verifica-gli-abbinamenti]

Una riconciliazione ha lo stesso id del suo estratto conto:

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

curl "https://www.getbeel.com/api/v1/reconciliations/$STATEMENT_ID/matches?state=to_confirm" \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

Ogni movimento ha un abbinamento. `match_type` è `exact`, `fuzzy` (da controllare), `manual` o `unmatched`, con una `confidence` da `0.00` a `1.00`. `state` dice cosa fare:

| Stato               | Significato                                                 |
| ------------------- | ----------------------------------------------------------- |
| `to_confirm`        | È stata trovata una fattura: approvala o rifiutala          |
| `reconciled`        | Confermato                                                  |
| `missing_invoice`   | Nessuna fattura trovata per questo pagamento                |
| `no_invoice_needed` | Confermato che non serve (commissioni, imposte, giroconti…) |
| `rejected`          | Il suggerimento era sbagliato                               |

Poi:

- `POST /reconciliations/{id}/matches/{matchId}/approve`: la fattura è giusta (per un pagamento senza fattura: non ne serve una).
- `POST /reconciliations/{id}/matches/{matchId}/reject`: il suggerimento è sbagliato.
- `POST /reconciliations/{id}/matches` con `{ "transaction_id", "invoice_id" }`: collega a mano una fattura ricevuta.
- `POST /reconciliations` con `{ "statement_id" }`: rilegge e riabbina da capo (sostituisce movimenti e abbinamenti).

## 3. Cosa manca [#3-cosa-manca]

- `GET /unmatched/payments`: uscite senza fattura, cioè i documenti da chiedere ai fornitori.
- `GET /unmatched/invoices`: fatture ricevute a cui non è abbinato nessun pagamento.

Entrambi accettano `from` e `to` (`YYYY-MM-DD`) e la consueta [paginazione](/it/api/pagination). `GET /bank-transactions` elenca tutti i movimenti, con i filtri `statement_id`, `from`, `to` e `status`.

## Con un assistente AI [#con-un-assistente-ai]

Il [server MCP](/it/api/mcp) ha `upload_bank_statement`, `get_bank_statement`, `get_reconciliation`, `list_unmatched`, `approve_match` e `match_manually`. L'assistente ti chiede conferma prima di ogni modifica.
