API-koppeling en webhooks uitgelegd: wat het is en wat u vraagt voor er gekoppeld wordt

Wat is een API-koppeling?

Een API-koppeling laat twee programma's rechtstreeks gegevens uitwisselen, zonder dat iemand iets overtypt of een bestand doorstuurt. API staat voor application programming interface: een afgesproken ingang waarlangs een ander programma gegevens opvraagt of wijzigt, volgens vaste regels en meestal met een sleutel.

In een servicebedrijf gaat het meestal om een paar vaste stromen. De boekhoudsoftware haalt de geboekte facturen op. Een ander programma leest de klanten of de installaties. Een automatiseringstool maakt een taak aan zodra een interventie afgewerkt is.

API of webhook: vragen of verwittigd worden

Het verschil zit in wie het initiatief neemt.

• Bij een API vraagt het andere programma. "Zijn er nieuwe facturen sinds gisteren?" Het vraagt op zijn eigen ritme, bijvoorbeeld elk uur of 's nachts, en kan met de juiste rechten ook gegevens wijzigen.
• Bij een webhook meldt uw software het zelf. Zodra er iets gebeurt, zoals een factuur die geboekt wordt, vertrekt er een kort bericht naar een internetadres van het andere programma. Dat programma moet dus altijd bereikbaar zijn.

Vaak werken de twee samen. De webhook meldt "factuur geboekt", en het andere programma vraagt daarna via de API de details van die factuur op.

Een API-sleutel is een toegang, met rechten

Een API-sleutel werkt als een wachtwoord voor een programma. Wie de sleutel heeft, krijgt de toegang die eraan hangt, zonder te vragen wie hij is. Daarom gelden er drie regels:

1. Geef alleen wat nodig is. Leest de boekhouding alleen facturen, dan krijgt de sleutel alleen het recht om facturen te lezen. Een gelekte sleutel of een fout in de koppeling richt dan nooit meer aan dan wat die sleutel mag.
2. Laat de koppeling werken onder een eigen gebruiker. Dan ziet u wat de koppeling doet, en zet u ze stop zonder een collega te blokkeren.
3. Bewaar de sleutel als een wachtwoord, en geef hem een einde. Stuur hem nooit door in een gewone e-mail. Een vervaldatum dwingt tot een bewuste vernieuwing. Stopt de samenwerking, trek de sleutel dan in.

Waarom een webhook ondertekend is

Een webhook komt binnen op een adres dat op het internet bereikbaar is. Wie dat adres kent, kan er in principe ook een vals bericht naartoe sturen, bijvoorbeeld "factuur betaald". Een handtekening lost dat op. De afzender berekent met een geheim dat alleen de twee programma's kennen een code over het bericht, en stuurt die mee. De ontvanger rekent dezelfde code na. Klopt ze, dan komt het bericht van de juiste afzender en is het onderweg niet gewijzigd. Een gangbare methode heet HMAC-SHA256.

De handtekening helpt alleen als de ontvanger ze ook controleert. Vraag dat dus na bij wie de koppeling bouwt.

Tien vragen voor er een API-koppeling gebouwd wordt

Een koppeling is een klein project. Laat de antwoorden op deze vragen op papier zetten voor er iets gebouwd wordt:

1. Welke gegevens gaan erdoor? Alleen geboekte facturen en creditnota's, of ook klanten en betalingen?
2. In welke richting? Van uw servicesoftware naar de boekhouding, omgekeerd, of beide? En welk programma heeft het laatste woord als een adres in beide verschilt?
3. Hoe vaak, of op welk moment? Meteen via een webhook, of één keer per nacht via de API?
4. Wie bouwt de koppeling? Uw leverancier, die van het andere programma, of een derde? Met welke documentatie?
5. Wie onderhoudt ze? Programma's veranderen. Wie past de koppeling aan, en wie betaalt dat?
6. Wat gebeurt er bij een fout? Wie krijgt een melding, waar ziet u wat er niet doorkwam, en wordt het opnieuw geprobeerd?
7. Wie is eigenaar van de sleutel? Onder welke gebruiker werkt de koppeling, en wie bewaart de sleutel?
8. Welke rechten krijgt de sleutel? Alleen lezen, of ook wijzigen? En in welke onderdelen?
9. Hoe trekt u de toegang in? Bij het einde van de samenwerking, of als u een lek vermoedt.
10. Hoe test u? Eerst met een paar records, en wie kijkt het resultaat na voor alles live gaat?

Gaan er persoonsgegevens van uw klanten naar een andere leverancier, bespreek dan met uw juridisch adviseur wat u met die leverancier moet afspreken. Welke vragen u over de opslag van uw gegevens stelt, leest u in gegevens in de cloud.

Soms volstaat een bestand

Niet elke uitwisseling heeft een koppeling nodig. Een export en een import doen hetzelfde werk, met de hand:

Gaat het om een maandelijkse stroom met weinig regels, of kan het andere programma geen API gebruiken, dan is een bestand vaak de eenvoudigste weg. Wordt het een dagelijkse taak die iemand telkens moet onthouden, dan loont een koppeling eerder de moeite.

Een voorbeeld: facturen naar de boekhouding

Een bedrijf voor waterbehandeling boekt zijn facturen in zijn servicesoftware. De boekhouder werkt in een eigen pakket en krijgt elke maand een export per e-mail. Hij stelt voor om dat via een API-koppeling te doen.

De office manager stelt de tien vragen. Het antwoord: alleen geboekte facturen en creditnota's, in één richting, één keer per nacht. De leverancier van het boekhoudpakket bouwt de koppeling. De sleutel werkt onder een aparte gebruiker die alleen facturen mag lezen, en vervalt na een jaar, zodat iemand hem bewust vernieuwt. Bij een fout krijgt de office manager een bericht van het boekhoudpakket. De eerste maand loopt de export nog mee, en de boekhouder vergelijkt de twee. Daarna valt de export weg.

Hoe dat werkt in Digitalnatie Service Suite

In Digitalnatie Service Suite staat de koppeling met andere software in Configuratie › Integraties, tabblad API en webhooks. Bovenaan het tabblad staan het adres van de API en de link Documentatie, voor wie de koppeling bouwt.

• Een recht op aanvraag: API-sleutels en webhooks vragen het technische recht API en webhooks. Geen enkel rolsjabloon geeft dat recht, ook dat van de beheerder niet: u vraagt het aan Digitalnatie.
• Een aparte gebruiker: met Nieuwe API-sleutel geeft u een Naam en kiest u bij Handelt als de gebruiker van wie de sleutel exact de rechten overneemt. Kies bij voorkeur een aparte gebruiker met beperkte rechten. De beheerder nodigt die gebruiker uit en geeft hem zijn rollen in Instellingen › Rollen.
• Alleen de nodige toegang: onder Toegang vinkt u aan wat de software mag Lezen (klanten, locaties, installaties, interventies, contracten, voorraad, facturen, rapporten) en wat ze mag Wijzigen. Desgewenst vult u Vervalt op in en beperkt u de sleutel met Toegestane IP-adressen.
• Eén keer zichtbaar: Service Suite bewaart alleen een vingerafdruk van de sleutel. Kopieer hem meteen en bewaar hem als een wachtwoord. Nieuwe sleutel maken vervangt hem, Intrekken schakelt hem definitief uit.
• Webhooks: met Nieuwe webhook geeft u een Naam en een Ontvangst-URL, een https-adres op het internet. Interne adressen worden geweigerd. Onder Gebeurtenissen kiest u wat er gemeld wordt, bijvoorbeeld Interventie aangemaakt, Interventie afgewerkt of Factuur of creditnota geboekt.
• Ondertekend en opnieuw verstuurd: elke melding is ondertekend met HMAC-SHA256, zodat de ontvanger kan nagaan dat ze van Service Suite komt. Mislukt een verzending, dan volgt een nieuwe poging, met steeds langere tussenpozen. Na 20 mislukkingen op rij wordt de webhook uitgeschakeld, en u schakelt hem weer in zodra het probleem opgelost is.
• Zonder koppeling: de beheerder laadt gegevens in met Gegevens importeren (Excel- of CSV-sjabloon, eerst een controle). De lijst van de interventies en de Rapporten exporteert u als CSV; het Financieel overzicht heeft een Excel-export van de resultatenrekening, voor wie het mag openen.

Goed om te weten: of een boekhoudpakket of andere software zo kan koppelen, hangt af van wat die software ondersteunt. Vraag het aan haar leverancier. Een webhook verwijderen wist ook de geschiedenis van zijn verzendingen. In het tabblad Diensten kunt u onder meer WhatsApp Business en MCP-servers koppelen en testen, maar via die koppelingen vertrekt nog niets.

Wie wat mag in de software zelf, leest u in rollen en rechten, en hoe u een klantenbestand inlaadt in klantgegevens importeren. Zie ook de module facturatie en aankoop.

Veelgestelde vragen

Wat is het verschil tussen een API en een webhook?

Bij een API vraagt een ander programma zelf gegevens op, op zijn eigen ritme, en kan het met de juiste rechten ook gegevens wijzigen. Bij een webhook meldt uw software zelf dat er iets gebeurd is, zoals een geboekte factuur, door een bericht naar een internetadres van het andere programma te sturen. Vaak werken de twee samen.

Wat is een API-sleutel?

Een API-sleutel is een toegang voor een programma, zoals een wachtwoord voor een persoon. Wie de sleutel heeft, krijgt de rechten die eraan hangen. Geef een sleutel daarom alleen de rechten die de koppeling nodig heeft, en bewaar hem zoals een wachtwoord.

Waarom is een webhook ondertekend?

Een webhook komt binnen op een adres dat op het internet bereikbaar is. Met de handtekening kan de ontvanger nagaan dat het bericht van de juiste afzender komt en onderweg niet gewijzigd is. Dat helpt alleen als de ontvangende software de handtekening ook controleert.

Kan ik Service Suite koppelen aan mijn boekhoudpakket?

Als uw boekhoudpakket met een API of met webhooks kan werken, kan het via een API-sleutel gegevens lezen, zoals facturen, en meldingen krijgen, zoals een geboekte factuur of creditnota. Wie de koppeling bouwt, spreekt u af met de leverancier van het pakket. Het recht om sleutels en webhooks aan te maken, vraagt u aan Digitalnatie. Kan het pakket dat niet, dan blijven een export en een import de weg.

Kan iedereen in Service Suite een API-sleutel aanmaken?

Nee. API-sleutels en webhooks vragen het technische recht API en webhooks, dat geen enkel rolsjabloon geeft, ook dat van de beheerder niet. U vraagt het aan Digitalnatie.