Een webshopverbinding beheren

Voordat je begint

Zes dingen, en de eerste twee kosten doorlooptijd in plaats van werk. Begin daarmee voordat je iets anders plant.

• Een eigen pCon.ui-instantie van EasternGraphics of je distributeur, ingericht als shop-instantie. Één licentie volstaat voor zowel de configurator als de catalogusimport: de import draait op hetzelfde instantie-id met het achtervoegsel _wcf, en die variant hoort bij de pCon.ui-licentie. Een instantie is namelijk óf een shop-instantie die eindigt in de winkelwagen, óf een lead-instantie die eindigt in een aanvraagformulier, nooit allebei, en alleen EasternGraphics kan het omzetten
• Je domeinen op de whitelist bij EasternGraphics. Eén live plus twee ontwikkeldomeinen, geen wildcards, elk subdomein apart, en het gaat met de hand op aanvraag
• Fabrikanten die OFML-data publiceren en hun catalogus met jouw account hebben gedeeld. Klopt dat voor een merk niet, dan maakt niets uit deze handleiding het voor dat merk werkend
• Een shop op een platform waar we een adapter voor hebben, en een beheerdersaccount dat een extensie mag installeren
• Een sleutel uit je portaal, uitgegeven voor de site waarop hij gaat draaien. Geef er per omgeving een aparte uit in plaats van een live sleutel naar een testomgeving te kopiëren
• Ruimte in PHP voor een grote configuratie. max_input_vars staat standaard op 1000 en dat is op bij ongeveer twintig artikelen in één configuratie, dus vraag je host om 5000 en een post_max_size die daarbij past. Daaronder weigert de shop een grote configuratie in plaats van er de helft van aan te nemen

De volgorde

De volgorde telt, want twee stappen wachten op anderen en de rest niet. Zet het wachten op dag één in gang.

1. Vraag de whitelist-regels aan bij EasternGraphics. Bedenk eerst welke drie domeinen. Dit is de stap die het meest kans maakt er een week bij te doen, dus hij gaat voorop terwijl je hem pas als laatste nodig hebt.

2. Zet je configurator-instantie in het portaal. Het portaal controleert het id bij EasternGraphics en laat zien wat er werkelijk op je domeinlijst staat, dus je ziet of stap één geland is in plaats van ernaar te moeten vragen.

3. Geef een sleutel uit voor de site. De rauwe sleutel zie je precies één keer. Bewaar hem waar de andere inloggegevens van je shop staan, en niet in een chatbericht.

4. Installeer de adapter en plak de sleutel. De verbinding meldt zichzelf aan zodra hij voor het eerst belt, en staat daarna in je portaal met de versie die hij draait.

5. Importeer een handvol artikelen, niet de catalogus. Pak er één eenvoudige en één ingewikkelde. Je controleert taal, prijs en of de specificatie is aangekomen, en dat wil je op twee producten ontdekken en niet op tweehonderd.

6. Open de configurator op een ervan. Is stap één nog niet geland, dan merk je het hier.

7. Configureer iets en zet het in de winkelwagen. Controleer de prijs, de specificatie en de onderdeelartikelen op de winkelwagenregel, plaats dan een testorder en controleer hetzelfde op de order.

8. Importeer daarna de rest, en pas dan.

De catalogusimport

De import loopt van de server van je shop naar de onze en vandaar naar de catalogus. Je doorloopt de echte fabrikantboom in je eigen admin, vinkt aan wat je wilt, en maakt er producten van.

Wat hij per artikel wegschrijft:

• De titel, uit de tekst van de fabrikant of uit een sjabloon dat je instelt
• De specificatie als tabel van eigenschappen en waarden
• De prijs van de startconfiguratie
• De render als productafbeelding
• Merk en serie, als iets waarop je kunt filteren
• De artikelreferentie, waarmee de productpagina later zijn eigen configurator samenstelt

Wat hij overslaat. Artikelen die de fabrikant als niet bestelbaar markeert worden niet geïmporteerd, en de reden komt in de foutenlijst in plaats van nergens. Een artikel dat zonder bruikbare tekst terugkomt is geen overslag maar een symptoom: zie de taalnotitie hieronder.

Wat een herimport doet. Opnieuw draaien volgt de nieuwe prijslijst en de nieuwe teksten. De afbeeldingengalerij wordt vervangen en niet aangevuld, dus herhaalde imports stapelen geen renders op, en een artikel waarvan de afbeelding en de render hetzelfde bestand zijn wordt één keer opgeslagen in plaats van twee.

Eén artikel is niet één product. Een artikelnummer codeert een startconfiguratie en geen model. Een bureau-artikel kan een keuzelijst van tien breedtes dragen, wat betekent dat elk artikelnummer uit een serie importeren dertig producten kan opleveren waar er één volstaat. Bedenk hoe je een serie wilt modelleren voordat je hem importeert, want het terugdraaien is bewerkelijk.

De configurator op de productpagina

De configurator laadt in een iframe op je eigen productpagina, op je eigen domein, met jouw catalogus en jouw prijzen. Er is geen aparte configuratorsite en geen tweede afrekening.

Het adres dat hij laadt wordt op het moment van renderen samengesteld, uit twee dingen: de artikelreferentie op het product, en de configurator-instantie die centraal voor je account staat. Er wordt niets in het productrecord gebakken. Dat is geen detail: het betekent dat naar een andere pCon-instantie verhuizen één wijziging in één scherm is, in plaats van elk product dat je ooit importeerde.

Een handmatig adres per product bestaat als override, voor de gevallen waarin een product iets nodig heeft wat de automatische samenstelling niet kan uitdrukken. Behandel het als een noodluik. Een product met een handmatig adres volgt je centrale instellingen niet meer, en dat ben je een jaar later vergeten.

Instellingen, en welke laag wint

De verschijningsvorm van de configurator komt uit vier lagen, die elk de vorige overschrijven. De volgorde kennen is het verschil tussen een instelling wijzigen en je afvragen waarom er niets gebeurt.

1. Wat de adapter afleidt. De interfacetaal en de taal van de productdata komen uit de locale van de pagina; het btw-land komt uit de btw-instellingen van je shop zelf. Voor de meeste shops klopt dit al en kom je aan de andere drie lagen nooit toe.

2. Je klantprofiel in het portaal. De standaard voor de hele vloot, voor een klant met meer dan één shop.

3. Het verbindingsprofiel in het portaal. Het antwoord per shop, en de laag die je waarschijnlijk zoekt. Deze parameters beschrijven hoe de configurator ingebed is, en dat is een eigenschap van de shop en niet van de licentie.

4. De store view of de shortcode. Het noodluik, voor die ene store view of die ene pagina die echt afwijkt.

De adapters houden met opzet geen eigen verschijningsinstellingen aan buiten de overrides hierboven. Dat deden ze wel, en een instelling met een standaardwaarde wint altijd van een centrale waarde, waardoor het centrale profiel een shop nooit kon bereiken. Zoek je waar je iets moet wijzigen, begin dan bij laag drie.

Twee talen, niet één. De interfacetaal zet de knoppen en de omlijsting. De taal van de productdata zet de eigenschaps- en materiaalnamen van de fabrikant. Het zijn losse instellingen en ze mogen verschillen, maar zet je ze per ongeluk ongelijk, dan toont je configurator Engelse knoppen boven Nederlandse materialen, of andersom.

Van configuratie naar orderregel

Zodra de klant op in winkelwagen drukt, post de configurator het resultaat naar een gesigneerd adres op je eigen shop. Je shop controleert het verzoek voordat er iets bij de winkelwagen in de buurt komt, importeert de render, en stuurt de bezoeker door.

Het transport is OCI-punchout, dezelfde standaard die inkoopsystemen en leverancierscatalogi onderling gebruiken. Dat is bewust: het is een formaat dat de ontwikkelaars van je platform misschien al kennen, en het is niet iets dat wij hiervoor bedacht hebben.

Wat een geconfigureerde regel draagt:

• De titel en het artikelnummer van de fabrikant, allebei volgend op de configuratie en niet op het product waar het begon
• De geconfigureerde prijs, met netto en bruto apart
• De variantcode en de fabrikant- en seriecodes
• De leesbare eigenschappentekst: elke eigenschap die de klant koos
• De onderdeelartikelen onder de regel, elk met hun eigen nummer en prijs, zodat inkoop erop kan bestellen
• De render
• Een link die exact dezelfde configuratie heropent, 24 uur geldig

Geverifieerde prijzen. De configurator ondertekent de prijs die hij meldt, en je shop kan die handtekening controleren voordat hij hem aanneemt. Zonder die controle is een prijs die bij je shop binnenkomt een bewering en geen feit, en gaat een bureau van tienduizend euro voor één euro de winkelwagen in. De instelling heet Require verified prices en hij staat standaard aan. Laat hem aan. Het enige geval om hem uit te zetten is een instantie die helemaal geen prijzen voert: die stuurt geen handtekening mee, en dan zou elke add-to-cart geweigerd worden.

Herconfigureren. De heropen-link brengt exact terug wat de klant configureerde. Hij verloopt na 24 uur, lang genoeg om een sessie af te maken en kort genoeg dat een oude link in een oude mail geen weg terug wordt naar een verouderde prijs.

WooCommerce in het bijzonder

Een gewone WordPress-plugin zonder buildstap. De instellingen staan op een eigen scherm en zijn gegroepeerd zoals deze handleiding: connector, configurator, configureer-knop, productimport, beveiliging.

Waar de configurator op de pagina komt. WooCommerce-thema's verschillen enorm, dus de plaatsing is een instelling en geen aanname: voor de productsamenvatting, erna, erin, na het hele product, of alleen handmatig. Er staat een prioriteit naast voor thema's die de hook eerder of later moeten draaien dan gebruikelijk. Vecht je thema terug, zet plaatsing dan op handmatig en zet de shortcode waar je hem hebben wilt.

Nuttige buren. De iframe-hoogte neemt elke CSS-lengte, dus70vh en 800px kunnen allebei. Er is een optie om de pCon iFrame Resizer te gebruiken, en een om de eigen productsamenvatting van het thema te verbergen bij producten die volledig door de iframe worden geconfigureerd.

Importopties. Je kiest per veld of de import de titel, de omschrijving, de prijs, de afbeeldingen, de attributen, merk en serie en de SKU wegschrijft. De titel kan uit de lange tekst of de korte omschrijving van de fabrikant komen, of uit een sjabloon dat je zelf schrijft. Zet uit wat je shop met de hand onderhoudt, en een herimport laat het met rust.

Magento 2 in het bijzonder

Een Magento 2-module die je met Composer installeert uit een eigen besloten repository, als bewise/module-pcon-configurator. Hij vraagt Magento 2.4 of nieuwer op PHP 8.3, 8.4, 8.5, en dat declareert het pakket zelf, dus Composer controleert het voordat hij installeert in plaats van dat je er achteraf achter komt.

Waar alles staat. De instellingen staan onder Stores, Configuration, in een BEWISE-sectie, achter een eigen recht, zodat je catalogiseren kunt uitbesteden zonder de sleutel uit handen te geven. De catalogusbrowser is een eigen adminpagina onder Catalog.

Wat hij met je catalogus doet. De artikelreferentie en de handmatige override zijn productattributen, toegevoegd via data patches. Elke pCon-eigenschap wordt een filterbaar select-attribuut, wat betekent dat layered navigation op de configuratie-opties zelf werkt en niet alleen op je eigen attributen. Merk en serie worden categorieën, want Magento heeft geen merktaxonomie om ze in te zetten.

Scope. De import schrijft in default scope, dus geïmporteerde data verschijnt in het adminformulier en geldt in één keer voor alle store views. Verschillen per store view horen in de overridelaag en niet in de import.

Leeg na elke wijziging aan de module de caches. Magento compileert dependency injection en gegenereerde code, en blijft de gecompileerde versie van de oude code draaien zonder het te melden. Dit is gewoon Magento-gedrag en niet eigen aan deze module, maar het is wel de meest voorkomende reden dat een wijziging niets lijkt te doen.

Wat je zonder ons kunt wijzigen

Alles in het portaal en alles in het instellingenscherm van de adapter, en dat dekt samen bijna de hele dagelijkse bediening:

• Je configurator-instantie, die bij het opslaan bij EasternGraphics gecontroleerd wordt
• Talen, btw-land en de andere inbedparameters, per shop
• Sleutels uitgeven en intrekken, waarbij allebei vastgelegd wordt
• Welke velden de import wegschrijft, en hoe titels worden opgebouwd
• Waar de configurator op de pagina staat, en hoe hoog hij is
• Of ongeverifieerde prijzen geaccepteerd worden

Wat je niet zelf kunt is een domein op de whitelist zetten, want dat is de lijst van EasternGraphics en niet de onze, en een eigen portaalaccount aanmaken, want accounts maken wij aan. Al het andere is een scherm.