Received invoices
List and review supplier invoices, upload one for the AI to read, and manage the categories and AI rules that file them.
Received invoices are the supplier invoices and receipts of your company: from SDI (source: "sdi"), collected from email (email) or the forwarding address (forwarded), uploaded (manual), or read from a bank movement (bank_transaction). The same list as Received invoices in the app.
Reads take received_invoices:read and work with both key modes. Writes take received_invoices:write and a live key: the books are real, there is no sandbox copy (403 livemode_required with a test key).
List
curl "https://www.getbeel.com/api/v1/received-invoices?status=pending_review" \
-H "Authorization: Bearer $GETBEEL_API_KEY"Newest invoice date first, paginated. Filter by status (processing, pending_review, verified, rejected, exported, missing_document), source, search and date_from / date_to. With a test key the list holds only the invoices received in the sandbox.
MCP: list_received_invoices, and list_collected_documents for those still to review.
Approve or reject
curl -X POST https://www.getbeel.com/api/v1/received-invoices/$INVOICE_ID/approve \
-H "Authorization: Bearer $GETBEEL_API_KEY"POST /received-invoices/{id}/approvemoves an invoice frompending_review(orrejected) toverified, like reviewing it in the app. Already verified: nothing changes.POST /received-invoices/{id}/rejectmoves it frompending_review(orverified) torejected: use it for documents that are not invoices.
MCP: approve_collected_document, with decision: "reject" to reject.
Reverse charge on foreign invoices
An invoice from a foreign supplier collected by email, the forwarding address or an upload carries reverse_charge: the autofattura getbeel proposed for it (null when none applies, for example an Italian supplier or an invoice received through SDI).
{
"tipo_documento": "TD17",
"status": "proposed",
"reason": "non_eu_services",
"deadline_basis": "effettuazione",
"deadline": "2026-12-15"
}tipo_documento:TD17services from abroad,TD18goods from another EU state,TD19goods already in Italy;nullwhen no TD applies or the supplier country is missing. The rule decides it, not the AI.status, the live state of the proposal:proposed(the XML draft is generated automatically),needs_review(check it on the Autofatture page first),needs_country(enter the supplier country),not_required(goods imported from outside the EU: the customs document replaces the TD),generated(the XML draft exists, not sent),sent(handed to SDI),dismissed(deleted by the team).reasonanddeadlineare the ones the rule set when the proposal was made (or when the team set its country and type).deadline: the 15th of the month after the receipt of the invoice (EU suppliers,receipt) or after the purchase (non-EU suppliers,effettuazione), art. 1, c. 3-bis, lett. b, d.lgs. 127/2015.
Sending the autofattura to SDI is always done by a person in the app. Rules and sources: Autofatture.
Upload an invoice
Send a PDF, JPEG, PNG or WEBP (up to 50 MB) for the AI to read, as an upload in the 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
}- Send
file_url(a publichttpsURL, no redirects) orfile_base64withfile_name. The type is read from the file, not its name. - Each file uses one invoice credit (Pricing).
GET /received-invoices/uploads/{id}follows it:pendingandprocessingwhile the AI reads it,completedwhen the invoice is in the list withstatus: "pending_review",failedwith the reason inerror.skippedcounts files that were not an invoice or were a duplicate.
| Status | code | When |
|---|---|---|
| 413 | payload_too_large | The file is over 50 MB |
| 415 | unsupported_file_type | Not a PDF, JPEG, PNG or WEBP (FatturaPA XML arrives through SDI receiving) |
| 402 | credits_exhausted | No invoice credits left |
MCP: upload_received_invoice, get_received_invoice_upload.
Categories
Categories file received invoices by type of cost. A received invoice carries the category's slug 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 /categorieslists them in the app's order.POST /categoriesadds one: its slug comes from the label, its colour from the next preset unless you sendcolor(#rrggbborhsl()).PATCH /categories/{id}renames or recolours one; the slug stays.DELETE /categories/{id}deletes one and moves its invoices toother. Default categories cannot be deleted (409 default_category).POST /received-invoices/{id}/categorywith{ "category": "software" }sets an invoice's category (422 unknown_categoryfor a slug the team doesn't have).
MCP: list_categories, create_category, update_category, delete_category, set_received_invoice_category.
AI rules
Plain-language instructions the AI follows, in order, when it reads your invoices. The same rules as Settings → AI rules.
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" }'typeisinvoice_scan(the default: reading received invoices) orfattura_emessa(drafting issued invoices from Stripe payments). The scope follows the type:invoice_scanrules take thereceived_invoicesscopes,fattura_emessarules theinvoicesscopes.- A new rule goes last of its type and applies to the next invoices the AI reads; invoices already read stay as they are.
GET /ai-ruleslists them (filter withtype).PATCH /ai-rules/{id}changes the text or pauses the rule ("active": false).DELETE /ai-rules/{id}deletes it.
MCP: list_ai_rules, create_ai_rule, update_ai_rule, delete_ai_rule.
Related
- Connections: connect a mailbox and scan it for invoices.
- SDI receiving: receive supplier invoices straight from SDI.
- Webhooks:
received_invoice.createdfor every new invoice.