Authenticatie en scopes
Begin bij de vraag hoe de koppeling zich identificeert. Lees of de API een clientcredential, een API-sleutel, een ondertekend verzoek of een gebruikerstoken gebruikt. Controleer hoe tokens verlopen en hoe ze worden vernieuwd. Een token dat tijdens een lange import verloopt, kan een onvolledig record achterlaten.
Kijk daarna naar de scopes. De koppeling hoort alleen de rechten te vragen die zij nodig heeft. Als de documentatie één brede scope noemt voor elke actie, vraag dan of lezen en schrijven gescheiden kunnen worden. Leg vast welke persoon of welk systeem de credential beheert.
Endpoints en limieten
Maak een lijst van de endpoints die de workflow nodig heeft. Controleer per endpoint de vorm van het verzoek, de verplichte velden en de vorm van het antwoord. Kijk of de API het volledige record teruggeeft of alleen een id waarvoor een tweede aanroep nodig is.
Lees de limietsectie voordat je een bulkactie plant. Noteer de limiet, het venster en het antwoord wanneer de limiet is bereikt. Bouw een wachtrij met een oplopende wachttijd in plaats van strak opnieuw te proberen. Als de documentatie geen limiet noemt, vraag support dan naar de productiewaarde.
Idempotentie en dubbele gebeurtenissen
Netwerken proberen opnieuw. Een webhook kan opnieuw aankomen en een import kan opnieuw starten na een time-out. Een idempotente write gebruikt een stabiele sleutel, zodat het tweede verzoek hetzelfde record bijwerkt in plaats van een nieuw record maakt. Vraag of de API een idempotentiesleutel ondersteunt en stuur hetzelfde verzoek opnieuw in de sandbox.
Bewaar voor gebeurtenissen het event-id en negeer een gebeurtenis die je al hebt verwerkt. Die kleine tabel maakt een herhaalde fasewijziging zichtbaar voordat zij een kandidaatrecord raakt.
Webhooks, herhaling en replay
Controleer welke gebeurtenissen bestaan en wat de payload bevat. Een payload met alleen een id dwingt een tweede aanroep af, dus bevestig dat het vervolgende endpoint beschikbaar is. Lees het herhaalschema en de ondertekeningsmethode. Verifieer de handtekening voordat je een payload vertrouwt.
Vraag hoe je een gebeurtenis opnieuw afspeelt die is gemist terwijl je dienst uit lag. Een replaypad hoort bij het ontwerp, niet bij een noodgeval. Log elk event-id, de responscode en het tijdstip, zodat je met de leverancier kunt vergelijken.
Schema, versies en veldwijzigingen
Vraag hoe de API omgaat met een nieuw veld of een hernoemde waarde. Een versieheader en een afkondigingstermijn geven je tijd om bij te werken. Zonder beleid kan een kleine wijziging een mapping breken die gisteren nog werkte.
Bewaar je eigen kopie van de veldmapping met de API-versie waarop zij is gericht. Als de leverancier een wijziging aankondigt, vergelijk dan de mapping, werk de sandbox bij en test de geraakte overdracht voordat je naar productie gaat.
Fouten, logboeken en verwijdering
Leg vast wat je systeem met elke foutklasse doet. Een validatiefout vraagt om een persoon, een tijdelijke serverfout om een nieuwe poging en een authenticatiefout om een nieuw token. Schrijf die regels op en toon ze in het integratielogboek.
Vraag hoe een verwijderverzoek de API bereikt en wat het antwoord bevestigt. Controleer of de verwijdering opnames, transcripties en afgeleide samenvattingen omvat. Documenteer de route van het kandidaatverzoek naar de leverancier en terug, zodat het team een vraag kan beantwoorden zonder te gissen.
Sandbox en support
Vraag om een sandbox met voorbeelddata en een manier om een mislukte aanroep na te bootsen. Test het normale pad, een dubbele gebeurtenis, een verlopen token en een geweigerd veld. Houd testrecords gescheiden van productie.
Vraag tot slot wie de koppeling ondersteunt en hoe je die bereikt. Een duidelijk escalatiepad met vaste contacten hoort naast de endpointlijst. De checklist neemt niet elk risico weg, maar zij laat zien welke onderdelen het team echt heeft afgesproken.