GetbeelDocs
API referenceReceived invoices

Receive an invoice in the sandbox

Test keys only (403 test_mode_required with a live key). Receives a FatturaPA (your XML or base64 .p7m, or a sample addressed to your company when the body is empty) as if a supplier sent it through SDI: it is parsed like a real one, listed by GET /received-invoices with the test key (source sdi, status pending_review) and fires received_invoice.created to test webhook endpoints. Nothing reaches the app.

POST
/sandbox/inbound-invoices

Test keys only (403 test_mode_required with a live key). Receives a FatturaPA (your XML or base64 .p7m, or a sample addressed to your company when the body is empty) as if a supplier sent it through SDI: it is parsed like a real one, listed by GET /received-invoices with the test key (source sdi, status pending_review) and fires received_invoice.created to test webhook endpoints. Nothing reaches the app.

Authorization

apiKey
headerAuthorizationBearer <token>

API key: gb_test_… or gb_live_…

Header Parameters

Idempotency-Key?string

Recommended. Retrying with the same key and body within 24 hours replays the first response (header Idempotent-Replayed: true) instead of acting twice. The same key with a different body returns 422 idempotency_key_reused.

Lengthlength <= 255
Getbeel-Company?string

Act on one of the account's client companies (its id from GET /companies) instead of the key's own account. 404 company_not_found when the key cannot act on it.

Formatuuid

Request Body

application/json
  1. body
xml?string

A FatturaPA XML (or base64 .p7m) to receive. Omit it to receive a sample invoice addressed to your company.

Length1 <= length <= 5242880

Response Body

OK

application/json
  1. response
object*string
id*string
source*string

How the invoice reached getbeel: sdi (received through SDI on the company codice destinatario), email, forwarded, bank_transaction, manual, …

invoice_number*string|null
invoice_type*string
invoice_date*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
Formatdate
due_date*|null
status*string
payment_status*string
category*string
currency*string
amount_subtotal*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
amount_tax*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
amount_total*string

Decimal amount as a string

Match^-?\d+\.\d{2}$
vendor*
reverse_charge*|

The reverse-charge autofattura getbeel proposed for this invoice of a foreign supplier (null when none applies). The XML draft is on the Autofatture page; sending it to SdI is always a user action.

created_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
updated_at*string
Match^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
Formatdate-time
Example Request
curl -X POST 'https://www.getbeel.com/api/v1/sandbox/inbound-invoices' \  -H 'Content-Type: application/json' \  -d '{}'
Example Response
{  "object": "received_invoice",  "id": "string",  "source": "email",  "invoice_number": "string",  "invoice_type": "invoice",  "invoice_date": "2026-10-29",  "due_date": "2026-10-29",  "status": "verified",  "payment_status": "string",  "category": "string",  "currency": "string",  "amount_subtotal": "122.00",  "amount_tax": "122.00",  "amount_total": "122.00",  "vendor": {    "name": "string",    "vat_number": "string",    "email": "string",    "country": "string",    "city": "string",    "address": "string"  },  "reverse_charge": {    "tipo_documento": "TD17",    "status": "proposed",    "reason": "non_eu_services",    "deadline_basis": "receipt",    "deadline": "2026-10-29"  },  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}