GetbeelDocs

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}/approve moves an invoice from pending_review (or rejected) to verified, like reviewing it in the app. Already verified: nothing changes.
  • POST /received-invoices/{id}/reject moves it from pending_review (or verified) to rejected: 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).

reverse_charge
{
  "tipo_documento": "TD17",
  "status": "proposed",
  "reason": "non_eu_services",
  "deadline_basis": "effettuazione",
  "deadline": "2026-12-15"
}
  • tipo_documento: TD17 services from abroad, TD18 goods from another EU state, TD19 goods already in Italy; null when 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).
  • reason and deadline are 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" }'
Response
{
  "object": "received_invoice_upload",
  "id": "scan_1794408453000_k3j9x2a",
  "status": "pending",
  "files": 1,
  "processed": 0,
  "skipped": 0,
  "error": null
}
  • Send file_url (a public https URL, no redirects) or file_base64 with file_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: pending and processing while the AI reads it, completed when the invoice is in the list with status: "pending_review", failed with the reason in error. skipped counts files that were not an invoice or were a duplicate.
StatuscodeWhen
413payload_too_largeThe file is over 50 MB
415unsupported_file_typeNot a PDF, JPEG, PNG or WEBP (FatturaPA XML arrives through SDI receiving)
402credits_exhaustedNo 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 /categories lists them in the app's order. POST /categories adds one: its slug comes from the label, its colour from the next preset unless you send color (#rrggbb or hsl()).
  • PATCH /categories/{id} renames or recolours one; the slug stays. DELETE /categories/{id} deletes one and moves its invoices to other. Default categories cannot be deleted (409 default_category).
  • POST /received-invoices/{id}/category with { "category": "software" } sets an invoice's category (422 unknown_category for 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" }'
  • type is invoice_scan (the default: reading received invoices) or fattura_emessa (drafting issued invoices from Stripe payments). The scope follows the type: invoice_scan rules take the received_invoices scopes, fattura_emessa rules the invoices scopes.
  • 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-rules lists them (filter with type). 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.

  • Connections: connect a mailbox and scan it for invoices.
  • SDI receiving: receive supplier invoices straight from SDI.
  • Webhooks: received_invoice.created for every new invoice.

On this page