Skip to content
MCP server for Claude, ChatGPT, Cursor and Claude Code

The REST API for Italian e-invoicing

Send and receive SDI invoices by API, with an SDI simulator for tests.

Already using Getbeel

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

Quickstart

From key to sent invoice in three calls

Base URL: https://www.getbeel.com/api/v1

  • Ferramenta Bellandi S.p.A.46 · Nov 42989,00 €
  • Studio Dentistico Marchetti45 · Nov 31464,00 €
  • Cantina Valle Ombrosa Soc. Agr.44 · Oct 31732,00 €
  • Hotel Lungolago S.r.l.43 · Oct 293050,00 €
  • Pasticceria Ferri di Ferri L. & C. S.n.c.42 · Oct 27610,00 €
  • Officina Meccanica Rinaldi S.r.l.41 · Oct 241830,00 €
  • Agriturismo Le Colline40 · Oct 20540,00 €
  • Studio Associato Conti39 · Oct 162440,00 €
  • Libreria Il Portico38 · Oct 12312,30 €
  • Vivaio Fratelli Neri37 · Oct 8975,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"

Resources

What the API covers

Italian legal terms stay Italian (codice_destinatario, natura, tipo_documento); everything else is English.

  • companies

    The companies (P.IVA) you act for: fiscal data, regime fiscale, SDI readiness.

    POST /v1/companiesGET /v1/companies/{id}
  • invoices

    Outgoing invoices and credit notes (TD01, TD02, TD04, TD05, TD06, TD24, TD25): draft, send, reopen after a rejection.

    POST /v1/invoicesPOST /v1/invoices/{id}/sendPOST /v1/invoices/{id}/reopenPOST /v1/invoices/{id}/credit-notes
  • received-invoices

    Turn SDI receiving on, then list the invoices received on your codice destinatario or collected from email, and approve them.

    POST /v1/sdi-receivingGET /v1/received-invoicesPOST /v1/received-invoices/{id}/approve
  • connections

    Connect a mailbox or use your forwarding address, scan it and get collected supplier invoices as data.

    POST /v1/connections/emailPOST /v1/connections/{id}/scanGET /v1/forwarding-address
  • reconciliations

    Upload a bank statement and get the matches to review and the payments without an invoice.

    POST /v1/bank-statementsGET /v1/reconciliations/{id}/matchesGET /v1/unmatched/payments
  • taxes

    Italian companies: tax deadlines, VAT registers and filings (F24, LIPE) prepared for you to check.

    GET /v1/companies/me/tax-calendarGET /v1/companies/me/vat-registersPOST /v1/filings
  • Keys, scopes and conventions

    • Test keys (gb_test_…) use the sandbox, live keys (gb_live_…) the real SDI. Same endpoints.
    • Keys are scoped (invoices:read, invoices:write, bank:read…), revocable and shown once.
    • OAuth 2.1 with PKCE for MCP clients (Claude, ChatGPT, Cursor).
    • Every POST that creates or sends takes an Idempotency-Key, kept for 24 hours.
    • JSON with snake_case fields, ISO 8601 dates and amounts as decimal strings ("122.00").
    • Errors have a type, a code and the parameter at fault. SDI rejection codes are on the invoice as sdi.error_codes.
  • An event for every SDI receipt, payment and deadline

    HTTPS POST with a Getbeel-Signature header (HMAC-SHA256), retried with backoff for about 3 days. You manage endpoints in the app (Settings → API keys & MCP).
  • Test every outcome before going live

    The outcome depends on the invoice you send, so your tests stay deterministic.

SDKs and tools

Use any HTTP client today

The OpenAPI 3.1 spec is the source for the reference docs, the SDKs and the MCP tools.

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

Terminal

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

Start automating all your financials with AI