Create invoice series

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

Creates a new invoice series for the company (NIF) 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.

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

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)
If the same key is sent twice, the result of the first operation is returned
Keys 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 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_type?string

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

UNASSIGNED: Legacy series, compatible with any invoice type
STANDARD: Standard invoice
SIMPLIFIED: Simplified invoice
CORRECTIVE: Corrects or cancels a previous invoice
PROFORMA: Proforma (commercial document, non-fiscal numbering)

Value in"UNASSIGNED" | "STANDARD" | "SIMPLIFIED" | "CORRECTIVE" | "PROFORMA"

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"

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.

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/configuration/series" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Main Series",
    "code": "FAC",
    "format": "{CODIGO}-{YYYY}-{NUM:4}"
  }'

curl -X POST "https://app.beel.es/api/v1/configuration/series" \  -H "Content-Type: application/json" \  -d '{    "name": "Main Series",    "code": "FAC",    "format": "{CODIGO}-{YYYY}-{NUM:4}"  }'

{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "document_type": "UNASSIGNED",
    "name": "Main Series",
    "code": "FAC",
    "description": "Series for standard invoices",
    "format": "{CODIGO}-{YYYY}-{NUM:4}",
    "counter_reset": "NEVER",
    "initial_number": 1,
    "active": true,
    "default_series": false,
    "numbering_locked": true,
    "created_at": "2019-08-24T14:15:22Z",
    "next_number": 0,
    "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": "FORBIDDEN",
    "message": "You do not have permission 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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "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 invoice series

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

409application/json

422application/json

500application/json

defaultapplication/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json