Ricezione da SDI
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
- 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). - La risposta contiene il codice destinatario da dare ai fornitori.
- 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. Da quel momento ogni fattura arriva a Getbeel, qualunque codice abbia scritto il fornitore.
- Ogni fattura ricevuta crea una fattura ricevuta (
status: "pending_review",source: "sdi") e invia il webhookreceived_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.
curl -X POST https://getbeel.com/api/v1/sdi-receiving \
-H "Authorization: Bearer $GETBEEL_LIVE_KEY" \
-H "Idempotency-Key: $(uuidgen)"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: 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
Ogni fattura ricevuta dallo SDI costa 0,18 € sul listino (prezzi). 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
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.
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
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.
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.
Più aziende (multi-company)
Software house, marketplace e commercialisti gestiscono le aziende dei clienti da un solo account, con una sola chiave API.
Fatture ricevute
Elenca e controlla le fatture dei fornitori, caricane una da far leggere all'AI e gestisci le categorie e le regole AI che le archiviano.