GetbeelDocs

Autenticazione

Chiavi API di test e live, scope e buone pratiche.

Ogni richiesta porta una chiave API nell'header Authorization:

La pagina Chiavi API e MCP: chiavi di test e live, permessi e indirizzo del server MCP.

curl https://www.getbeel.com/api/v1/me \
  -H "Authorization: Bearer gb_test_..."

Chiavi di test e live

PrefissoModalitàCosa succede all'invio
gb_test_TestL'invio va alla sandbox: nessuna fattura arriva allo SDI
gb_live_LiveLa 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.

ScopeConsente
account:readGET /me, strumento MCP whoami
invoices:readGET /invoices, GET /invoices/{id}, strumenti list_invoices, get_invoice
received_invoices:readGET /received-invoices, strumento list_received_invoices
invoices:validatePOST /invoices/validate, strumento validate_invoice
invoices:writePOST /invoices, POST /invoices/{id}/send, strumenti create_invoice_draft, send_invoice
received_invoices:writePOST /received-invoices/{id}/approve e /reject, strumento approve_collected_document (chiavi live)
bank:readEstratti conto, movimenti, riconciliazioni, abbinamenti, elenchi dei non abbinati
bank:writeCaricare estratti conto, avviare riconciliazioni, approvare, rifiutare e collegare abbinamenti (chiavi live)
connections:readGET /connections, GET /forwarding-address, strumento list_connections
connections:writeCollegare caselle email e Stripe, scansionare caselle, sincronizzare Stripe (chiavi live)
taxes:readScadenzario fiscale (anche .ics), adempimenti preparati, posizione IVA stimata
taxes:writePreparare un adempimento (F24) e caricare la quietanza (chiavi live)
advisors:readGET /advisors, strumento list_advisors
advisors:writeInvitare o rimuovere un commercialista con accesso in sola lettura: POST /advisors, DELETE /advisors/{id} (chiavi live)
drive:readCartelle, 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:writeCreare una cartella: POST /drive/folders, strumento create_drive_folder (chiavi live)
billing:writeCreare 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":

codeSignificato
missing_api_keyManca l'header Authorization: Bearer …
invalid_api_keyLa chiave non esiste o è scritta male
api_key_revokedLa chiave è stata revocata
api_key_expiredLa chiave è scaduta
api_key_suspendedChi 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.

In questa pagina