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.
Le fatture ricevute sono le fatture e le ricevute dei fornitori della tua azienda: dallo SDI (source: "sdi"), raccolte dalle email (email) o dall'indirizzo di inoltro (forwarded), caricate (manual) o lette da un movimento bancario (bank_transaction). È lo stesso elenco di Fatture ricevute nell'app.
Le letture richiedono received_invoices:read e vanno con entrambe le modalità di chiave. Le scritture richiedono received_invoices:write e una chiave live: la contabilità è reale, non ne esiste una copia nella sandbox (403 livemode_required con una chiave di test).
Elencare
curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
-H "Authorization: Bearer $GETBEEL_API_KEY"Dalla data fattura più recente, con paginazione. Filtra per status (processing, pending_review, verified, rejected, exported, missing_document), source, search e date_from / date_to. Con una chiave di test l'elenco contiene solo le fatture ricevute nella sandbox.
MCP: list_received_invoices, e list_collected_documents per quelle ancora da controllare.
Approvare o rifiutare
curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
-H "Authorization: Bearer $GETBEEL_API_KEY"POST /received-invoices/{id}/approveporta una fattura dapending_review(orejected) averified, come quando la controlli nell'app. Già verificata: non cambia nulla.POST /received-invoices/{id}/rejectla porta dapending_review(overified) arejected: usalo per i documenti che non sono fatture.
MCP: approve_collected_document, con decision: "reject" per rifiutare.
Reverse charge sulle fatture estere
Una fattura di un fornitore estero raccolta via email, dall'indirizzo di inoltro o da un caricamento porta reverse_charge: l'autofattura che getbeel ha proposto (null se non serve, per esempio fornitore italiano o fattura ricevuta dallo SDI).
{
"tipo_documento": "TD17",
"status": "proposed",
"reason": "non_eu_services",
"deadline_basis": "effettuazione",
"deadline": "2026-12-15"
}tipo_documento:TD17servizi dall'estero,TD18beni da un altro stato UE,TD19beni già in Italia;nullse nessun TD si applica o manca il paese del fornitore. Lo decide la regola, non l'AI.status, lo stato attuale della proposta:proposed(la bozza XML è generata da sola),needs_review(verificala prima nella pagina Autofatture),needs_country(inserisci il paese del fornitore),not_required(beni importati da fuori UE: vale il documento doganale, nessun TD),generated(la bozza XML esiste, non inviata),sent(consegnata allo SDI),dismissed(eliminata dal team).reasonedeadlinesono quelli fissati dalla regola quando la proposta è stata creata (o quando il team ne ha impostato paese e tipo).deadline: il 15 del mese successivo alla ricezione della fattura (fornitori UE,receipt) o all'acquisto (fornitori extra UE,effettuazione), art. 1, c. 3-bis, lett. b, d.lgs. 127/2015.
L'invio dell'autofattura allo SDI lo fa sempre una persona nell'app. Regole e fonti: Autofatture.
Caricare una fattura
Invia un PDF, JPEG, PNG o WEBP (fino a 50 MB) da far leggere all'AI, come un caricamento nell'app.
curl -X POST https://www.getbeel.com/api/v1/received-invoices/uploads \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "file_url": "https://example.com/fattura-rossi.pdf" }'{
"object": "received_invoice_upload",
"id": "scan_1794408453000_k3j9x2a",
"status": "pending",
"files": 1,
"processed": 0,
"skipped": 0,
"error": null
}- Invia
file_url(un URLhttpspubblico, senza redirect) oppurefile_base64confile_name. Il tipo si legge dal file, non dal nome. - Ogni file usa un credito fattura (Prezzi).
GET /received-invoices/uploads/{id}lo segue:pendingeprocessingmentre l'AI lo legge,completedquando la fattura è nell'elenco constatus: "pending_review",failedcon il motivo inerror.skippedconta i file che non erano fatture o erano duplicati.
| Stato | code | Quando |
|---|---|---|
| 413 | payload_too_large | Il file supera i 50 MB |
| 415 | unsupported_file_type | Non è un PDF, JPEG, PNG o WEBP (gli XML FatturaPA arrivano dalla ricezione SDI) |
| 402 | credits_exhausted | Crediti fattura esauriti |
MCP: upload_received_invoice, get_received_invoice_upload.
Categorie
Le categorie archiviano le fatture ricevute per tipo di costo. Una fattura ricevuta porta lo slug della categoria in category.
curl -X POST https://www.getbeel.com/api/v1/categories \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "label": "Software" }'GET /categoriesle elenca nell'ordine dell'app.POST /categoriesne aggiunge una: lo slug viene dal nome, il colore dal prossimo predefinito, se non inviicolor(#rrggbbohsl()).PATCH /categories/{id}rinomina o ricolora una categoria; lo slug resta.DELETE /categories/{id}la elimina e sposta le sue fatture inother. Le categorie predefinite non si eliminano (409 default_category).POST /received-invoices/{id}/categorycon{ "category": "software" }imposta la categoria di una fattura (422 unknown_categoryper uno slug che il team non ha).
MCP: list_categories, create_category, update_category, delete_category, set_received_invoice_category.
Regole AI
Istruzioni in linguaggio naturale che l'AI segue, in ordine, quando legge le tue fatture. Le stesse regole di Impostazioni → Regole AI.
curl -X POST https://www.getbeel.com/api/v1/ai-rules \
-H "Authorization: Bearer $GETBEEL_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "text": "Le fatture di Amazon Web Services vanno nella categoria software" }'typeèinvoice_scan(il predefinito: la lettura delle fatture ricevute) ofattura_emessa(le bozze delle fatture emesse dai pagamenti Stripe). Lo scope segue il tipo: le regoleinvoice_scanrichiedono gli scopereceived_invoices, quellefattura_emessagli scopeinvoices.- Una regola nuova va in fondo al suo tipo e vale per le prossime fatture che l'AI legge; quelle già lette restano come sono.
GET /ai-rulesle elenca (filtra contype).PATCH /ai-rules/{id}cambia il testo o mette in pausa la regola ("active": false).DELETE /ai-rules/{id}la elimina.
MCP: list_ai_rules, create_ai_rule, update_ai_rule, delete_ai_rule.
Correlati
- Connessioni: collega una casella e cercaci le fatture.
- Ricezione SDI: ricevi le fatture dei fornitori direttamente dallo SDI.
- Webhook:
received_invoice.createdper ogni nuova fattura.