API v1.0.3 — VeriFactu exemptions, document types, stricter validations

ChangelogApr 18, 2026Breaking

Second round of VeriFactu compliance improvements: invoice lines can now carry an explicit exemption reason, the tax-types endpoint exposes the full LIVA exemption catalog, invoice series can be typed, and the id_otro VeriFactu rules are now enforced with specific error messages.

What breaks

irpf_rate enum — 21.00 is removed and 1.00 is added on lines[].irpf_rate (POST/PUT /v1/invoices, POST /v1/invoices/{invoice_id}/corrective) and on default_irpf_rate (PUT /v1/configuration/taxes). 21% IRPF is not a valid withholding rate for the flows BeeL. supports.
template_html removed — the template_types[].template_html property no longer ships in GET /v1/configuration/invoice-customization-options. PDF templates are owned and rendered by the backend; clients should not inspect the raw HTML.
Stricter NIF pattern — POST/PUT /v1/customers and POST /v1/customers/bulk now validate nif against the full DNI/NIE/CIF regex ^(\d{8}[A-Z]|[ABCDEFGHJKLMNPQRSUVW]\d{7}[A-Z0-9]|[XYZ]\d{7}[A-Z])$ instead of the permissive ^[A-Z0-9]{9}$. Previously-accepted but invalid strings (e.g. ABCDEFGHI) will now be rejected.

What else changed

Invoice line exemption reasons — exemption_reason (enum covering EXENTA_ART_*, NO_SUJETA_*, ISP_ART_84_2_*, REGIMEN_ART_* and OTRO) and the free-text exemption_reason_text are now accepted and returned on invoice lines. Required by VeriFactu whenever a line is exempt or not-subject.
Exemption reasons catalog — GET /v1/configuration/tax-types returns the full LIVA exemption catalog so integrators can build UIs without hardcoding the list.
Typed invoice series — new document_type on /v1/configuration/series (request, response and list query filter), so you can segregate series for invoices, corrective invoices, etc.
Descriptive alternative ID types — id_otro.type now accepts PASSPORT, COUNTRY_ID, NIF_IVA, RESIDENCE_CERTIFICATE, OTHER_DOCUMENT, NOT_REGISTERED alongside the legacy numeric codes 02–07 (still valid, now deprecated).
VeriFactu id_otro rules enforced at the boundary — if country_code = ES the type must be PASSPORT (03) or NOT_REGISTERED (07); if type = NOT_REGISTERED the country_code must be ES. Violations return 422 with a specific message per rule (previously a generic "identificador alternativo no es válido").