Quickstart
Create a test key, make your first call, validate an XML and send an invoice in the sandbox.
Send your first e-invoice in about five minutes, in the sandbox: nothing reaches the real SDI and nothing is billed.
Before you start
- A Getbeel account with a team. Settings → Company does not need to be complete for test keys.
- Permission to manage settings in that team (owners and members, not auditors), to create a key.
- Not needed: a card, a plan, a live key or SDI set-up. The sandbox and test keys are free (Pricing).
Using a coding agent?
Copy this prompt into Claude Code, Cursor or 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.Create a test key
In the Getbeel app open Settings → API keys & MCP and create a key in Test mode. The key (gb_test_…) is shown once: copy it right away.
Members who can manage settings can create keys (owners and members, not auditors).
export GETBEEL_API_KEY="gb_test_..."Make your first call
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"
]
}
}The response is shortened. api_key.mode confirms you are using a test key.
Validate a FatturaPA XML
Send an XML file as is, or as JSON { "xml": "…" }. Nothing is sent or stored.
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"]
}Validation uses the official FatturaPA XSD schema (v1.2.3) and the SDI content controls that depend on the file alone (Specifiche tecniche v1.9.1, Appendice 1: VAT and natura, totals with SDI's tolerances, summaries, document type rules), the same checks Getbeel runs before every send. Each error carries the Agenzia delle Entrate code and wording: 00200 for the schema (with the line in the file), 00201 past 50 format errors, 00313–00476 for content. Not checked locally: signatures, the AdE registries (VAT numbers, recipient codes) and duplicates.
Create a draft
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": "Consulting, October", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00" }
]
}'The response is the invoice with status: "draft" and its id. The full list of fields is in the API reference.
Send the draft to the sandbox
curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"With a test key the send goes to the sandbox, which answers like SDI: the invoice moves to sent and then to delivered. Check the status with GET /invoices/{id} or receive webhooks.
Try a rejection
Create another draft with "partita_iva": "00000000000" for the customer and send it: the sandbox rejects it with code 00305 (customer IdCodice not valid) and the invoice becomes rejected: correct it and send it again with the same number and date (see SDI lifecycle). Every outcome is on the Sandbox page.
What just happened
- You created a test key. It acts on your team with your access, only on sandbox data. It is stored as a hash: Getbeel cannot show it again.
GET /mechecked it.api_key.modeistestandapi_key.scopeslists what the key may do.- The XML was validated with the same checks Getbeel runs before every send. Nothing was stored.
- A draft was created with
status: "draft", the next number of the test sequence and today's date. Until you send it, change it withPATCH /invoices/{id}. - The sandbox answered like SDI:
sent, thendelivered(orrejectedwith the SDI code). With a live key the same calls reach the real SDI.
If it fails
| Error | Cause | Fix |
|---|---|---|
401 missing_api_key | No Authorization header | Send -H "Authorization: Bearer $GETBEEL_API_KEY" |
401 invalid_api_key | The key is mistyped, or the variable is empty | echo $GETBEEL_API_KEY, then copy the key again or create a new one |
403 insufficient_scope | The key lacks the scope named in the message | Create a key with that scope (keys cannot be edited) |
403 company_not_eligible | Issuing needs an Italian company profile | Complete Settings → Company |
422 on POST /invoices | A field is missing or invalid; param names it | Fix the field and send again with a new Idempotency-Key |
{
"error": {
"type": "authentication_error",
"code": "missing_api_key",
"message": "No API key provided. Send it as 'Authorization: Bearer gb_…'."
}
}Every code and what to do with it: Errors.