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

Create default invoice series

Scopeseries:write

Deprecated. Use PUT /v1/companies/{company_id}/series/defaults, which behaves identically. Ensuring a set of defaults is idempotent, so the canonical form is a PUT.

Idempotently ensures the company (NIF) in focus has a default invoice series for each relevant DocumentType (STANDARD, SIMPLIFIED, CORRECTIVE) in the current environment.

  • Already there: a document type that already has a default keeps it, and it is returned unchanged.
  • Missing: a new series is created with code F, S or R and format {CODIGO}-{YYYY}-{NUM:4}, active and marked as default.
  • Code taken: if that code is already in use by a manually created series, the document type is skipped and omitted from the response.
POST
/v1/configuration/series/defaults

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

Header Parameters

Idempotency-Key?string

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.

StatusCodeWhen
400INVALID_IDEMPOTENCY_KEYThe key breaks the format rules above.
409IDEMPOTENCY_KEY_PROCESSINGThe first request is still in flight. Wait and retry with the same key.
409IDEMPOTENCY_KEY_MISMATCHThe key was already used with a different body. Use a new key.
Match^[a-zA-Z0-9_-]+$
Lengthlength <= 255

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/configuration/series/defaults"
{
  "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"
      }
    ]
  },
  "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": "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": "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"
  }
}

Delete an invoice series DELETE

Soft-deletes an invoice series, deactivating it first if it is active. - **The code is not released:** it stays taken after the deletion because it identifies the invoices already issued under it, so recreating a series with the same code answers `409 SERIES_CODE_DUPLICATED`. - **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 is deleted and the type is left with none, a valid state in which issuing without an explicit `series_id` answers `SERIES_DEFAULT_NOT_FOUND`.

Get default series status per document type GET

**Deprecated.** Use `GET /v1/companies/{company_id}/series/defaults`, which behaves identically. Reports, for each `DocumentType` used by automatic invoicing, whether there is a default invoice series and which one: `exists`, plus the `series_id` when there is one. - **Why check it:** a document type with no default series makes an incoming charge be skipped with `failure.payment.skip.missing_default_series` instead of invoiced. - **Environment:** test or production is resolved automatically from your request context; no input needed.