Servidor MCP para Claude, ChatGPT, Cursor y Claude Code
La API REST para la facturación electrónica italiana
Envía y recibe facturas SDI por API, con un simulador SDI de pruebas.
Ya lo usan
Inicio rápido
De la clave a la factura enviada en tres llamadas
URL base: https://www.getbeel.com/api/v1
- Ferramenta Bellandi S.p.A.46 · 4 nov2989,00 €Entregada
- Studio Dentistico Marchetti45 · 3 nov1464,00 €Entregada
- Cantina Valle Ombrosa Soc. Agr.44 · 31 oct732,00 €Emitida · en el cassetto fiscale
- Hotel Lungolago S.r.l.43 · 29 oct3050,00 €Entregada
- Pasticceria Ferri di Ferri L. & C. S.n.c.42 · 27 oct610,00 €Enviada al SDI
- Officina Meccanica Rinaldi S.r.l.41 · 24 oct1830,00 €Entregada
- Agriturismo Le Colline40 · 20 oct540,00 €Entregada
- Studio Associato Conti39 · 16 oct2440,00 €Entregada
- Libreria Il Portico38 · 12 oct312,30 €Entregada
- Vivaio Fratelli Neri37 · 8 oct975,00 €Entregada
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"Recursos
Qué cubre la API
Los términos fiscales italianos se quedan en italiano (codice_destinatario, natura, tipo_documento); el resto está en inglés.
- companies
Las empresas (P.IVA) para las que operas: datos fiscales, régimen fiscal, preparación para el SDI.
POST /v1/companiesGET /v1/companies/{id} - invoices
Facturas emitidas y notas de crédito (TD01, TD02, TD04, TD05, TD06, TD24, TD25): borrador, envío y reapertura tras un rechazo.
POST /v1/invoicesPOST /v1/invoices/{id}/sendPOST /v1/invoices/{id}/reopenPOST /v1/invoices/{id}/credit-notes - received-invoices
Activa la recepción SDI y luego lista las facturas recibidas en tu codice destinatario o recopiladas del email, y apruébalas.
POST /v1/sdi-receivingGET /v1/received-invoicesPOST /v1/received-invoices/{id}/approve - connections
Conecta un buzón o usa tu dirección de reenvío, escanéalo y recibe como datos las facturas de proveedores recopiladas.
POST /v1/connections/emailPOST /v1/connections/{id}/scanGET /v1/forwarding-address - reconciliations
Sube un extracto y obtén los casamientos por revisar y los pagos sin factura.
POST /v1/bank-statementsGET /v1/reconciliations/{id}/matchesGET /v1/unmatched/payments - taxes
Empresas italianas: vencimientos fiscales, registros de IVA y obligaciones (F24, LIPE) preparados para revisar.
GET /v1/companies/me/tax-calendarGET /v1/companies/me/vat-registersPOST /v1/filings
Claves, permisos y convenciones
- Las claves de prueba (gb_test_…) usan el sandbox, las live (gb_live_…) el SDI real. Mismos endpoints.
- Las claves tienen permisos (invoices:read, invoices:write, bank:read…), se pueden revocar y se muestran una sola vez.
- OAuth 2.1 con PKCE para clientes MCP (Claude, ChatGPT, Cursor).
- Cada POST que crea o envía acepta un Idempotency-Key, que se guarda 24 horas.
- JSON con campos en snake_case, fechas ISO 8601 e importes como cadenas decimales ("122.00").
- Los errores tienen un tipo, un código y el parámetro que falla. Los códigos de rechazo del SDI están en la factura, en sdi.error_codes.
Un evento por cada recibo del SDI, pago y vencimiento
POST HTTPS con la cabecera Getbeel-Signature (HMAC-SHA256), con reintentos y backoff durante unos 3 días. Los endpoints se gestionan en la app (Configuración → Claves API y MCP).Prueba cada resultado antes de pasar a producción
El resultado depende de la factura que envías, así tus pruebas son deterministas.
SDKs y herramientas
Hoy funciona con cualquier cliente HTTP
La especificación OpenAPI 3.1 es la fuente de la documentación de referencia, los SDKs y las herramientas 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



