Collegamento banca
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 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
-
Crea un account su Enable Banking.
-
Nel pannello di controllo 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. -
In "Allowed redirect URLs" aggiungi esattamente:
https://getbeel.com/api/open-banking/callback -
Attiva l'applicazione con "Activate by linking accounts": in modalità limitata l'applicazione legge solo i conti collegati lì.
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.
Collega una banca
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"
}
EOFGetbeel prova la chiave con una chiamata reale, la salva cifrata (non viene mai restituita) e avvia l'accesso alla banca. Risposta 201:
{
"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
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. Ogni conto ha IBAN, saldo, numero di movimenti sincronizzati e pending_transactions (vedi sotto).
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.
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
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
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
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
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.