Changelog

Track all updates to the BeeL. API.

Breaking

API v1.1.0 — Refactored invoice recipient & payment_info, new series defaults

Invoice recipient and payment_info schemas have been refactored to use structured objects with allOf composition. This change normalizes the API and enables future extensibility. Also adds new series defaults endpoints.

  • Structured recipient and payment_info — PUT /v1/invoices/{invoice_id} now uses allOf composition with PaymentInfo and Recipient schemas. Fields like nif, legal_name, iban, method are still available via the referenced schemas, but the structure changed from inline to composed. Regenerate your SDK if you use one.
  • New series defaults endpoints — POST /v1/configuration/series/defaults and GET /v1/configuration/series/defaults-status allow setting and checking per-document-type default series.
  • Idempotency-Key header — Now formally documented on POST /v1/customers.
  • Invoice email options — All invoice endpoints now return email_config and send_automatically fields in responses.
  • PUT /v1/invoices/{invoice_id} schema change — recipient and payment_info now use allOf composition referencing Recipient and PaymentInfo schemas. The fields (nif, legal_name, iban, method, etc.) remain available but the schema path changed from inline properties to a $ref. Clients using generated SDKs may need to regenerate.
  • SDK regeneration recommended — If you use generated clients from the OpenAPI spec, regenerate them to pick up the new schema references. The underlying fields are the same; only the structure (and how the SDK types represent them) has changed.
ImprovementBreaking

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

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.

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

API v1.0.1 — VeriFactu operation_date & spec improvements

This release aligns the API with Spanish anti-fraud law (Ley Antifraude / VeriFactu) requirements for invoice dates. The issue_date is now always set to today and a new operation_date field lets you record when the operation actually took place.

  • New operation_date field on invoices — use when invoicing for a past operation (e.g., services delivered last month but invoiced this month)
  • issue_date is now read-only and always set to today per VeriFactu regulations
  • issue_date removed from required fields in CreateInvoiceRequest
  • Duplicate invoice no longer accepts a custom issue_date — duplicates are always dated today
  • Idempotency header renamed from X-Idempotency-Key to Idempotency-Key (standard naming)
  • Improved due_date documentation — must be same as or after today's date
  • New start_date field on recurring invoice creation
Release

BeeL API v1.0 — Public Launch

The BeeL API is now publicly available. Full REST API for invoicing, customer management, products, tax configuration, and VeriFactu compliance — all with a 7-day free trial.

  • Complete invoice lifecycle: create, issue, send, pay, void, and correct
  • Customer and product catalog management with bulk operations
  • VeriFactu compliance with automatic AEAT submission
  • Webhook notifications for invoice and VeriFactu events
  • Idempotency support for safe retries on all creation endpoints
  • Sandbox environment with unlimited invoices for testing
  • OpenAPI 3.0 specification for client generation in any language

Update webhook subscription PATCH

Partially updates a webhook subscription. Only provided fields are updated. Use this endpoint to: - **Change the endpoint URL** (`url`) - **Change subscribed events** (`events`) - **Enable or disable** the subscription (`active`)