Skip to main content
Glama
BeeL MCP server

BeeL MCP server

Official
by beel-es

beel_create_simplified_exchange

DestructiveIdempotent

Issues a full standard invoice to replace one or more simplified invoices when the customer requests their tax details, marking the originals as voided due to exchange.

Instructions

Issues a full invoice in exchange for one or more simplified invoices already issued, when the customer asks for an invoice with their details. It is not a corrective invoice: it documents the same operations again with the recipient identified (RD 1619/2012, art. 15.6).

  • What it issues: a STANDARD invoice with the lines of the simplified invoices and the recipient sent, numbered in series_id or in the company's default standard series. It lists the invoices it replaces in replaced_invoice_ids.

  • The simplified invoices: each becomes VOIDED with void_cause EXCHANGED, in the same act: their records are not cancelled, the exchange replaces them. They must be simplified invoices (422 EXCHANGE_REQUIRES_SIMPLIFIED), issued and not voided, exchanged or corrected before (422 SIMPLIFIED_NOT_EXCHANGEABLE), and each one listed once in simplified_invoice_ids (422 EXCHANGE_DUPLICATED_SIMPLIFIED, before anything is read or numbered).

  • The exchange invoice cannot be voided afterwards (422 EXCHANGE_INVOICE_NOT_VOIDABLE), and when it is recorded as F3 it cannot be corrected yet (see the corrective operation).

  • VeriFactu: the exchange invoice is recorded as F3, identifying each simplified invoice it replaces by number and issue date. Each of them must already be accepted by the AEAT, or nothing is issued: one issued without VeriFactu fails with 422 SIMPLIFIED_EXCHANGE_NOT_RECORDABLE; one whose record is still pending fails with 422 EXCHANGE_SIMPLIFIED_NOT_YET_ACCEPTED (wait until the AEAT accepts it and retry); one whose record was rejected fails with 422 EXCHANGE_SIMPLIFIED_RECORD_REJECTED (fix or resubmit it first).

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

⚠️ Read before calling:

  • Fiscal rules, domains simplified, records: beel_rules_list with domain, or resource beel://guardrails/.

  • How to tell, before issuing, whether a NIF can issue, and what each blocker means. (resource: beel://guardrails/verifactu-gates)

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>",
      "body": "<body>"
    },
    "name": "beel_create_simplified_exchange"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes
company_idYesUnique 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.
idempotency_keyNoOptional 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.

  1. Changed8 schema fields changedv0.10.0
    • changedInput schema / $defs / Address / description
      Previous value: -"Address you send when you create or update a company, a customer or an onboarding.\n\nAddresses you read back are described by their own schema.\n"New value: +"Address you send when you create or update a company, a customer or an onboarding.\n\nA required field made only of whitespace passes the length checks below but leaves the\naddress without that part, so it is rejected with `422`: `STREET_EMPTY`,\n`POSTAL_CODE_EMPTY`, `CITY_EMPTY` or `PROVINCE_EMPTY`.\n\nAddresses you read back are described by their own schema.\n"
    • changedInput schema / $defs / Address / properties / province / description
      Previous value: -"Province or state - Latin characters only"New value: +"Province or state - Latin characters only. Required for an address in Spain\n(`country_code` `ES`, or no country at all); optional elsewhere, where many addresses\nhave none. A Spanish address without it is rejected with a `422`.\n"
    • changedInput schema / $defs / Address / required
      Previous value: -[
      -  "street",
      -  "postal_code",
      -  "city",
      -  "province"
      -]New value: +[
      +  "street",
      +  "postal_code",
      +  "city"
      +]
    • changedInput schema / $defs / AlternativeIdentifier / description
      Previous value: -"Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n"New value: +"Alternative identifier for customers without Spanish Tax ID.\n\n### VeriFactu rules (checked when you send it, `422` on violation)\n- `country_code` is required, except for `PASSPORT` (03) and `NOT_REGISTERED` (07), the two\n  types AEAT accepts with `ES`: omitted, `ES` applies. Missing for any other type, the\n  identifier is rejected with `ALTERNATIVE_ID_COUNTRY_REQUIRED`, and `error.details` names\n  the field where it was sent: `alternative_id.country_code` on a customer,\n  `recipient.alternative_id.country_code` on an invoice recipient. Same code in both.\n- If `country_code = ES`, then `type` **must** be `PASSPORT` (03) or `NOT_REGISTERED` (07)\n  (`ALTERNATIVE_ID_SPAIN_INVALID_TYPE`).\n- If `type = NOT_REGISTERED` (07), then `country_code` **must** be `ES`\n  (`ALTERNATIVE_ID_REQUIRES_SPAIN`), and `number` **must** be a Spanish DNI or NIE: a\n  Spanish company is always registered (`RECIPIENT_UNREGISTERED_ID_MUST_BE_DNI_OR_NIE`).\n  That DNI or NIE must not be one the AEAT census identifies: if it is, the identifier is\n  rejected with `ALTERNATIVE_ID_ACTUALLY_IN_CENSUS` and has to be sent as `nif`. A customer\n  is checked when it is saved; an invoice recipient, when the invoice is issued with\n  VeriFactu. If the census does not answer, the identifier is not rejected.\n- If `type = NIF_IVA` (02), `country_code` **must** be an EU member state other than Spain\n  (`ALTERNATIVE_ID_VAT_REQUIRES_EU_COUNTRY`), and `number` **must** have that country's\n  EU VAT number structure as AEAT defines it: the country prefix (`EL` for Greece) followed\n  by the national number, e.g. `FR40303265045`, `DE123456789`, `EL094014201`\n  (`ALTERNATIVE_ID_VAT_INVALID_FORMAT`). Lowercase letters are accepted and stored in\n  uppercase. A customer from outside the EU is identified with another type, such as\n  `OTHER_DOCUMENT` or `COUNTRY_ID`.\n\nA `number` that is blank once trimmed is rejected with `ALTERNATIVE_ID_INVALID`.\n\nWell-formed is not the same as registered: an EU VAT number that is not in the VIES\ncensus is still rejected by VeriFactu after the invoice is issued.\n\nAn identifier returned in a response is the one stored. A customer saved before a rule\nexisted keeps its identifier and can still be read; issuing an invoice to it with an\nidentifier that breaks these rules is rejected with the same code, before a number is used.\n\n### Matrix of allowed combinations\n| `type`                 | `country_code = ES` | `country_code ≠ ES` |\n|------------------------|:-------------------:|:-------------------:|\n| `NIF_IVA` (02)         | ✗                   | EU member states only |\n| `PASSPORT` (03)        | ✓                   | ✓                   |\n| `COUNTRY_ID` (04)      | ✗                   | ✓                   |\n| `RESIDENCE_CERTIFICATE` (05) | ✗             | ✓                   |\n| `OTHER_DOCUMENT` (06)  | ✗                   | ✓                   |\n| `NOT_REGISTERED` (07)  | ✓                   | ✗                   |\n"
    • changedInput schema / $defs / CreateSimplifiedExchangeRequest / properties / simplified_invoice_ids / description
      Previous value: -"The simplified invoices the full invoice replaces, issued and not voided, exchanged or\ncorrected. Their lines, in this order, become the lines of the full invoice.\n"New value: +"The simplified invoices the full invoice replaces, issued and not voided, exchanged or\ncorrected. Their lines, in this order, become the lines of the full invoice. Each one\nappears once: a repeated id fails with `422 EXCHANGE_DUPLICATED_SIMPLIFIED`.\n"
    • removedInput schema / $defs / CreateSimplifiedExchangeRequest / properties / simplified_invoice_ids / uniqueItems
      Removed value: -true
    • addedInput schema / $defs / EmailConfiguration / description
      Added value: +"Who the invoice is emailed to when `send_automatically` is true. Every address in\n`recipients` and `cc` must have a domain with a dot, or the request answers\n`422 INVALID_EMAIL_FORMAT`. With `send_automatically` true and no recipients here, no\n`customer_id` and no recipient email, there is nobody to send to: `422`\n`AUTOMATIC_EMAIL_CONFIG_INVALID`.\n"
    • addedInput schema / properties / body / type
      Added value: +"object"
  2. Addedv0.9.0

TDQS

A4.8/5.0
Behavior5/5

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

Goes far beyond the annotations: it discloses that each simplified invoice becomes VOIDED with EXCHANGED rather than being cancelled, that the exchange invoice itself cannot afterwards be voided, and that VeriFactu acceptance of every source is a hard gate with distinct 422 codes for pending vs rejected. This is exactly the consequence-level context an agent needs for a destructive, open-world operation.

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-loaded with the one-sentence purpose and the corrective-invoice disambiguation, then organized into bolded bullets covering the issuance, the sources and VeriFactu. It is long, but nearly every line carries operational meaning; some error-code detail overlaps with the schema's own descriptions.

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 nested, 3-parameter, destructive operation with no output schema, the definition covers the trigger, the numbering, the side effects on sources, and the AEAT acceptance preconditions with actionable error codes. Nothing essential for a correct first call appears to be missing.

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

Parameters4/5

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

Schema coverage is 67%, and the description compensates well: it explains that the full invoice is numbered in series_id or the company default, that simplified_invoice_ids lines become the invoice lines in order with max 50 items, and that the recipient must be identified as a standard invoice requires. It does not touch the options/idempotency_key parameters, leaving those to the schema text.

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?

States a precise verb+resource ('Issues a full invoice in exchange for one or more simplified invoices') and immediately distinguishes it from the sibling corrective-invoice operation: 'It is not a corrective invoice: it documents the same operations again with the recipient identified'. An agent can route between beel_create_corrective_invoice, beel_issue_invoice and this tool without opening schemas.

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?

Gives an explicit real-world trigger ('when the customer asks for an invoice with their details'), names the alternative it is not (corrective invoice), and points to prerequisite reading (beel_rules_list, beel://guardrails/verifactu-gates). Preconditions for the source invoices are enumerated with the exact failure code for each.

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

Deploy Server

Other Tools