# v1.2.0 — VeriFactu validation pack

Invalid fiscal combinations now fail at request time with specific `422`s. Adds a public error-code catalog, metadata filters, the RD-ley rates and BIZUM.

May 22, 2026 · Breaking

Third wave of VeriFactu compliance hardening: invalid fiscal combinations are now rejected at request time with specific 422s, a public error-code catalog is available at docs.beel.es with stable per-code pages, Stripe-style metadata filtering on the invoices list, RD-ley 11/2022 temporary rates (5% IVA + 0.625% equivalence surcharge), BIZUM as a new payment method, and several Stripe Connect refinements.

## What breaks

- **Stricter VeriFactu validation rejects previously-accepted invoices** — invoices that combined incompatible options (ISP + equivalence surcharge, OSS + ISP exemption, simplified invoice + IRPF, 0% IVA without reason, etc.) used to pass the request and fail later. They now fail with 422 and a specific code at request time. Re-test integrations that exercise edge-case fiscal combinations.
- **`VatPercentage` schema type widened from `integer` to `number`** — all currently allowed values are still whole numbers (0, 4, 5, 10, 21), so wire-level responses do not change. Strongly-typed SDK clients generated from the OpenAPI spec (Java, C#, Go) should regenerate to pick up the new schema type; loose clients (JavaScript, Python without strict typing) need no changes.
- **`payment_info.method = BIZUM` may be returned where it previously wasn't** — clients that exhaustively switch on `method` should add a `BIZUM` branch (or a default arm).
- **`lines[].iva_rate = 5.00` may now be returned** — same as above for clients enumerating known rates.

## What else changed

- **VeriFactu validation pack** — incompatible fiscal combinations now fail with a specific 422 before the billing record is built: simplified invoices combined with cross-border / IRPF / ISP, ISP carrying the equivalence surcharge, OSS regime + ISP exemption, 0% IVA lines without an explicit reason, regimes / exemption articles that are currently unsupported. Each case returns its own error code so you can branch on it.
- **Public error-code catalog at `docs.beel.es/errors/{code}`** — every code that an API-key integrator can receive now has a stable, deep-linkable page. The `type` URI in error responses resolves there directly. The catalog covers 199 codes across 8 domains; codes that only surface from the web app are deliberately kept out.
- **`metadata[key]=value` filter on `GET /v1/invoices`** — Stripe-style deepObject filtering. Multiple pairs are AND'd together. Up to 50 pairs per request; keys must match `^[A-Za-z0-9_\-.]{1,64}$`. Example: `?metadata[external_order_id]=ORD-42&metadata[tenant]=acme`.
- **New 5% VAT rate (RD-ley 11/2022)** — `VatPercentage` now accepts `5` as a valid temporary reduced rate alongside 0, 4, 10 and 21.
- **New 0.625% equivalence surcharge** — `EquivalenceSurchargePercentage` adds `0.625`, the surcharge that pairs with 5% VAT under RD-ley 11/2022. Documented allowed pairings: 4 ↔ 0.5, 5 ↔ 0.625, 10 ↔ 1.4, 21 ↔ 5.2.
- **BIZUM as a payment method** — `payment_info.method` now accepts `BIZUM`. Returned in responses and accepted on `POST/PUT /v1/invoices`.
- **Clearer error when scheduling an ORDINARIA invoice without a recipient identifier** — now returns 422 with a specific, actionable message instead of the previous generic validation error.
- **PDF includes the VeriFactu QR consistently** — the downloaded PDF now always carries the VeriFactu QR when the invoice has one (previously a race could ship a PDF without it).
- **Stripe Connect refinements** — forward and corrective invoices generated from Stripe now mirror the exact Stripe charge total (no recalculation). Simplified invoices preserve the Stripe customer's name/email instead of falling back to `Consumidor final`. The cross-border alternative-ID gap is closed.

## Endpoints

- `GET /v1/invoices` — Added `metadata[key]=value` query parameter (deepObject) for filtering by metadata pairs

## Where to go next

- [Error reference](/errors)
- [Handling errors guide](/guides/handling-errors)
- [Equivalence surcharge](/verifactu/equivalence-surcharge)

---

Full OpenAPI spec: https://docs.beel.es/api/openapi