Server MCP per Claude, ChatGPT, Cursor e Claude Code
L'API REST per la fatturazione elettronica italiana
Invia e ricevi fatture SDI via API, con un simulatore SDI per i test.
Lo usano già
Quickstart
Dalla chiave alla fattura inviata in tre chiamate
URL di base: https://www.getbeel.com/api/v1
- Ferramenta Bellandi S.p.A.46 · 4 nov2989,00 €Consegnata
- Studio Dentistico Marchetti45 · 3 nov1464,00 €Consegnata
- Cantina Valle Ombrosa Soc. Agr.44 · 31 ott732,00 €Emessa · nel cassetto fiscale
- Hotel Lungolago S.r.l.43 · 29 ott3050,00 €Consegnata
- Pasticceria Ferri di Ferri L. & C. S.n.c.42 · 27 ott610,00 €Inviata al SDI
- Officina Meccanica Rinaldi S.r.l.41 · 24 ott1830,00 €Consegnata
- Agriturismo Le Colline40 · 20 ott540,00 €Consegnata
- Studio Associato Conti39 · 16 ott2440,00 €Consegnata
- Libreria Il Portico38 · 12 ott312,30 €Consegnata
- Vivaio Fratelli Neri37 · 8 ott975,00 €Consegnata
export GETBEEL_API_KEY=gb_test_… # test key: simulated SDI curl "https://www.getbeel.com/api/v1/invoices?limit=1" \ -H "Authorization: Bearer $GETBEEL_API_KEY"Risorse
Cosa copre l'API
I termini fiscali italiani restano in italiano (codice_destinatario, natura, tipo_documento); tutto il resto è in inglese.
- companies
Le aziende (P.IVA) per cui operi: dati fiscali, regime fiscale, abilitazione SDI.
POST /v1/companiesGET /v1/companies/{id} - invoices
Fatture emesse e note di credito (TD01, TD02, TD04, TD05, TD06, TD24, TD25): bozza, invio, riapertura dopo uno scarto.
POST /v1/invoicesPOST /v1/invoices/{id}/sendPOST /v1/invoices/{id}/reopenPOST /v1/invoices/{id}/credit-notes - received-invoices
Attivi la ricezione SDI, poi elenchi le fatture ricevute sul tuo codice destinatario o raccolte dalle email e le approvi.
POST /v1/sdi-receivingGET /v1/received-invoicesPOST /v1/received-invoices/{id}/approve - connections
Collega una casella email o usa l'indirizzo di inoltro, avvia la scansione e ricevi come dati le fatture dei fornitori raccolte.
POST /v1/connections/emailPOST /v1/connections/{id}/scanGET /v1/forwarding-address - reconciliations
Carica un estratto conto e ottieni gli abbinamenti da verificare e i pagamenti senza fattura.
POST /v1/bank-statementsGET /v1/reconciliations/{id}/matchesGET /v1/unmatched/payments - taxes
Aziende italiane: scadenze fiscali, registri IVA e adempimenti (F24, LIPE) preparati da controllare.
GET /v1/companies/me/tax-calendarGET /v1/companies/me/vat-registersPOST /v1/filings
Chiavi, permessi e convenzioni
- Le chiavi di test (gb_test_…) usano la sandbox, quelle live (gb_live_…) lo SDI reale. Stessi endpoint.
- Le chiavi hanno permessi specifici (invoices:read, invoices:write, bank:read…), sono revocabili e vengono mostrate una sola volta.
- OAuth 2.1 con PKCE per i client MCP (Claude, ChatGPT, Cursor).
- Ogni POST che crea o invia accetta un Idempotency-Key, conservato per 24 ore.
- JSON con campi in snake_case, date ISO 8601 e importi come stringhe decimali ("122.00").
- Gli errori hanno un tipo, un codice e il parametro errato. I codici di scarto SDI sono sulla fattura, in sdi.error_codes.
Un evento per ogni ricevuta SDI, pagamento e scadenza
POST HTTPS con header Getbeel-Signature (HMAC-SHA256), con retry e backoff per circa 3 giorni. Gli endpoint li gestisci nell'app (Impostazioni → Chiavi API e MCP).Prova ogni esito prima di andare live
L'esito dipende dalla fattura che invii, così i tuoi test restano deterministici.
SDK e strumenti
Oggi funziona con qualsiasi client HTTP
La specifica OpenAPI 3.1 è la fonte per la documentazione di riferimento, gli SDK e i tool MCP.
const headers = {
Authorization: `Bearer ${process.env.GETBEEL_API_KEY}`,
'Content-Type': 'application/json',
};
const draft = await fetch('https://www.getbeel.com/api/v1/invoices', {
method: 'POST',
headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
body: JSON.stringify({
tipo_documento: 'TD01',
customer: {
denominazione: 'Rossi S.r.l.',
partita_iva: 'IT01234567890',
codice_destinatario: 'ABCDE12',
},
lines: [
{ description: 'Consulenza', quantity: '1', unit_price: '1000.00', vat_rate: '22.00' },
],
}),
}).then((res) => res.json());
const sent = await fetch(`https://www.getbeel.com/api/v1/invoices/${draft.id}/send`, {
method: 'POST',
headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
}).then((res) => res.json());
console.log(sent.status); // "sent" with a test key, "sending" with a live key
- $ node send-invoice.mjs
- sent
- ↳ webhook invoice.delivered · RC



