Voor ontwikkelaars

API v1

Laatst bijgewerkt: oktober 2026

Met de API leest een koppeling van jouw bedrijf — een boekhoud- of BI-pakket — je offertes, opdrachten, facturen en planning. Alleen lezen: via de API wijzigt er niets. De API hoort bij het pakket Enterprise; heeft je groep meerdere BV's, dan maak je per BV een eigen token.

Authenticatie

Een beheerder maakt het token in het dashboard onder Beheer → API en kiest welke bronnen het mag lezen. Het token wordt één keer getoond; bewaar het direct in je koppeling.
Stuur het mee in de kop Authorization: Bearer cbk_… — nooit in de URL. Een verzoek met een token in de URL wordt geweigerd.
Kwijt of gelekt? Trek het token in onder Beheer → API en maak een nieuw. Een ingetrokken token werkt meteen niet meer.

curl -H "Authorization: Bearer cbk_…" \ "https://app.calcurabouw.nl/api/v1/offertes?limit=50"

Bronnen en velden

Elke bron heeft een lijst en een ophalen-op-id. Een lijst geeft {"data": [...], "volgende_cursor": "…" | null}, een enkel object {"data": {...}}. Bedragen zijn euro's met twee decimalen; datums zijn ISO (2026-09-27) en tijdstippen (aangemaakt_op, gewijzigd_op, verstuurd_op) zijn UTC, met een Z erachter (2026-09-27T10:15:00Z). Van de opdrachtgever geeft de API alleen klant_id en klant_naam — geen adres, e-mail of telefoon — en geen namen van medewerkers.

Offertes — scope offertes:lezen

Paden: GET /offertes, GET /offertes/{id}
Filters: status (aangevraagd, offerte_in_de_maak, verstuurd, on_hold, gewonnen, verloren), gewijzigd_sinds
Velden: id, offertenummer, status, betreft, kenmerk, klant_id, klant_naam, aanvraag_op, offerte_op, geldig_tot, verstuurd_op, gewonnen_op, verloren_op, contractwaarde_excl, bedragen, aangemaakt_op, gewijzigd_op

Opdrachten — scope opdrachten:lezen

Paden: GET /opdrachten, GET /opdrachten/{id}
Filters: gewijzigd_sinds
Velden: id, offertenummer, betreft, klant_id, klant_naam, gewonnen_op, contractwaarde_excl, bedragen, start, eind, leverdatum, team_id, team, aantal_taken, aangemaakt_op, gewijzigd_op

Facturen — scope facturen:lezen

Paden: GET /facturen, GET /facturen/{factuurnummer}
Filters: —
Velden: factuurnummer, soort (termijn of meerwerk), offerte_id, offertenummer, klant_id, klant_naam, factuurdatum, vervaldatum, omschrijving, termijn_index, pct, bedrag_excl, btw, btw_21, btw_9, bedrag_incl, betaald, betaald_op, termijn_vervallen

Planning — scope planning:lezen

Paden: GET /planning, GET /planning/{id}
Filters: gewijzigd_sinds
Velden: id (van de opdracht), offertenummer, betreft, klant_id, klant_naam, start, eind, team_id, team, taken (id, fase, taak, start, eind, mijlpaal), gewijzigd_op

bedragen bevat subtotaal_excl, korting, btw, btw_21, btw_9, totaal_incl. Een opdracht is een gewonnen offerte en heeft hetzelfde id. Een factuur met termijn_vervallen: true hoort bij een betalingstermijn die sindsdien uit de offerte is gehaald; de factuur zelf blijft bestaan.

Een proefaccount begint met een voorbeeldproject. Dat zit niet in de API: het staat in geen lijst en op id volgt een 404, ook voor een factuur die je erop maakte. Kies je in het dashboard bij dat project “Als echt project houden”, dan is het een opdracht als elke andere.

Paginering

limit: 1 tot 100, standaard 50.
Staat er een volgende_cursor in het antwoord, geef die mee als cursor voor de volgende pagina; null is de laatste.
Offertes, opdrachten en planning staan op aanmaakdatum, nieuwste eerst; facturen op factuurnummer, hoogste eerst.
Met gewijzigd_sinds haal je alleen op wat sindsdien is gewijzigd: een ISO-datum of -tijdstip, met Z of een offset (codeer de + dan als %2B); zonder aanduiding is het UTC. Een gewijzigd_op uit een eerder antwoord kun je letterlijk terugsturen.

De rem

Hoogstens 60 verzoeken per minuut per token, en 300 per minuut per account over al zijn tokens samen. Daarboven volgt een 429 met de kop Retry-After. Een verzoek dat op een fout uitkomt (bijvoorbeeld een ontbrekende scope) telt ook mee. Stuurt één adres binnen een minuut meer dan 30 ongeldige tokens, dan krijgt het nog een minuut een 429 op ongeldige tokens; een geldig token werkt gewoon door.

Foutcodes

Een fout heeft de vorm {"detail": {"code": "…", "message": "…"}}, met twee uitzonderingen die het framework zelf geeft: een 405 en een 422 (zie de tabel).

Status	Code	Betekenis
400	token_in_url	Er staat een token in de URL. Het verzoek is niet uitgevoerd; trek dat token in en maak een nieuw.
400	ongeldige_cursor / ongeldige_parameter	De cursor of een filter klopt niet.
401	token_ontbreekt / token_ongeldig	Geen token, of een token dat niet bestaat of is ingetrokken.
402	feature_not_entitled	Het account heeft geen pakket met API-koppelingen (Enterprise). Naast code en message staat hier ook feature.
403	scope_ontbreekt	Het token mag deze bron niet lezen.
403	account_geblokkeerd	Het account is niet actief.
404	niet_gevonden	Het object bestaat niet in dit account, of het pad bestaat niet onder /api/v1.
405	—	De API kent alleen GET. De foutvorm is hier {"detail": "Method Not Allowed"}.
422	—	Een parameter heeft een ongeldige waarde, bijvoorbeeld limit boven 100. De detail is hier een lijst met per parameter wat er mis is.
429	te_veel_verzoeken	De rem is bereikt, of er kwamen van jouw adres te veel ongeldige tokens (30 per minuut). De kop Retry-After zegt na hoeveel seconden het weer kan.

Privacy

Je koppeling leest gegevens van jouw klanten; jouw bedrijf blijft daarvoor verantwoordelijk. Wat wij vastleggen en hoe lang, staat in de privacyverklaring.