# Facturen

`GET` en `POST /api/v1/invoices`. Maak een concept of verstuur direct: versturen nummert en vergrendelt.

## Facturen ophalen

`GET /api/v1/invoices` vraagt `invoices:read` en geeft de vijftig nieuwste facturen, nieuwste eerst. Een sleutel met profielbeperking ziet alleen facturen van dat profiel.

```json
{
  "data": [
    {
      "id": "7f2b…",
      "number": "2026-0012",
      "status": "sent",
      "total_incl": 12100,
      "issue_date": "2026-03-01",
      "customer_id": "c0a8…",
      "public_token": "pt_…"
    }
  ]
}
```

Met `public_token` maak je de publieke pagina van de factuur: `https://invoice.cijfr.com/p/<token>`. Daar staat de pdf, iDEAL en de SEPA-QR.

## Factuur aanmaken

`POST /api/v1/invoices` vraagt `invoices:write` en accepteert `Idempotency-Key`. Zonder `send` is het resultaat een concept dat je in de app verder bewerkt. Met `send: true` geeft Cijfr de factuur meteen uit: gatloos nummer, vergrendeld, en de e-mail naar de klant wordt verstuurd.

| Veld | Type | Verplicht | Toelichting |
| --- | --- | --- | --- |
| `customerId` | uuid | ja | Klant uit `POST /customers` of de app |
| `lines` | array | ja | 1 tot 500 regels, zie hieronder |
| `issueDate` | date | nee | Standaard vandaag |
| `dueDate` | date | nee | Standaard `issueDate` + 14 dagen |
| `send` | boolean | nee | `true` = uitgeven en e-mailen, standaard `false` |
| `profileId` | uuid | nee | Cijfr-profiel voor huisstijl en reeks |

| Regelveld | Type | Verplicht | Toelichting |
| --- | --- | --- | --- |
| `description` | string | nee | Regeltekst, standaard `Regel` |
| `quantity` | number | nee | Aantal, standaard `1` |
| `unitPriceCents` | integer | nee | Prijs per eenheid in centen |
| `vatTreatment` | enum | nee | `standard_21`, `reduced_9`, `zero`, `exempt`, `reverse_charge`, `intra_community` |
| `productId` | uuid | nee | Koppelt de regel aan een product |

```bash
curl https://api.cijfr.com/api/v1/invoices \
  -H "Authorization: Bearer $CIJFR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-order-1042" \
  -d '{
    "customerId": "c0a8…",
    "send": true,
    "lines": [
      {
        "description": "Websiteonderhoud maart",
        "quantity": 4,
        "unitPriceCents": 7500,
        "vatTreatment": "standard_21"
      }
    ]
  }'
```

```json
{
  "data": {
    "id": "7f2b…",
    "number": "2026-0012",
    "public_token": "pt_…",
    "emailed": true,
    "emailError": null
  }
}
```

## Wat je moet weten

- `send: true` vergrendelt de factuur meteen. Daarna is hij onveranderbaar; een correctie is een creditnota in de app.
- `emailed` is `false` met een `emailError` als de mail niet weg kon, bijvoorbeeld zonder gekoppelde maildienst. De factuur is dan wél uitgegeven.
- Klant-, product- en profiel-id's moeten bij jouw organisatie horen, anders `400 validation`.
- Kan je organisatie niet versturen (betaling achter), dan `402 billing_readonly`. Concepten aanmaken kan nog wel.
- Totaalbedragen rekent de server uit; je hoeft zelf geen totalen mee te sturen.