Quickstart
Crea una chiave di test, fai la prima chiamata, valida un XML e invia una fattura nella sandbox.
Invia la tua prima fattura elettronica in circa cinque minuti, nella sandbox: niente arriva allo SDI vero e niente si paga.
Prima di iniziare
- Un account Getbeel con un team. Per le chiavi di test Impostazioni → Azienda non deve essere completa.
- Il permesso di gestire le impostazioni in quel team (titolari e membri, non i revisori), per creare una chiave.
- Non servono: una carta, un piano, una chiave live o la configurazione SDI. La sandbox e le chiavi di test sono gratuite (Prezzi).
Usi un agente di programmazione?
Copia questo prompt in Claude Code, Cursor o Codex.
Add the Getbeel API to this project.
1. Read https://docs.getbeel.com/en/api/quickstart.md and https://docs.getbeel.com/llms.txt before writing code.
2. Read the API key from the GETBEEL_API_KEY environment variable. Never hard-code it. Use a test key (gb_test_...) until I say otherwise.
3. Base URL: https://www.getbeel.com/api/v1. Call GET /me first to check the key.
4. Validate invoices with POST /invoices/validate and create drafts with POST /invoices.
5. Show me the draft and wait for my OK before calling POST /invoices/{id}/send.
6. Send an Idempotency-Key header (a new UUID per operation) on every POST that creates or sends.
7. Handle errors by error.type and error.code; on 429 wait for the Retry-After seconds.Crea una chiave di test
Nell'app Getbeel apri Impostazioni → Chiavi API e MCP e crea una chiave in modalità Test. La chiave (gb_test_…) viene mostrata una volta sola: copiala subito.
Possono creare chiavi i membri con il permesso di gestire le impostazioni (proprietari e membri, non i revisori).
export GETBEEL_API_KEY="gb_test_..."Fai la prima chiamata
curl https://www.getbeel.com/api/v1/me \
-H "Authorization: Bearer $GETBEEL_API_KEY"{
"object": "account",
"id": "5b0c2f8e-6a3d-4c1e-9f0a-2d7b1e4c9a10",
"name": "Rossi S.r.l.",
"slug": "rossi",
"company": {
"name": "Rossi S.r.l.",
"vat_number": "01234567890",
"regime_fiscale": "RF01",
"sdi_configured": true
},
"api_key": {
"prefix": "gb_test_a1B2",
"mode": "test",
"scopes": [
"account:read",
"invoices:read",
"received_invoices:read",
"invoices:validate"
]
}
}La risposta è abbreviata. api_key.mode ti conferma che stai usando una chiave di test.
Valida un XML FatturaPA
Manda un file XML così com'è, oppure in JSON come { "xml": "…" }. Niente viene inviato né salvato.
curl https://www.getbeel.com/api/v1/invoices/validate \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/xml" \
--data-binary @fattura.xml{
"object": "validation_result",
"valid": false,
"tipo_documento": "TD01",
"errors": [
{
"code": "00421",
"message": "DatiRiepilogo (rate 22): Imposta 30 does not match calculated 22.00"
}
],
"checks": ["structure", "xsd", "business_rules"]
}La validazione usa lo schema XSD ufficiale FatturaPA (v1.2.3) e i controlli SdI sul contenuto che dipendono dal solo file (Specifiche tecniche v1.9.1, Appendice 1: IVA e natura, totali con le tolleranze SdI, riepiloghi, regole per tipo documento), gli stessi controlli che Getbeel esegue prima di ogni invio. Ogni errore ha il codice e la descrizione dell'Agenzia delle Entrate: 00200 per lo schema (con la riga del file), 00201 oltre 50 errori di formato, 00313–00476 per i contenuti. Non controllati in locale: firme, anagrafe tributaria (partite IVA, codici destinatario) e duplicati.
Crea una bozza
curl https://www.getbeel.com/api/v1/invoices \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"tipo_documento": "TD01",
"customer": {
"denominazione": "Bianchi S.p.A.",
"partita_iva": "01234567890",
"country": "IT",
"codice_destinatario": "ABCDE12",
"address": "Via Roma 1",
"postal_code": "20121",
"city": "Milano",
"province": "MI"
},
"lines": [
{ "description": "Consulenza ottobre", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00" }
]
}'La risposta è la fattura con status: "draft" e il suo id. L'elenco completo dei campi è nel riferimento API.
Invia la bozza nella sandbox
curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Con una chiave di test l'invio va alla sandbox, che risponde come lo SDI: la fattura passa a sent e poi a delivered. Controlla lo stato con GET /invoices/{id} oppure ricevi i webhook.
Prova uno scarto
Crea un'altra bozza con "partita_iva": "00000000000" per il cliente e inviala: la sandbox la scarta con il codice 00305 (IdCodice del cliente non valido) e la fattura passa a rejected: correggila e inviala di nuovo con lo stesso numero e la stessa data (vedi ciclo di vita SDI). Tutti gli esiti sono nella pagina Sandbox.
Cosa è successo
- Hai creato una chiave di test. Agisce sul tuo team con i tuoi accessi, solo sui dati della sandbox. È salvata come hash: Getbeel non può mostrarla di nuovo.
GET /mel'ha verificata.api_key.modeètesteapi_key.scopeselenca cosa può fare la chiave.- L'XML è stato validato con gli stessi controlli che Getbeel fa prima di ogni invio. Non è stato salvato nulla.
- È stata creata una bozza con
status: "draft", il numero successivo della sequenza di test e la data di oggi. Finché non la invii, la modifichi conPATCH /invoices/{id}. - La sandbox ha risposto come lo SDI:
sent, poidelivered(oppurerejectedcon il codice SDI). Con una chiave live le stesse chiamate arrivano allo SDI vero.
Se qualcosa non va
| Errore | Causa | Soluzione |
|---|---|---|
401 missing_api_key | Manca l'header Authorization | Invia -H "Authorization: Bearer $GETBEEL_API_KEY" |
401 invalid_api_key | La chiave è sbagliata o la variabile è vuota | echo $GETBEEL_API_KEY, poi copia di nuovo la chiave o creane una nuova |
403 insufficient_scope | Alla chiave manca il permesso indicato nel messaggio | Crea una chiave con quel permesso (le chiavi non si modificano) |
403 company_not_eligible | Per emettere serve un profilo aziendale italiano | Completa Impostazioni → Azienda |
422 su POST /invoices | Un campo manca o non è valido; param dice quale | Correggi il campo e invia di nuovo con un nuovo Idempotency-Key |
{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No API key provided. Send it as 'Authorization: Bearer gb_…'."
}
}Tutti i codici e cosa fare: Errori.
Prossimi passi
Webhook
Ricevi un evento firmato per ogni esito SDI, senza interrogare l'API.
MCP
Fai preparare le fatture a Claude, ChatGPT o Cursor, e approvale tu.
Passa a live
Crea una chiave live quando il flusso nella sandbox funziona dall'inizio alla fine.
SDK e CLI
Le stesse chiamate in TypeScript, Python o dal terminale.