# Receiving from SDI (https://docs.getbeel.com/en/api/sdi-receiving)

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 [#how-it-works]

1. **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`).
2. The response has the **codice destinatario** to give to suppliers.
3. **Register the code as indirizzo telematico** in the Agenzia delle Entrate area (Fatture e Corrispettivi). The company does it, once: see the [guide](/en/guide/codice-destinatario). From then on every invoice reaches Getbeel, whatever code the supplier wrote.
4. Each received invoice creates a received invoice (`status: "pending_review"`, `source: "sdi"`) and sends the `received_invoice.created` webhook.

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.

```bash
curl -X POST https://getbeel.com/api/v1/sdi-receiving \
  -H "Authorization: Bearer $GETBEEL_LIVE_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## Status and checklist [#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](/en/guide/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 [#cost]

Each invoice received from SDI costs €0.18 on the rate card ([pricing](/en/api/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 [#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`.

```bash
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 [#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.

<Callout type="info">
  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.
</Callout>
