Conventies

Elke request en response volgt dezelfde regels. Ken je deze pagina, dan ken je de hele API.

De envelope

Elke response heeft dezelfde structuur. Gelukt:

json

{
  "data": { },
  "meta": { }
}

Mislukt:

json

{
  "error": {
    "code": "not_found",
    "message": "Invoice not found."
  }
}

data bevat het object of de lijst waar je om vroeg. meta bevat extra informatie zoals paginering. Er is geen top-level success-boolean. Bij fouten lees je op de pagina Fouten hoe error in elkaar zit.

Identifiers

Elk object heeft een guid: een UUID die niet verandert. Relaties verwijzen met *_guid, bijvoorbeeld client_guid op een factuur. Sla deze GUID's op in je eigen systeem om objecten terug te vinden.

Heb je zelf een systeem met eigen id's? Gebruik dan external_id: een vrij veld dat je zelf vult en waarop je kunt filteren waar het endpoint dat ondersteunt.

Datums en bedragen

Datums: YYYY-MM-DD, bijvoorbeeld 2026-07-21 (zoals invoice_date / due_date).
Tijdstippen: ISO-achtige strings in velden zoals created_at, paid_at en sent_at.
Bedragen: decimale getallen in euro's. Op facturen o.a. subtotal, vat, vat_price, total_ex_vat en total_inc_vat.

Paginering

Lijst-endpoints pagineren met page en per_page. Default page=1, default per_page=25, maximum per_page=200.

bash

curl -sS "https://api.appficient.nl/v1/invoices?page=2&per_page=50" \
  -H "Authorization: Bearer apf_jouw_key_hier"

De response vertelt in meta waar je bent:

json

{
  "data": [ ],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 128,
    "pages": 3
  }
}

Filteren, zoeken en sorteren

Filter met queryparameters, bijvoorbeeld ?client_guid=... of ?payment_status=....
Zoek met ?search=... (op veel lijsten ook alias ?qs=...) op de velden die per endpoint gedocumenteerd staan.
Sorteer met ?sort= en ?order=asc|desc. Welke sort-velden een endpoint ondersteunt staat bij dat endpoint.

Een onbekende waarde in een filter, sort of enum geeft een 422 met uitleg. De API raadt nooit stilzwijgend iets voor je.