GetbeelDocs

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

  1. Crea un account su Enable Banking.

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

  3. In "Allowed redirect URLs" aggiungi esattamente:

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

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"
}
EOF

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

In questa pagina