List the invoice series of a company
Scopeseries:readReturns the invoice series of a company.
- Filters:
activerestricts to active or inactive series — omit it and you get all of them.document_typereturns the series of that type, the only ones that can number it. - Pagination (opt-in): send
pageand/orlimitto receive a single page plus adata.paginationblock with the totals. Omit both and the response carries the full list indata.seriesand nopaginationblock.
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
Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. 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 company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.
uuidQuery Parameters
Filters by activity: true returns only active series, false only inactive ones.
Omit it and you get all the series, active and inactive.
Filter by document type
"UNASSIGNED" | "STANDARD" | "SIMPLIFIED" | "CORRECTIVE" | "SIMPLIFIED_CORRECTIVE" | "PROFORMA"Page number (starts at 1). Omit for the full, unpaginated list.
1 <= valueItems per page. Omit for the full, unpaginated list.
1 <= value <= 100Response 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": "The invoice must have at least one line",
"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. - **Document type:** `document_type` is required. `UNASSIGNED` is rejected with `422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED`: corrective invoices need a series of their own. - **Code:** must be unique within the company; a code already taken answers `409`. - **Unique numbers per issuer:** a series whose `code` and `format` could print a number that another series of the company (in the same environment, active or not) can also print is rejected with `409 SERIES_FORMAT_OVERLAPS`, naming that series. Proforma series are not compared. - **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, with its code, format, counter state, document type and whether it is the default of that type.