← Terug naar home Voor ERP-leveranciers

ERP-koppelvlak
Grossier.nu

Dit is wat het ERP van een grossier aanbiedt, zodat Grossier.nu er rechtstreeks mee koppelt. Eén beschrijving voor elk ERP: wie hem overneemt sluit aan op de generieke koppeling van het platform, wie alleen de eisen in een eigen API inbouwt krijgt een koppeling op maat. Status: concept 0.5, openbaar. Vragen en terugmeldingen via support@grossier.nu.

Drie lagen

Het platform eist niet dat een ERP alles levert. Het koppelt al op een klein minimum en werkt dan met minder; alles daarboven meldt het ERP zelf, en het platform past zich aan. Een onderdeel dat ontbreekt is geen storing, maar een functie die de garage in de shop mist.

Eisen en vorm

De eisen gelden altijd, ook voor wie de functies in een bestaande API inbouwt. De vorm (endpoints, velden, foutcodes uit de OpenAPI-beschrijving) is de aanbevolen uitwerking.

1. Idempotent bestellen op de platformreferentie: bestaat de order al, dan komt die terug, nooit een tweede; het ERP legt vast vóór het antwoordt.
2. Exact matchen van artikelen op ERP-artikel-id, EAN of artikelnummer plus merk; gelijkheid na normalisatie, nooit op een deel van het nummer.
3. Stabiele identiteiten voor klant, artikel, order, factuur, retour en inkooporder.
4. Wijzigingen sinds een tijdstip, met een door het ERP teruggegeven vertrekpunt en stabiele paginering.
5. Vrije voorraad is aanwezig min gereserveerd, per vestiging.
6. Een order faalt niet op een onbekend artikel; de regel landt zichtbaar voor handwerk.
7. Prijs en levermoment worden geboekt zoals meegegeven, tenzij de module Prijs actief is.
8. Echte foutstatussen; een fout komt nooit als geslaagd antwoord terug.

	Vorm overgenomen	Alleen de eisen, in een eigen API
Koppeling	De generieke koppeling van het platform: basis-URL en sleutel instellen, klaar.	Een koppeling op maat, door het platform te bouwen en te onderhouden.
Doorlooptijd	De acceptatiescenario's draaien direct tegen de testomgeving.	Eerst een analyse van de API, dan bouwen, dan dezelfde scenario's.
Uitbreidingen later	Een nieuwe module is aan beide kanten een instelling.	Elke uitbreiding is opnieuw maatwerk.
Kosten en planning	Geen bouwkosten voor de koppeling aan platformzijde.	In overleg, afhankelijk van de afwijking.

Documenten, versie 0.5

Wijzigingen per versie

Versie	Datum	Wat is er veranderd
0.5	22 oktober 2026	Uitkomst van een doorloop van de webshop op een ERP dat alleen dit koppelvlak implementeert: acht plekken waar een bouwer moest raden. Toeslagen op orderniveau (verzendkosten, kleine-orderkosten, bezorgtoeslag) apart op de order, nooit als artikelregel; alleen vestigingen uit /branches tellen, de vestiging van de klant is “uw vestiging”, zonder vestigingen één voorraadgetal; het routeschema geldt voor eigen voorraad, voor leveranciersartikelen bepaalt het platform het levermoment, met een levermoment per orderregel; vaste orderstatus statusCode naast de leverstatus; factuurbedragen per veld beschreven, met amountOpen; documentlinks zijn voor het platform, niet voor de garage; retouren teruglezen als delta, met wat de garage terugziet; op een inkooporder alleen leverancierscodes uit het ERP. statusCode, de toeslagen op de order en amountOpen zijn verplicht. Volledige lijst in bijlage C van de specificatie.
0.4	22 oktober 2026	Klant lezen van het volledige koppelvlak naar het minimum: elke order verwijst naar een klant-id van het ERP, en de grossier moet die koppeling kunnen controleren vóór de eerste order. Laag 1 is daarmee artikel, klant en order. Ketenscenario A17 toegevoegd: één klant en één order van klant lezen tot retourstatus, met gelijkblijvende identiteiten over alle stappen.
0.3	21 oktober 2026	Uitkomst van een tweede bouwtest, waarin een nieuwe bouwer zonder voorkennis een ERP uit versie 0.2 bouwde en de generieke koppeling erop werd bijgetrokken. Artikel geeft leveranciers met inkoopprijs, btw-tarief en adviesprijs terug; vastgelegd wat artikelen aanleggen met een bestaand artikel doet; regelstatussen afgebakend; matchen zonder terugval bij een niet-passend merk; retourregel verwijst altijd naar een order; documentlinks zonder sleutel, ten minste een uur geldig, plus documenten per order met sleutel; idempotentie vóór validatie en uniek per grossier; capabilities expliciet en modules leidend; tijd op milliseconden, cursor 24 uur geldig, totalCount altijd; ordernummer exact, zoekfilters beschreven; klant aanmaken met optioneel e-mailadres en één adresregel, platformreferentie achteraf te zetten; inkoopregels met verkoopregelnummer; module Testomgeving met beheerhandelingen onder /test/; meldingen (webhooks) uit de modules, als voorgenomen uitbreiding; foutcodes en transportregels aangevuld. Volledige lijst in bijlage C van de specificatie.
0.2	21 oktober 2026	Uitkomst van een bouwtest: een bouwer zonder voorkennis bouwde een ERP uit de spec, het platform koppelde er in één keer op. Twee werkwijzen benoemd (ERP-beheerd, platform-beheerd) met masterData in de capabilities; module Artikelen aanleggen; idempotentie puur op platformreferentie; matchen vastgelegd (normalisatie, volgorde, matchedOn); prijscorrectie zichtbaar en niet bij online betaling; regelstatussen gedefinieerd en platformLineRef; delta over alle klanten, sort en totalCount; document-URL zonder sleutel; retouren altijd onder /returns; foutcodes aangevuld; module Testomgeving. Volledige lijst in bijlage C van de specificatie.
0.1	21 oktober 2026	Eerste openbare concept: drie lagen, bindende eisen los van de aanbevolen vorm, OpenAPI met 24 operaties.

Zolang het versienummer onder 1.0 ligt is de inhoud een concept en kan hij wijzigen op basis van wat ERP-leveranciers terugmelden; een conceptversie kan ook een eis aanscherpen. Vanaf 1.0 zijn wijzigingen binnen /v1 alleen toevoegend.