NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoice Series

Mark series as default (deprecated)

Scopeseries:write

Deprecated. 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 and document type; the previous default is automatically unmarked.
  • Must be active: an inactive series cannot be marked as default.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

POST
/v1/configuration/series/{series_id}/default

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

series_idstring

Series ID to mark as default

Formatuuid

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)
  • Retrying with the same key replays the first response when it was a success (2xx) or a server error (5xx): same status and body, plus the header Idempotency-Replay: true. After a 5xx, check whether the operation took effect before retrying with a new key
  • A 4xx is not stored: the key is released, so the corrected request can reuse it
  • Stored responses 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 for the Retry-After seconds (2) 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

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": "The invoice must have at least one line",
  "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": "INVOICE_NOT_FOUND",
    "message": "Invoice 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": "The invoice must have at least one line",
  "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 (deprecated) 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`. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

Delete series (deprecated) 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`. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.