BeeL MCP server

Official

Overview Schema Source Related Servers Discussions Admin

beel_void_invoice

DestructiveIdempotent

Voids an issued invoice made by mistake, such as a test or accidental duplicate, keeping the document and never reusing its number. Use a corrective invoice if the operation took place.

Instructions

Voids an issued invoice of this company. The document is kept and its number is never reused.

When to use it: the invoice was issued by mistake — the operation never took place, it was a test, or it is an accidental duplicate. If the operation did take place but the invoice is wrong, issue a corrective invoice instead (POST …/{invoice_id}/corrective). The exception is a withholding that should not have been applied: it is not a cause for a corrective, so void the invoice and issue a new one without it.
Sent or paid: voiding an invoice that was already emailed to the customer or paid requires issued_in_error: true, confirming it was issued by mistake; without it the request fails with 422 VOID_REQUIRES_ISSUED_IN_ERROR. What counts is the fact, not the current status: an email in the invoice's sending history (moving it back from SENT to ISSUED does not erase it), or a paid_at (it stays after the invoice is RECTIFIED). Corrective invoices follow the same rule.
Corrected invoices: an invoice with live corrective invoices cannot be voided — it was corrected, so the operation took place; issue another corrective (422 INVOICE_HAS_LIVE_CORRECTIVES). A TOTAL corrective cannot be voided either: the invoice it rectifies would stay voided with nothing to offset it (422 TOTAL_CORRECTIVE_NOT_VOIDABLE).
reason: required, at least 10 characters — it is fiscal data.
void_date: deprecated. A date earlier than the invoice's issue date is rejected with 422 VOID_DATE_BEFORE_ISSUE_DATE.
VeriFactu: when it is enabled for the invoice, a cancellation record is submitted to the AEAT.
PDF: unchanged. The PDF of the invoice stays the one that was delivered; the void is reported by the invoice's status and the invoice.voided webhook.
Proformas: voiding an ACTIVE proforma is a plain status change with no fiscal effect — no corrective invoice, nothing submitted to the AEAT. The voided proforma is kept as the record of a rejected or withdrawn offer and stays listed.

BeeL API endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/void (reference: https://docs.beel.es)

⚠️ Read before calling:

Fiscal rules, domains void, lifecycle: beel_rules_list with domain, or resource beel://guardrails/.
The status names, the proforma lifecycle, and which tool performs each operation. (resource: beel://guardrails/invoice-state-machine)

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "company_id": "<company_id>",
      "invoice_id": "<invoice_id>",
      "body": "<body>"
    },
    "name": "beel_void_invoice"
  }
}

Input Schema

Name	Required	Description
`body`	Yes
`company_id`	Yes	Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
`invoice_id`	Yes	Invoice ID
`idempotency_key`	No	Optional idempotency key for this operation. Omit it and one is derived from the request itself, which makes a blind retry safe but also collapses a SECOND, deliberately identical operation into the first for 24 hours. Set it — to an order id, or anything unique per intended operation — whenever you mean to create something that may look identical to what you just created.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.10.0Nov 5, 2026

changedInput schema / $defs / VoidInvoiceRequest / properties / issued_in_error / description

Previous value: -"Confirms that the invoice was issued by mistake: the operation it describes never took\nplace, it was a test, or it is an accidental duplicate. A void is only for those cases\n(RD 1007/2023, art. 11.1); an operation that did take place is corrected with a\ncorrective invoice.\n\nRequired as `true` when the invoice has already been sent or paid — delivering or\ncollecting it suggests the operation was real, so the void has to say it was not.\nWithout it such a void fails with `422 VOID_REQUIRES_ISSUED_IN_ERROR`.\n"New value: +"Confirms that the invoice was issued by mistake: the operation it describes never took\nplace, it was a test, or it is an accidental duplicate. A void is only for those cases\n(RD 1007/2023, art. 11.1); an operation that did take place is corrected with a\ncorrective invoice.\n\nRequired as `true` when the invoice has already been emailed to the customer or paid —\ndelivering or collecting it suggests the operation was real, so the void has to say it\nwas not. It is the fact that counts, not the current `status`: an email in the\ninvoice's sending history, or a `paid_at`, still require it after the invoice moves\nback to `ISSUED` or becomes `RECTIFIED`.\nWithout it such a void fails with `422 VOID_REQUIRES_ISSUED_IN_ERROR`.\n"

addedInput schema / properties / body / type
```
Added value: +"object"
```
addedInput schema / properties / invoice_id / type
```
Added value: +"string"
```

Changed2 schema fields changedv0.9.0Oct 1, 2026

addedInput schema / $defs / VoidInvoiceRequest / properties / issued_in_error

Added value: +{
+  "default": false,
+  "description": "Confirms that the invoice was issued by mistake: the operation it describes never took\nplace, it was a test, or it is an accidental duplicate. A void is only for those cases\n(RD 1007/2023, art. 11.1); an operation that did take place is corrected with a\ncorrective invoice.\n\nRequired as `true` when the invoice has already been sent or paid — delivering or\ncollecting it suggests the operation was real, so the void has to say it was not.\nWithout it such a void fails with `422 VOID_REQUIRES_ISSUED_IN_ERROR`.\n",
+  "type": "boolean"
+}

changedInput schema / $defs / VoidInvoiceRequest / properties / void_date / description

Previous value: -"**Deprecated and ignored.** The void is recorded with the instant it actually takes\nplace, returned as `voided_at` on the invoice. A void cannot be dated by the caller,\nso any value sent here has no effect and will be removed in a future version.\n"New value: +"**Deprecated.** The void is recorded with the instant it actually takes place,\nreturned as `voided_at` on the invoice: a void cannot be dated by the caller, and this\nvalue never changes `voided_at`. It will be removed in a future version. A date earlier\nthan the invoice's issue date is rejected with `422 VOID_DATE_BEFORE_ISSUE_DATE`.\n"

Changed6 schema fields changedv0.5.0Aug 30, 2026

removedInput schema / $defs / UUID / example

Removed value: -"550e8400-e29b-41d4-a716-446655440000"

addedInput schema / $defs / VoidInvoiceRequest / additionalProperties
```
Added value: +false
```
removedInput schema / $defs / VoidInvoiceRequest / properties / reason / example
```
Removed value: -"Invoice issued with incorrect customer data"
```
removedInput schema / $defs / VoidInvoiceRequest / properties / void_date / example
```
Removed value: -"2025-01-20"
```
addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / company_id / description

Previous value: -"NIF (company) the operation acts on. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A NIF you do not reach answers `403`, and so does a NIF that does not exist, so the existence of a NIF in another account is never disclosed."New value: +"Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed."

First observedv0.3.1Aug 25, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive/idempotent/openWorld, but the description goes well beyond them: it names the 422 error codes and their triggers, explains that history facts (sending history, paid_at) override current status, describes the VeriFactu/AEAT submission, that the PDF is unchanged, and that voiding is reported via status and the invoice.voided webhook. It also explains the proforma special case where the void has no fiscal effect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads purpose and then organizes the rest under bolded headings, so the length is navigable and each section carries distinct information. There is mild redundancy (the 'fact not status' point appears twice, and the trailing resource pointers repeat) but nothing is filler for a destructive fiscal operation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, fiscal, no-output-schema mutation, the description covers outcomes (status change, webhook, unchanged PDF), failure modes with named error codes, and edge cases (correctives, TOTAL correctives, proformas, VeriFactu). An agent has enough to decide, call, and interpret the result without further lookups.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is effectively high (75% nominal, and the void_date/issued_in_error descriptions are themselves long), so the description's param bullets mostly restate schema content such as reason's 10-character minimum and the issued_in_error rationale. It does add value by tying parameters to specific error codes (VOID_REQUIRES_ISSUED_IN_ERROR, VOID_DATE_BEFORE_ISSUE_DATE), which the schema also mentions, so the net gain over structured fields is modest and the baseline 3 fits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource ('Voids an issued invoice of this company') and adds the non-obvious consequence (document kept, number never reused). It also distinguishes itself from the sibling corrective-invoice path, so an agent can route between the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (mistake, test, duplicate), when not to (real operation with wrong data → corrective invoice), and carves out a named exception (withholding that should not have been applied). The sent/paid and live-corrective preconditions give concrete decision rules rather than vague advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server