BeeL
Get StartedVeriFactuStripeAPI Reference
Invoice Series

Create invoice series

Creates a new invoice series.

Note: The first series created by a user is automatically marked as default.

Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
POST
/v1/configuration/series

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

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
  • PROFORMA: Proforma (commercial document, non-fiscal numbering)
Value in"SIN_ASIGNAR" | "FACTURA_ORDINARIA" | "FACTURA_SIMPLIFICADA" | "FACTURA_RECTIFICATIVA" | "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_resetstring

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 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

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}",    "counter_reset": "NEVER"  }'
{
  "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": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "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": "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"
  }
}

Create default invoice series POST

Idempotently ensures the user has a default invoice series for each relevant `DocumentType` (FACTURA_ORDINARIA, FACTURA_SIMPLIFICADA, FACTURA_RECTIFICATIVA) in the current environment. - If a default already exists for a tipo, it is returned unchanged. - If a default is missing, a new series is created with code F/S/R and format `{CODIGO}-{YYYY}-{NUM:4}`, marked as default and active. - If the code is already in use by a manually-created series, that tipo is skipped (omitted from the response). Used by integration setup screens after connecting Stripe Connect, and as a recovery action for users who connected before automatic creation was wired in.

Delete series DELETE

Soft-deletes an invoice series. If the series is active, it is automatically deactivated before deletion. The series code becomes available for reuse. **Restriction:** Cannot delete the default series. Assign another series as default first.