Waar een AFAS-koppeling in de praktijk op stukloopt

AFAS noemt voor fouten in de REST API vier responscodes: 400, 401, 500 en 503. Dat staat zo in de responscodes van de REST API. Een 401 zegt alleen dat u niet geauthentiseerd bent, niet waarom. Wie een haperende AFAS-koppeling beheert, leert de oorzaken dus niet uit de foutcode maar uit het moment waarop hij optreedt. Hieronder vijf momenten die vaak terugkomen; typische gevallen, geen reconstructie van één klant. Voor welke connectoren u waarvoor nodig hebt is er een aparte naslagpagina; dit stuk gaat over wat er daarna kapotgaat.

Het moment dat het token niet meer geldt

De koppeling heeft maanden gedraaid en meldt op een maandag 401 op elke aanroep. AFAS noemt bij 401 twee oorzaken: een verkeerd webserviceadres of een verlopen token. Een classic token is volgens de beveiligingspagina van AFAS "een gebruikersnaam en wachtwoord die toegang geeft tot één specifieke omgeving", en het hangt aan een systeemgebruiker. Wordt die gebruiker opgeruimd bij een accountschoonmaak, dan is het token waardeloos zonder dat iemand het token zelf heeft aangeraakt.

Er komt een tweede oorzaak bij. AFAS schrijft in de overstapinformatie naar OAuth dat bestaande classic tokens vanaf september 2026 een einddatum van 15 februari 2027 krijgen, en dat app connectoren die zes maanden of langer niet gebruikt zijn worden geblokkeerd. Een koppeling die alleen bij de jaarafsluiting draait, kan dus in de tussentijd zijn app connector kwijtraken. Het vinkje "geblokkeerd" op de app connector is dan het eerste wat u nakijkt, vóór u in de code gaat zoeken.

Het moment dat de GetConnector een veld mist

De koppeling geeft geen fout maar levert lege waarden, of valt om op een veld dat er gisteren nog was. Een GetConnector is geen vaste API maar een gegevensverzameling die een beheerder in Profit heeft samengesteld, en de veldnamen in de kolom Veld zijn de namen die de koppeling terugkrijgt. Iemand die in Profit een veld hernoemt naar iets leesbaars, of een veld weghaalt dat hem overbodig lijkt, verandert daarmee de output van de koppeling. Een typisch moment is een opschoonronde na een Profit-update, als de beheerder de inrichting naloopt en opruimt wat hij niet kent.

De metainfo-aanroep op een GetConnector geeft volgens de GetConnector-documentatie de actuele velden terug; een koppeling die bij het opstarten controleert of de velden waar hij op rekent er nog zijn, meldt het verschil in plaats van er stil overheen te lezen.

Het moment dat de UpdateConnector weigert

Schrijven naar AFAS geeft een 500, met een tekst die volgens dezelfde documentatie in de header X-Profit-Error staat, in Base64. Wie die header niet ontcijfert, zoekt op de verkeerde plek. Ontcijferd staat er de inhoudelijke reden. Typische redenen: een verplicht veld dat leeg is, een codetabelwaarde die niet bestaat, een relatie die is geblokkeerd. Welke velden verplicht zijn, staat in de UpdateConnector-beschrijvingen met een sterretje, maar wat er in een codetabel mag staan, verschilt per inrichting. Een verkooporder die in januari doorging, kan in maart stranden omdat iemand een betaalconditie heeft opgeruimd.

Speciale tekens apart: AFAS eist UTF-8; wat er anders aankomt, wordt een vraagteken in Profit. Die verminking valt pas op als een klant zijn eigen naam op de factuur ziet.

Het moment dat het te veel wordt

Een koppeling die goed werkt, wordt groter gemaakt. Dan komen de grenzen die AFAS documenteert in beeld: maximaal zes parallelle aanroepen, een time-out bij verbindingen die ongeveer een kwartier open staan, 75 MB per aanroep, en een fair-use-beleid waarbij AFAS contact opneemt als "elke minuut dezelfde dataset van 15mb wordt opgehaald". Een koppeling die elke vijf minuten de volledige artikeltabel binnenhaalt om te kijken of er iets veranderd is, krijgt daar geen foutcode voor, maar wel een bericht van AFAS. AFAS adviseert daarom gewijzigde gegevens op te vragen en in porties te werken met skip en take, altijd met een sortering, anders schuiven de records tussen twee pagina's door.

Het moment van de omgevingswissel

De koppeling is op de testomgeving gebouwd en gaat naar productie. De adressen verschillen op één woord: in het domein staat bij test resttest en bij productie rest, en de omgevingsnaam begint met T in plaats van O. Het token dat op test werkte, geldt voor die ene omgeving en dus niet voor productie. Een app connector op productie moet opnieuw dezelfde Get- en UpdateConnectoren aangevinkt hebben, want wat er niet in staat, is niet aan te roepen. En de filterautorisatie van de connectorgebruiker bepaalt welke records de GetConnector überhaupt teruggeeft. Een koppeling die op test alle debiteuren zag en op productie de helft, heeft geen bug maar een gebruikersgroep die op productie anders is ingericht.

Wat u zelf kunt nakijken

Bij vier van deze vijf storingen verkleint één logregel per aanroep het zoekgebied: tijdstip, omgeving, connectornaam, HTTP-code en de ontcijferde X-Profit-Error. Wie dat regeltje heeft, ziet snel of het in de toegang zit (alles 401 vanaf één moment), de inrichting (500 met een veldnaam erin), of de volumegrens (time-outs op de grote aanroepen). Het vijfde geval, het veld dat stilletjes verdwijnt, vangt alleen een controle op de metainfo.

Wat niet in dit lijstje past, ligt meestal niet aan de koppeling. Een order die met de juiste velden en zonder fout in AFAS komt maar bij de verkeerde afdeling belandt, is een inrichtingsvraag voor een Profit-consultant; dat schrijven we ook zo op de koppelingspagina. Wat wel bij de koppeling hoort, staat daar onder wat we bouwen en wat het beheer kost.