InvoiceSeries

Create invoice series

Deprecated. Use POST /v1/companies/{company_id}/series, which behaves identically.

Creates a new invoice series for the company in focus.

  • Code: must be unique within the company; a code already taken answers 409.
  • 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.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

post/v1/configuration/series

Request

  • Base URL: https://app.beel.es/api
  • URL: https://app.beel.es/api/v1/configuration/series
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

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.

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

Request body

document_type'UNASSIGNED' | 'STANDARD' | 'SIMPLIFIED' | 'CORRECTIVE' | 'SIMPLIFIED_CORRECTIVE' | 'PROFORMA' required

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 required

Descriptive name of the series

codestring required

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

descriptionstring nullable

Optional series description

formatstring required

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.

counter_reset'NEVER' | 'ANNUAL' | 'MONTHLY'

Counter reset policy:

  • NEVER: Counter never resets (continuous numbering)
  • ANNUAL: Counter resets yearly
  • MONTHLY: Counter resets monthly
initial_numberinteger

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.

activeboolean

Whether the series is active

default_seriesboolean

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.

Example request

{
  "name": "Main Series",
  "code": "FAC",
  "description": "Series for standard invoices",
  "format": "{CODIGO}-{YYYY}-{NUM:4}",
  "initial_number": 1
}

Response

Series created successfully

successboolean required

Example response

{
  "success": true,
  "data": {
    "name": "Main Series",
    "code": "FAC",
    "description": "Series for standard invoices",
    "format": "{CODIGO}-{YYYY}-{NUM:4}",
    "initial_number": 1
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.