Autenticazione
Chiavi API di test e live, scope e buone pratiche.
Ogni richiesta porta una chiave API nell'header Authorization:

curl https://www.getbeel.com/api/v1/me \
-H "Authorization: Bearer gb_test_..."Chiavi di test e live
| Prefisso | Modalità | Cosa succede all'invio |
|---|---|---|
gb_test_ | Test | L'invio va alla sandbox: nessuna fattura arriva allo SDI |
gb_live_ | Live | La fattura viene trasmessa allo SDI e ha valore fiscale |
Gli endpoint sono gli stessi. Sviluppa e collauda con una chiave di test e passa a una chiave live solo in produzione. Le letture (GET) restituiscono i dati del tuo account in entrambe le modalità.
Creare e gestire le chiavi
Le chiavi si creano in Impostazioni → Chiavi API e MCP nell'app.
- La chiave viene mostrata una sola volta. Getbeel conserva solo un hash e il prefisso (es.
gb_live_a1B2), che vedi nell'elenco. - Puoi impostare una scadenza e revocare una chiave in qualsiasi momento.
- Una chiave appartiene a un team e agisce come il membro che l'ha creata: vede solo i dati di quel team.
- Se il membro esce dal team, le sue chiavi vengono revocate. Se perde il permesso di gestire le impostazioni (per esempio diventa revisore), le sue chiavi restano sospese.
Scope
Quando crei una chiave scegli cosa può fare. Una richiesta a un endpoint fuori dagli scope della chiave riceve 403 insufficient_scope.
| Scope | Consente |
|---|---|
account:read | GET /me, strumento MCP whoami |
invoices:read | GET /invoices, GET /invoices/{id}, strumenti list_invoices, get_invoice |
received_invoices:read | GET /received-invoices, strumento list_received_invoices |
invoices:validate | POST /invoices/validate, strumento validate_invoice |
invoices:write | POST /invoices, POST /invoices/{id}/send, strumenti create_invoice_draft, send_invoice |
received_invoices:write | POST /received-invoices/{id}/approve e /reject, strumento approve_collected_document (chiavi live) |
bank:read | Estratti conto, movimenti, riconciliazioni, abbinamenti, elenchi dei non abbinati |
bank:write | Caricare estratti conto, avviare riconciliazioni, approvare, rifiutare e collegare abbinamenti (chiavi live) |
connections:read | GET /connections, GET /forwarding-address, strumento list_connections |
connections:write | Collegare caselle email e Stripe, scansionare caselle, sincronizzare Stripe (chiavi live) |
taxes:read | Scadenzario fiscale (anche .ics), adempimenti preparati, posizione IVA stimata |
taxes:write | Preparare un adempimento (F24) e caricare la quietanza (chiavi live) |
advisors:read | GET /advisors, strumento list_advisors |
advisors:write | Invitare o rimuovere un commercialista con accesso in sola lettura: POST /advisors, DELETE /advisors/{id} (chiavi live) |
drive:read | Cartelle, file e link di download: GET /drive, GET /drive/files/{id}/download, strumenti list_drive, get_drive_file. I file delle fatture richiedono anche received_invoices:read, gli estratti conto bank:read |
drive:write | Creare una cartella: POST /drive/folders, strumento create_drive_folder (chiavi live) |
billing:write | Creare un link "Aggiungi credito" da far pagare a una persona (POST /billing/topups, strumento create_billing_topup) e un link "Cambia carta" (POST /billing/payment-method, strumento create_billing_card_link) (chiavi live; mai selezionato di default) |
Gli endpoint che creano e inviano fatture richiedono lo scope invoices:write. Le nuove chiavi hanno tutti gli scope selezionati tranne advisors:write, che dà a una persona un accesso duraturo ai dati dell'azienda: togli quelli che a un'integrazione non servono. Gli scope non si possono modificare dopo: crea una nuova chiave.
Dai a ogni integrazione solo gli scope che le servono: una chiave che legge soltanto non può inviare fatture.
Errori di autenticazione
Tutti con stato 401 e type: "authentication_error":
code | Significato |
|---|---|
missing_api_key | Manca l'header Authorization: Bearer … |
invalid_api_key | La chiave non esiste o è scritta male |
api_key_revoked | La chiave è stata revocata |
api_key_expired | La chiave è scaduta |
api_key_suspended | Chi l'ha creata non può più gestire le chiavi |
Buone pratiche
- Tieni la chiave sul server, in una variabile d'ambiente come
GETBEEL_API_KEY. Mai nel codice, nel browser o in un'app mobile. - Usa una chiave per integrazione, così puoi revocarne una senza fermare le altre.
- Se una chiave finisce in un repository o in un log, revocala e creane una nuova.
Client MCP: nessuna chiave
Claude, ChatGPT e Cursor si collegano al server MCP con l'accesso (OAuth 2.1). Il collegamento ha un team, una modalità e degli scope come una chiave, e compare in Impostazioni → Chiavi API e MCP → App collegate.