Een API-koppeling laten maken: data, fouten en beheer

Zo'n koppeling laat systemen gegevens uitwisselen via een afgesproken toegang. Maar dat twee pakketten een API hebben, betekent nog niet dat jouw proces daarmee volledig is geregeld. Je moet ook bepalen wat er wordt doorgestuurd, wanneer dat gebeurt en hoe je ziet of het goed is gegaan.

Dat zijn nuttige vragen om vooraf te stellen als je een API-koppeling wilt laten maken. Ze bepalen een groot deel van het werk én van het beheer dat daarna nodig is. Weet je nog niet waar je moet beginnen? Lees dan welke bedrijfsprocessen je als eerste automatiseert.

Beschrijf eerst de overdracht

Begin met één concrete route. Bijvoorbeeld: een gecontroleerde aanvraag moet een contactpersoon en een taak in het CRM opleveren. Welke gegevens zijn daarvoor nodig? En op welk moment mag dat gebeuren?

Schrijf ook op wat buiten die route valt. Misschien hoeft een wijziging in het CRM niet terug naar het formulier of de website. Een overdracht in één richting kan een heel andere opdracht zijn dan twee systemen die elkaar voortdurend moeten bijwerken.

Maak de gewenste uitkomst controleerbaar. 'De systemen zijn gekoppeld' zegt weinig. 'Een goedgekeurde aanvraag verschijnt met de juiste eigenaar en zonder dubbel contact in het CRM' geeft een veel duidelijker uitgangspunt voor de bouw en de test.

Kies per gegeven één leidende bron

Als dezelfde informatie op meerdere plekken staat, moet duidelijk zijn waar wijzigingen beginnen. Stel dat een klant in het ene systeem een nieuw adres krijgt, terwijl iemand in het andere systeem nog met het oude adres werkt. Welke versie moet de koppeling dan gebruiken?

Spreek dat per soort gegeven af. Voor klantgegevens kan het CRM leidend zijn, terwijl een ander systeem bijvoorbeeld de orderstatus beheert. Het hoeft niet voor alle informatie hetzelfde pakket te zijn.

Controleer ook hoe velden op elkaar aansluiten. Een volledige naam in één tekstveld is iets anders dan een voornaam en achternaam apart. Een verplichte landcode kan ontbreken in de bron. Zulke verschillen vragen om afspraken voordat je gegevens automatisch doorstuurt.

Een bestaande koppeling kan voldoende zijn

Bekijk eerst of er al een koppeling beschikbaar is die de gewenste route ondersteunt. Dat kan vanuit het platform zelf of via aanvullende tooling. Let daarbij op de gegevens, acties en uitzonderingen die jij nodig hebt, niet alleen op de namen van de twee systemen in een integratielijst.

Een bestaande oplossing kan bijvoorbeeld nieuwe contacten aanmaken, maar geen aangepaste velden bijwerken. Of wel een order ophalen, maar niet de status terugsturen. Controleer dat met een echte situatie uit jullie proces.

Een custom koppeling wordt interessant wanneer de standaardroute niet past. Je kunt dan de verwerking op jullie werkwijze afstemmen. Daar horen ook afspraken over onderhoud bij, want de systemen aan beide kanten kunnen veranderen.

Wat gebeurt er als een verzoek mislukt?

Een ontvangend systeem kan tijdelijk onbereikbaar zijn. Een record kan worden afgewezen omdat een verplicht veld ontbreekt. En soms komt er geen duidelijke bevestiging terug, terwijl een actie wel is uitgevoerd.

Gewoon opnieuw versturen kan dan een dubbele taak of bestelling opleveren. Daarom moet de koppeling kunnen herkennen wat al verwerkt is en welke acties veilig opnieuw kunnen worden geprobeerd. Stripe beschrijft hiervoor bijvoorbeeld idempotente verzoeken: herhalen zonder onbedoeld dezelfde handeling nogmaals uit te voeren. Hoe je dit regelt, verschilt per gekoppeld systeem.

Maak fouten daarnaast zichtbaar. Een bericht in een technisch log is weinig waard als niemand het bekijkt. Spreek af wie een melding krijgt, welke gegevens nodig zijn om het probleem te onderzoeken en hoe een medewerker een vastgelopen overdracht herstelt.

Leg beheer vast voordat de koppeling live gaat

De koppeling heeft toegang tot systemen nodig. Bepaal wie die toegang beheert en hoe je voorkomt dat alles afhankelijk is van het persoonlijke account van één medewerker. Geef alleen de toegang die nodig is voor de afgesproken handelingen.

Neem ook wijzigingen mee. Wat gebeurt er als een veld wordt hernoemd, een abonnement verandert of een leverancier een API aanpast? Wie beoordeelt de impact en wie voert het herstel uit?

Vraag bij oplevering om een overzicht van de gegevensstromen, de foutafhandeling en de beheerafspraken. Daarmee kan je team begrijpen wat er gebeurt zonder zelf de code te hoeven lezen.

Test meer dan het succesvolle voorbeeld

Een goede test laat zien dat een normale aanvraag aankomt. Een bruikbare oplevering laat ook zien hoe de koppeling omgaat met een bestaand contact, ontbrekende gegevens en een mislukte overdracht.

Neem zulke situaties op in de scope en controleer de uitkomst in beide systemen. Dan zie je of de koppeling niet alleen informatie verplaatst, maar ook jullie proces ondersteunt.

Wil je een koppeling met ons uitwerken? Neem de twee systemen en één terugkerende overdracht als vertrekpunt. Vanuit die route kunnen we onderzoeken wat al beschikbaar is, waar maatwerk nodig is en wie de koppeling straks beheert.