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

Update invoice series (deprecated)

Scopeseries:write

Deprecated. The canonical form has a single update verb, PATCH /v1/companies/{company_id}/series/{series_id}. The same body produces the same result there — this route already merges field by field, leaving absent fields untouched — with one difference: an explicit description: null, which this route ignores, clears the description under PATCH.

Updates an existing invoice series with the body you send; absent fields keep their value.

  • Numbering fields: code, format, counter_reset and initial_number are rejected once the series has issued invoices (numbering_locked is true). name, description, active, default_series and document_type can always be changed.
  • active: a default series cannot be deactivated — set another one as default first.
  • default_series: sending false on 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, which unmarks the previous one for you. 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.

PUT
/v1/configuration/series/{series_id}

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

Formatuuid

Request Body

document_type?string

Document type associated with a series. Values mirror InvoiceType, so the series a document needs is named exactly like the document:

  • UNASSIGNED: Legacy value of series created before types existed. A series numbers only documents of its own type, so an UNASSIGNED series numbers none (422 SERIES_INCOMPATIBLE_DOC_TYPE); give it a type to keep using it. No series can be created with it or moved to it (422 SERIES_UNASSIGNED_TYPE_NOT_ALLOWED). The live ones were given the type they numbered most.
  • STANDARD: Standard invoice
  • SIMPLIFIED: Simplified invoice
  • CORRECTIVE: Corrects or cancels a previous standard invoice (R1–R4)
  • SIMPLIFIED_CORRECTIVE: Corrects a simplified invoice (R5). Spanish law requires R5 to be numbered apart from R1–R4, so they have a series type of their own
  • PROFORMA: Proforma (commercial document, non-fiscal numbering)
Value in"UNASSIGNED" | "STANDARD" | "SIMPLIFIED" | "CORRECTIVE" | "SIMPLIFIED_CORRECTIVE" | "PROFORMA"
name?string

Descriptive name of the series

Length1 <= length <= 100
code?string

Alphanumeric series code (used in {CODIGO} variable). Allows uppercase letters, numbers, hyphens and underscores.

Match^[A-Z0-9\-_]{1,50}$
Length1 <= length <= 50
description?string|null

Optional series description

Lengthlength <= 1000
format?string

Format template with available variables (UPPERCASE ONLY):

  • {CODIGO}: Series code (e.g., "FAC")
  • {YYYY}: Year with 4 digits (e.g., "2025")
  • {YY}: Year with 2 digits (e.g., "25")
  • {MM}: Month with 2 digits (e.g., "01")
  • {NUM}: Sequential number without padding (e.g., "1")
  • {NUM:X}: Sequential number with padding (e.g., {NUM:4} → "0001")

REQUIRED: Must contain at least {NUM} or {NUM:X} IMPORTANT: Only uppercase (rejects {yy}, {mm}, {codigo}, etc.)

Valid examples:

  • "{CODIGO}-{YYYY}-{NUM:4}" → "FAC-2025-0001"
  • "{CODIGO}/{NUM:6}" → "FAC/000001"
  • "{YYYY}{MM}-{NUM:3}" → "202501-001"

The generated number is the invoice number sent to the AEAT, which accepts at most 60 printable ASCII characters and none of ", ', <, >, =. A format whose longest possible number breaks that rule is rejected with 422 SERIES_FORMAT_NUMBER_TOO_LONG or SERIES_FORMAT_INVALID_CHARACTERS. The counter counts as at least 9 digits, with or without padding: {NUM:X} is a minimum width, not a maximum.

Match^[A-Z0-9\-_/{}:]*$
Length1 <= length <= 255
counter_reset?string

Counter reset policy:

  • NEVER: Counter never resets (continuous numbering)
  • ANNUAL: Counter resets yearly
  • MONTHLY: Counter resets monthly
Value in"NEVER" | "ANNUAL" | "MONTHLY"
initial_number?integer

Initial number for this series counter. Useful for adjusting numbering before the series issues its first invoice. For example, if you want the next invoice to be 2025-0054, set initial_number=54. It applies only to the first period in which the series issues an invoice: with counter_reset: ANNUAL or MONTHLY, every later year or month starts at 1. With NEVER there is a single period, so numbering simply continues from it.

Formatint64
Range1 <= value <= 999999
active?boolean

Whether the series is active.

Restriction: A default series cannot be deactivated (another must be set as default first).

default_series?boolean

Whether this is the default series.

Restriction: An inactive series cannot be marked as default.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://app.beel.es/api/v1/configuration/series/550e8400-e29b-41d4-a716-446655440000" \  -H "Content-Type: application/json" \  -d '{}'
{
  "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": "SERIES_FORMAT_NUMBER_TOO_LONG",
    "message": "The number this series generates can reach 64 characters and the AEAT accepts at most 60 (series and number together). Shorten the code or the fixed text of the format"
  },
  "meta": {
    "timestamp": "2026-09-24T10: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 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.

Get the fiscal summary of a company GET

Returns the VAT and IRPF summary of the invoices issued under this company over the requested period, together with the annual IRPF projection and its progressive bracket breakdown. `start_date` and `end_date` go together: send both, or neither. Omitting both defaults to the current month; sending only one answers `400`, because a period you did not ask for is worse than an error. The range may not exceed 365 days, and every fault names itself in `details.reason`.