Invoice Series

Update invoice series

Updates an existing invoice series. Can only update: - Description - Active/inactive status - Whether it is default Cannot modify: code, prefix, number_format (to maintain consistency with existing invoices). Business rules: - Cannot deactivate a default series (must set another as default first) - Cannot mark an inactive series as default

PUT
/v1/configuration/series/{series_id}

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Path Parameters

series_idstring

Series ID

Formatuuid

Request Body

document_type?string

Document type associated with a series:

  • SIN_ASIGNAR: Legacy series, compatible with any invoice type
  • FACTURA_ORDINARIA: Standard invoice
  • FACTURA_SIMPLIFICADA: Simplified invoice
  • FACTURA_RECTIFICATIVA: Rectificative invoice
Value in"SIN_ASIGNAR" | "FACTURA_ORDINARIA" | "FACTURA_SIMPLIFICADA" | "FACTURA_RECTIFICATIVA"
name?string

Descriptive name of the series

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

Optional series description

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
Default"ANNUAL"
Value in"NEVER" | "ANNUAL" | "MONTHLY"
initial_number?integer

Initial number for this series counter. Useful for adjusting numbering or resetting the counter. For example, if you want the next invoice to be 2025-0054, set initial_number=54.

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

curl -X PUT "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": "SIN_ASIGNAR",
    "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,
    "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"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "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"
  }
}

Mark series as default POST

Marks an invoice series as the user's default. **Business rules:** - Only one series can be default per user - The series must be active (cannot mark an inactive series) - The previous default series is automatically unmarked **Note:** This operation is idempotent - calling it multiple times with the same series has no additional effects.

Change status of multiple invoices POST

Changes the status of multiple invoices in a single operation. **Supported status changes:** - **SENT:** Mark multiple invoices as sent (from ISSUED) - **PAID:** Mark multiple invoices as paid (from ISSUED, SENT, or OVERDUE) **Partial success:** If some invoices cannot be updated, the operation continues with the others. The response includes details of failures. **Limits:** - Maximum 50 invoices per request **Validations:** - All invoices must belong to the authenticated user - Each invoice must be in a valid status for the requested transition - For PAID: payment_date is required