Het probleem
Benfida bedient professionele klanten — apothekers, therapeuten, artsen en groothandelaars — in België, Nederland, Frankrijk en Luxemburg. Elke nieuwe professionele aanvraag vereiste een reeks manuele stappen van een beheerder:
- Het BTW-nummer verifiëren via de Europese VIES-databank
- De correcte prijscatalogus koppelen op basis van het facturatieland (andere tarieven voor BE, NL, FR en LU)
- Intracom BTW-vrijstelling activeren voor EU-bedrijven buiten België
- De betaaltermijn instellen: directe betaling bij checkout of 30 dagen netto
- Controleren of de professional al een bestaand Shopify-klantaccount had om duplicaten te vermijden
Met een groeiend professioneel klantenbestand was deze manuele flow niet langer schaalbaar. De oplossing: een volledig op maat gebouwd registratieplatform dat elke stap automatiseert.
De architectuur
De oplossing is een Node.js/Express API-server gehost op DigitalOcean App Platform, met automatische deploys via GitHub. De server verwerkt formulierinzendingen, valideert en verrijkt de data, en spreekt rechtstreeks de Shopify Plus GraphQL API aan via een OAuth-token.
Verwerkingspipeline in 9 stappen
Stap 1 — E-mailprecheck Vóór het invullen van het formulier wordt het e-mailadres gecontroleerd via de Shopify API. Bestaat er al een B2B-account? Dan krijgt de gebruiker onmiddellijk een loginlink en wordt verdere registratie geblokkeerd.
Stap 2 — Formuliervalidatie (Zod) Alle velden worden server-side gevalideerd via een strikt Zod-schema: adresstructuur, BTW-formaat, landcodes en betaaltermijn. Ontbrekende of foutieve data wordt teruggerapporteerd met precieze foutmeldingen per veld.
Stap 3 — BTW-opkuis & auto-prepend
Annotaties zoals (ondernemingsnummer) worden automatisch gestript. Voor BE en LU wordt de landcode automatisch toegevoegd. De frontend voert de VIES-opzoeking al uit bij het verlaten van het BTW-veld, zodat de professional zijn gegevens bevestigd ziet nog voor hij het formulier indient.
Stap 4 — VIES-validatie (EU SOAP API) Het gereinigde BTW-nummer wordt via de Europese VIES-databank geverifieerd. Bij bevestiging worden bedrijfsnaam en adres automatisch ingevuld. Is VIES tijdelijk onbeschikbaar, dan wordt de aanvraag alsnog aanvaard maar de beheerder ontvangt een ⚠️-markering in de notificatie-mail voor manuele controle.
Stap 5 — Intracom-bepaling Automatische detectie of een EU-bedrijf buiten België in aanmerking komt voor BTW-vrijstelling via intracom-reverse charge. Relevant voor groothandelaars in Nederland, Frankrijk en Luxemburg.
Stap 6 — Shopify bedrijf aanmaken (companyCreate)
Het volledige bedrijfsprofiel wordt aangemaakt inclusief factuur- en verzendadres, BTW-registratienummer en contactpersoon. Een bestaande Shopify-klant wordt automatisch als contactpersoon gekoppeld via companyAssignCustomerAsContact.
Stap 7 — Catalogus koppelen (non-blocking)
Op basis van het facturatieland wordt automatisch de correcte prijscatalogus gekoppeld via catalogContextUpdate. Een fout bij deze stap blokkeert de registratie niet — de koppeling wordt gelogd voor opvolging.
Stap 8 — Betaaltermijn instellen (conditioneel)
Koos de professional voor 30 dagen betaaltermijn? Dan wordt via companyLocationUpdate automatisch het NET 30-betalingssjabloon ingesteld — uitsluitend als het BTW-nummer live door VIES werd bevestigd. Zonder bevestiging is deze optie verborgen in het formulier.
Stap 9 — Notificatie- en welkomstmail De beheerder ontvangt een gestructureerde HTML-mail met alle bedrijfsgegevens, een directe link naar Shopify Admin en eventuele VIES-waarschuwingen. De professional ontvangt een tweetalige welkomstmail (NL/FR) met loginlink.
Slimme UX & beveiliging
UX-beslissingen:
- Volledig tweetalig (NL/FR): Automatische taaldetectie op basis van URL-parameter. Alle validatiemeldingen, banners en e-mails worden in de gekozen taal verstuurd.
- Progressieve onthulling: Het formulier toont stap per stap enkel relevante secties. De betaaltermijnkeuze verschijnt enkel voor professionals met een VIES-bevestigd BTW-nummer.
- Auto-lookup bij blur: Het BTW-veld triggert automatisch een VIES-opzoeking zodra de professional het veld verlaat, zonder knop.
Beveiliging:
- API-sleutelbeveiliging: Elke formulierverzending vereist een
X-API-Keyheader. Verzoeken zonder geldige sleutel worden geblokkeerd met HTTP 403. - Rate limiting: Aparte limieten op het e-mailcheck-endpoint (30 req/15 min) en het registratie-endpoint om misbruik te voorkomen.
- Server-side hervalidatie: Alle client-side validatie wordt server-side herhaald via Zod. De client kan nooit een ongeldige staat doorzetten.
Resultaat & ROI
| Metric | Voor | Na |
|---|---|---|
| Cataloguskoppeling | Manueel, per land | 100% automatisch |
| BTW-verificatie | Manueel, per aanvraag | Real-time VIES — 0 manuele controles |
| Onboarding tijd | Uren beheerder | < 3 seconden |
| Schaalbaarheid | Groeit lineair met personeel | Volledig autonoom |
Elke nieuwe B2B-professional wordt volledig automatisch onboarded: BTW geverifieerd, bedrijf aangemaakt, juiste catalogus gekoppeld, betaaltermijn ingesteld en welkomstmail verstuurd — zonder enige manuele tussenkomst van het Benfida-team. Enkel aanvragen met een niet-verifieerbaar BTW-nummer worden geflagd voor manuele opvolging.