Hoe koppel je bestaande tools aan een nieuw systeem?

Met een API-integratie wisselen systemen gegevens uit via een afgesproken software-interface. Het ene systeem kan bijvoorbeeld een klant opzoeken, een factuurvoorstel aanmaken of een betaalstatus ophalen. Een goede koppeling bepaalt niet alleen welke gegevens reizen, maar ook wie ze mag wijzigen en wat er gebeurt wanneer de uitwisseling niet eenduidig slaagt.

Begin daarom niet bij een lijst beschikbare koppelingen. Begin bij een overdracht: welke medewerker wacht nu op welke informatie, welke actie volgt daarop en welk bestaand pakket blijft verantwoordelijk? Hieronder werken we dat uit voor een illustratief proces waarin een nieuw opdrachtsysteem aansluit op een bestaande administratie.

Bepaal per gegeven het leidende systeem

Het opdrachtsysteem kan leidend zijn voor de opdracht en de vrijgave van geleverd werk. Het boekhoudpakket kan leidend blijven voor de financiële klantreferentie, factuurnummering en definitieve documenten. Die verdeling is belangrijker dan de afspraak dat systemen in het algemeen “twee kanten op synchroniseren”.

Maak een kleine gegevensafspraak: veld, bron, bestemming, wijzigingsrichting en conflictregel. Voor een factuurvoorstel leg je bijvoorbeeld vast dat het opdracht-ID uit het opdrachtsysteem komt, de debiteurreferentie uit de administratie en de goedgekeurde prestatieregels uit de uitvoering. Een veranderde klantnaam in het CRM hoeft geen reden te zijn om historische factuurgegevens te overschrijven.

Leg externe record-ID’s apart vast. Een naam is geen stabiele sleutel en een e-mailadres kan wijzigen. Gebruik alleen automatische samenvoeging wanneer de identiteit voldoende vaststaat. Anders ontstaat een taak om de koppeling tussen de twee records te beoordelen.

Vertaal betekenis, niet alleen veldnamen

Een veld dat in beide systemen “status” heet, kan iets anders betekenen. Goedgekeurd, verzonden, verwerkt en betaald zijn verschillende momenten. Beschrijf voor elke overgang de voorwaarde en de verwachte uitkomst. Laat onbekende waarden niet automatisch op een gunstige standaard uitkomen.

Controleer ook valuta, afronding, tijdzones, datumvelden, lege waarden en de betekenis van een verwijderd record. Afhankelijk van het proces is verwijderen in de bron aanleiding voor een blokkade of archivering, niet voor een onvoorwaardelijke verwijdering in de bestemming. Bij bestanden moet duidelijk zijn of het om een kopie, een versie of alleen een tijdelijke downloadlink gaat.

De eerste oplevering van deze fase is een klein gegevenscontract dat zowel een procesverantwoordelijke als een ontwikkelaar kan toetsen. Voeg voorbeelden toe van een geldig record, een ontbrekend verplicht veld en een conflicterende wijziging.

Onderzoek API-toegang vóór de bouw

Een pakket met een API biedt niet noodzakelijk toegang tot ieder scherm of iedere handeling. Controleer de bedoelde endpoints, lees- en schrijfrechten, het abonnement, de betreffende administratie en de voorwaarden voor een appregistratie. Test met een beperkte verbinding of het benodigde gegeven werkelijk beschikbaar is.

Moneybird beschrijft in de authenticatiedocumentatie onder meer OAuth en de bijbehorende toegangsrechten. Welke methode past, hangt af van de toepassing. Leg vast namens welk account of welke organisatie de koppeling werkt en hoe die toegang wordt ingetrokken.

Maak beheeraccounts niet afhankelijk van één vertrekkende medewerker. Bewaar toegangsmiddelen buiten frontendcode en foutmeldingen. Gebruik gescheiden test- en productie-instellingen en geef de koppeling alleen de rechten die voor haar werk nodig zijn. Een foutmelding mag een recordreferentie tonen zonder een compleet klantdossier of een geheime sleutel mee te sturen.

Webhooks en periodiek ophalen vullen elkaar aan

Een webhook is een bericht waarmee een leverancier je systeem op een gebeurtenis wijst. Het is geen alternatief voor het hele API-ontwerp: na zo’n bericht kan je koppeling juist de API gebruiken om de actuele toestand op te halen. Periodiek ophalen kan passend zijn als een gebeurtenismelding ontbreekt of als aanvullende controle.

Behandel inkomende berichten als onbevestigde input totdat hun herkomst en inhoud zijn gecontroleerd. De verificatiemethode verschilt per leverancier. Moneybird beschrijft bijvoorbeeld verificatie van webhookhandtekeningen. Kopieer die aanpak niet zonder meer naar een andere API met een ander contract.

Maak de ontvangst en de verwerking afzonderlijk zichtbaar. Een bericht kan technisch ontvangen zijn terwijl een volgende handeling wacht op ontbrekende gegevens. De gebruiker moet dan niet “klaar” zien, maar bijvoorbeeld “ontvangen, controle nodig”.

Ontwerp voor dubbele en onzekere uitkomsten

Stel dat het boekhoudpakket een concept heeft aangemaakt, maar het antwoord onderweg verloren gaat. Een time-out betekent dan niet dat de handeling niet is uitgevoerd. Onvoorwaardelijk opnieuw proberen kan een dubbel document veroorzaken.

Bewaar daarom een eigen verwerkingsreferentie en het externe record-ID. Controleer bij een onzekere uitkomst of de bedoelde actie al is verwerkt. Sommige API’s ondersteunen idempotency keys: een herkenbare sleutel om herhaalde aanvragen van dezelfde bewerking af te handelen. De Mollie-documentatie over idempotency beschrijft zo’n mechanisme. Ondersteuning en geldigheid zijn API-specifiek; een eigen verwerkingsadministratie blijft nodig.

Maak onderscheid tussen een tijdelijke storing en inhoudelijk ongeldige gegevens. Een tijdelijke fout kan een begrensde herhaalpoging krijgen. Een onbekende debiteur of ontbrekende bevoegdheid vraagt eerst correctie. Definieer wie een vastgelopen item oppakt en hoe diegene het gecontroleerd hervat.

Test de overdracht, niet alleen het antwoord van de API

• Een geldige vrijgegeven opdracht levert precies het afgesproken concept op, met een terugvindbare koppeling tussen bron en bestemming.
• Een dubbele gebeurtenis, time-out en herstart veroorzaken geen extra document of tweede klantbericht.
• Een ingetrokken toegang en een onbereikbare leverancier worden zichtbaar, zonder dat items stilzwijgend verdwijnen.
• Een wijziging na vrijgave wordt volgens de afgesproken versie- of goedkeuringsregel behandeld.
• Een record van een andere administratie of klantorganisatie wordt niet gelezen of gewijzigd door alleen een ander ID aan te bieden.
• Het totaal van verwerkt, wachtend en afgewezen sluit aan op de ontvangen werkvoorraad.

Test waar mogelijk in een afgescheiden omgeving. Als een leverancier geen passende testvoorziening biedt, leg dan vooraf vast welke beperkte controles wel veilig uitvoerbaar zijn. Een test mag niet ongemerkt echte betalingen, documenten of klantberichten veroorzaken.

Een koppeling opleveren inclusief beheer

Bij de overdracht horen de gegevensafspraken, benodigde rechten, configuratie, testgevallen en een herstelhandleiding. Spreek af wie leverancierwijzigingen volgt, fouten beoordeelt en toegangen beheert. Een periodieke vergelijking tussen bron en bestemming kan afwijkingen vinden die losse foutmeldingen niet laten zien.

Een bestaande connector kan voldoende zijn als die de juiste handelingen, controles en beheeropties biedt. Maatwerk wordt relevant waar zulke afspraken niet goed passen. Bekijk onze aanpak voor integraties en leg beheer en doorontwikkeling vast voordat de koppeling belangrijk dagelijks werk overneemt.