# v1.0.3 — exemptions and document types

VeriFactu exemptions and document types, plus stricter validation on fiscal fields.

Apr 18, 2026 · Breaking

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").

---

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