Aller au contenu
Serveur MCP pour Claude, ChatGPT, Cursor et Claude Code

L'API REST de la facturation électronique italienne

Envoyez et recevez des factures SDI par API, avec un simulateur.

Ils l’utilisent déjà

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

Démarrage rapide

De la clé à la facture envoyée en trois appels

URL de base: https://www.getbeel.com/api/v1

  • Ferramenta Bellandi S.p.A.46 · 4 nov.2989,00 €
  • Studio Dentistico Marchetti45 · 3 nov.1464,00 €
  • Cantina Valle Ombrosa Soc. Agr.44 · 31 oct.732,00 €
  • Hotel Lungolago S.r.l.43 · 29 oct.3050,00 €
  • Pasticceria Ferri di Ferri L. & C. S.n.c.42 · 27 oct.610,00 €
  • Officina Meccanica Rinaldi S.r.l.41 · 24 oct.1830,00 €
  • Agriturismo Le Colline40 · 20 oct.540,00 €
  • Studio Associato Conti39 · 16 oct.2440,00 €
  • Libreria Il Portico38 · 12 oct.312,30 €
  • Vivaio Fratelli Neri37 · 8 oct.975,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"

Ressources

Ce que couvre l'API

Les termes fiscaux italiens restent en italien (codice_destinatario, natura, tipo_documento) ; tout le reste est en anglais.

  • companies

    Les sociétés (P.IVA) pour lesquelles vous agissez : données fiscales, régime fiscal, préparation SDI.

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

    Factures émises et avoirs (TD01, TD02, TD04, TD05, TD06, TD24, TD25) : brouillon, envoi, réouverture après un rejet.

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

    Activez la réception SDI, puis listez les factures reçues sur votre codice destinatario ou collectées par e-mail, et approuvez-les.

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

    Connectez une boîte mail ou utilisez votre adresse de transfert, lancez l'analyse et récupérez les factures fournisseurs collectées sous forme de données.

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

    Importez un relevé et obtenez les rapprochements à vérifier et les paiements sans facture.

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

    Sociétés italiennes : échéances fiscales, registres de TVA et déclarations (F24, LIPE) préparés pour vérification.

    GET /v1/companies/me/tax-calendarGET /v1/companies/me/vat-registersPOST /v1/filings
  • Clés, permissions et conventions

    • Les clés de test (gb_test_…) utilisent la sandbox, les clés live (gb_live_…) le vrai SDI. Mêmes endpoints.
    • Les clés ont des permissions (invoices:read, invoices:write, bank:read…), sont révocables et affichées une seule fois.
    • OAuth 2.1 avec PKCE pour les clients MCP (Claude, ChatGPT, Cursor).
    • Chaque POST qui crée ou envoie accepte un Idempotency-Key, conservé 24 heures.
    • JSON avec des champs en snake_case, des dates ISO 8601 et des montants en chaînes décimales ("122.00").
    • Les erreurs ont un type, un code et le paramètre en cause. Les codes de rejet du SDI figurent sur la facture dans sdi.error_codes.
  • Un événement pour chaque accusé SDI, paiement et échéance

    POST HTTPS avec l'en-tête Getbeel-Signature (HMAC-SHA256), relancé avec backoff pendant environ 3 jours. Les endpoints se gèrent dans l'app (Paramètres → Clés API et MCP).
  • Testez chaque issue avant la mise en production

    L'issue dépend de la facture envoyée, vos tests restent donc déterministes.

SDK et outils

Fonctionne dès aujourd'hui avec n'importe quel client HTTP

La spécification OpenAPI 3.1 alimente la documentation de référence, les SDK et les outils 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

Commencez à automatiser toute votre gestion financière avec l'IA