Guides

Practical guides for working with the BeeL. API — idempotency, rate limits, error handling, email delivery, metadata filtering, and a fiscal glossary.

A short collection of cross-cutting topics every BeeL. integration needs.

Idempotency

Use Idempotency-Key to retry safely.

Rate limits

Quotas per endpoint and how to back off.

Sending email

Queued delivery, recipient rules, and throughput limits.

Handling errors

Response shape, status codes, and retry rules.

Filtering by metadata

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

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.
POST takes an Idempotency-Key header so retries never create duplicates — see Idempotency. The header is ignored on PUT, PATCH and DELETE.
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: issued invoices can't be deleted (void them instead) and the default invoice series can't be removed — both 400 BUSINESS_RULE_VIOLATION. A customer that has invoices can't be deleted either, and that one is a 409: set active: false on it instead. See Handling errors.
List endpoints paginate with page + limit (max 100) and return a pagination object — iterate to pagination.total_pages.