# Ricezione da SDI (https://docs.getbeel.com/it/api/sdi-receiving)

Ricevi le fatture dei fornitori dal Sistema di Interscambio, con codice destinatario, checklist e sandbox.

Getbeel riceve dal Sistema di Interscambio (SDI) le fatture che i fornitori mandano alla tua azienda e le mette tra le fatture ricevute, già lette dall'XML (anche se firmato `.p7m`). Le trovi con `GET /received-invoices` e `source: "sdi"`, accanto a quelle raccolte da email, inoltro o caricamento.

Scope: `received_invoices:read` per leggere lo stato, `received_invoices:write` per attivare la ricezione e per la sandbox.

## Come funziona [#come-funziona]

1. **Attiva la ricezione** con `POST /sdi-receiving` (o dall'app, in Impostazioni → Ricezione SDI). Servono i dati dell'azienda completi (`422 company_not_ready`) e l'add-on SDI (`402 sdi_addon_required`). Solo chiavi live (`403 livemode_required`).
2. La risposta contiene il **codice destinatario** da dare ai fornitori.
3. **Registra il codice come indirizzo telematico** nell'area riservata dell'Agenzia delle Entrate (Fatture e Corrispettivi). Lo fa l'azienda, una volta: vedi la [guida](/it/guide/codice-destinatario). Da quel momento ogni fattura arriva a Getbeel, qualunque codice abbia scritto il fornitore.
4. Ogni fattura ricevuta crea una fattura ricevuta (`status: "pending_review"`, `source: "sdi"`) e invia il webhook `received_invoice.created`.

Se lo stesso documento era già stato raccolto dalla email (stesso fornitore, numero e data), Getbeel lo collega a quello esistente invece di crearne un secondo, e non invia un nuovo webhook.

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

## Stato e checklist [#stato-e-checklist]

`GET /sdi-receiving` restituisce:

| Campo                            | Significato                                                                                                                |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `status`                         | `not_enabled`, `pending`, `active` o `error` (`last_error` dice perché)                                                    |
| `codice_destinatario`            | Il codice da dare ai fornitori e registrare come indirizzo telematico                                                      |
| `fiscal_id`                      | La P.IVA (o il codice fiscale) per cui ricevi                                                                              |
| `indirizzo_telematico.confirmed` | Un membro ha confermato nell'app di averlo registrato (Getbeel non può verificarlo)                                        |
| `conservazione`                  | Lo stato della [conservazione gratuita AdE](/it/guide/conservazione): `not_activated`, `active`, `expired`, con le date    |
| `readiness.steps`                | `company_data`, `sdi_addon`, `receiving_enabled`, `indirizzo_telematico`, `conservazione` (consigliato), ognuno con `done` |
| `links`                          | Il portale Fatture e Corrispettivi e la pagina informativa dell'Agenzia                                                    |

Una P.IVA può ricevere in un solo workspace Getbeel: un secondo tentativo risponde `409 fiscal_id_taken`.

## Costo [#costo]

Ogni fattura ricevuta dallo SDI costa 0,18 € sul listino ([prezzi](/it/api/pricing)). Una fattura raccolta dalle email si paga come estrazione email, non come ricezione dallo SDI; se la stessa fattura arriva anche dallo SDI, conta la ricezione SDI.

## Sandbox [#sandbox]

Con una chiave di test, `POST /sandbox/inbound-invoices` riceve una fattura come se arrivasse dallo SDI: passa il tuo XML (o un `.p7m` in base64) in `xml`, oppure manda un corpo vuoto per ricevere una fattura di esempio intestata alla tua azienda. MCP: `create_sandbox_inbound_invoice`.

```bash
curl -X POST https://getbeel.com/api/v1/sandbox/inbound-invoices \
  -H "Authorization: Bearer $GETBEEL_TEST_KEY"
```

La fattura compare in `GET /received-invoices` con la stessa chiave di test (`source: "sdi"`) e il webhook `received_invoice.created` va agli endpoint di test. Nell'app non compare nulla. Un XML illeggibile risponde `422 invoice_unreadable`.

## MCP [#mcp]

Il tool `get_sdi_receiving_status` legge lo stato e la checklist; `list_received_invoices` accetta `source: "sdi"`. L'attivazione resta nell'app o nell'API: la registrazione presso l'Agenzia delle Entrate la fa l'azienda.

<Callout type="info">
  Oggi la ricezione passa da un provider di trasmissione accreditato
  (openapi.com): il codice destinatario è il suo. Le fatture che non si riescono
  ad abbinare a un'azienda restano in quarantena e le controlliamo a mano.
</Callout>
