NewInvoice designs and replaceable member grants
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoice Designs

Create an invoice design

Scopeinvoice-designs:write

Creates 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.


POST
/v1/companies/{company_id}/invoice-designs
AuthorizationBearer <token>

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

company_idstring

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.

Formatuuid

Header Parameters

Idempotency-Key?string

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 carries Idempotency-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
  • POST operations 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.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe 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.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255
template_type?string

Invoice 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.

Value in"MODERN_TABLE" | "PROFESSIONAL_SERVICE" | "MINIMAL" | "CLASSIC" | "PAYMENT"
accent_color?string

Accent colour, #RRGGBB; returned in lowercase.

Match^#[0-9A-Fa-f]{6}$
font?string

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.

qr_position?string

Where the VeriFactu QR is printed, at the top of the first page.

Value in"TOP_CENTER" | "TOP_LEFT"
language?string
Value in"es" | "en" | "ca"
logo_source?string

COMPANY prints the logo the company has when each invoice is issued, NONE no logo.

Value in"COMPANY" | "NONE"
namestring
Length1 <= length <= 100

Response 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.