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

Update invoice series partially

Scopeseries:write

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

Updates only the fields present in the body, leaving every other field of the series as it is.

  • Clearing a field: a field sent as null is cleared — only description supports it (see PatchSeriesRequest).
  • Numbering fields: the same guard as PUT. code, format, counter_reset and initial_number are rejected once the series has issued invoices.
  • default_series: it is not a way to clear the default. Sending false for the series that currently is the default is rejected with DEFAULT_CANNOT_BE_UNMARKED; promote another series with PUT /v1/companies/{company_id}/series/{series_id}/default instead. Sending false for a series that is not the default stays a no-op 200.
PATCH
/v1/configuration/series/{series_id}

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

series_idstring

Series ID

Formatuuid

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"
name?string

Descriptive name of the series. Cannot be cleared.

Length1 <= length <= 100
code?string

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

Series description. Send null to clear it.

Lengthlength <= 1000
format?string

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

Counter reset policy:

  • NEVER: Counter never resets (continuous numbering)
  • ANNUAL: Counter resets yearly
  • MONTHLY: Counter resets monthly
Value in"NEVER" | "ANNUAL" | "MONTHLY"
initial_number?integer

Initial number for this series counter. Only while the series has no issued invoices.

Formatint64
Range1 <= value <= 999999
active?boolean

Whether the series is active.

Restriction: A default series cannot be deactivated (another must be set as default first).

default_series?boolean

Whether this is the default series.

Restriction: An inactive series cannot be marked as default.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://app.beel.es/api/v1/configuration/series/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "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": "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": "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": "NOT_FOUND",
    "message": "Resource not found"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}

List invoice series GET

**Deprecated.** Use `GET /v1/companies/{company_id}/series`, which behaves identically. Retrieves the invoice series of the company (NIF) in focus. The listing is always scoped to one company; it never spans several. - **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. - **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.

Mark series as default POST

**Deprecated.** Use `PUT /v1/companies/{company_id}/series/{series_id}/default`, which behaves identically. Marking a series as the default is idempotent, so the canonical form is a `PUT`. Marks an invoice series as the default one for its document type. - **One per type:** only one series can be the default per company (NIF) and document type; the previous default is automatically unmarked. - **Must be active:** an inactive series cannot be marked as default.