Waarom API-koppelingen vastlopen zodra het druk wordt

De bestelling staat netjes in de webshop, maar in het ERP is er niets van terug te vinden. Een nieuwe klant is aangemaakt in het CRM en heeft twee dagen later nog steeds geen toegang tot het klantportaal. De voorraadstanden op de marketplace lopen structureel een paar uur achter. Wie dagelijks met gekoppelde systemen werkt, herkent dit soort meldingen meteen.

De foutmelding die u op zo'n moment vindt, is zelden de oorzaak. Het is het punt waarop het probleem eindelijk zichtbaar werd. De echte oorzaak ligt bijna altijd eerder in het traject: de koppeling is ooit gebouwd als een stukje technisch leidingwerk tussen twee applicaties, en inmiddels loopt er een deel van uw dagelijkse operatie doorheen.

Dat verschil valt pas op als de omstandigheden veranderen. Het volume verdubbelt, een leverancier past zijn API aan, of een bericht wordt na een time-out voor de zekerheid nog een keer verstuurd. Dan blijkt dat een koppeling meer moet kunnen dan gegevens doorgeven. Hij moet ook omgaan met vertraging, dubbele berichten, onvolledige gegevens en systemen die tijdelijk niet reageren. Is dat vooraf geregeld, dan blijft een storing een technisch incident. Is dat niet geregeld, dan wordt het handwerk, achterstand en uitleg richting klanten.

Waarom loopt een koppeling eigenlijk vast?

Een API-koppeling loopt vast zodra twee systemen verschillende verwachtingen hebben over data, timing of beschikbaarheid. Het ene systeem gaat ervan uit dat een klantnummer altijd meekomt. Het andere kent dat nummer pas toe nadat iemand de klant heeft goedgekeurd. Of uw webshop stuurt bij elke wijziging direct een bericht, terwijl de ontvangende partij niet meer dan zestig verzoeken per minuut accepteert.

Meestal valt niemand daar iets te verwijten. Wat ontbreekt, zijn afspraken over uitzonderingen. Mag een order twee keer verwerkt worden als niet zeker is of de eerste is aangekomen? Wat gebeurt er met een adres dat niet valideert? Wat moet er gebeuren als de API van een leverancier tien minuten stil ligt? Zonder antwoord op dat soort vragen stopt de koppeling bij het eerste scenario dat afwijkt van de ideale route.

Daar komt bij dat API's bewegen. Externe partijen wijzigen velden, versies, authenticatie en limieten. Soms met een aankondiging maanden vooraf, soms met een regel in een changelog die niemand leest. Een integratie die vorig jaar probleemloos draaide, kan daardoor vandaag stilvallen zonder dat er aan uw kant iets is veranderd.

De technische oorzaken op een rij

Data die niet op elkaar aansluit

Verschillen in datamodellen zijn veruit de meest voorkomende oorzaak. Uw webshop kent één veld voor productstatus, terwijl het voorraadsysteem onderscheid maakt tussen beschikbaar, gereserveerd, onderweg en geblokkeerd. Wordt die vertaling niet bewust gemaakt, dan krijgt de ontvangende kant een waarde waar hij niets mee kan.

Verplichte velden zijn de tweede klassieker. Een telefoonnummer, btw-nummer of landcode is optioneel in het bronsysteem en verplicht in het doelsysteem. Een koppeling die daarop controleert vóór verzending, houdt het bericht tegen en benoemt precies wat ontbreekt. Gebeurt dat niet, dan groeit er een stapel afgekeurde berichten die iemand later handmatig moet uitzoeken, meestal net op het moment dat het toch al druk is.

Timing en volgorde

Veel processen bestaan uit stappen die op elkaar wachten. Eerst de klant, dan de order, dan de factuur. Komt de order eerder binnen dan de klant, dan wordt hij afgekeurd omdat de klant nog niet bestaat. Bij een koppeling tussen CRM en ERP is dit een van de vaakst terugkerende oorzaken van vastlopers.

Het speelt vooral bij koppelingen die via webhooks of achtergrondprocessen lopen, waar berichten elkaar kunnen inhalen. Alles onmiddellijk doorzetten voelt snel, maar levert niet altijd het beste resultaat. Een korte wachtrij waarin de volgorde gegarandeerd is, is voor dit soort ketens betrouwbaarder. Het gaat dan om seconden of minuten die u bewust inbouwt, niet om de uren achterstand die ontstaan als berichten ongemerkt blijven liggen.

Time-outs, limieten en tijdelijke uitval

Elke externe API heeft grenzen. Onderhoud, een time-out, een limiet op het aantal aanvragen per minuut: het hoort erbij. Een koppeling die bij elke fout meteen opnieuw verstuurt, maakt het probleem groter. De API krijgt extra verkeer op het slechtst denkbare moment en weigert daarna nog meer verzoeken.

Vaker opnieuw proberen is dus niet het antwoord. Wat wel werkt: opnieuw aanbieden met oplopende tussenpozen, een maximum aantal pogingen, en een aparte plek voor berichten die het definitief niet redden. Zo blijft een storing beheersbaar en verdwijnt er niets stilletjes uit beeld.

Verlopen tokens en gewijzigde versies

Toegang tot een API loopt meestal via tokens, sleutels of OAuth. Tokens verlopen, rechten worden aangepast, beveiligingseisen worden strenger. Staan die gegevens hard in de code of is niemand eigenaar van het beheer, dan stopt de koppeling op een willekeurig moment. In de praktijk vaak in het weekend.

Versiebeheer verdient dezelfde aandacht. Een leverancier hernoemt een veld, verwijdert een endpoint of verandert de structuur van een antwoord. Contracttests en een vaste controle op aangekondigde wijzigingen kosten weinig tijd en zorgen ervoor dat u het merkt voordat uw collega's het merken.

Vaak zit het probleem niet in de code

Techniek is maar de helft van het verhaal. Koppelingen lopen ook vast omdat onduidelijk is wie er aan zet is als het misgaat. De softwareleverancier wijst naar de hostingpartij, de hostingpartij naar de bouwer van de koppeling, en die wijst naar de externe API. Ondertussen wacht de klantenservice op gegevens die nodig zijn om iemand te helpen.

Een koppeling heeft daarom een functioneel eigenaar nodig. Iemand die weet welke gegevens erdoorheen lopen, wat het voor de business betekent als die stroom stokt, en wanneer een afwijking om actie vraagt. Dat hoeft geen ontwikkelaar te zijn. Wel iemand die de knoop kan doorhakken: mag deze order tot morgen wachten, moet dit nu hersteld worden, of draaien we de batch later opnieuw?

Geef wijzigingen in het proces een vaste plek in datzelfde overleg. Een extra factuurveld, een nieuwe orderstatus of een verkoopkanaal erbij lijkt klein. Voor een koppeling betekent het vaak dat validaties, vertalingen en foutafhandeling opnieuw langs moeten. Betrek uw technische partner voordat de wijziging live gaat, niet op de dag dat de gegevens niet meer doorkomen.

Wat een koppeling wel betrouwbaar maakt

Het begint met de gegevensstroom scherp krijgen. Niet alleen "systeem A stuurt orders naar systeem B", maar ook: welk systeem is leidend bij tegenstrijdige gegevens, welke velden zijn verplicht, hoe snel moet iets beschikbaar zijn, en wat gebeurt er als een stap mislukt? Dat zijn zakelijke keuzes met technische gevolgen, geen technische details.

Daarna komt de foutafhandeling. Een melding als "synchronisatie mislukt" helpt niemand verder. Bruikbaar is: order 10482 is afgekeurd omdat de landcode van het afleveradres ontbreekt, om 09:14, na drie pogingen. Daar kan een medewerker iets mee, en een ontwikkelaar ook.

Logging op zich is nog geen bewaking. U wilt ook weten wanneer aantallen afwijken van normaal. Gaan er doorgaans duizend orders per uur door de koppeling en zijn het er ineens twintig, dan is dat een signaal, ook al staat er geen enkele fout in het log. Juist die stille storingen worden anders pas aan het einde van de dag ontdekt.

Voor kritische processen loont het om berichten tijdelijk vast te houden in een wachtrij. Ligt het ontvangende systeem eruit, dan blijven ze bewaard en worden ze gecontroleerd verwerkt zodra dat systeem terug is. Zorg er dan wel voor dat dubbele verwerking onmogelijk is. Dubbele berichten komen in de praktijk gewoon voor, bijvoorbeeld na een time-out waarbij niet vaststaat of het eerste bericht is aangekomen. De koppeling moet dan herkennen dat het om dezelfde order gaat en de tweede negeren.

En test met de rommelige gevallen. Niet alleen met een perfecte testorder, maar ook met een Belgisch adres van vier cijfers, een ontbrekend klantnummer, een retour, een geannuleerde betaling en een ontvangend systeem dat halverwege de verwerking wegvalt. Daar zit het verschil tussen een demo die het doet en een proces dat een drukke maandag overleeft.

Repareren of opnieuw bouwen?

Niet elke vastgelopen koppeling vraagt om een herbouw. Is de opzet logisch, is de code nog te volgen en komen de fouten vooral door wijzigingen aan de andere kant, dan is gericht bijwerken genoeg. Authenticatie vernieuwen, validatie toevoegen, een veld anders vertalen: dat is werk van dagen, geen maanden.

Opnieuw bouwen is verstandiger als de koppeling een verzameling noodoplossingen is geworden. De signalen zijn tamelijk herkenbaar: dagelijkse handmatige correcties, foutmeldingen waarvan niemand de oorzaak kent, code die niemand meer durft aan te raken en afhankelijkheden die alleen in het hoofd van één persoon zitten. Op dat punt kost doorlappen op jaarbasis meer dan het proces opnieuw ontwerpen.

Vergeet de omgeving eronder niet. Een goed gebouwde koppeling kan alsnog traag worden als achtergrondtaken te weinig capaciteit krijgen, de database bezwijkt onder piekbelasting of hosting en applicatiebeheer los van elkaar staan. Bij LJPc zitten ontwikkeling en hosting bij elkaar, zodat het zoeken naar de oorzaak niet langs drie partijen hoeft.

De beste koppeling is niet de koppeling waar u nooit iets van hoort. Het is de koppeling waarvan u weet welke gegevens onderweg zijn, wie aan de bel trekt bij een afwijking en hoe herstel verloopt. Dan is techniek gewoon gereedschap, en geen dagelijkse bron van vertraging.