Publieke API

De publieke API laat uw eigen software met Service Suite praten: een boekhoudpakket dat facturen ophaalt, een klantenportaal dat een interventie aanmaakt, een dashboard dat de status van uw toestellen volgt.

Het is een productinterface: u werkt met klanten, sites, toestellen, serviceorders, contracten, voorraad en facturen. U hoeft niets te weten over hoe Service Suite intern is opgebouwd.

Het scherm API-sleutels. Een sleutel handelt altijd als een gekozen gebruiker.

Waarvoor u dit gebruikt

• Klanten en sites gelijk houden met uw bestaande beheersysteem.
• Serviceorders laten aanmaken door een ander systeem — een monitoringtool, een webformulier, een klantenportaal.
• Facturen en voorraadstanden uitlezen voor rapportering.
• Een extern systeem verwittigen zodra een interventie is afgerond.

Wie dit kan gebruiken

Rol	Wat die doet
Beheerder	Maakt sleutels aan, kent rechten toe en trekt sleutels in
Uw ontwikkelaar of leverancier	Gebruikt de sleutel om te koppelen

Vereisten: beheerderstoegang tot Service Suite, en iemand die de koppeling kan bouwen. Er is geen bijkomende licentie of module nodig.

Snel starten

Basisadres	https://<uw-service-adres>/api/v1/
Specificatie	/api/v1/openapi.json — OpenAPI 3.1
Documentatiepagina	/api/docs

curl https://<uw-service-adres>/api/v1/me \
  -H "Authorization: Bearer <API_KEY>"

/me is de gezondheidscontrole: ze bewijst dat de sleutel werkt en toont exact wat hij mag.

{
  "data": {
    "credential": {
      "name": "Boekhouding — nachtelijke synchronisatie",
      "prefix": "a1b2c3d4",
      "scopes": ["customers:read", "invoices:read"],
      "expires_at": null
    },
    "acting_as": { "id": 42, "name": "Koppeling boekhouding" },
    "api_version": "v1"
  }
}

Een sleutel aanmaken

1. Ga naar Instellingen → Publieke API → Nieuwe API-sleutel.

2. Geef de sleutel een naam die zegt waarvoor hij dient. Die naam staat in het toegangslogboek.

3. Kies namens welke gebruiker de sleutel werkt. Dit is de echte rechtengrens — zie hieronder.

4. Vink de rechten (scopes) aan die de koppeling nodig heeft, en niet meer.

5. Stel eventueel een vervaldatum en toegelaten IP-reeksen in.

6. Bewaar. Het geheim wordt één keer getoond. Kopieer het meteen naar uw wachtwoordkluis.

Het geheim is daarna niet meer op te vragen

Er wordt alleen een onomkeerbare afdruk van het geheim bewaard. Niemand kan het achteraf terugvinden — ook Digitalnatie niet. Bent u het kwijt, dan vernieuwt u de sleutel.

Een sleutel is geen recht

Elke aanvraag loopt namens de gekozen gebruiker, met diens rechten en zichtbaarheidsbereik. Een sleutel die aan een technieker hangt die enkel zijn eigen opdrachten ziet, ziet via de API precies hetzelfde — niet meer.

De rechten van de sleutel kunnen dus alleen beperken, nooit uitbreiden. Maak voor koppelingen een aparte gebruiker aan met exact de rechten die de koppeling nodig heeft.

Rechten (scopes)

Scope	Wat het opent
customers:read / customers:write	Klanten
locations:read / locations:write	Sites & locaties
assets:read / assets:write	Toestellen & materieel
service_orders:read / service_orders:write	Serviceorders
contracts:read	Onderhoudscontracten
stock:read	Voorraad
invoices:read	Facturen
reports:read	Rapportgegevens
webhooks:manage	Webhooks beheren

Voorraad en facturen zijn in v1 enkel leesbaar. Boekingen en voorraadmutaties gebeuren in Service Suite zelf, niet via de API.

Wat u kunt opvragen en wijzigen

Bron	Lezen	Aanmaken	Wijzigen	Archiveren
customers	✅	✅	✅	✅
locations	✅	—	✅	—
assets	✅	✅	✅	✅
service-orders	✅	✅	✅	—
contracts	✅	—	—	—
stock	✅	—	—	—
invoices	✅	—	—	—

GET    /api/v1/<bron>              lijst
GET    /api/v1/<bron>/<id>         één record
POST   /api/v1/<bron>              aanmaken
PATCH  /api/v1/<bron>/<id>         wijzigen
DELETE /api/v1/<bron>/<id>         archiveren (nooit definitief wissen)

DELETE archiveert. Er wordt via de API nooit iets definitief verwijderd.

Velden worden bewust vrijgegeven

Elke bron geeft een vaste lijst velden terug. Een nieuw veld in Service Suite verschijnt niet vanzelf in de API — dat is een bewuste beslissing per veld, en het verschil tussen een API en een databankuitvoer over HTTP.

Paginering, filteren en sorteren

curl "https://<uw-service-adres>/api/v1/assets?customer_id=57&page=2&page_size=100&sort=-write_date" \
  -H "Authorization: Bearer <API_KEY>"

Parameter	Standaard	Maximum
page	1	—
page_size	50	200

Vraagt u meer dan 200, dan krijgt u er 200 — geen foutmelding.

Sorteren met sort, meerdere velden gescheiden door komma’s, - vooraan voor aflopend. Filteren met de filternamen van de bron; updated_since staat op elke bron en is wat u nodig hebt voor een incrementele synchronisatie.

Sorteer- en filternamen liggen per bron vast. Een naam die niet bestaat, wordt geweigerd in plaats van stil genegeerd — zo merkt u een tikfout meteen, in plaats van maanden later te ontdekken dat uw filter nooit werkte.

Veilig opnieuw proberen

Stuur bij elke POST een eigen Idempotency-Key:

curl -X POST https://<uw-service-adres>/api/v1/service-orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Idempotency-Key: <UNIEKE_WAARDE_PER_AANVRAAG>" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": 57, "location_id": 112, "description": "Jaarlijks onderhoud"}'

Verliest u de verbinding en probeert u opnieuw met dezelfde sleutelwaarde, dan krijgt u het oorspronkelijke resultaat terug in plaats van een tweede serviceorder. Zonder die kop is een herhaalde aanvraag een echte tweede aanvraag.

Elke aanvraag krijgt ook een X-Request-Id terug. Vermeld die bij een melding — daarmee is uw aanvraag terug te vinden in het logboek.

Aanvraagsnelheid

Soort	Per minuut
Lezen	600
Schrijven	120
Webhooks beheren	60
Mislukte aanmeldingen	20

De teller loopt per sleutel, dus een drukke koppeling verbruikt het budget van een andere niet. Bij overschrijding krijgt u 429 met een Retry-After-kop. Respecteer die en probeer opnieuw met oplopende wachttijd.

Foutmeldingen

Code	Betekenis	Wat u doet
400	Ongeldige parameter of veld	Corrigeer de aanvraag; het antwoord noemt het veld
401	Sleutel ontbreekt, is fout, vervallen of ingetrokken	Controleer de sleutel
403	De sleutel mist de nodige scope, of de gebruiker het recht	Ken de scope toe, of pas de rechten van de gebruiker aan
404	Bestaat niet, of ligt buiten het bereik van de gebruiker	Controleer id en rechten
409	Conflict — bijvoorbeeld een hergebruikte Idempotency-Key met een andere inhoud	Gebruik een nieuwe waarde
429	Te veel aanvragen	Wacht en probeer opnieuw

Een 403 door een ontbrekende scope en een 403 door ontbrekende rechten van de gebruiker vragen een verschillende oplossing. Het antwoord zegt welke van de twee het is.

Webhooks

Een mogelijkheid die u zelf inschakelt

Webhooks zijn volledig ondersteund, maar er staat er standaard geen enkele klaar. Een ontvangstadres is iets dat u per omgeving zelf aanmaakt en beheert. Zolang u er geen aanmaakt, verstuurt Service Suite niets naar buiten.

In plaats van te blijven bevragen, laat u Service Suite u verwittigen.

Gebeurtenis	Wanneer
service_order.created	Een serviceorder is aangemaakt
service_order.updated	Een serviceorder is gewijzigd
service_order.status_changed	De status is veranderd
service_order.completed	De interventie is afgerond
asset.created / asset.updated	Een toestel is aangemaakt of gewijzigd
contract.created	Een onderhoudscontract is aangemaakt
invoice.posted	Een factuur is geboekt

Elke levering draagt een HMAC-SHA256-handtekening. Controleer die vóór u de inhoud gebruikt — zo weet u dat de melding echt van uw omgeving komt. Leveringen gebeuren op de achtergrond en worden bij een fout opnieuw geprobeerd met oplopende wachttijd.

Uw ontvangstadres moet publiek bereikbaar zijn. Adressen op een privénetwerk worden geweigerd.

Webhooks vereisen versleutelde opslag

Een handtekeningsleutel moet leesbaar blijven om te kunnen ondertekenen, dus hij kan niet worden weggehasht. Hij wordt daarom versleuteld bewaard, met een sleutel die buiten de databank leeft. Is die versleuteling in een omgeving niet beschikbaar, dan wordt een webhook geweigerd in plaats van onbeschermd opgeslagen.

Afscherming tussen omgevingen

Elke klant werkt in zijn eigen afgescheiden omgeving. De API bepaalt die omgeving uit het adres waarmee u ze aanspreekt; een parameter om van omgeving te wisselen bestaat niet en wordt geweigerd. Bovendien is elke sleutel gebonden aan de omgeving die hem uitgaf, zodat een kopie van een omgeving nooit met de sleutels van het origineel kan worden aangesproken.

Nazicht

Elke aanvraag wordt geregistreerd: tijdstip, sleutel, methode, bron, antwoordcode, duur en een aanwijzing van de herkomst. Inhoud van aanvragen, sleutels en koppen worden nooit vastgelegd. Zo blijft het logboek bruikbaar om een probleem te onderzoeken, zonder zelf een tweede kopie van uw gegevens te worden.

Gekende beperkingen

Vermeld in plaats van stilgehouden.

• Voorraad en facturen zijn in v1 enkel leesbaar. Aanmaken of wijzigen kan niet via de API.
• Techniekers, ploegen, projecten en uren hebben in v1 geen eigen bron.
• De API kent één versie, v1. Wijzigingen die bestaande koppelingen zouden breken, komen in een volgende versie en niet in deze.

Goede praktijken

• Eén sleutel per koppeling, nooit één gedeelde sleutel. Zo kunt u er één intrekken zonder de rest te breken.
• Ken enkel de scopes toe die de koppeling gebruikt. Begin bij lezen alleen.
• Gebruik altijd Idempotency-Key bij het aanmaken.
• Synchroniseer incrementeel met updated_since in plaats van telkens alles op te halen.
• Bewaar het geheim in een kluis, nooit in broncode of in een configuratiebestand dat mee in versiebeheer gaat.
• Stel een vervaldatum in voor sleutels van externe partijen.

Volgende stap

• Rechten & beveiliging — welke gebruiker de sleutel wordt
• Integraties — kant-en-klare koppelingen
• Automatiseringen — automatiseren zonder te programmeren
• Aanmelden met Microsoft of Google