dit bladDit blad is voor je ontwikkelaar of boekhouder: wat de API kan, hoe een aanroep eruitziet en hoe je een webhook controleert.
Voor je ontwikkelaar of boekhouder
Een REST API zonder verrassingen.
Kant-en-klare koppelingen met boekhoudpakketten leveren we niet. Wel een kleine, voorspelbare API waarmee je ontwikkelaar of boekhouder er zelf een maakt.
Bonnen ophalen
GET /v1/entries geeft je bonnen, nieuwste eerst, met cursor-paginering (maximaal 100 per pagina). Filter op status.
Klussen synchroniseren
GET /v1/jobs leest je actieve klussen, POST /v1/jobs maakt er een aan. Zo blijft je klussenlijst gelijk met je eigen planning.
Webhooks
Een bericht naar jouw server bij elke nieuwe bon (new.entry) en elke goedkeuring (approved.entry), ondertekend met HMAC-SHA256. Je adres registreren gaat langs dezelfde weg als de sleutel.
API-sleutels per bedrijf
Een sleutel komt alleen bij je eigen bedrijf en wordt op de server als hash bewaard. Aanvragen en intrekken gaat via info@meerstaat.nl; een beheerscherm in de app is er nog niet.
één sleutel, één header, één antwoord
- basis-url
- https://app.meerstaat.nl/api/v1
- sleutel
- Authorization: Bearer mk_...
Drie voorbeelden
Zo praat je met de API.
De sleutel krijg je precies één keer te zien. Daarna staat er nog alleen een hash van op de server, ook voor ons.
Goedgekeurde bonnen ophalen, 25 per pagina
curl "https://app.meerstaat.nl/api/v1/entries?status=approved&limit=25" \
-H "Authorization: Bearer mk_JOUW_SLEUTEL"Het antwoord bevat nextCursor. Is die null, dan ben je klaar.
De volgende pagina, met de cursor uit het vorige antwoord
curl "https://app.meerstaat.nl/api/v1/entries?status=approved&cursor=aZ29fK1pQ7" \
-H "Authorization: Bearer mk_JOUW_SLEUTEL"Geef de id van de laatste bon door als cursor voor de volgende pagina.
Een klus aanmaken vanuit je eigen planning
curl -X POST "https://app.meerstaat.nl/api/v1/jobs" \
-H "Authorization: Bearer mk_JOUW_SLEUTEL" \
-H "Content-Type: application/json" \
-d '{"name": "Dakkapel Bakker, Amersfoort", "client": "De heer Bakker"}'Antwoord: 201 met de aangemaakte klus, inclusief id voor je eigen administratie.
doorlopen tot nextCursor leeg is
en dit gebeurt er zonder dat jij erom vraagt
De volledige OpenAPI 3.1-specificatie, inclusief het webhook-contract en de controle van de HMAC-handtekening, staat op meerstaat.nl/openapi.yaml. Je kunt hem rechtstreeks in Postman, Insomnia of een generator laden.
Beginnen
De sleutel vraag je aan zodra er bonnen zijn.
Eerst bonnen, dan koppelen. Mail vanaf het adres van het account naar info@meerstaat.nl op het moment dat je ontwikkelaar de sleutel nodig heeft; je krijgt hem terug en ziet hem daarna niet meer.
geen creditcard nodig
maandelijks opzegbaar