Guides

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

Use Idempotency-Key to retry safely.

Quotas per endpoint and how to back off.

Response shape, status codes, and retry rules.

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

Spanish ↔ English fiscal terminology with API field mapping.

API conventions

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

PUT is a partial update. Send only the fields you want to change; everything else stays as is.
POST and PUT take an Idempotency-Key header so retries never create duplicates — see Idempotency.
DELETE is a soft delete on most resources: the entity stops appearing in listings but is preserved for audit. It is idempotent and restorable only via support.
Some deletions are forbidden by fiscal rules: issued invoices can't be deleted (void them instead), customers with invoices can only be deactivated, and the default invoice series can't be removed. These come back as 400 BUSINESS_RULE_VIOLATION — see Handling errors.
List endpoints paginate with page + limit (max 100) and return a pagination object — iterate to pagination.total_pages.