NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoice Series

Create an invoice series for a company

Scopeseries:write

Creates an invoice series under a company (NIF).

  • 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.
POST
/v1/companies/{company_id}/series

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

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF 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)
  • 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.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe 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

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/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": "La factura debe tener al menos una línea",
  "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": "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": "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"
  }
}

Get the default series of a company GET

Reports, for each `DocumentType` used by automatic invoicing flows, whether the company (NIF) has a default invoice series and which one: `exists`, plus the `series_id` when there is one. - **No default:** that document type cannot be issued without naming a `series_id` explicitly, and automatic flows skip it with `failure.payment.skip.missing_default_series`. - **Environment:** resolved from the request context; it takes no input.

List the invoice series of a company GET

Returns the invoice series of a company (NIF). - **Filters:** `active` restricts to active or inactive series — omit it and you get all of them. `document_type` filters by type and always includes the `UNASSIGNED` series, which are compatible with any type. - **Pagination (opt-in):** send `page` and/or `limit` to receive a single page plus a `data.pagination` block with the totals. Omit both and the response carries the full list in `data.series` and no `pagination` block.