GetbeelDocs

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:

StatoSignificato
pendingIn coda
processingLettura del file
parsedMovimenti salvati (webhook bank_statement.parsed)
matchingAbbinamento AI alle fatture ricevute
reviewFatto: gli abbinamenti aspettano la verifica (webhook reconciliation.completed)
completedSegnato come concluso nell'app
failedNon 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:

StatoSignificato
to_confirmÈ stata trovata una fattura: approvala o rifiutala
reconciledConfermato
missing_invoiceNessuna fattura trovata per questo pagamento
no_invoice_neededConfermato che non serve (commissioni, imposte, giroconti…)
rejectedIl 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

  • 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.

In questa pagina