ERP-koppelvlak Grossier.nu (0.5.0)

Alleen vestigingen uit deze lijst tellen; voorraad op een vestigingscode die hier niet in staat, negeert het platform. De vestiging van de klant (Customer.branchCode) toont de shop als "uw vestiging", de andere samen als "elders bij de grossier". Of voorraad van een andere vestiging leverbaar is en wanneer, bepaalt het platform met zijn routes. Een ERP zonder vestigingen meldt feature branches false en levert voorraad als één getal zonder branchCode.

Tot 500 sleutels per aanroep. Het ERP matcht exact (spec hoofdstuk 6): op erpArticleId (bekend id wint, zonder controle van de overige velden), anders op ean (voorloopnullen tellen niet; past hij op meer artikelen, dan stopt de reeks met ambiguous), anders op articleNumber + brand/brands, anders op articleNumber alleen als dat binnen het ERP uniek is en het platform géén merk meestuurt. Klopt een meegegeven merk niet, dan not_found (met candidates als het nummer bij een ander merk bestaat). Nooit op een deel van het nummer. Inactieve artikelen tellen mee voor de uniciteit.

Elke sleutel komt precies één keer terug, herkenbaar aan requestId. Onbekend = known: false. Fouten per sleutel raken alleen die sleutel; een sleutel zonder requestId, een dubbele requestId of meer dan 500 sleutels geeft 400 voor de hele aanroep.

Voorraad per vestiging uit GET /branches, altijd alle vestigingen (ook met 0); zonder vestigingen één StockLevel zonder branchCode (spec 11).

Met module pricing en een meegegeven erpCustomerId bevat elk bekend, actief artikel het blok price. Zonder de module negeert het ERP erpCustomerId, zonder waarschuwing.

Zonder updatedSince de volledige stam, gepagineerd. Met updatedSince alleen rijen die sindsdien gewijzigd zijn, inclusief inactief gemaakte artikelen (active: false). Stabiele sortering op (updatedAt, erpArticleId).

Sleutel is de artikelsleutel (erpArticleId als bekend, anders EAN of artikelnummer + merk), gezocht volgens spec hoofdstuk 6. Bestaat het artikel niet, dan wordt het aangelegd (201). Bestaat het, dan (200):

• articleNumber, brand en ean blijven ongemoeid (de schrijfwijze van de grossier wint);
• de overige meegegeven velden worden bijgewerkt; null of weggelaten = niet wijzigen;
• suppliers wordt per supplierCode bijgewerkt of aangevuld, nooit verwijderd;
• een inactief artikel wordt weer actief.

Een onbekend erpArticleId is 404; een sleutel die op meer artikelen past is 422 business_rule; een inkoopprijs van 0 of lager is 400. Een onbekende supplierCode wordt bewaard zoals meegegeven. Idempotent: nogmaals sturen geeft hetzelfde artikel. Het antwoord bevat suppliers, vatRate en salesPriceGross zoals het ERP ze nu kent.

Eén rij per artikel per vestiging. quantityFree = fysiek aanwezig min gereserveerd. Een artikel dat op een vestiging op nul staat komt met quantityFree: 0 terug zodat de kopie wordt bijgewerkt. updatedAt van een rij wijzigt bij elke mutatie van aanwezig, gereserveerd of expectedAt; rijen van inactieve artikelen blijven staan. Zonder vestigingen (feature branches false) één rij per artikel, zonder branchCode. Stabiele sortering op (updatedAt, erpArticleId, branchCode).

Precies één van debtorNumber, platformReference, email of updatedSince. Vergelijking van debtorNumber genormaliseerd (letters en cijfers, hoofdletterongevoelig); het ERP geeft alle klanten die passen. Meer dan één treffer is dubbelzinnig: het platform koppelt dan niet. updatedSince met een tijdstip ver in het verleden levert de volledige klantenlijst.

Idempotent op platformReference. Het ERP kent debiteurnummer en betaalvoorwaarden toe en geeft ze terug. Bestaat er al een debiteur met hetzelfde e-mailadres of KvK-nummer, dan mag het ERP weigeren met 422 business_rule. Het platform plaatst de order daarna op het teruggegeven erpCustomerId; een order maakt zelf nooit een klant aan.

Het platform roept dit alleen aan bij het inloggen. Daarna werkt het op erpCustomerId. Een mislukte inlog is 401 met code: invalid_credentials, geen 200 met een vlag. De inlognaam is hoofdletterongevoelig, het wachtwoord hoofdlettergevoelig. Een geblokkeerde klant logt in en komt terug met isBlocked: true.

Wijzigt alleen platformReference; andere velden in de body negeert het ERP. Daarna is de klant te vinden met GET /customers?platformReference=. Nogmaals met dezelfde waarde geeft 200 met dezelfde klant. Draagt een andere klant deze referentie al, dan 422 business_rule.

platformReference is de idempotentiesleutel, uniek per grossier. Het ERP controleert hem vóór elke andere validatie.

• Nieuw: 201 met de aangemaakte, bevestigde order; het ERP legt de order vast vóór het antwoordt.
• Bestaat al: 200 met de bestaande order in zijn huidige stand, ongeacht de inhoud van de nieuwe aanvraag, ook als die nu ongeldig zou zijn; het ERP vergelijkt niet.

Een onbekende klant is 404, een onbekende vestiging 400, een geblokkeerde klant 422 customer_blocked. Boven de kredietlimiet neemt het ERP de order aan en mag het regels op manual zetten; weigeren op krediet is 422 business_rule. Een onbekend artikel wijst de order niet af: de regel krijgt status: manual. Met module articles.manage legt het platform het artikel vóór de order aan; de regel volgt daarna de gewone regelstatussen (zie OrderLineStatus). Het ERP boekt unitPriceNet zoals meegegeven. Met module pricing vergelijkt het exact op twee decimalen met zijn actuele berekening bij het bestelde aantal; bij een verschil mag het corrigeren en meldt het dat met priceCorrected en requestedUnitPriceNet. Bij payment.method: online corrigeert het niet; toeslagen (per regel en op orderniveau) corrigeert het nooit. Eigen voorraad wordt gereserveerd op source.branchCode, anders delivery.branchCode, anders de vestiging van de klant.

Toeslagen op orderniveau (verzendkosten, kleine-orderkosten, bezorgtoeslag) komen in surcharges, nooit als artikelregel; het ERP legt ze vast zoals het wil, geeft ze terug in Order.surcharges en telt ze mee in totalNet en totalGross. Het levermoment op de kop (delivery.promisedAt) geldt voor elke regel zonder eigen promisedAt; het ERP neemt beide over zoals meegegeven. Na het plaatsen is statusCode ten minste confirmed.

Twee gebruikswijzen. Delta (updatedSince): over alle klanten, of met erpCustomerId per klant; sortering oplopend op (updatedAt, erpOrderId), sort wordt genegeerd. Zoeken (zonder updatedSince): erpCustomerId verplicht, tenzij op platformReference wordt gezocht; sort naar keuze. De zoekfilters werken ook op regelniveau (articleNumber, vehicleRegistration, text) en geven dan de hele order terug, met alle regels. Delta en zoekfilters mogen samen; alle filters gelden tegelijk. Alleen platformReference is het minimum; elke andere combinatie vraagt feature orders.history. Retouren die via het platform zijn aangemeld staan nooit in deze lijst (zie /returns).

Geeft elke order van de grossier, ongeacht de klant; de sleutel is per grossier en het platform controleert zelf of de order bij de vragende klant hoort.

Het document met de sleutel, voor het platform; het platform geeft het zelf aan de garage door. Het zusje van GET /invoices/{erpInvoiceId}/document. Bestaat het document (nog) niet, dan 404.

Met updatedSince is erpCustomerId optioneel (delta over alle klanten); zonder is hij verplicht. Zonder delta aflopend op factuurdatum, daarna id. unpaidOnly = open en partial, ook open creditnota's.

Het document met de sleutel, voor het platform; het platform geeft het zelf aan de garage door. Daarnaast is er documentUrl (zonder sleutel, tijdgebonden), ook alleen voor het platform. Bestaat het document (nog) niet, dan 404.

Idempotent op platformReference, zoals een order. Elke regel verwijst naar een regel van een eerdere order (erpOrderId of erpOrderNumber, plus orderLineNo of article). Staat het artikel op meer regels van die order, dan 422 business_rule met het verzoek orderLineNo mee te geven. Per orderregel hoogstens het geleverde aantal min eerder aangemelde retouren, per soort (article, coreOnly) apart; afgewezen retouren tellen niet mee. Overschrijden is 422 met errors[] per regel.