AFAS Magento koppeling: orders, voorraad en prijzen zonder handwerk

AFAS Profit stelt data beschikbaar via connectoren. Met een GetConnector lees je data uit AFAS, met een UpdateConnector schrijf je data terug. Een GetConnector is geen vaste tabel maar een view die in AFAS zelf wordt ingericht: welke velden erin zitten, bepaal je in Profit. Daardoor is de inrichting in AFAS net zo belangrijk als de code aan de Magento-kant. Wijzigt iemand de view, dan verandert de output van de koppeling.

De REST-omgeving heeft per AFAS-omgeving een eigen adres, in de vorm van een omgevingsnummer gevolgd door rest.afas.online/profitrestservices. Voor test- en acceptatieomgevingen bestaan aparte adressen. Je authenticeert met een token per gebruiker of app-connector, dat je Base64-gecodeerd meestuurt in de Authorization-header met het voorvoegsel AfasToken. AFAS vereist TLS 1.2. Het token geeft precies de rechten van de gekoppelde AFAS-gebruiker, dus een aparte koppelgebruiker met minimale rechten is verplicht kost, geen luxe.

Ophalen gaat in pagina's met de parameters skip en take. Zonder die parameters geeft AFAS de eerste 100 rijen terug. Alles in één keer ophalen kan technisch, maar AFAS raadt het af. Combineer pagineren altijd met een vaste sortering, anders kan de volgorde tussen calls verschuiven en mis je records of krijg je dubbelen. AFAS adviseert verder om het aantal kolommen maal de take-waarde onder de 150.000 te houden. Eén API-call mag maximaal 75 MB zijn en verbindingen die langer dan ongeveer 15 minuten openstaan worden afgebroken. Daar ontwerp je je batches op.

Het belangrijkste architectuurpunt: AFAS heeft geen webhooks voor artikelen, voorraad of prijzen. Webhooks bestaan alleen voor dossieritems en workflows. Wil je weten wat er in AFAS is veranderd, dan moet je pollen op de velden aangemaakt op en gewijzigd op. Een koppeling die elke paar minuten de volledige artikellijst ophaalt, botst met het fair-use-beleid van AFAS en is bovendien traag. Delta-synchronisatie op gewijzigd op, met een opgeslagen laatste-sync-tijdstip, is de juiste route.

Schrijven naar AFAS gaat via UpdateConnectors met POST voor nieuwe records, PUT voor wijzigingen en DELETE voor verwijderen. Verkooporders gaan bijvoorbeeld via de UpdateConnector FbSales. De payload is genest en AFAS valideert streng: één veld op de verkeerde plek en je krijgt een foutmelding terug in plaats van een order. Daarom bouwen we die payloads centraal op één plek, met tests, en loggen we elke afwijzing met de originele foutmelding van AFAS.

Realtime klinkt altijd beter, maar het is niet voor elk gegeven nodig of zelfs mogelijk. Omdat AFAS voor artikelen, voorraad en prijzen geen webhooks biedt, is alles wat van AFAS naar Magento gaat in de praktijk near-realtime: een poll elke paar minuten op wijzigingen. Voor voorraad is dat meestal ruim voldoende. Voor prijzen is een dagelijkse of uurlijkse sync vaak genoeg, mits je acties ook netjes op tijd aan- en uitzet.

Orders gaan wel direct, want Magento kan na een betaling meteen een event afvuren. Wij zetten die order dan niet synchroon in AFAS tijdens het afrekenen, maar in een queue. De klant krijgt zijn bevestiging, en de koppeling probeert het daarna. Is AFAS even niet bereikbaar of in onderhoud, dan wacht de order in de queue en gaat hij later alsnog door. Een checkout die stilvalt omdat het ERP traag reageert, is een ontwerpfout.

Voor B2B-shops met klantspecifieke prijzen speelt een extra keuze: haal je de prijs live uit AFAS op bij het bekijken van een product, of synchroniseer je prijslijsten vooraf naar Magento? Live ophalen is altijd actueel, maar maakt de snelheid van je shop afhankelijk van de API van AFAS. Vooraf synchroniseren is sneller en robuuster. Wij kiezen vrijwel altijd voor vooraf synchroniseren met een live controle bij het plaatsen van de order.

Dubbele orders zijn het meest voorkomende probleem. Een call naar AFAS loopt in een time-out, de koppeling weet niet of de order is aangekomen en probeert het opnieuw. Resultaat: twee orders in AFAS, twee keer gepickt. De oplossing is idempotentie: het Magento-ordernummer als externe referentie in AFAS opslaan en voor elke retry eerst controleren of de order al bestaat.

Stille fouten zijn het tweede probleem. Een koppeling die faalt zonder dat iemand het merkt, is erger dan geen koppeling, omdat iedereen aanneemt dat het goed gaat. Elke afgewezen order, elke mislukte voorraadsync en elke achterstand in de queue moet een melding opleveren bij een persoon, met de foutmelding van AFAS erbij. Een logbestand op een server dat niemand leest, telt niet.

Het derde probleem is drift in de inrichting. Iemand voegt in AFAS een veld toe aan een view, verandert een artikelgroep of zet een nieuw magazijn op, en de koppeling gaat stuk of, erger, synchroniseert ineens verkeerde data. Daarom documenteren we de verwachte GetConnector-structuur in de code en valideren we elke response daartegen. Wijkt de structuur af, dan stopt de sync en krijg je een melding, in plaats van dat er foute voorraad in je shop komt.