Configuracion

Create invoice series

Creates a new invoice series. **Note:** The first series created by a user is automatically marked as default.

POST
/configuracion/series

Authorization

X-API-Key<token>

API Key authentication.

Format: X-API-Key: beel_sk_<key>

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

nombrestring

Descriptive name of the series

Length1 <= length <= 100
codigostring

Alphanumeric series code (used in {CODIGO} variable). Allows uppercase letters, numbers, hyphens and underscores.

Match^[A-Z0-9\-_]{1,50}$
Length1 <= length <= 50
descripcion?string|null

Optional series description

Lengthlength <= 1000
formatostring

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
reseteo_contadorstring

Counter reset policy:

  • NUNCA: Counter never resets (continuous numbering)
  • ANUAL: Counter resets yearly
  • MENSUAL: Counter resets monthly
Default"ANUAL"
Value in"NUNCA" | "ANUAL" | "MENSUAL"
numero_inicial?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 numero_inicial=151. Default value is 1.

Default1
Formatint64
Range1 <= value <= 999999
activa?boolean

Whether the series is active

Defaulttrue
predeterminada?boolean

Whether this is the default series

Defaultfalse

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/configuracion/series" \  -H "Content-Type: application/json" \  -d '{    "nombre": "Serie Principal",    "codigo": "FAC",    "formato": "{CODIGO}-{YYYY}-{NUM:4}",    "reseteo_contador": "NUNCA"  }'
{
  "success": true,
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "nombre": "Serie Principal",
    "codigo": "FAC",
    "descripcion": "Serie para facturas ordinarias",
    "formato": "{CODIGO}-{YYYY}-{NUM:4}",
    "reseteo_contador": "NUNCA",
    "numero_inicial": 1,
    "activa": true,
    "predeterminada": false,
    "created_at": "2019-08-24T14:15:22Z",
    "updated_at": "2019-08-24T14:15:22Z"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is not valid",
    "details": {
      "campo": "specific error message"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "details": {
      "field_name": "Field is required"
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Update invoice series PUT

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

Delete series DELETE

Deactivates an invoice series. **Soft delete:** The series is marked as inactive, not physically deleted. **Restriction:** Cannot delete the default series or series with invoices.