Saltar al contenido
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

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

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 €
  • Studio Dentistico Marchetti45 · 3 nov1464,00 €
  • Cantina Valle Ombrosa Soc. Agr.44 · 31 oct732,00 €
  • Hotel Lungolago S.r.l.43 · 29 oct3050,00 €
  • Pasticceria Ferri di Ferri L. & C. S.n.c.42 · 27 oct610,00 €
  • Officina Meccanica Rinaldi S.r.l.41 · 24 oct1830,00 €
  • Agriturismo Le Colline40 · 20 oct540,00 €
  • Studio Associato Conti39 · 16 oct2440,00 €
  • Libreria Il Portico38 · 12 oct312,30 €
  • Vivaio Fratelli Neri37 · 8 oct975,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"

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.

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

Empieza a automatizar toda tu gestión financiera con IA