---
title: "Formaten en paginering · EenFactuurMaken.nl"
description: "De afspraken van de EenFactuurMaken.nl REST API. JSON, bedragen in centen, decimalen als string, datums, lijsten en paginering, filteren, sorteren en PATCH."
url: "https://eenfactuurmaken.nl/docs/api/conventions"
markdown_url: "https://eenfactuurmaken.nl/docs/api/conventions.md"
language: "nl-NL"
---

# Formaten en paginering

De afspraken van de EenFactuurMaken.nl REST API. JSON, bedragen in centen, decimalen als string, datums, lijsten en paginering, filteren, sorteren en PATCH.

## JSON

Je stuurt JSON met `Content-Type: application/json` en krijgt JSON terug. Uitzonderingen: PDF (`application/pdf`), UBL (`application/xml`), ZIP-exports en het uploaden van een logo (`multipart/form-data` met een veld `file`).

## Bedragen in centen

Alle bedragen zijn **hele centen** in velden die eindigen op `Cents`: `unitPriceCents: 8500` is € 85,00. Zo heb je nooit afrondingsverschillen. Prijzen op regels zijn **exclusief btw**.

Creditnota's bewaren bedragen **positief**. Reken ze zelf negatief in rapportages.

## Decimalen als string

Aantallen, kortingen, btw-tarieven en wisselkoersen zijn decimalen. Stuur ze als string of getal: `"2.5"`, `2.5` en `"2,5"` werken allemaal. Je krijgt ze terug als string, bijvoorbeeld `"quantity": "2.5000"`, `"vatRate": "21.00"`.

## Datums

- Zakelijke datums (factuurdatum, vervaldatum, leverdatum) zijn `YYYY-MM-DD`, zonder tijd. "Vandaag" is vandaag in Nederland.
- Tijdstempels (velden die eindigen op `At`, zoals `createdAt` en `paidAt`) zijn ISO 8601 in UTC.

## Id's

Id's zijn strings (uuid). Je ziet alleen je eigen gegevens: het id van iets van iemand anders geeft gewoon `404 not_found`.

## Lijsten

Lijsten geven altijd dit terug:

```json
{
  "data": [ { "id": "…", "number": "2026-0001" } ],
  "page": 1,
  "pageSize": 25,
  "total": 132
}
```

Blader met `page` (vanaf 1) en `pageSize` (standaard 25, maximaal 100).

### Facturen filteren

`GET /invoices` kent deze parameters:

| Parameter | Waarden |
| --- | --- |
| `status` | `draft`, `issued`, `sent`, `paid`, `cancelled`, `overdue` (onbetaald en te laat), `open` (definitief of verstuurd, onbetaald) |
| `kind` | `invoice` of `credit_note` |
| `customerId` | Facturen van één klant |
| `q` | Zoeken op nummer, klant of referentie |
| `from`, `to` | Factuurdatum vanaf / tot en met (`YYYY-MM-DD`) |
| `sort` | `issueDate`, `number`, `total`, `dueDate`, `createdAt`; met `-` ervoor aflopend. Standaard `-createdAt` |

Voorbeeld: alle te late facturen, oudste vervaldatum eerst:

```bash
curl "https://eenfactuurmaken.nl/api/v1/invoices?status=overdue&sort=dueDate&pageSize=100" \
  -H "Authorization: Bearer $EENFACTUURMAKEN_API_KEY"
```

Klanten en producten zoek je met `q`; gearchiveerde klanten tel je mee met `includeArchived=true`.

## Maken en wijzigen

- `POST` maakt iets aan en geeft het nieuwe object terug (status `201`). Acties zoals `/issue` en `/mark-paid` geven het bijgewerkte object terug (status `200`).
- `PATCH` wijzigt alleen de velden die je meestuurt. Velden die je weglaat, blijven zoals ze waren. Stuur `null` (of `""` bij tekst) om een veld leeg te maken.
- Bij facturen vervangt `lines` in een `PATCH` **alle** regels. Stuur dus de complete lijst.
- `DELETE` geeft een kort antwoord terug, zoals `{ "id": "…", "deleted": true }`. Een klant of product dat nog op facturen staat, wordt gearchiveerd in plaats van verwijderd.

Een definitieve factuur kun je niet meer met `PATCH` wijzigen (`409 invoice_locked`). Gebruik een [creditnota](https://eenfactuurmaken.nl/docs/credit-notes).

## Standaardwaarden

Laat je velden weg bij het maken van een factuur, dan vullen we ze in zoals de app dat doet: datums van vandaag, de betaaltermijn, valuta, taal en btw-behandeling van de klant of je bedrijf, en `supplyType` van de klant of je bedrijf (standaard `services`). Zie [Btw-behandeling kiezen](https://eenfactuurmaken.nl/docs/vat/treatments#suggestion).

## Factuurobject

`GET /invoices/{id}` geeft alle velden van de factuur, plus:

- `lines` (op volgorde) en de totalen (`subtotalCents`, `vatTotalCents`, `totalCents`);
- `displayStatus`: de status, met `overdue` voor te late facturen;
- `seller` en `customer`: bij een definitieve factuur de vastgelegde gegevens, bij een concept de actuele;
- `compliance`: de [controle](https://eenfactuurmaken.nl/docs/invoices/checks) (alleen bij concepten);
- `publicUrl`: de [online factuur](https://eenfactuurmaken.nl/docs/invoices/online-invoice), of `null`;
- `firstViewedAt`, `viewedAt` en `viewCount`: wanneer je klant hem bekeek;
- `creditNotes`: creditnota's voor deze factuur;
- `creditedInvoiceNumber` en `creditedInvoiceDate` bij een creditnota.

In lijsten krijg je een korte versie: id, soort, status, displayStatus, nummer, datums, klantnaam, totaal, valuta en betaaldatum.

Laatst bijgewerkt op 13 oktober 2026