Banca e riconciliazione
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.
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).
Scope: bank:read per leggere, bank:write per caricare e verificare.
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:
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):
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
Una riconciliazione ha lo stesso id del suo estratto conto:
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}/matchescon{ "transaction_id", "invoice_id" }: collega a mano una fattura ricevuta.POST /reconciliationscon{ "statement_id" }: rilegge e riabbina da capo (sostituisce movimenti e abbinamenti).
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. GET /bank-transactions elenca tutti i movimenti, con i filtri statement_id, from, to e status.
Con un assistente AI
Il server 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.