# E-invoicing

> Where the law requires structured e-invoices, Ownrecord generates an EN 16931 e-invoice (UBL 2.1, Peppol BIS Billing 3.0) for every invoice and credit note your entity routes to a provider, sends it after the document is issued, and follows its status.

More and more countries require invoices as structured data sent through a certified network instead of PDFs: public buyers first (B2G), then domestic business sales (B2B), sometimes consumer receipts (fiscalisation). Ownrecord generates the e-invoice from the issued document, validates its generator against the official rules, and hands the document to an **e-invoicing provider** (a certified access point or a national intermediary) that delivers it and reports what happened to it.

The PDF stays the human-readable copy. The e-invoice carries the same content, fixed when the document was issued: numbers, parties, lines, the tax per rate and the legal notes.

## Routes: which provider sends what

Each legal entity configures, per mode, which provider sends the e-invoices of documents to buyers in a **country** for a **transaction type**:

| Type  | Applies to                                                                                    |
| ----- | --------------------------------------------------------------------------------------------- |
| `b2b` | Invoices and credit notes whose buyer is a business                                           |
| `b2c` | Receipts and credit notes whose buyer is a consumer                                           |
| `b2g` | Documents of customers marked as public bodies (customer metadata `einvoice_buyer_type: b2g`) |

Each country and type takes one route. Documents of a case without a route get no e-invoice. A route applies from the moment it is saved: documents issued earlier aren't sent.

Configure the routes on the entity page (**E-invoicing**) or with [`einvoice.settings.update`](https://ownrecord.io/docs/reference/einvoice-settings-update.md). The page also shows what the knowledge base's e-invoicing mandates of the entity's home country call for, and whether each is covered. Mandates are shown whatever their review status in the knowledge base.

### The home-country mandate and going live

An entity whose home country requires e-invoices for domestic B2B sales (for example Croatia's Fiscalization 2.0) can't take a brand live until a provider is configured for that case in **live mode**: the go-live checklist item "E-invoicing for the home country". The requirement holds as soon as the knowledge base records such a mandate in force, even before the record is reviewed.

## What is sent

For each routed document, Ownrecord generates **EN 16931 UBL 2.1 in the Peppol BIS Billing 3.0 profile**: an `Invoice` (type 380) or a `CreditNote` (381) that names the original invoice. Its generator is checked against the official CEN/TC 434 EN 16931 rules and the Peppol BIS Billing 3.0 rules in CI.

| Your document                                                            | VAT category in the e-invoice                                |
| ------------------------------------------------------------------------ | ------------------------------------------------------------ |
| VAT charged (any rate above zero)                                        | `S`, with the rate                                           |
| VAT charged at zero                                                      | `Z`                                                          |
| Reverse charge                                                           | `AE`, with the reverse-charge wording printed on the invoice |
| Exempt                                                                   | `E`, with the exemption note                                 |
| Outside the scope of the tax (an export, a sale where you don't collect) | `O`, without VAT identifiers (EN 16931 BR-O-02)              |

Some documents can't be expressed in EN 16931 and fail instead: a document mixing lines outside the scope of VAT with taxed lines, a reverse-charge document without the buyer's VAT ID, a currency with more than two decimals.

### Electronic addresses

Peppol delivers to **electronic addresses** (participant IDs): a scheme code and an identifier, written `<scheme>:<identifier>`, e.g. `9934:HR12345678903`.

- **The seller's** is the entity's Peppol address from its e-invoicing settings; without one, it is derived from the entity's VAT ID where the Peppol code list has a VAT scheme for the country.
- **The buyer's** is the customer's `einvoice_endpoint` metadata; without it, it is derived from the buyer's VAT ID the same way. Consumers, and businesses in countries whose VAT numbers aren't Peppol addresses (Sweden, Finland, Denmark), need the metadata.

### Customer metadata e-invoicing reads

| Key                        | Value                                                                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `einvoice_endpoint`        | The buyer's electronic address, `<scheme>:<identifier>` (e.g. `0208:0123456789`)                                             |
| `einvoice_buyer_type`      | `b2g` for a public body: its documents take the `b2g` route                                                                  |
| `einvoice_buyer_reference` | The buyer's reference for its invoices (Peppol requires one; e.g. a German Leitweg-ID). Without it, the customer ID is used. |

The values are read when the e-invoice is queued (and again when it is retried), and recorded with it.

## Status

An e-invoice moves through these statuses; each change is an event:

| Status      | Meaning                                                              | Event                |
| ----------- | -------------------------------------------------------------------- | -------------------- |
| `pending`   | Queued for sending, right after the document was issued              |                      |
| `queued`    | Generated, stored and taken by the provider (`externalId` is its ID) | `einvoice.sent`      |
| `delivered` | Delivered to the buyer's access point or platform                    | `einvoice.delivered` |
| `accepted`  | Accepted by the receiver                                             | `einvoice.accepted`  |
| `rejected`  | Refused by the receiver; `error.message` gives the reason            | `einvoice.rejected`  |
| `failed`    | Couldn't be generated or sent, for a reason retrying alone won't fix | `einvoice.failed`    |

Ownrecord asks the provider about e-invoices on their way every 15 minutes, less often as time passes. A rejected or failed e-invoice raises an `EINVOICE_REJECTED` alert; the document itself stands. Fix the cause (for example the customer's `einvoice_endpoint`), then send it again from the invoice page or with [`einvoices.retry`](https://ownrecord.io/docs/reference/einvoices-retry.md). A wrong invoice is corrected with a credit note, which gets its own e-invoice.

The invoice and credit note pages show their e-invoice's status. [`einvoices.list`](https://ownrecord.io/docs/reference/einvoices-list.md) with `documentId` returns it over the API. The generated document is stored with its SHA-256, like the PDF.

## Providers

Certified providers are added as Ownrecord contracts them. Until then, the **fake provider** exists in development and test only: it accepts every document, reports it `queued`, `delivered` a minute later and `accepted` after five. A buyer whose name contains `(reject)` makes it reject the document after a minute, so you can try a rejection end to end. A real deployment refuses it, so nothing ever pretends an e-invoice was sent.

Fiscalisation of consumer receipts at the moment of sale, where a country requires it, comes with the home-country provider.
