Guides

Practical guides for the BeeL. API — the invoice lifecycle, amounts, series, recurring invoices, proformas, bulk work, errors, idempotency and limits.

A short collection of the topics every BeeL. integration needs.

Invoicing

Integrating BeeL. into your ERP

Who issues, who sends, your own PDF and QR, numbering, correctives.

Invoice lifecycle

Every status, what each one allows, dates, voiding and payments.

Amounts and rounding

How line and invoice totals are computed, to the cent.

Series and numbering

Number formats, counter resets and when a number is assigned.

Recurring invoices

Cadence, how a series ends, failures and pauses.

Proformas

Quotes with no fiscal validity, and converting them into invoices.

Branding and PDF

Logo, template, colours and languages of the invoice PDF.

Sending email

Queued delivery, recipient rules, and throughput limits.

Data

Bulk operations and exports

Batches, PDF archives, exports and how a batch reports each row.

Importing data

Bring customers and products over from CSV or Holded.

Fiscal summary

VAT and IRPF for a period, to help you prepare your returns.

Filtering by metadata

Attach key/value pairs to invoices and query them back.

Integrating reliably

Handling errors

Response shape, status codes, and retry rules.

Idempotency

Use Idempotency-Key to retry safely.

Rate limits

Quotas per endpoint and how to back off.

Limits and pagination

Page sizes, body and file sizes, and batch caps.

Glossary

Spanish ↔ English fiscal terminology with API field mapping.

API conventions

The API uses standard REST verbs (GET read, POST create, PUT replace, PATCH partial update, DELETE remove) with a few BeeL-specific rules worth knowing up front:

PATCH is how you edit a resource. It touches only the fields present in the body and leaves everything else untouched. A field sent as null is cleared — which is different from omitting it. Invoices, customers, products, series, recurring invoices and the company itself are all edited this way: PATCH /v1/companies/{company_id}/invoices/{invoice_id}, …/customers/{customer_id}, …/products/{product_id}, …/series/{series_id}, …/recurring-invoices/{recurring_invoice_id} and PATCH /v1/companies/{company_id}.
There is no full-replacement PUT on those resources, so you can never wipe a field by forgetting it. Where PUT does appear it states a desired state, not a replacement document: the default series (PUT /v1/companies/{company_id}/series/defaults), the tax and VeriFactu configuration, an invoice's schedule, a member's grant, the account owner. Those are idempotent by design — repeating one is a no-op rather than an error.
Every POST takes an Idempotency-Key header so retries never create duplicates, and so do the PUT, PATCH and DELETE operations that declare it — see Idempotency.
DELETE semantics vary by resource. Draft invoices and series are soft-deleted (kept for audit, gone from listings); a customer is really deleted — it returns 404 afterwards, never appears in the list under any value of active, and its NIF is released for reuse.
Some deletions are forbidden by fiscal rules: an issued invoice can't be deleted — void it instead (400 STATUS_NOT_DELETABLE, see Invoice lifecycle) — and neither can a series that has invoices or is the default (Deleting a series). A customer that has invoices can't be deleted either, and that one is a 409: set active: false on it instead.
List endpoints paginate with page + limit and return a pagination object — see Limits and pagination.