GetbeelDocs

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}/approve porta una fattura da pending_review (o rejected) a verified, come quando la controlli nell'app. Già verificata: non cambia nulla.
  • POST /received-invoices/{id}/reject la porta da pending_review (o verified) a rejected: 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).

reverse_charge
{
  "tipo_documento": "TD17",
  "status": "proposed",
  "reason": "non_eu_services",
  "deadline_basis": "effettuazione",
  "deadline": "2026-12-15"
}
  • tipo_documento: TD17 servizi dall'estero, TD18 beni da un altro stato UE, TD19 beni già in Italia; null se 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).
  • reason e deadline sono 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" }'
Risposta
{
  "object": "received_invoice_upload",
  "id": "scan_1794408453000_k3j9x2a",
  "status": "pending",
  "files": 1,
  "processed": 0,
  "skipped": 0,
  "error": null
}
  • Invia file_url (un URL https pubblico, senza redirect) oppure file_base64 con file_name. Il tipo si legge dal file, non dal nome.
  • Ogni file usa un credito fattura (Prezzi).
  • GET /received-invoices/uploads/{id} lo segue: pending e processing mentre l'AI lo legge, completed quando la fattura è nell'elenco con status: "pending_review", failed con il motivo in error. skipped conta i file che non erano fatture o erano duplicati.
StatocodeQuando
413payload_too_largeIl file supera i 50 MB
415unsupported_file_typeNon è un PDF, JPEG, PNG o WEBP (gli XML FatturaPA arrivano dalla ricezione SDI)
402credits_exhaustedCrediti 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 /categories le elenca nell'ordine dell'app. POST /categories ne aggiunge una: lo slug viene dal nome, il colore dal prossimo predefinito, se non invii color (#rrggbb o hsl()).
  • PATCH /categories/{id} rinomina o ricolora una categoria; lo slug resta. DELETE /categories/{id} la elimina e sposta le sue fatture in other. Le categorie predefinite non si eliminano (409 default_category).
  • POST /received-invoices/{id}/category con { "category": "software" } imposta la categoria di una fattura (422 unknown_category per 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) o fattura_emessa (le bozze delle fatture emesse dai pagamenti Stripe). Lo scope segue il tipo: le regole invoice_scan richiedono gli scope received_invoices, quelle fattura_emessa gli scope invoices.
  • 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-rules le elenca (filtra con type). 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.created per ogni nuova fattura.

In questa pagina