Receiving from SDI
Receive supplier invoices from the Sistema di Interscambio, with codice destinatario, checklist and sandbox.
Getbeel receives from the Sistema di Interscambio (SDI) the invoices suppliers send to your company and adds them to the received invoices, read from the XML (signed .p7m files too). You find them with GET /received-invoices and source: "sdi", next to the ones collected from email, forwarding or uploads.
Scopes: received_invoices:read to read the status, received_invoices:write to turn receiving on and for the sandbox.
How it works
- Turn receiving on with
POST /sdi-receiving(or in the app, Settings → SDI receiving). It needs complete company data (422 company_not_ready) and the SDI add-on (402 sdi_addon_required). Live keys only (403 livemode_required). - The response has the codice destinatario to give to suppliers.
- Register the code as indirizzo telematico in the Agenzia delle Entrate area (Fatture e Corrispettivi). The company does it, once: see the guide. From then on every invoice reaches Getbeel, whatever code the supplier wrote.
- Each received invoice creates a received invoice (
status: "pending_review",source: "sdi") and sends thereceived_invoice.createdwebhook.
If the same document was already collected from email (same supplier, number and date), Getbeel links it to the existing one instead of creating a second, and sends no new webhook.
curl -X POST https://getbeel.com/api/v1/sdi-receiving \
-H "Authorization: Bearer $GETBEEL_LIVE_KEY" \
-H "Idempotency-Key: $(uuidgen)"Status and checklist
GET /sdi-receiving returns:
| Field | Meaning |
|---|---|
status | not_enabled, pending, active or error (last_error says why) |
codice_destinatario | The code to give suppliers and register as indirizzo telematico |
fiscal_id | The P.IVA (or codice fiscale) you receive for |
indirizzo_telematico.confirmed | A member confirmed in the app that it is registered (Getbeel cannot check it) |
conservazione | The status of the free AdE conservazione: not_activated, active, expired, with dates |
readiness.steps | company_data, sdi_addon, receiving_enabled, indirizzo_telematico, conservazione (recommended), each with done |
links | The Fatture e Corrispettivi portal and the Agenzia's information page |
A P.IVA can receive in one Getbeel workspace only: a second attempt answers 409 fiscal_id_taken.
Cost
Each invoice received from SDI costs €0.18 on the rate card (pricing). An invoice collected from email is billed as email extraction, not SDI receiving; if the same invoice also arrives from SDI, the SDI receipt counts.
Sandbox
With a test key, POST /sandbox/inbound-invoices receives an invoice as if it came from SDI: pass your XML (or a base64 .p7m) in xml, or send an empty body to receive a sample invoice addressed to your company. MCP: create_sandbox_inbound_invoice.
curl -X POST https://getbeel.com/api/v1/sandbox/inbound-invoices \
-H "Authorization: Bearer $GETBEEL_TEST_KEY"The invoice shows in GET /received-invoices with the same test key (source: "sdi") and the received_invoice.created webhook goes to test endpoints. Nothing shows in the app. An unreadable XML answers 422 invoice_unreadable.
MCP
The get_sdi_receiving_status tool reads the status and the checklist; list_received_invoices takes source: "sdi". Turning receiving on stays in the app or the API: the company does the Agenzia delle Entrate registration itself.
Today receiving goes through an accredited transmission provider (openapi.com): the codice destinatario is theirs. Invoices that cannot be matched to a company stay in quarantine and we check them by hand.