# Integrating BeeL. into your ERP

The decisions every ERP integration makes — who issues the invoice, who renders the PDF and sends the email, how to continue your numbering, how to correct an invoice, and how to hear back from AEAT.

You already have an ERP that creates invoices, numbers them and emails them. This page answers the questions that come up when BeeL. joins that flow, in the order an integration usually meets them. Each answer links to the guide that goes deeper.

> **Not legal or tax advice.** This page describes how BeeL. works. It is not legal or tax advice: confirm your own obligations, and those of the businesses you invoice for, with your tax advisor.

## Where the invoice is issued

**In BeeL., always.** The invoice registered with AEAT is the one issued through BeeL.: BeeL. assigns its number from one of the issuer's series, computes its fingerprint, chains it to the previous record and submits it. The API does not register an invoice that was numbered or fingerprinted somewhere else, so BeeL. cannot sign and submit records for invoices your ERP numbers on its own.

What stays in your ERP is up to you:

| You want to… | Do this |
|---|---|
| Keep BeeL.'s PDF and email | Issue with `options.send_automatically: true`, or call [`send`](/invoices/sendCompanyInvoice) later |
| Render your own PDF | Issue in BeeL.; the API returns the number and the QR data. Check the architecture with your tax advisor first — see [Your own PDF](#your-own-pdf-and-qr) |
| Send your own email | Leave `send_automatically` out (it defaults to `false`) and send the document yourself |

The one thing you can't do is hand the customer a document whose number differs from the one registered with AEAT. Store BeeL.'s `invoice_number` in your ERP as the invoice's official number.

## Who generates the record, the hash and the chain

**BeeL., for every invoice it issues.** When you issue through the API, BeeL. generates the registration record (*registro de alta*), computes its SHA-256 fingerprint (*huella*), chains it to the previous record of the same NIF and submits it to AEAT. Voids produce their own cancellation record the same way, and correctives R1–R5 their own registration. Each issuing NIF has its own chain; you never compute or store one.

There is no mode in which your system computes the hash or keeps the chain and BeeL. only signs and submits: no request field accepts a hash, a previous record or a chain position. An architecture that needs the chain to live in your own system — a POS that fingerprints tickets locally, for example — needs a different kind of provider.

The rules that apply to software built on the API, and AEAT's criteria for systems made of several components, are in [Compliance and responsibilities](/verifactu/compliance-and-responsibilities#software-built-on-the-api).

> **Rules that apply here:** [REC-004 · BeeL. generates the hash and the chain](/rules/records#rec-004)

## When BeeL. or AEAT is unavailable

The two cases are different, because only one of them stops you from issuing.

### BeeL.'s API does not answer

**You cannot issue until it answers again.** The invoice number is assigned by BeeL. at the moment of issuing, and there is no offline mode, no pre-assigned block of numbers and no way to register later an invoice your system numbered while BeeL. was unreachable. A ticket numbered by your own system in the meantime would not be an invoice issued through BeeL., and BeeL. cannot register it afterwards — see [Compliance and responsibilities](/verifactu/compliance-and-responsibilities#software-built-on-the-api).

What you can do:

- **Queue the sale, not the invoice.** Keep the order in your system without an invoice number, and issue it through the API once BeeL. answers.
- **Keep the real date.** `issue_date` is the day the invoice is actually issued; send the day of the sale as `operation_date` — see [Dates](/guides/invoice-lifecycle#dates).
- **Retry safely.** Send every issue request with an `Idempotency-Key`, so a request that did reach BeeL. before the connection dropped is not issued twice — see [Idempotency](/guides/idempotency).
- **Check the status page.** [status.beel.es](https://status.beel.es) reports incidents.

Drafts and scheduled invoices do not help here: creating either one is also an API call, and a draft has no number until it is issued.

### AEAT does not answer

**You keep issuing normally.** The invoice is numbered and issued through BeeL. whatever AEAT's state; its submission is retried by BeeL. on its own. If it goes out on a later day than the invoice's issue date, BeeL. marks it as a late submission automatically — see [Dates and late submission](/verifactu/what-aeat-receives#dates-and-late-submission). Meanwhile the invoice reads `NOT_SUBMITTED` or `PENDING`; follow it with the `verifactu.status.updated` webhook and [reconcile](/verifactu/handling-rejections#reconcile-do-not-only-listen) the ones that stay there.

> **Rules that apply here:** [REC-007 · Keep invoicing when AEAT is unreachable](/rules/records#rec-007)

## Turning off BeeL.'s email

Nothing is emailed unless you ask for it. The processing `options` of [Create invoice](/invoices/createCompanyInvoice) all default to `false`:

```json
{
  "options": {
    "issue_directly": true,
    "send_automatically": false
  }
}
```

With `issue_directly: true` and no `send_automatically`, the invoice is numbered, registered with AEAT and its PDF generated, and nobody receives an email — even when the customer has an email address. The invoice stays `ISSUED`, with an empty `sending_history`. You can still send it from BeeL. at any moment with [`POST …/invoices/{invoice_id}/send`](/invoices/sendCompanyInvoice). Details in [Sending email](/guides/sending-email).

## Several brands under one NIF

Branding belongs to the **company**, and a company is one NIF. The logo, template and colour are set once per company in [Branding and PDF](/guides/branding-and-pdf), and BeeL.'s invoice emails show the company's trade name — or its legal name, if it has none — as the sender. Four trade names that share a NIF therefore share one look in BeeL.'s PDF and email.

Per invoice you can still change the email's `subject`, `message`, `recipients` and `cc` (`options.email_config` on create, or the body of `send`). You cannot change the logo or the sender per invoice.

If each brand needs its own look:

- **Render the PDF and send the email yourself**, with each brand's template — read [Your own PDF and QR](#your-own-pdf-and-qr) first.
- **Give each brand its own series** (`FAC-A-`, `FAC-B-`, …) so the numbering tells them apart. Series are per company and you can have as many as you need — see [Series and numbering](/guides/series-and-numbering). Pass `series_id` when you create the invoice.
- Use `metadata` (for example `{"brand": "acme"}`) to find a brand's invoices later — see [Filtering by metadata](/guides/filtering-by-metadata).

## Your own PDF and QR

The API returns the QR data (`verifactu.qr_base64`, and the URL in `verifactu.qr_url`) a few seconds after issuing — it is not in the issue response yet — together with BeeL.'s number. BeeL.'s own PDF already carries the number, the QR and its legend.

Before you build your own invoice document, check that architecture with your tax advisor: under the criteria AEAT has published, software that prints the invoice or generates its QR can be a component of the billing system that needs its own *declaración responsable* (the producer's signed statement of compliance). The rules are quoted in [Software built on the API](/verifactu/compliance-and-responsibilities#software-built-on-the-api), and what applies to the QR and its legend in [QR code and the invoice PDF](/verifactu/qr-and-pdf#rendering-your-own-pdf).

## Continuing your numbering

Create the series with `initial_number` set to the number after your ERP's last one (`151` if the last was `0150`). `initial_number` applies only to the first period — with `ANNUAL` or `MONTHLY`, every later period starts at 1 — and it locks with the first invoice, so pick the reset for next year now, from the table in [Continuing a sequence from another system](/guides/series-and-numbering#continuing-a-sequence-from-another-system). Credit notes in their own sequence (`REC-…`) need a default `CORRECTIVE` series, as described in [Correctives and proformas](/guides/series-and-numbering#correctives-and-proformas).

## Knowing when AEAT answers

Don't poll: subscribe to `verifactu.status.updated`, which fires when the submission leaves `PENDING`. The event list is in [Webhook events](/webhooks/events), and [Deduplication](/webhooks/deduplication) covers redeliveries. Reconcile periodically as a safety net — [Handling AEAT rejections](/verifactu/handling-rejections) explains why.

## Correcting and voiding

A corrective invoice points at the original by its BeeL. `invoice_id`, so only invoices issued in BeeL. can be corrected: one your ERP issued before the integration is corrected with the system that issued it. Void only an invoice that should never have existed. What each one does to the original is in [Invoice lifecycle](/guides/invoice-lifecycle#voiding-and-correcting), which to pick in [Cancel vs amend](/verifactu/cancel-and-fix), and the request shapes in [Corrective invoices](/verifactu/corrective-invoices).

## Before you go live

- [ ] Every invoice in your ERP stores BeeL.'s `invoice_id` and `invoice_number`
- [ ] Your series (ordinary and corrective) exist in the live environment, with the right `initial_number`
- [ ] You decided who sends the email, and `send_automatically` matches that decision
- [ ] If you render your own PDF, you checked that architecture with your tax advisor, and it prints BeeL.'s number, the QR and its legend
- [ ] A webhook subscription for `verifactu.status.updated` is active, and your receiver checks signatures
- [ ] Your ERP handles `REJECTED` — see [Handling AEAT rejections](/verifactu/handling-rejections)
- [ ] Retries of `POST` requests carry an `Idempotency-Key` — see [Idempotency](/guides/idempotency)

## Related

<Related>

- [Invoice lifecycle](/guides/invoice-lifecycle) — what each status allows
- [Series and numbering](/guides/series-and-numbering) — continue your existing numbering
- [Compliance and responsibilities](/verifactu/compliance-and-responsibilities) — who is responsible for what
- [Idempotency](/guides/idempotency) — retry safely from your ERP

</Related>

---

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