Changelog
Every change to the BeeL. API, newest first — what moved, when the old way stops working, and how to tell whether it affects you.
Most changes are one entry here. A few are big enough to need the old-to-new route table, the retirement calendar and a way to check your own integration against it — those keep their entry in this list and link to the full note.
Every deprecated route also tells you the same thing in its own responses —
Deprecation: true, a Sunset date and Link: <successor>; rel="successor-version" —
so you never have to trust a page over your own traffic.
A literal % in a filter value dropped the filter. series_code matched any series containing the code. Sorting customers ignored the documented field names. Only series_code changes a response you may rely on today.
The published global ceiling drops to 1000 req/60 s to match what was already enforced. Strict and Global count per IP, not per credential.
Bodies above 2 MB answer 413 REQUEST_BODY_TOO_LARGE. 411 LENGTH_REQUIRED is gone — chunked encoding is accepted.
Two overlapping updates: the second now answers 409 CONCURRENT_MODIFICATION instead of silently discarding the first.
Several documented responses and one header were never actually sent. They are out of the contract; the server did not change.
Tax breakdowns travel complete and add up. Series publish the next number they will assign. Recurring invoices declare frequency in the request.
Create managed accounts in bulk from a spreadsheet — template, preview, apply — and see where each claim stands.
A body that parses but breaks a rule now answers 422 with a code and populated details, not an empty 400.
From 2026-09-03 the flat routes reject an undeclared query parameter with 400 instead of ignoring it. Until then they answer 200 with a BeeL-Warning header naming it.
Voided invoices now carry void_cause, void_reason and voided_at, so a direct void and a total corrective are told apart without a second call.
Lists answer data.<plural>, deletes answer 204 unless the body informs, and every create returns Location. DELETE products/bulk takes ?ids= instead of a body.
Lists: data is never a bare array anymore. Six lists that answered data: [...] + root pagination (companies of an account, series, recurring invoices, payment events, request logs, sent emails) now answer data.<plural> + data.pagination — deprecated flat aliases included, since they share the schema. Five unpaginated lists (company stats, email indicators, payment connections, recurring history, series defaults) are wrapped in data.{plural} with no pagination block.Deletes: DELETE .../customers/{id} and DELETE .../representation now answer 204 with no body — their old 200 bodies carried nothing you could not already know. Bulk deletes and DELETE .../activations keep their 200 body (partial results and the computed effective_at are only knowable from the response).DELETE /v1/companies/{company_id}/products/bulk no longer takes a request body — a body on DELETE has no defined semantics and intermediaries may drop it. Send ?ids= (comma-separated, max 100 per request), same as customers/bulk.Every single-resource 201 now carries a Location header pointing at the created resource's canonical GET — including actions that produce a resource (corrective, convert, derivations, generate, payment-event draft). Claim tokens point at their claim_url. Bulk creations carry none: there is no single URI to point at.PUT /v1/configuration/series/{series_id} is now deprecated like the rest of the flat series routes. It has no drop-in successor: the canonical PATCH /v1/companies/{company_id}/series/{series_id} behaves the same for every body except an explicit description: null, which the old PUT ignored and the PATCH honours by clearing the field.Declarative sweep: every live operation now documents 429 and 500, every tag is declared, and the account companies operations moved from the PublicCompanies tag to AccountCompanies.These changes ship without a grace window: measured traffic on the affected shapes was test-mode only. If your integration reads any of the old list shapes, adapt the paths above — everything else about each operation is unchanged.
The invoice field first announced as external_reference is now called external_ref. Responses already emit the new name; the old one is still accepted when you write, as a deprecated alias.
Responses emit external_ref — the old name is no longer returnedWrites still accept external_reference, as a deprecated aliasAffects the request body of the create-invoice routes and the GET /v1/invoices query filterNothing has stopped working, and no removal date is announced yet
New: an account can hold several NIFs, each addressed in the path. As a result the old flat routes are deprecated — 82 operations gain a Sunset date, and all but three a successor route, and keep answering until then.
82 operations are deprecated, each with a Sunset date and, for all but three, a successor routeNothing is removed — every deprecated route keeps answering until its Sunset dateDeprecated routes carry Deprecation: true, Sunset and, where a successor is declared, Link: <successor>; rel="successor-version"The three replacing PUTs (customer, product, recurring invoice) declare no successor: the canonical PATCH merges instead of replacing, so it is not a drop-in
The status filter on GET /v1/invoices accepts a comma-separated list, so one request covers several statuses.
Invoices accept an external_reference — your own order id — that you can filter by and that is enforced as unique.
Invoice lines carry a line_type. Set SUPLIDO to pass through amounts paid in your client’s name, outside the taxable base.
A Request Logs endpoint family lets you inspect what your own API keys have called — method, path, status, timing and the full detail.
Official CLI on npm as @beel_es/cli. Run any endpoint from the terminal, sandbox by default, nothing to install.
Official Node.js / TypeScript SDK on npm as @beel_es/sdk, fully typed from the spec.
Idempotency keys accept any string, country becomes optional, and webhook URLs must be HTTPS.
The header that selects the active company is now Beel-Active-Company, was X-Active-Profile.
Invalid fiscal combinations now fail at request time with specific 422s. Adds a public error-code catalog, metadata filters, the RD-ley rates and BIZUM.
Invoice recipient and payment_info become structured objects, and new series get sensible defaults.
VeriFactu exemptions and document types, plus stricter validation on fiscal fields.
issue_date is now always today, and a new operation_date carries the date the service was actually rendered.
The BeeL. API is publicly available: invoicing, customers, products, tax configuration and VeriFactu, with a 7-day trial.