Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es

beel_create_recurring_invoice_derivation

Idempotent

Creates a recurring invoice template from an existing invoice, copying its lines, recipient, series, and payment details so you only need to define the recurrence schedule.

Instructions

Creates a recurring invoice template of this company taking its lines, recipient, series and payment data from an existing invoice, so only the recurrence has to be described.

  • from_invoice_id: the source invoice. It must belong to the company in the path, and one you cannot reach is reported the same way as one that does not exist. It is not modified by this call.

  • Recurrence: name, day_of_month and start_date are required; end_date and frequency are optional. The cadence is not taken from the source invoice — a one-off invoice has none to copy — so it is described here like any other recurrence field: every 1 (MONTHLY), 3 (QUARTERLY) or 12 (YEARLY) months, MONTHLY when omitted. It governs the step from the first invoice onwards, not where that first one lands.

  • VeriFactu: not inherited from the source invoice. Each generated invoice is registered with AEAT, or not, according to the company's regime when it is issued.

Endpoint: POST /v1/companies/{company_id}/recurring-invoices/derivations

⚠️ Read before calling:

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

Input Schema

TableJSON 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. Changed13 schema fields changedv0.9.0
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / day_of_month / description
      Added value: +"Day of the month the invoices are issued. A month that does not have that day falls\nback to its last day: a template on `31` issues on 28 February (29 in a leap year)\nand on 30 April. So `31` is how you ask for the last day of the month it generates\nin — there is no separate flag for it, and the accepted range stays 1–31.\n\nThe adjustment does not stick and the schedule does not drift: every generation is\nrecalculated from the `day_of_month` you sent, never from the date it was adjusted\nto (31 Jan → 28 Feb → 31 Mar).\n"
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / draft_in_advance
      Added value: +{
      +  "description": "Whether the template prepares a draft for review before emitting. The window is fixed at\n5 days and both options emit on the scheduled day. Omitted, the template is created\nwithout the review draft. Same field, same meaning and same default as when you create a\ntemplate from scratch: deriving from an invoice does not give it a second semantics.\n",
      +  "type": "boolean"
      +}
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / frequency / description
      Previous value: -"Generation cadence. Only `MONTHLY` is supported today; the field exists in the\nrequest so an unsupported cadence is rejected instead of silently creating a\nmonthly template. Omitted, `MONTHLY` applies.\n"New value: +"Generation cadence: `MONTHLY` every month, `QUARTERLY` every 3 months, `YEARLY` every 12 months. Omitted, `MONTHLY` applies.\n\nIt governs the step from the first invoice onwards, not where that first one lands: the\nfirst occurrence is the first `day_of_month` on or after `start_date`, found one month at\na time whatever the cadence. A yearly template starting 15 February with `day_of_month`\n10 first invoices on 10 March, then every 10 March after that — it does not wait a year.\n"
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / frequency / enum
      Previous value: -[
      -  "MONTHLY"
      -]New value: +[
      +  "MONTHLY",
      +  "QUARTERLY",
      +  "YEARLY"
      +]
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / name / minLength
      Added value: +1
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / name / pattern
      Added value: +"^\\S.*$"
    • changedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / start_date / description
      Previous value: -"Date the subscription started. A past date is accepted and stored as sent — useful\nwhen migrating subscriptions from another system — but it never anchors generation\nin the past: `next_generation` moves to the first upcoming `day_of_month`. Invoices\nare never back-dated, so the missed periods are not generated.\n"New value: +"Date the subscription started. A past date is accepted and stored as sent — useful\nwhen migrating subscriptions from another system — but it never anchors generation\nin the past. `next_generation` becomes the next date of the template's own calendar\nthat is still ahead: the grid of `day_of_month` dates anchored at `start_date`, one\nevery `frequency`. On a quarterly or yearly template that can be months from now, not\nthis month. Invoices are never back-dated, so the missed periods are not generated.\n"
    • removedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / properties / verifactu_enabled
      Removed value: -{
      -  "description": "Whether the invoices this template generates enter VeriFactu.\n\nOmitting it inherits the value from the source invoice: pointing at one of your\nVeriFactu invoices and asking for it every month keeps VeriFactu. Send `true` or\n`false` explicitly to override that inheritance.\n",
      -  "type": "boolean"
      -}
    • addedInput schema / $defs / Email
      Added value: +{
      +  "description": "Email address (minimum valid email is 5 chars, e.g. a@b.co)",
      +  "format": "email",
      +  "maxLength": 255,
      +  "minLength": 5,
      +  "type": "string"
      +}
    • addedInput schema / $defs / RecurringEmailConfigRequest / properties / cc / items / $ref
      Added value: +"#/$defs/Email"
    • removedInput schema / $defs / RecurringEmailConfigRequest / properties / cc / items / type
      Removed value: -"string"
    • addedInput schema / $defs / RecurringEmailConfigRequest / properties / recipients / items / $ref
      Added value: +"#/$defs/Email"
    • removedInput schema / $defs / RecurringEmailConfigRequest / properties / recipients / items / type
      Removed value: -"string"
  2. Changed3 schema fields changedv0.5.0
    • addedInput schema / $defs / CreateRecurringInvoiceDerivationRequest / additionalProperties
      Added value: +false
    • 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."
  3. First observedv0.3.1

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already disclose idempotency and open-world behavior, while the description adds meaningful context: the source invoice is not modified, the recurrence cadence is not inherited from the source, and VeriFactu registration follows the company's regime when each invoice is issued. It does not describe return values or rate limits, but these are less critical for a creation tool.

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

Conciseness5/5

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

The description is front-loaded with the core purpose, then structured into focused bullets for the source invoice, recurrence, and VeriFactu. Every sentence earns its place, and the warning at the end is directly actionable.

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 multi-parameter creation tool with rich annotations and a detailed input schema, the description covers all invocation-critical details: required recurrence fields, source-invoice constraints, cadence semantics, and the VeriFactu caveat. No output schema exists, and the description does not need to explain return values for correct invocation.

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?

The description adds meaning beyond the schema for `from_invoice_id` (must belong to the company; unreachable invoices are reported like nonexistent ones) and for recurrence parameters (which are required vs optional, and that cadence is not copied from the source invoice). With 67% schema description coverage, the description still provides useful contextual semantics, though some details duplicate the schema.

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?

The first sentence states a specific verb and resource: 'Creates a recurring invoice template of this company taking its lines, recipient, series and payment data from an existing invoice.' This distinguishes the tool from the sibling `beel_create_recurring_invoice`, which creates a template from scratch, by making the existing-invoice derivation central.

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

Usage Guidelines4/5

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

The description gives clear context for when to use it: when you already have an invoice and only want to describe the recurrence. It also includes a prerequisite warning to read fiscal rules before calling, but it does not explicitly name the alternative tool (`beel_create_recurring_invoice`) or provide when-not-to-use exclusions.

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