Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es

beel_create_product

Idempotent

Creates a product or service in a company's catalog and returns its ID for reusable invoice line defaults like name, price, unit, and taxes.

Instructions

Creates a product or service in the catalog of the company in the path and returns it with its id. A product holds reusable defaults for invoice lines: name, price, unit and taxes.

  • Required: only name. Omitted, category is SERVICE, and the product is created active.

  • code: optional, and unique within the company. A code another product of the company already uses answers 409 with PRODUCT_DUPLICATE.

  • Taxes: equivalence_surcharge_rate has to be coherent with main_tax.regime_key; an incoherent pair answers 422 (see the field).

  • Several at once: POST /v1/companies/{company_id}/products/bulk creates up to 100 in one call.

Endpoint: POST /v1/companies/{company_id}/products

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. Changed4 schema fields changedv0.9.0
    • changedInput schema / $defs / CreateProductRequest / properties / irpf_rate / description
      Previous value: -"IRPF withholding percentage (optional)"New value: +"IRPF withholding percentage (optional).\n\nThe rate must be one of `IrpfPercentage` (`INVALID_IRPF` otherwise) and one\nthe company can bear, the same check as an invoice line (see\n`WithholdingOptions` in the tax configuration): an entity gets the rates of\nindividuals rejected with `IRPF_RATE_NOT_FOR_CORPORATE_ISSUER`, and an individual gets\n`9.5` rejected with `IRPF_RATE_ONLY_FOR_CORPORATE_ISSUER`.\n"
    • changedInput schema / $defs / RegimeKey / description
      Previous value: -"Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies:\n- 01: General regime operation\n- 02: Export\n- 03: Used goods, art, antiques\n- 04: Investment gold\n- 05: Travel agencies\n- 06: Group of entities\n- 07: Cash basis\n- 08: IPSI/IVA/IGIC operations\n- 09: Mediating agencies\n- 10: Third-party collections\n- 11: Local rental\n- 14: VAT pending in certifications\n- 15: VAT pending successive tract\n- 17: OSS and IOSS\n- 18: Equivalence surcharge\n- 19: REAGYP\n- 20: Simplified regime\n\n**One exception to \"a key you send is the key you get\":** when the line ends up\ncarrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate`\nor it was inherited from the company's tax configuration — a `01` is rewritten to\n`18`, because a surcharge under the general regime is fiscally incoherent. Send\n`equivalence_surcharge_rate: 0` explicitly to keep `01`. See\n`equivalence_surcharge_rate` in the invoice line for the full rules.\n"New value: +"Regime key according to VeriFactu regulations. Omitted, `01` (general regime) applies:\n- 01: General regime operation\n- 02: Export (IVA and IGIC; not IPSI, whose AEAT list is `01, 08, 11, 18, 19, 20`)\n- 03: Used goods, art, antiques (not accepted, see below)\n- 04: Investment gold\n- 05: Travel agencies\n- 06: Group of entities (not accepted, see below)\n- 07: Cash basis\n- 08: Operation subject to another indirect tax — IPSI or IGIC on an IVA line, IPSI or IVA\n  on an IGIC line. It is **not** the general regime of IGIC, which is `01`.\n- 09: Mediating agencies\n- 10: Third-party collections\n- 11: Local rental\n- 14: VAT pending in certifications (not accepted, see below)\n- 15: VAT pending successive tract\n- 17: OSS and IOSS\n- 18: Equivalence surcharge\n- 19: REAGYP\n- 20: Simplified regime\n\n**What AEAT requires with each key** (Validaciones VERI*FACTU 3.1.3.15.6), checked on\nIVA and IGIC lines before the invoice is numbered. Otherwise the request is rejected with\n`422` and the code in brackets:\n- `04`: only reverse charge (an `ISP_ART_84_2_*` reason) or an exemption\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `08`: only `exemption_reason: NO_SUJETA_LOCALIZACION`, at 0 %\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `10`: only `exemption_reason: NO_SUJETA_ART_7_9`, on a `STANDARD` invoice whose\n  recipient has a `nif` (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`,\n  `REGIME_KEY_REQUIRES_STANDARD_INVOICE`, `REGIME_KEY_REQUIRES_RECIPIENT_NIF`).\n- `11` (IVA): a subject line only at 21 %, and no reverse charge\n  (`REGIME_KEY_REQUIRES_VAT_RATE`, `REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n- `06` and `14` are not accepted (`REGIME_KEY_NOT_SUPPORTED`): AEAT requires with them\n  data the invoice does not carry (a cost-based taxable base; an operation date after the\n  issue date and a public-administration recipient).\n- `03` (used goods) is not accepted (`REGIME_KEY_NOT_SUPPORTED`): under it the invoice\n  must not show the tax separately (RD 1619/2012, art. 16.2.c), and it always does. The\n  corrective of an invoice that already carried `03` keeps it.\n- `05` (travel agencies) and `07` (cash basis) are accepted, and the invoice PDF carries\n  the mention of their regime (RD 1619/2012, art. 6.1 n and p). `07`: no reverse charge,\n  no non-subject reason and, of the exemptions, only art. 20 or `OTRO`\n  (`REGIME_KEY_CLASSIFICATION_NOT_ACCEPTED`).\n`GET /v1/tax-types` only offers the keys that are accepted.\n\n**One exception to \"a key you send is the key you get\":** when the line ends up\ncarrying an equivalence surcharge — whether you sent `equivalence_surcharge_rate`\nor it was inherited from the company's tax configuration — a `01` is rewritten to\n`18`, because a surcharge under the general regime is fiscally incoherent. Send\n`equivalence_surcharge_rate: 0` explicitly to keep `01`. See\n`equivalence_surcharge_rate` in the invoice line for the full rules.\n"
    • changedInput schema / $defs / TaxInfo / description
      Previous value: -"Complete tax information with cross-validations:\n- IVA: real rates 4, 5, 10, 21 (see below for 0)\n- IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real \"Tipo Cero\"\n- IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)\n- OTHER: any percentage between 0 and 100\n\n**0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted\non a line, but only together with an `exemption_reason` (exempt or non-subject\noperation); on its own it says nothing and the line is rejected. That is why\n`GET /v1/tax-types` publishes 4, 5, 10 and 21 for IVA and not 0: the legitimate way\nto a 0 % IVA line is through an exemption reason, which the same response also\npublishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and\nneeds no reason.\n\n**IVA 5 %** (RD-ley 11/2022 and its extensions, on electricity, gas and basic\nfoodstuffs) is no longer in force for new operations, but it stays valid: corrective\ninvoices and late-filed invoices for the periods when it applied must be able to carry\nit. Its equivalence surcharge pair is 0.625.\n\nException: when regime_key = \"17\" (OSS/IOSS) the invoice applies the destination\ncountry VAT instead of the Spanish one, so any percentage in the EU range [0, 27]\nis accepted regardless of the tax type set — including 0 without an exemption reason.\n"New value: +"Complete tax information with cross-validations:\n- IVA: real rates 4, 10, 21, and the temporary 2, 5 and 7.5 (see below for 0)\n- IGIC: 0, 3, 5, 7, 9.5, 15, 20 — here 0 is the real \"Tipo Cero\"\n- IPSI: real rates 0.5, 1, 2, 4, 8, 10 (see below for 0)\n- OTHER: any percentage between 0 and 100\n\n**0 % under IVA and IPSI is not a rate, it is the exemption sentinel.** It is accepted\non a line, but only together with an `exemption_reason` (exempt or non-subject\noperation); on its own it says nothing and the line is rejected. That is why\n`GET /v1/tax-types` publishes the IVA rates without 0: the legitimate way\nto a 0 % IVA line is through an exemption reason, which the same response also\npublishes. IGIC is different — its 0 % is a real legal rate (basic necessities) and\nneeds no reason.\n\n**IVA 5 %** (the temporary rate applied from 2022 to electricity, gas and certain\nfoodstuffs) is no longer in force for new operations. AEAT only accepts it on operations\ndated from 2022-07-01 to 2024-09-30: send the `operation_date` of that period, because\nwithout one the issue date decides and a line at 5 % is rejected with\n`422 VAT_RATE_NOT_ACCEPTED_ON_DATE`. Its equivalence surcharge pair is 0.5 up to 2022-12-31\nand 0.62 from 2023-01-01. **IVA 2 % and 7.5 %** (temporary rates of the last quarter of 2024)\nare accepted only on operations dated from 2024-10-01 to 2024-12-31, with surcharges 0.26\nand 1.\n\nException: when regime_key = \"17\" (OSS/IOSS) the invoice applies the destination\ncountry VAT instead of the Spanish one, so any percentage in the EU range [0, 27]\nis accepted regardless of the tax type set — including 0 without an exemption reason.\n"
    • changedInput schema / $defs / TaxType / description
      Previous value: -"Tax type by territory:\n- IVA: Iberian Peninsula and Balearic Islands (4%, 5%, 10%, 21%)\n- IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%)\n- IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%)\n- OTHER: Configurable 0%-100%\n\nUnder IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject\nsentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate.\nSee `TaxInfo` for the full rules.\n"New value: +"Tax type by territory:\n- IVA: Iberian Peninsula and Balearic Islands (4%, 10%, 21%; 2%, 5% and 7.5% only on operations of their period)\n- IGIC: Canary Islands (0%, 3%, 5%, 7%, 9.5%, 15%, 20%)\n- IPSI: Ceuta and Melilla (0.5%, 1%, 2%, 4%, 8%, 10%)\n- OTHER: Configurable 0%-100%\n\nUnder IVA and IPSI, 0% is not one of these rates: it is the exemption/non-subject\nsentinel and always travels with an `exemption_reason`. IGIC's 0% is a real rate.\nSee `TaxInfo` for the full rules.\n"
  2. Changed16 schema fields changedv0.5.0
    • addedInput schema / $defs / CreateProductRequest / additionalProperties
      Added value: +false
    • removedInput schema / $defs / CreateProductRequest / properties / code / example
      Removed value: -"SERV-001"
    • removedInput schema / $defs / CreateProductRequest / properties / default_price / example
      Removed value: -85.5
    • removedInput schema / $defs / CreateProductRequest / properties / description / example
      Removed value: -"Specialized technical consulting services"
    • removedInput schema / $defs / CreateProductRequest / properties / equivalence_surcharge_rate / example
      Removed value: -5.2
    • removedInput schema / $defs / CreateProductRequest / properties / irpf_rate / example
      Removed value: -15
    • removedInput schema / $defs / CreateProductRequest / properties / name / example
      Removed value: -"Technical consulting"
    • removedInput schema / $defs / CreateProductRequest / properties / unit / example
      Removed value: -"hours"
    • removedInput schema / $defs / ProductCategory / example
      Removed value: -"CONSULTING"
    • removedInput schema / $defs / RegimeKey / example
      Removed value: -"01"
    • addedInput schema / $defs / TaxInfo / additionalProperties
      Added value: +false
    • removedInput schema / $defs / TaxInfo / example
      Removed value: -{
      -  "percentage": 21,
      -  "regime_key": "01",
      -  "type": "IVA"
      -}
    • removedInput schema / $defs / TaxInfo / properties / percentage / example
      Removed value: -21
    • removedInput schema / $defs / TaxType / example
      Removed value: -"IVA"
    • 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.4/5.0
Behavior4/5

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

Annotations already declare non-readOnly, idempotent, non-destructive, openWorld. The description adds genuinely useful behavior beyond that: duplicate `code` yields 409 PRODUCT_DUPLICATE and an incoherent tax pair yields 422, with the default active/category behavior spelled out.

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?

Front-loaded opening sentence, then tight bullets for Required/code/Taxes/several-at-once, ending with the endpoint. Every line carries an actionable constraint with no filler.

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

Completeness4/5

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

No output schema, but the description states what is returned (the product with its id) and documents the notable failure modes. Combined with a 67%-covered schema, an agent has enough to invoke correctly; minor detail like the full parameter list is left to the schema.

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 already rich, but the description adds value the schema does not: the uniqueness semantics of `code` within the company and the specific error it triggers, plus the coherence requirement between equivalence_surcharge_rate and main_tax.regime_key.

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 specific verb and resource (creates a product or service in the company's catalog) plus the return value (the product with its id). It also distinguishes itself from the bulk sibling by naming beel_create_products_bulk for multi-create.

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?

Gives concrete context: only `name` is required, omitted `category` defaults to SERVICE, the product is created active, and it routes bulk creation to the /products/bulk endpoint. It lacks an explicit 'when not to use this / use X instead' for single-vs-list cases, but the practical guidance is clear.

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