Technische handleiding

# Inleiding

Deze technische handleiding is geschreven voor ontwikkelaars. De Mollie Plus plugin is te krijgen via de Craft Plugin Store (opens new window).

Deze handleiding is zorgvuldig samengesteld door WHITE Digital Agency. Het is niet toegestaan deze Craft handleiding te verspreiden zonder ons hiervoor vooraf om toestemming te vragen. Eventueel genoemde merken en beeldmerken zijn eigendom van Pixel & Tonic (opens new window) en Mollie (opens new window).

Aanvullingen of opmerkingen? Laat het ons weten! Samen kunnen we anderen helpen bij een geweldige Craft ervaring.

Er is ook een handleiding voor Craft CMS en Craft Commerce beschikbaar.

# Requirements

  • Deze plugin vereist Craft CMS 3.4 of later.
  • Deze plugin vereist Craft Commerce versie 3.1 of later (versie 3.2 of hoger is vereist om het zijpanel op de bestelpagina weer te geven).
  • Een geactiveerd Picqer account is vereist.
  • De Craft website moet publiekelijk toegankelijk zijn.
  • Om de plugin te kunnen configureren moet je rechten hebben om instellingen te wijzigen in Craft (wijzigingen toestaan), de user moet Admin zijn in Craft.
  • De plugin moet een aangepaste tabel in je database kunnen maken.
  • Deze plugin is compatible met Composer 2.0.

# Installatie

Volg deze stappen om de Picqer plugin voor Craft CMS te installeren:

  1. Open je terminal en ga naar je Craft project:
    cd /path/to/project
  2. Vertel Composer dan om de plugin te laden:
    composer require white-nl/commerce-picqer
  3. Installeer de plugin via de CLI:
    ./craft plugin/install commerce-picqer

Je kunt de Picqer-plugin ook installeren via de Plugin Store in het Craft Control Panel. Ga naar Settings → Plugins en klik op de Commerce Picqer “Install” knop.

# Activeer je licentie

Deze plugin vereist een commerciële licentie. Na het succesvol installeren van de plugin, zie je een waarschuwingsbalk in Craft. Klik op deze balk om je licentie te activeren in de Craft Plugin Store met je Craft ID.

# Basis setup

Open na de installatie de instellingenpagina van de plugin in je Craft project om Picqer in Craft in te stellen.

# Verbind Craft met Picqer

Geef je Picqer API Subdomein en API Key op in Settings > tab General (andere tabbladen zijn uitgeschakeld totdat je dit hebt gedaan). Je kunt API Keys aanmaken in je control panel van Picqer via Settings → sectie API Keys.

connect.

# Orders exporteren van Craft naar Picqer

Als je automatisch orders wilt pushen van Craft naar Picqer, dan kun je deze functie inschakelen door te navigeren naar de “Craft to Picqer” tab in de instellingen van de plugin. Deze stap is volledig optioneel: sla deze stap over als je alleen Picqer data wilt importeren in Craft.

exporting orders.

  • Om het exporteren van Craft naar Picqer volledig in- of uit te schakelen, kun je de optie “Push orders to Picqer” gebruiken.
  • Je kunt bij “Order Status to push orders” aangeven van welke status de orders automatisch naar Picqer worden gepusht. Als een Craft Commerce order met een van de opgegeven statussen wordt opgeslagen, wordt deze automatisch naar Picqer gepusht als conceptorder.
  • Daarnaast kun je Craft productprijzen mee laten pushen met de order (waarbij de standaardprijzen van elk product geconfigureerd in Picqer worden overschreven), of ontbrekende producten automatisch laten aanmaken in Picqer door de corresponderende selectievakjes in te schakelen.
  • Bij het exporteren van orders zal de Picqer plugin proberen om producten in Picqer te matchen op SKU van een product/variant in Craft en een Product Code in Picqer. Als de optie “Automatically create missing products” is ingeschakeld, zal Craft ontbrekende producten maken in Picqer door SKU te gebruiken als een Product Code, titel van het product als een Product Name, en Variant Price als een Price in Picqer. Je moet alle extra informatie die je nodig hebt handmatig invoeren in het Picqer configuratiescherm. Anders geeft de Picker API een foutmelding als je een bestelling probeert te maken met een ontbrekend product.
  • Je kunt Craft ook automatisch voorraad laten toewijzen en de order in Picker in de verwerkingsstatus laten zetten wanneer een order overgaat naar een van de opgegeven orderstatussen. Dit kan ook in één keer, voor één specifieke bestelstatus. Als je “voorraad toewijzen” doet, worden webshop artikelen gereserveerd voor de corresponderende order en afgetrokken van de totale voorraad. “Processing” van een order betekent dat deze wordt afgerond en toegevoegd aan een picklijst.

Zorg ervoor dat je de instellingen van de plug-in dubbel controleert als je wijzigingen aanbrengt in bestelstatussen, vooral als je een status verwijdert of de naam van een handle wijzigt.

# Gegevens importeren van Picqer in Craft

Je kunt automatisch alle productvoorraadwijzigingen van Picqer naar Craft halen, of automatisch orderstatussen in Craft bijwerken als ze in Picqer worden gewijzigd. Navigeer hiervoor naar “Picqer to Craft” in de plugin instellingen. Deze stap is ook optioneel: sla deze stap over als je alleen orders wilt exporteren van Craft naar Picqer.

# Productvoorraad synchroniseren met Picqer

Craft kan de productvoorraad in Craft automatisch bijwerken als deze verandert in Picqer door de optie “Pull product stock” in te schakelen en de webhook te registreren.

import data.

Je website moet publiek toegankelijk zijn om de webhooks te laten werken. De Picqer-servers zullen verbinding maken met het webhook-eindpunt van jouw website om meldingen te versturen over de wijzigingen in Picqer. Als het adres van je website verandert, werkt de webhook niet meer en moet je hem opnieuw registreren.

Het is mogelijk om webhooks te registreren op een omgeving via de Picqer instellingenpagina, zelfs als je systeeminstellingen voor een bepaalde omgeving vergrendelt (bijvoorbeeld je productieserver met uitgeschakelde systeeminstellingen).

Vergeet niet de wijzigingen op te slaan door op de knop “Save” te klikken.

# Craft orderstatussen bijwerken bij verandering van een Picqer orderstatus

Wanneer de orderstatus in Picqer verandert, kun je de Craft orderstatus automatisch laten veranderen om de verandering te weerspiegelen. Bijvoorbeeld, wanneer de Picqer order overgaat van de “concept” status naar de “processing” status, kan deze plugin automatisch de orderstatus in Craft veranderen in de gewenste status (zoals “Shipped”); of wanneer de Picqer order wordt geannuleerd, kan het de orderstatus in Craft ook instellen op “Cancelled”.

update status.

  • Om dit te laten werken, maak je eerst alle gewenste order statussen aan in Craft: navigeer naar Commerce → System Settings → Order Statuses.
  • Zodra je alle mogelijke order statussen hebt geconfigureerd, ga je terug naar de Picqer plugin instellingen en configureer je de “Order status mapping” tabel: voeg een rij toe en als je een directe match wilt tussen de Picqer order status en Craft order status, laat je de eerste kolom op “(Any)” staan en selecteer je Picqer en Craft order statussen uit de dropdowns.
  • Als je een complexere orderstatusstroom hebt, kan de eerste kolom van de mapping tabel nuttig worden: door daar een specifieke orderstatus te selecteren zal de mapping regel alle orders met andere orderstatussen negeren.
  • Nadat je de mapping hebt geconfigureerd, kun je het selectievakje “Pull order status” inschakelen en de webhook ervoor registreren.

Your website should be publicly accessible in order for the webhooks to work. Picqer servers will contact the webhook endpoint of your website to send notifications about the changes in Picqer. If your website address changes, the webhook will stop working and you would need to register it again.

Het is mogelijk om webhooks te registreren op een omgeving via de Picqer instellingenpagina, zelfs als je systeeminstellingen voor een bepaalde omgeving vergrendelt (bijvoorbeeld je productieserver met uitgeschakelde systeeminstellingen).

Vergeet niet de wijzigingen op te slaan door op de knop “Save” te klikken.

Zorg ervoor dat je de instellingen van de plug-in dubbel controleert als je wijzigingen aanbrengt in bestelstatussen; vooral als je een status verwijdert of de naam van een handle wijzigt.

# Geavanceerde instellingen

# Snelle voorraadupdates

Als je project veel producten heeft en de voorraad erg snel wisselt, kan het inschakelen van de “Pull product stock” optie de prestaties van je website beïnvloeden. Als (en alleen als!) dit invloed heeft op je website, kun je de “Fast stock updates” optie inschakelen op het “Advanced” tabblad van de plugin instellingen. Dit zorgt ervoor dat de plugin alleen de voorraadwaarde in de database direct wijzigt, zonder dat er een complete product opslaan procedure wordt gestart die normaal wordt uitgevoerd.

stock updates.

Het inschakelen van deze optie kan interfereren met andere plugins die werken met productvoorraad. Doe dit alleen als je zeker weet wat je doet.

# Weergave naam plugin

Je kunt de weergavenaam van de plugin in het systeem veranderen door de corresponderende optie op het tabblad “Advanced” van de plugin-instellingen te wijzigen. Dit zal alle plugin vermeldingen in het Craft control panel hernoemen (behalve in de “Plugins” sectie).

# Picqer informatie op de order detailspagina

Deze plugin voegt een extra informatiepanel toe aan de bestelgegevenspagina in het Craft control panel.

orderdetail

Nadat de bestelling naar Picqer is gepushed, vind je nuttige informatie over de bestelling:

  • Picqer Order ID met een link naar de order in het Picqer control panel.
  • Of de voorraad is toegewezen in Picker of niet.
  • Of de order al dan niet in de status Processed is gezet.
  • Een link naar de openbare orderstatuspagina.

Je Craft Commerce versie moet 3.2 of hoger zijn om dit panel weer te geven.

# Probleemoplossing

# Foutmeldingen

Deze plugin is ontworpen om Craft te laten werken zonder onderbrekingen van de normale orderverwerking, zelfs als er problemen optreden met de Picqer integratie. Het toont geen foutmeldingen aan de gebruiker. In plaats daarvan worden alle foutmeldingen naar de logs van het Craft systeem gestuurd.

Het produceert de logberichten in het logsysteem van Craft, gemarkeerd met een aparte categorie, 'commercepicqer'. Inspecteer de applicatie log om Picqer foutmeldingen te vinden. Daarnaast kun je Picqer logberichten altijd uitpakken in een apart logdoel. Om dit te laten werken, kun je je config/app.php bestand als volgt configureren:

# Craft 3.x

return [
    '*' => [
        'components' => [
            'log' => function() {
                $config = craft\helpers\App::logConfig();
                if ($config) {
                    $config['targets']['commercepicqer'] = [
                        'class' => \craft\log\FileTarget::class,
                        'logFile' => '@storage/logs/commercepicqer.log',
                        'categories' => ['commercepicqer'],
                        //'levels' => Logger::LEVEL_ERROR | Logger::LEVEL_WARNING,
                        'logVars' => [],
                    ];
                }
                return $config ? Craft::createObject($config) : null;
            },
        ]
    ]
];

# Craft 3.6+

return [
    '*' => [
        'components' => [
            'log' => [
                'targets' => [
                    '__fileTarget' => function() {
                        if (!class_exists(FileTarget::class)) {
                            return null;
                        }
                        return Craft::createObject([
                            'class' => FileTarget::class,
                            'logFile' => '@storage/logs/commercepicqer.log',
                            'categories' => ['commercepicqer'],
                            //'levels' => Logger::LEVEL_ERROR | Logger::LEVEL_WARNING,
                            'logVars' => [],
                        ]);
                    }
                ],
            ],
        ]
    ],
];

# Webhook fouten

Als een webhook die door Picqer is aangeroepen te vaak mislukt, kan Picqer deze uitschakelen. In dat geval moet je de webhook opnieuw registreren op de instellingenpagina van de plugin.

Om uit te zoeken wat de oorzaak is van de problemen met de webhook, kun je kijken in de webhook call log in je Picqer control panel, onder Settings → Webhooks.

webhook failures

# Synchronisatieproblemen

Als Craft niet de juiste meldingen ontvangt over wijzigingen in de order in Picqer (bijvoorbeeld als de webhook niet meer werkt door een verkeerde handmatige actie in de order in Picqer), kan het nodig zijn om Craft te dwingen om de status van de ordersynchronisatie te “vergeten”.

Om dit te doen, moet je handmatig het corresponderende record in de database verwijderen. Je kunt ze vinden in de tabel 'commercepicqer_ordersyncstatus'.

# Picqer support

Neem contact op met Picqer als je vragen hebt over de plugin en de configuratie van het Picqer dashboard.

Deze handleiding wordt je aangeboden door WHITE Digital Agency. Bezoek white.nl om meer van ons werk te zien.