Skip to main content
Glama
beel-es

BeeL MCP server

Official
by beel-es
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

beel_get_invoice_pdf

Read-onlyIdempotent

Retrieve a temporary pre-signed URL to download an issued invoice's PDF, with an optional short wait for asynchronous generation and clear errors for drafts or unregistered invoices.

Instructions

Returns a temporary pre-signed URL to download the invoice PDF.

  • URL: expires in five minutes and only allows GET.

  • Waiting: a PDF is produced asynchronously, so this request waits for it (up to ten seconds) instead of handing you a polling loop to write. Bound the wait with Prefer: wait=N, or opt out with Prefer: wait=0.

  • 202: only when the wait elapsed with the PDF still in flight. No body is returned; ask again after Retry-After.

  • Drafts: a draft has no fiscal PDF and answers 400 INVOICE_NOT_ISSUED_NO_PDF immediately — that one never waits. Issue it, or render it with GET …/{invoice_id}/pdf/preview.

  • Not registered with the AEAT: under VeriFactu the PDF carries the QR code of the invoice's registration. An invoice whose registration was rejected before reaching the AEAT, or that was voided without ever being registered, has no PDF and answers 400 INVOICE_NOT_REGISTERED_NO_PDF immediately. Its verifactu.error_message says why.

  • Never modified: the PDF of an issued invoice is generated once — with its VeriFactu QR when it applies — and stays the document you delivered. Voiding the invoice or issuing a corrective against it does not change the PDF: read the invoice's status to know it.

Endpoint: GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
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.
invoice_idYesInvoice ID

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.5.0
    • removedInput schema / $defs / UUID / example
      Removed value: -"550e8400-e29b-41d4-a716-446655440000"
    • 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."
  2. First observedv0.3.1

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations (readOnlyHint/idempotentHint/destructiveHint), which only cover the safety profile. It discloses the 5-minute URL expiry, GET-only access, the async 10-second wait with Prefer: wait=N/0, the 202 + Retry-After contract, two specific 400 error codes with their causes, and the immutability of the issued PDF. This is unusually rich behavioral disclosure.

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 the core purpose in one sentence, then uses bold-labeled bullets that each earn their place. It is longer than typical but nearly all content is behavioral information an agent needs; only minor tightening would be possible.

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?

There is no output schema, so the description must explain the return contract, and it does: the URL and its expiry, the empty 202 body plus Retry-After, and the two 400 responses. An agent has everything required to invoke and interpret the result.

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 description coverage is 100% for both parameters, so the schema already carries the semantics (including company_id's ownership/403 behavior). The description adds nothing about company_id or invoice_id, so the baseline 3 applies; the Prefer header mention is not a declared parameter.

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 (returns) plus resource (temporary pre-signed URL to download the invoice PDF) in the very first sentence. This is clearly distinguishable from siblings like beel_get_invoice, beel_get_invoice_preview, and beel_download_representation_document, and the endpoint line confirms the resource.

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 covers when the tool does not apply — drafts ('Issue it, or render it with GET …/{invoice_id}/pdf/preview') and unregistered/voided invoices — and names the alternative call for drafts. It also explains the wait semantics and how to opt out, so an agent knows exactly what to expect before calling.

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