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à
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 €Remise
- Studio Dentistico Marchetti45 · 3 nov.1464,00 €Remise
- Cantina Valle Ombrosa Soc. Agr.44 · 31 oct.732,00 €Émise · dans le cassetto fiscale
- Hotel Lungolago S.r.l.43 · 29 oct.3050,00 €Remise
- Pasticceria Ferri di Ferri L. & C. S.n.c.42 · 27 oct.610,00 €Envoyée au SDI
- Officina Meccanica Rinaldi S.r.l.41 · 24 oct.1830,00 €Remise
- Agriturismo Le Colline40 · 20 oct.540,00 €Remise
- Studio Associato Conti39 · 16 oct.2440,00 €Remise
- Libreria Il Portico38 · 12 oct.312,30 €Remise
- Vivaio Fratelli Neri37 · 8 oct.975,00 €Remise
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.
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



