Vai al contenuto
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à

  • VideoTok
  • TaxCoach
  • Mimoso
  • Editby
  • Pillar
  • Roses.ee
  • Funnel Consulting

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 €
  • Studio Dentistico Marchetti45 · 3 nov1464,00 €
  • Cantina Valle Ombrosa Soc. Agr.44 · 31 ott732,00 €
  • Hotel Lungolago S.r.l.43 · 29 ott3050,00 €
  • Pasticceria Ferri di Ferri L. & C. S.n.c.42 · 27 ott610,00 €
  • Officina Meccanica Rinaldi S.r.l.41 · 24 ott1830,00 €
  • Agriturismo Le Colline40 · 20 ott540,00 €
  • Studio Associato Conti39 · 16 ott2440,00 €
  • Libreria Il Portico38 · 12 ott312,30 €
  • Vivaio Fratelli Neri37 · 8 ott975,00 €

GET /v1/invoices

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.

api/send-invoice.mjs
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

Terminale

  1. $ node send-invoice.mjs
  2. sent
  3. ↳ webhook invoice.delivered · RC

Inizia ad automatizzare tutta la gestione finanziaria con l'AI