Create an invoice design
Scopeinvoice-designs:writeCreates a design at version 1. It changes no PDF until it is assigned to a series
(invoice_design_id) or made the default design of the company.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
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.
uuidHeader Parameters
Idempotency key to prevent duplicates in sensitive operations.
- Any unique client-generated string (e.g. an order id). A UUID also works but is not required
- Allowed characters: letters, digits,
_and-(max 255 chars) - Retrying with the same key replays the first response when it was a success (2xx) or a
server error (5xx): same status and body, plus the header
Idempotency-Replay: true. After a 5xx other than 503, check whether the operation took effect before retrying with a new key - After a
503, retry first with the same key. If the response carriesIdempotency-Replay: true, the operation may have taken effect: check the resource before using a new key. Without that header, the retry runs the operation once - A 4xx is not stored: the key is released, so the corrected request can reuse it
- Stored responses expire 24 hours after processing
POSToperations that only read data (exports, batch PDF downloads, previews) ignore this header: they run on every call and their response is never stored
The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.
| Status | Code | When |
|---|---|---|
400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight: wait for the Retry-After seconds (2) and retry with the same key a few times. If it keeps answering 409, the first response could not be stored: check the resource instead of retrying. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Invoice PDF template. MODERN_TABLE is a structured table layout for
product/service lines; PROFESSIONAL_SERVICE is a text-based layout;
MINIMAL is a table with thin rules that shows the tax in a column of its
own when it fits; CLASSIC is a traditional layout with the issuer in the header and
boxed blocks; PAYMENT highlights the amount due and the payment details in a panel
at the foot.
"MODERN_TABLE" | "PROFESSIONAL_SERVICE" | "MINIMAL" | "CLASSIC" | "PAYMENT"Accent colour, #RRGGBB; returned in lowercase.
^#[0-9A-Fa-f]{6}$Typeface of the PDF: INTER sans serif, SOURCE_SERIF serif, PLEX_MONO monospaced.
More typefaces will be added: treat one you do not know as INTER.
Where the VeriFactu QR is printed, at the top of the first page.
"TOP_CENTER" | "TOP_LEFT""es" | "en" | "ca"COMPANY prints the logo the company has when each invoice is issued, NONE no logo.
"COMPANY" | "NONE"1 <= length <= 100Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoice-designs" \ -H "Content-Type: application/json" \ -d '{ "name": "Montseny Joyas", "template_type": "PROFESSIONAL_SERVICE", "accent_color": "#224da9", "font": "SOURCE_SERIF" }'{
"success": true,
"data": {
"template_type": "MODERN_TABLE",
"accent_color": "#fc481d",
"font": "INTER",
"qr_position": "TOP_CENTER",
"language": "es",
"logo_source": "COMPANY",
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "Montseny Joyas",
"version": 3,
"is_default": true,
"is_archived": true,
"series_count": 6,
"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Invalid request"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid.",
"details": {
"legal_name": "The field 'legal_name' cannot be empty",
"recipient.address.postal_code": "Contains invalid characters."
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Update VeriFactu configuration (deprecated) PUT
**Deprecated.** Use `PUT /v1/companies/{company_id}/verifactu-configuration`, which behaves identically. Updates the VeriFactu configuration of the company in focus. - **Writable fields:** only `enabled`. The rest of the returned configuration (`status`, `signed`, `activated`, `nif_status`) is resolved server-side. - **Full replacement:** `enabled` is required — this PUT replaces the whole state, it is not a partial merge, so omitting it is a client error and not a silent `false`. - **Turning it on registers the NIF for VeriFactu submission in the same call**, atomically: if the registration is refused nothing is persisted and the response carries the reason. In Live it requires a signed and validated AEAT representation first, or `422 VERIFACTU_REPRESENTATION_REQUIRED`. - **Sandbox is always on:** `enabled: false` there answers `422` `VERIFACTU_ALWAYS_ON_IN_SANDBOX`. ## Turning it off Setting `enabled` to false stops sending invoices to the AEAT and starts deregistering the NIF from VeriFactu submission. It does **not** deactivate the NIF: the activation is a fact of its own for the (company, environment) pair, so issuing carries on and `issuing-readiness` stays `ready`. Releasing the NIF is always `DELETE /v1/companies/{company_id}/activations`, with its own guarantees. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.
Delete an invoice design DELETE
Deletes the design, archived or not. It no longer appears in the list, reading it answers `404`, and it stops counting towards the 50 designs of the company. Invoices already issued do not change: they keep the design version they were issued with. The design is shared by Test and Live, so deleting it with a Test credential also deletes it for Live. For that reason the default design cannot be deleted, and neither can a design used by any series of the company, in Test or in Live, whichever environment the credential belongs to. Repeating the request with the same `Idempotency-Key` answers `204` again.