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

List the invoice series of a company

Scopeseries:read

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.
GET
/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

Query Parameters

active?boolean

Filters by activity: true returns only active series, false only inactive ones. Omit it and you get all the series, active and inactive.

document_type?string

Filter by document type (UNASSIGNED series are always included)

Value in"UNASSIGNED" | "STANDARD" | "SIMPLIFIED" | "CORRECTIVE" | "PROFORMA"
page?integer

Page number (starts at 1). Omit for the full, unpaginated list.

Range1 <= value
limit?integer

Items per page. Omit for the full, unpaginated list.

Range1 <= value <= 100

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/series"
{
  "success": true,
  "data": {
    "series": [
      {
        "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"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20,
      "has_next": true,
      "has_previous": true
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
    "details": {
      "field": "invoice_id",
      "invalid_value": "deliveries",
      "expected_format": "UUID"
    }
  },
  "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": "Validation constraint violation.",
    "details": {
      "limit": "must be greater than or equal to 1"
    }
  },
  "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"
  }
}

Create an invoice series for a company POST

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

Get an invoice series GET

Returns one invoice series of a company (NIF), with its code, format, counter state, document type and whether it is the default of that type.