Create an invoice series for a company

Creates an invoice series under a company.

Document type: document_type is required. UNASSIGNED is rejected with 422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED: corrective invoices need a series of their own.
Code: must be unique within the company; a code already taken answers 409.
Unique numbers per issuer: a series whose code and format could print a number that another series of the company (in the same environment, active or not) can also print is rejected with 409 SERIES_FORMAT_OVERLAPS, naming that series. Proforma series are not compared.
Numbering: format must contain {NUM} or {NUM:X} and only accepts uppercase tokens. counter_reset defaults to ANNUAL, so a format with no year token has to be sent with counter_reset: NEVER.
Default series: the first series created for a document type is marked as default even if you send default_series: false.

Authorization

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, check whether the operation took effect before retrying with a new key
A 4xx is not stored: the key is released, so the corrected request can reuse it
Stored responses expire 24 hours after processing

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.
`409`	`IDEMPOTENCY_KEY_MISMATCH`	The key was already used with a different body. Use a new key.

Match^[a-zA-Z0-9_-]+$

Lengthlength <= 255

Request Body

document_typestring

Document type associated with a series. Values mirror InvoiceType, so the series a document needs is named exactly like the document:

UNASSIGNED: Legacy value of series created before types existed. A series numbers only documents of its own type, so an UNASSIGNED series numbers none (422 SERIES_INCOMPATIBLE_DOC_TYPE); give it a type to keep using it. No series can be created with it or moved to it (422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED). The live ones were given the type they numbered most.
STANDARD: Standard invoice
SIMPLIFIED: Simplified invoice
CORRECTIVE: Corrects or cancels a previous standard invoice (R1–R4)
SIMPLIFIED_CORRECTIVE: Corrects a simplified invoice (R5). Spanish law requires R5 to be numbered apart from R1–R4, so they have a series type of their own
PROFORMA: Proforma (commercial document, non-fiscal numbering)

namestring

Descriptive name of the series

Length1 <= length <= 100

codestring

Alphanumeric series code (used in {CODIGO} variable). Allows uppercase letters, numbers, hyphens and underscores.

Match^[A-Z0-9\-_]{1,50}$

Length1 <= length <= 50

description?string|null

Optional series description

Lengthlength <= 1000

formatstring

Format template with available variables (UPPERCASE ONLY):

{CODIGO}: Series code (e.g., "FAC")
{YYYY}: Year with 4 digits (e.g., "2025")
{YY}: Year with 2 digits (e.g., "25")
{MM}: Month with 2 digits (e.g., "01")
{NUM}: Sequential number without padding (e.g., "1")
{NUM:X}: Sequential number with padding (e.g., {NUM:4} → "0001")

REQUIRED: Must contain at least {NUM} or {NUM:X} IMPORTANT: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)

Valid examples:

"{CODIGO}-{YYYY}-{NUM:4}" → "FAC-2025-0001"
"{CODIGO}/{NUM:6}" → "FAC/000001"
"{YYYY}{MM}-{NUM:3}" → "202501-001"

The generated number is the invoice number sent to the AEAT, which accepts at most 60 printable ASCII characters and none of ", ', <, >, =. A format whose longest possible number breaks that rule is rejected with 422 SERIES_FORMAT_NUMBER_TOO_LONG or SERIES_FORMAT_INVALID_CHARACTERS. The counter counts as at least 9 digits, with or without padding: {NUM:X} is a minimum width, not a maximum.

Match^[A-Z0-9\-_/{}:]*$

Length1 <= length <= 255

counter_reset?string

Value in"NEVER" | "ANNUAL" | "MONTHLY"

initial_number?integer

Initial number for this series counter. Useful when migrating from another system and wanting to continue existing numbering. For example, if the last invoices were 2024-0150, you can set initial_number=151. Default value is 1. It applies only to the first period in which the series issues an invoice: with counter_reset: ANNUAL or MONTHLY, every later year or month starts at 1. With NEVER there is a single period, so numbering simply continues from it.

Default1

Formatint64

Range1 <= value <= 999999

active?boolean

Whether the series is active

Defaulttrue

default_series?boolean

Whether this is the default series for its document_type.

Auto-promotion: the domain guarantees that, while at least one series exists for a given (document_type, environment), exactly one of them is the default. So if you create the first series of a document_type (no default exists yet for that type and environment), it is marked as default even if you send false — the response will then return default_series: true. Send true to also unmark the current default of that type.

Defaultfalse

Response Body

application/json

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/series" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "A",
    "name": "Serie Principal",
    "document_type": "STANDARD",
    "description": "Default series for standard invoices",
    "format": "{CODIGO}/{YYYY}/{NUM:4}",
    "counter_reset": "ANNUAL",
    "initial_number": 1,
    "default_series": true
  }'

curl -X POST "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/series" \  -H "Content-Type: application/json" \  -d '{    "code": "A",    "name": "Serie Principal",    "document_type": "STANDARD",    "description": "Default series for standard invoices",    "format": "{CODIGO}/{YYYY}/{NUM:4}",    "counter_reset": "ANNUAL",    "initial_number": 1,    "default_series": true  }'

Invoice series created with configuration and next number

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "code": "A",
    "name": "Serie Principal",
    "document_type": "STANDARD",
    "description": "Default series for standard invoices",
    "format": "{CODIGO}/{YYYY}/{NUM:4}",
    "counter_reset": "ANNUAL",
    "initial_number": 1,
    "default_series": true,
    "active": true,
    "created_at": "2025-02-09T11:00:00Z",
    "updated_at": "2025-02-09T11:00:00Z"
  },
  "meta": {
    "timestamp": "2025-02-09T11:00:00Z",
    "request_id": "req_serie_001"
  }
}

{
  "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": "SERIES_FORMAT_NUMBER_TOO_LONG",
    "message": "The number this series generates can reach 64 characters and the AEAT accepts at most 60 (series and number together). Shorten the code or the fixed text of the format"
  },
  "meta": {
    "timestamp": "2026-09-24T10: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"
  }
}

Create an invoice series for a company

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

409application/json

422application/json

429application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json