beel_issue_invoice
Finalize a draft invoice by assigning its definitive number and making it immutable for AEAT submission; correct or void it afterward instead of editing.
Instructions
Finalizes a draft invoice of this company: assigns its definitive number from the configured series and makes it immutable.
Irreversible: an issued invoice is corrected with a corrective invoice (
POST …/{invoice_id}/corrective) or voided (POST …/{invoice_id}/void), never edited.Asynchronous: PDF generation and submission to the AEAT happen after the response, so a
200means the invoice was accepted for submission, not that the AEAT has registered it. Usewait_for_pdfto wait for the PDF.Nothing to collect: a
STANDARDorSIMPLIFIEDinvoice whosetotal_to_payis 0 is issued asPAID, withpayment_dateequal toissue_date. It is registered with the AEAT like any other invoice, with a total of 0.
BeeL API endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/issue (reference: https://docs.beel.es)
⚠️ Read before calling:
Fiscal rules, domains lifecycle, records: 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)
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>",
"invoice_id": "<invoice_id>"
},
"name": "beel_issue_invoice"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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 | |
| wait_for_pdf | No | If `true`, waits for PDF generation and returns the URL in the response. Adds ~1-2s of latency but guarantees the PDF is immediately available. | |
| 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. | |
| attach_source_invoices | No | Only applies when the invoice has automatic email sending enabled. If `true`, the email sent after issuing also attaches a ZIP (`suplidos_<invoice-number>.zip`) with the PDFs of the source invoices referenced by the invoice's SUPLIDO consolidation lines. Access to sources owned by managed accounts is re-checked with the same rules as issuing, and the request fails synchronously with an actionable error — never a partial ZIP — if the invoice has no consolidation sources (`ATTACH_SOURCE_INVOICES_NO_SOURCES`), a source is not reachable (`ATTACH_SOURCE_INVOICE_UNAVAILABLE`) or a source has no generated PDF (`ATTACH_SOURCE_PDF_MISSING`). |