API-documentatie

Authenticatie

Elke aanroep gaat over HTTPS en draagt een API-sleutel mee als bearer-token:

curl https://api.smedr.nl/v1/quotes \
  -H "Authorization: Bearer smedr_live_..."

Een beheerder maakt sleutels aan in smedr onder Instellingen → API-sleutels. De sleutel wordt daar één keer getoond en daarna nergens meer bewaard — ook niet door ons.

Een sleutel bepaalt zelf bij welke organisatie hij hoort. Er zit dus geen organisatie- of accountnaam in het pad, en je kunt met een sleutel nooit bij gegevens van een andere organisatie.

Behandel een sleutel als een wachtwoord. Zet hem nooit in front-end-code of in een openbare repository; hij hoort thuis op een server of in een geheimenkluis.

Rechten

Per sleutel wordt aangevinkt wat hij mag, per gebied en gesplitst in lezen en schrijven. Ontbreekt een recht, dan antwoordt de API met 403 en noemt hij welk recht mist.

Schrijven impliceert lezen: een sleutel die relaties mag aanmaken, mag ze ook ophalen.

Inkoopprijs en interne notitie op een product zitten achter een apart recht (products.cost). Zonder dat recht komen die velden niet in het antwoord, en worden ze bij het schrijven geweigerd in plaats van genegeerd.

Paginatie

Lijsten geven data en nextCursor terug. Is nextCursor gevuld, dan is er een volgende pagina; geef hem mee als ?cursor=. Is hij null, dan ben je klaar.

GET /v1/products?limit=100
GET /v1/products?limit=100&cursor=MjAyNi0wOC0yNlQxMDoxMjowMy4xMjM0NTYrMDJ8OGMyYg

De cursor is ondoorzichtig: lees er niets uit en bouw hem niet zelf. limit is standaard 50 en maximaal 200; een hogere waarde wordt afgekapt, niet geweigerd.

Alleen ophalen wat gewijzigd is

Geef ?updated_since= mee met een tijdstip, dan krijg je alleen wat op of ná dat moment is gewijzigd. Bewaar de updatedAt van je laatste synchronisatie en gebruik die de volgende keer.

GET /v1/quotes?updated_since=2026-08-26T10:00:00Z

Gearchiveerde offertes komen mee met archived: true in plaats van te verdwijnen. Zo ziet je koppeling dát er iets veranderd is; zou een offerte stil uit de lijst vallen, dan zou je denken dat er niets gebeurd was.

Schrijven en herhalingen

Elke POST vereist een Idempotency-Key: een waarde die jij per aanvraag zelf verzint. Komt dezelfde aanvraag nog eens binnen — bijvoorbeeld na een time-out waarbij je niet weet of hij is aangekomen — dan krijg je hetzelfde antwoord terug in plaats van een tweede relatie of factuur.

curl -X POST https://api.smedr.nl/v1/customers \
  -H "Authorization: Bearer smedr_live_..." \
  -H "Idempotency-Key: order-2026-0912" \
  -H "Content-Type: application/json" \
  -d '{"name":"Voorbeeld BV","city":"Eindhoven"}'

Hergebruik je dezelfde sleutel voor een andere aanvraag, dan volgt 409. Gebruik dus per aanvraag een nieuwe waarde. Bij PATCH en PUT is de header niet nodig: die zijn van nature herhaalbaar.

Velden die het systeem zelf toekent — id, offertenummer, relatienummer, bedragen — worden genegeerd als je ze meestuurt. Totalen worden altijd berekend uit de regels.

Grenzen

Er geldt een limiet van 600 aanroepen per minuut per sleutel. Daarboven volgt 429 met een Retry-After-header die zegt hoeveel seconden je moet wachten.

Een offerte of factuur mag maximaal 500 regels en 50 secties hebben in één aanvraag.

Een sleutel kan een lijst met toegestane IP-adressen dragen. Staat die ingevuld, dan werkt de sleutel alleen vanaf die adressen.

Webhooks

In plaats van blijven vragen of er iets veranderd is, kun je smedr laten melden dát er iets gebeurd is. Een beheerder stelt in de app onder Instellingen → API-sleutels op het tabblad Webhooks een bestemming in: een https-adres van jou, plus de gebeurtenissen waarop je wilt luisteren.

Wij sturen dan een POST met deze body:

{
  "type": "quote.accepted",
  "occurredAt": "2026-08-27T10:12:03+02:00",
  "data": { "type": "quote", "id": "8c2b..." }
}

De melding draagt alleen identificatie, geen inhoud. Haal de resource daarna zelf op via de API. Dat is met opzet: zo is er geen tweede weergave die uit de pas kan lopen, en gaan er geen gegevens in bulk over een kanaal waarvan wij de bestemming niet kennen.

Antwoord met een status in de 2xx-reeks. Alles daarbuiten — en een omleiding — telt als mislukt.

Waarop je kunt luisteren. Een beheerder vinkt per bestemming aan welke van deze gebeurtenissen hij wil ontvangen:

Een melding voor iets dat jouw eigen koppeling zojuist heeft aangemaakt komt gewoon bij je terug. Wil je die lus vermijden, dan kun je bijvoorbeeld je eigen schrijfacties kort onthouden en de bijbehorende melding overslaan.

Controleer de handtekening. Elke melding draagt een header:

X-Smedr-Signature: t=1787812864,v1=9a3f…

Bereken HMAC-SHA256 over de tekst <t>.<ruwe body> met het ondertekengeheim dat je bij het instellen één keer te zien kreeg, en vergelijk die met v1. Reken over de ruwe body, niet over opnieuw geserialiseerde JSON — dan verandert de tekst en klopt de handtekening niet meer.

const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const mine = crypto.createHmac("sha256", secret)
  .update(t + "." + rawBody, "utf8").digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(mine), Buffer.from(v1));

Verwerp een melding waarvan t meer dan vijf minuten oud is. Het tijdstip zit ín de ondertekende tekst, dus zonder die controle kan iemand een onderschepte melding opnieuw afspelen.

Herhalingen en volgorde. Mislukt een levering, dan proberen wij het opnieuw met oplopende tussenpozen — een halve minuut, twee minuten, tien minuten, een uur, zes uur, een dag — en geven daarna op. Dat betekent twee dingen voor jou:

Antwoord snel — wij wachten maximaal vijf seconden. Doe het echte werk daarna, niet vóór je antwoordt: een trage verwerking leidt tot een time-out en dus tot herhalingen.

Foutmeldingen

Fouten hebben altijd dezelfde vorm, zodat je er één keer op hoeft te programmeren:

{
  "error": "forbidden",
  "message": "Deze API-sleutel heeft het recht 'quotes.view' niet"
}

Een 401 maakt geen onderscheid tussen "deze sleutel bestaat niet" en "deze sleutel mag hier niet vandaan". Dat is met opzet: het antwoord mag niet verklappen of een sleutel bestaat.

Relaties

De klanten en prospects van de organisatie.

Contactpersonen

Hangen altijd aan een relatie. De eerste contactpersoon wordt automatisch de primaire.

Producten

De catalogus. Inkoopprijs en interne notitie zitten achter het recht products.cost.

Offertes

Een offerte heeft secties met regels. Bedragen worden altijd berekend uit de regels, inclusief de kortingsregels van de organisatie.

{
  "customerId": "8c2b...",
  "reference": "Aanvraag 2026-0912",
  "sections": [{
    "title": "Werkzaamheden",
    "lines": [
      { "description": "Advies", "qty": 2, "unitPrice": 100, "vatRate": 21 },
      { "description": "Installatie", "qty": 1, "unitPrice": 250, "discountPct": 10 }
    ]
  }]
}

Projecten

Alleen beschikbaar als de organisatie de module Projecten afneemt.

Taken en interacties

Eén lijst voor beide: kind: "task" is iets dat nog moet gebeuren, de andere soorten zijn iets dat heeft plaatsgevonden. Vereist de module CRM.

Facturen

Via de API aangemaakte facturen zijn altijd concept. Definitief maken en versturen gebeurt in smedr: dat kent een factuurnummer toe uit een doorlopende reeks en stuurt post naar een echte klant. Vereist de module Facturen.

Abonnementen

Ook hier: via de API aangemaakte abonnementen zijn concept. Activeren start een terugkerende verplichting en blijft daarom een handeling in smedr. Vereist de module Abonnementen.