Formaten en paginering

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:

{
  "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:

Voorbeeld: alle te late facturen, oudste vervaldatum eerst:

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.

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.

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 (alleen bij concepten);
• publicUrl: de online factuur, 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.