AFAS Shopify koppeling: orders, voorraad en retouren zonder handwerk

Aan de AFAS-kant werk je met connectoren. Met een GetConnector lees je artikelen, voorraad, prijzen en debiteuren uit. Met een UpdateConnector schrijf je terug, bijvoorbeeld verkooporders via de UpdateConnector FbSales. Een GetConnector is een view die in AFAS zelf wordt ingericht. Wijzigt iemand die view, dan verandert wat de koppeling binnenkrijgt. Je authenticeert met een token dat Base64-gecodeerd in de Authorization-header gaat, met het voorvoegsel AfasToken. Gebruik daarvoor een aparte koppelgebruiker met minimale rechten.

AFAS adviseert om op te halen in pagina's met skip en take, altijd met een vaste sortering. Haal niet alles in één keer op. AFAS raadt aan om het aantal kolommen maal het aantal rijen per call onder de 150.000 te houden. Eén API-call mag volgens AFAS maximaal 75 MB zijn.

Aan de Shopify-kant werk je met de Admin GraphQL API. De REST Admin API is sinds 1 oktober 2024 legacy en nieuwe publieke apps moeten sinds april 2025 GraphQL gebruiken. Een nieuwe koppeling bouw je dus op GraphQL. Shopify rekent daar niet per request, maar per querykost. Elke query en mutation kost punten, en die punten lopen uit een bucket die per seconde bijvult.

Hoe snel die bucket bijvult, hangt af van je Shopify-abonnement. Volgens de documentatie van Shopify is dat 100 punten per seconde op Standard, 200 op Advanced, 1.000 op Shopify Plus en 2.000 voor Shopify for enterprise. Eén losse query mag nooit meer dan 1.000 punten kosten. Raakt de bucket leeg, dan krijg je een throttle-fout en moet je wachten. Een koppeling die duizenden voorraadmutaties tegelijk afvuurt, moet daar dus op doseren.

Voor grote hoeveelheden data heeft Shopify bulk operations. Die vallen volgens Shopify niet onder dezelfde kostenlimieten als losse queries. Wij gebruiken ze voor de eerste volledige sync van artikelen en voor grote exports. Voor dagelijkse delta's werken we met kleine, goed gedoseerde GraphQL-calls.

Zoek je op AFAS Shopify koppelingen, dan vind je een paar kant-en-klare opties. In de Shopify App Store staat de app AFAS Profit Financieel van Gladior. De listing beschrijft het uitwisselen van gegevens tussen Shopify en AFAS Profit, maar noemt niet precies welke datastromen erin zitten. Vraag dat dus vooraf na bij de leverancier.

Koppelplatform APIcenter biedt een Shopify-AFAS-integratie met flows voor producten, voorraad, klanten, verzendingen, orders en refunds. Alumio heeft een connector voor AFAS en een voor Shopify, die je in één flow combineert.

Zo'n standaardoplossing is vaak de goedkoopste start. Ga je ervoor, test dan drie dingen. Hoe gaat de app om met dubbele webhooks? Wat gebeurt er met een refund of een deelretour? En krijg je een melding als een order door AFAS wordt afgewezen? Als het antwoord op één van die vragen vaag is, weet je waar het later misgaat.

Een Shopify-order heeft een globaal unieke ID en een zichtbaar ordernummer, zoals #1001. Shopify zegt zelf dat dat zichtbare nummer niet uniek is over meerdere winkels, en dat het onderliggende nummer niet gegarandeerd doorlopend is. Gebruik het dus niet als enige sleutel. Wij slaan de Shopify-order-ID op als externe referentie in AFAS en tonen het zichtbare ordernummer voor je klantenservice. Heb je meerdere winkels, bijvoorbeeld per land, dan zit de winkel ook in de sleutel.

Idempotentie is bij Shopify extra belangrijk. Omdat dezelfde webhook vaker kan binnenkomen, controleert de koppeling voor elke order eerst of die al in AFAS staat. Een tweede levering van orders/create levert dan nooit een tweede order op.

Refunds zijn het lastigste deel. In Shopify is een refund een apart object op de order, met eigen regels voor producten, verzendkosten en eventuele correcties. In AFAS moet daar een creditering tegenover staan die op de juiste factuur en de juiste grootboekrekeningen landt. Hoe dat precies werkt, hangt af van je AFAS-inrichting. Daarom leggen we in de analyse per scenario vast wat er moet gebeuren: volledige refund, deelrefund, alleen verzendkosten, en een refund zonder retour.

Retouren lopen in Shopify via een eigen levenscyclus met webhooks zoals returns/request, returns/approve en returns/close. Wil je retourgoederen ook in de AFAS-voorraad terugzien, dan koppel je die stappen aan een retourontvangst in AFAS. Doe je dat niet, dan klopt je geld wel maar je voorraad niet.

Dubbele orders, door dubbele webhooks of een blinde retry na een time-out. De oplossing is idempotentie op de Shopify-order-ID, zoals hierboven beschreven.

Throttling bij grote updates. Een prijswijziging op het hele assortiment of een grote voorraadcorrectie in AFAS levert ineens duizenden mutaties op. Wie die ongedoseerd naar Shopify stuurt, loopt tegen de kostenlimiet aan. Een goede koppeling leest de kosteninformatie uit elke response, past het tempo aan en gebruikt bulk operations waar dat kan.

Stille fouten. Een gemiste webhook of een afgewezen order in AFAS valt pas op als een klant belt. Elke afwijzing en elke achterstand moet een melding opleveren bij een persoon, met de originele foutmelding van AFAS of Shopify erbij. Een reconciliatie-job die dagelijks Shopify-orders naast AFAS-orders legt, vangt de rest.

Drift in de inrichting. Iemand past een GetConnector-view in AFAS aan, of een app-wijziging in Shopify verandert welke velden beschikbaar zijn. Daarom valideren we elke AFAS-response tegen de verwachte structuur. Wijkt die af, dan stopt de sync en krijg je een melding, in plaats van dat er foute data in je winkel komt.