# 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

<Cards>
  <Card title="Integrating BeeL. into your ERP" href="/guides/erp-integration">
    Who issues, who sends, your own PDF and QR, numbering, correctives.
  </Card>
  <Card title="Invoice lifecycle" href="/guides/invoice-lifecycle">
    Every status, what each one allows, dates, voiding and payments.
  </Card>
  <Card title="Amounts and rounding" href="/guides/amounts-and-rounding">
    How line and invoice totals are computed, to the cent.
  </Card>
  <Card title="Series and numbering" href="/guides/series-and-numbering">
    Number formats, counter resets and when a number is assigned.
  </Card>
  <Card title="Recurring invoices" href="/guides/recurring-invoices">
    Cadence, how a series ends, failures and pauses.
  </Card>
  <Card title="Proformas" href="/guides/proformas">
    Quotes with no fiscal validity, and converting them into invoices.
  </Card>
  <Card title="Branding and PDF" href="/guides/branding-and-pdf">
    Logo, template, colours and languages of the invoice PDF.
  </Card>
  <Card title="Sending email" href="/guides/sending-email">
    Queued delivery, recipient rules, and throughput limits.
  </Card>
</Cards>

## Data

<Cards>
  <Card title="Bulk operations and exports" href="/guides/bulk-operations-and-exports">
    Batches, PDF archives, exports and how a batch reports each row.
  </Card>
  <Card title="Importing data" href="/guides/importing-data">
    Bring customers and products over from CSV or Holded.
  </Card>
  <Card title="Fiscal summary" href="/guides/fiscal-summary">
    VAT and IRPF for a period, to help you prepare your returns.
  </Card>
  <Card title="Filtering by metadata" href="/guides/filtering-by-metadata">
    Attach key/value pairs to invoices and query them back.
  </Card>
</Cards>

## Integrating reliably

<Cards>
  <Card title="Handling errors" href="/guides/handling-errors">
    Response shape, status codes, and retry rules.
  </Card>
  <Card title="Idempotency" href="/guides/idempotency">
    Use `Idempotency-Key` to retry safely.
  </Card>
  <Card title="Rate limits" href="/guides/rate-limits">
    Quotas per endpoint and how to back off.
  </Card>
  <Card title="Limits and pagination" href="/guides/limits-and-pagination">
    Page sizes, body and file sizes, and batch caps.
  </Card>
  <Card title="Glossary" href="/guides/glossary">
    Spanish ↔ English fiscal terminology with API field mapping.
  </Card>
</Cards>

## 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](/guides/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`](/errors/STATUS_NOT_DELETABLE), see [Invoice lifecycle](/guides/invoice-lifecycle#what-each-status-allows)) — and neither can a series that has invoices or is the default ([Deleting a series](/guides/series-and-numbering#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](/guides/limits-and-pagination#pagination).

---

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