beel_convert_proforma_to_invoice
Convert an accepted proforma into a draft or issued invoice, preserving the proforma as the customer's record. Handles ACTIVE and EXPIRED statuses, with atomic issuance and duplicate prevention.
Instructions
Converts an accepted proforma of this company into a real invoice. Only proformas in status
ACTIVE convert; one shown as EXPIRED is still ACTIVE underneath and converts too. The
proforma is preserved as the record of what the customer accepted: it keeps its PRO-...
number and PDF and moves to the terminal status CONVERTED.
The call creates a new STANDARD invoice in DRAFT, linked back through
source_proforma_id. With issue: true that invoice is numbered and issued in the same
atomic call: if issuing fails, nothing is created and the proforma stays ACTIVE.
422 CONVERSION_REQUIRES_PROFORMA when the document is not a proforma,
422 PROFORMA_NOT_CONVERTIBLE when it is not in ACTIVE, and
409 PROFORMA_ALREADY_CONVERTED when it has already been converted — a second call never
creates a second invoice.
Endpoint: POST /v1/companies/{company_id}/invoices/{invoice_id}/convert-to-invoice
⚠️ Fiscal guardrails — read before calling:
When an invoice can still be changed, and what to do once it cannot. (resource: beel://guardrails/invoice-state-machine)
For the exhaustive rules and worked examples, call beel_docs_search.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | ||
| company_id | Yes | 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. | |
| invoice_id | Yes | Invoice ID | |
| 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. |