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



