API v1.2.0 — VeriFactu validation pack, public error catalog, metadata filters, RD-ley rates, BIZUM

What breaks

• Stricter VeriFactu validation rejects previously-accepted invoices — invoices that combined incompatible options (ISP + recargo de equivalencia, OSS + ISP exemption, SIMPLIFICADA + 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 registro de facturación is built: SIMPLIFICADA combined with cross-border / IRPF / ISP, ISP carrying recargo de equivalencia, 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% recargo de equivalencia — 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). SIMPLIFICADA 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/invoicesAdded metadata[key]=value query parameter (deepObject) for filtering by metadata pairs

Where to go next