Mark series as default
Scopeseries:writeDeprecated. Use PUT /v1/companies/{company_id}/series/{series_id}/default, which
behaves identically. Marking a series as the default is idempotent, so the canonical form
is a PUT.
Marks an invoice series as the default one for its document type.
- One per type: only one series can be the default per company (NIF) and document type; the previous default is automatically unmarked.
- Must be active: an inactive series cannot be marked as default.
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
Series ID to mark as default
uuidHeader Parameters
Idempotency key to prevent duplicates in sensitive operations.
- Any unique client-generated string (e.g. an order id). A UUID also works but is not required
- Allowed characters: letters, digits,
_and-(max 255 chars) - If the same key is sent twice, the result of the first operation is returned
- Keys expire 24 hours after processing
The key is scoped per user and environment, and bound to the request body, so retrying after a network timeout replays the stored response instead of repeating the operation.
| Status | Code | When |
|---|---|---|
400 | INVALID_IDEMPOTENCY_KEY | The key breaks the format rules above. |
409 | IDEMPOTENCY_KEY_PROCESSING | The first request is still in flight. Wait and retry with the same key. |
409 | IDEMPOTENCY_KEY_MISMATCH | The key was already used with a different body. Use a new key. |
^[a-zA-Z0-9_-]+$length <= 255Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://app.beel.es/api/v1/configuration/series/550e8400-e29b-41d4-a716-446655440000/default"{
"success": true,
"data": {
"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"
},
"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": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "FORBIDDEN",
"message": "You do not have permission to access this resource"
},
"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": "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": "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"
}
}Update invoice series partially PATCH
**Deprecated.** Use `PATCH /v1/companies/{company_id}/series/{series_id}`, which behaves identically. Updates only the fields present in the body, leaving every other field of the series as it is. - **Clearing a field:** a field sent as `null` is cleared — only `description` supports it (see `PatchSeriesRequest`). - **Numbering fields:** the same guard as `PUT`. `code`, `format`, `counter_reset` and `initial_number` are rejected once the series has issued invoices. - **`default_series`:** it is not a way to clear the default. Sending `false` for the series that currently *is* the default is rejected with `DEFAULT_CANNOT_BE_UNMARKED`; promote another series with `PUT /v1/companies/{company_id}/series/{series_id}/default` instead. Sending `false` for a series that is *not* the default stays a no-op `200`.
Delete series DELETE
**Deprecated.** Use `DELETE /v1/companies/{company_id}/series/{series_id}`, which behaves identically. Soft-deletes an invoice series. If the series is active, it is automatically deactivated before deletion. - **The code is NOT released:** it stays taken even after deletion, because it identifies invoices already issued under it. Recreating a series with the same code returns `409 SERIES_CODE_DUPLICATED`, so always pick a new code. - **Default series:** it cannot be deleted *while another active series of the same document type exists* — promote that other one first. If it is the only series of its type, it can be deleted and the type is left with no series: a valid state in which issuing without an explicit series returns `SERIES_DEFAULT_NOT_FOUND`.