# 0014. Billingo is the system of record for invoices

- **Status:** Accepted
- **Date:** 2026-06-10

## Context

Hungarian invoicing is regulated: sequential numbering without gaps, NAV online reporting, storage
requirements, prescribed corrections. Getting it wrong is a legal problem, not a bug.

## Decision

**Do not issue invoices. Let [Billingo](https://www.billingo.hu/) do it, and store what it returns.**

Three console commands, run every minute in order
([`commands/BillingoController.php`](../../commands/BillingoController.php)):

| Command | Does |
|---------|------|
| `billingo/sync-partners` | pushes customers and companies to Billingo as partners |
| `billingo/invoice` | issues invoices for billable payments; stores `billingoId`, `invoiceNumber`, downloads the PDF into `invoiceFileId` |
| `billingo/sync` | reads invoice state back and advances the payment status |

Client: `deviddev/billingo-api-v3-php-sdk`. `BILLINGO_SEND_EMAIL` decides whether Billingo mails the invoice
to the customer on creation.

## Alternatives

- **Generate invoices in the application.** Means owning sequential numbering, NAV reporting and every
  regulatory change. Disproportionate, and a legal liability.
- **A different invoicing provider** (Számlázz.hu, Szamlazz API). Equivalent in principle; Billingo was the
  client's existing provider, so the partner and invoice data already lived there.
- **Manual invoicing in Billingo's own UI.** What it replaced — the payment records already exist here, and
  re-keying them was the actual cost being removed.

## Consequences

- **The application never generates an invoice number.** It stores what Billingo returns.
- **Recovery is one-directional.** An invoice that exists in Billingo but not here is recovered by
  `billingo/sync`. The reverse is not — a payment marked billed with no Billingo counterpart has to be sorted
  out by hand.
- **Correctness of the numbering, the reporting and the archive is Billingo's problem**, which is the whole
  point.
- Three cron entries and an external dependency on the critical billing path. A Billingo outage stops
  invoicing; it does not stop the site or the rentals.
- Customer data is pushed to a third party, which is a data-protection consideration the client accepted as
  part of using Billingo at all.
- The PDF is downloaded and stored locally (`invoiceFileId`), so the customer account area can serve invoices
  without calling Billingo per request.