Craft Commerce integratie

Doel: Leer hoe je jouw Craft webwinkel met je Sendcloud account kunt verbinden.

Vereisten

• Deze plugin vereist Craft CMS 3.3 of hoger
• Deze plugin vereist Craft Commerce versie 3.1 of later (versie 3.2 of hoger is nodig om het zijpaneel op de bestelpagina te tonen)
• De Craft website moet publiek toegankelijk zijn
• Om de plugin in te stellen moet het veranderen van instellingen toegestaan zijn in Craft (allow admin changes), en een gebruiker die een Admin is in Craft. Klik hiervoor toegang tot de instellingen. 

• De plugin moet in staat zijn een aangepaste tabel in je database te maken

• Deze plugin is compatibel met Composer 2.0

Stap 1: Installeer de Sendcloud plugin 

Volg de volgende stappen om de Sendcloud plugin voor Craft CMS te installeren:

1. Open je terminal en ga naar je Craft project:

   cd /path/to/project

2. Zeg dan tegen de Composer dat hij de plugin moet laden:
   

   composer require white-nl/craft-commercesendcloud

3. Installeer de plugin via de CLI:
   

    ./craft install/plugin commercesendcloud 

Stap 2: Activeer je licentie

Deze plugin vereist een commerciële licentie. Nadat je de plugin met succes geïnstalleerd hebt, zie je een waarschuwingsbalk in Craft. Klik op deze balk om je licentie in de Craft plugin store te activeren met je Craft ID.

Stap 3: Basisopstelling

Open na de installatie de plugin instellingen pagina in je Craft project om de installatie van Sendcloud in Craft te voltooien. 

1. Craft verbinden met Sendcloud
   Zorg ervoor dat je Craft website toegankelijk is voor de Sendcloud servers. Klik dan op Register om te verbinden met Sendcloud. Je wordt doorverwezen naar de Sendcloud website en gevraagd om de integratie te bevestigen. Na het opzetten van een verbinding zou de verbindingsstatus in Craft Active moeten zijn (het kan zijn dat je de pagina opnieuw moet laden om de veranderingen te zien).
   
   
   
2. Verzendmethoden maken
   De volgende stap is het aanmaken van verzendmethoden voor Sendcloud in Craft. De lijst onder de verbindingsstatus toont alle beschikbare Sendcloud verzendmethoden voor ingeschakelde landen in de winkelinstellingen van Craft Commerce. Als je sommige verzendmethoden niet ziet, controleer dan of je overeenkomstige landen hebt ingeschakeld in Craft Commerce.
   
   Om een Commerce verzendmethode te maken klik je op de plus + knop of maak je handmatig een verzendmethode met exact dezelfde naam als je Sendcloud verzendmethode. Je moet ook verzendregels instellen voor de nieuw aangemaakte verzendmethode om ze op de voorkant te laten verschijnen.
   
   
   
3. Kies de orderstatus om naar Sendcloud te pushen
   In het tabblad Order Sync in de instellingen van de Sendcloud plugin, kies je de Craft order status voor de bestellingen die je automatisch naar Sendcloud wilt laten pushen (je kunt er meer dan een kiezen). 

   Merk op dat de verzendmethode niet naar Sendcloud kan worden doorgestuurd voordat een verzendlabel is gemaakt. Als je een bestelling naar Sendcloud doorstuurt voordat je het verzendlabel gemaakt hebt, verschijnt de bestelling in Sendcloud met de standaard verzendmethode voorgeselecteerd. 

   Als je liever automatisch etiketten aanmaakt op het moment dat een bestelling overgaat naar een bepaalde bestelstatus, kun je dat doen door de status te kiezen in de optie "Etiketten aanmaken voor bestellingen". Voordat je een etiket maakt, zorgt de plugin er automatisch voor dat de bestelling correct naar Sendcloud wordt doorgestuurd. 

   
   
   
4. Breng Sendcloud pakketstatussen over naar Craft bestelstatussen
   Als je de bestelstatus in Craft automatisch wilt bijwerken aan de hand van de Sendcloud pakketstatus, kaart dan specifieke Sendcloud pakketstatus aan een Craft bestelstatus. De orderstatussen worden automatisch bijgewerkt als de pakketstatus verandert. Als Craft een niet gemapte pakketstatus ontvangt, wordt die genegeerd. Als je geen status toekent worden geen bestellingen bijgewerkt.
   
   
   
5. Bepaal of de integratie het Craft ordernummer of de order ID moet gebruiken.
   Als je werkt met verschillende mappings en andere systemen naast Sendcloud en Craft, geeft de optie om tussen deze twee te kiezen je meer flexibiliteit.
   
6. Vergeet niet de plugin instellingen op te slaan in Craft
   Klik op de rode Save knop als je klaar bent. 

Download labels 

Na voltooiing van de setup worden nieuwe bestellingen met de door jou gekozen bestelstatus naar Sendcloud gepushed en worden de verzendetiketten automatisch voor je aangemaakt. Er zijn twee manieren om verzendetiketten in Craft te downloaden - meerdere etiketten tegelijk, of een enkel etiket per keer.

1. Overzichtspagina van handelsorders
   Gebruik de selectievakjes om een of meer bestellingen te selecteren. Klik op Print Sendcloud Labels in het optiemenu. Het resulterende PDF bestand zal etiketten bevatten voor alle geselecteerde bestellingen.
   
   
   
2. Commerce bestelgegevens pagina

   Open een specifieke bestelling in Craft. Je vindt het Sendcloud informatiepaneel in de rechter zijbalk (alleen beschikbaar op Craft Commerce versies 3.2 of hoger). Klik op de Print Label knop. Het resulterende PDF bestand bevat etiketten voor de geselecteerde bestelling.

   Als je een etiket probeert af te drukken voor een bestelling waarvoor nog geen verzendetiket in Sendcloud is aangemaakt, wordt automatisch een nieuw etiket voor je aangemaakt. 

   

Orders handmatig pushen

Het is ook mogelijk om orders handmatig naar Sendcloud te pushen. Dit kan handig zijn als je een bestelling hebt met een andere status, of als de bestelling om een of andere reden niet gepushed wordt. Er zijn twee manieren om een order push naar Sendcloud te doen - meerdere orders tegelijk of een enkele order.

1. Overzichtspagina van handelsorders
   Gebruik de selectievakjes om een of meer bestellingen te selecteren, kies dan Push to Sendcloud in het optiemenu.

   Bij het pushen van een aantal bestellingen tegelijk kan de webserver het verzoek afbreken, met een timeout foutmelding tot gevolg. We raden je aan niet te proberen meer dan 50 orders tegelijk te pushen. Het is beter om het automatisch pushen van orders per status in te stellen (zie vorige stappen). 

   
   
2. Commerce bestelgegevens pagina
   Als de bestelling nog niet naar Sendcloud gepushed is, zie je de knop Push to Sendcloud (beschikbaar in Craft Commerce versies 3.2 of hoger)
   
   
   

   Na het pushen wordt aanvullende Sendcloud informatie en een knop om het label te downloaden beschikbaar.

   Merk op dat, wanneer je een bestelling handmatig naar Sendcloud pusht, er niet automatisch een verzendetiket wordt aangemaakt. Een etiket wordt pas aangemaakt als je voor de eerste keer een etiket probeert af te drukken. De verzendmethode en het adres worden niet naar Sendcloud gepushed tenzij je een verzendetiket aanmaakt, daarom verschijnt je bestelling met de standaard verzendmethode voorgeselecteerd. 

Servicepunt verzending (optioneel)

Deze plugin ondersteunt Sendcloud Service Point shipping. Dit is een complexere set up en custom development is nodig om de service point checker te integreren in de checkout pagina van je webshop. Omdat elk Craft project een andere front-end stack, template code en aanpak kan hebben, bevat deze plugin alleen een voorbeeld van de Sendcloud service point picker voor de standaard Craft Commerce demo shop frontend templates.

Na installatie vind je een drop-in vervanger voor de shipping template van Craft Commerce in de `example-templates` map. Kopieer en plak deze in je `templates` map. Volg daarna deze setup procedure:

1. Schakel servicepunten in Sendcloud in
   Om servicepunten (of afhaalpuntverzending) in Craft in te stellen, moet je eerst zorgen dat je servicepunten in Sendcloud hebt ingeschakeld en de dragers selecteren die je in de servicepuntkiezer wilt tonen.
   • Om servicepunten in Sendcloud in te schakelen, log je in op je account en ga je naar Instellingen > Integraties.
   • Zoek je Craft Commerce integratie in de lijst van verbonden webwinkels en klik op Bewerken.
   • Vink vervolgens de optie Servicepunten aan om de servicepuntfunctie in te schakelen, en kies de carries die je voor servicepuntlevering wilt aanbieden.
   • Klik op Opslaan als je klaar bent. 
     
     
     
     
2. Maak een verzendmethode voor servicepunten in Craft
   Na het inschakelen van Servicepunten in Sendcloud toont de plugin instellingen pagina de ingeschakelde status voor verzendpunten (groen) en de lijst met beschikbare verzendmethoden toont de methoden voor verzending met servicepunten.
   Om een Craft verzendmethode te maken, klik je op de plus (+) knop. Je kunt ook handmatig een verzendmethode maken met precies dezelfde naam als de Sendcloud verzendmethode. Je moet ook verzendregels voor de nieuw aangemaakte verzendmethode instellen om ze op de voorkant te laten verschijnen.
   
   
   
3. Integreer de servicepuntenkiezer in je front-end
   Als je de standaard Craft Commerce demo shop sjablonen gebruikt, kun je de sjablonen uit de `example-templates` map van onze plugin gewoon naar de `templates` map van je website kopiëren. 
   
   

Ons voorbeeldsjabloon doet het volgende:

• Het toont de knop Kies servicepunt voor verzendmethoden met servicepunten ingeschakeld.
• Als je op de knop klikt, verschijnt een Sendcloud servicepunt selectie iframe. De servicepunten worden uitgefilterd op de vervoerder van de gekozen verzendmethode en het gekozen verzendadres.
• Nadat je het servicepunt gekozen hebt, wordt het op de voorkant getoond en wordt een achtergrond AJAX verzoek naar de Sendcloud plugin gestuurd om de gekozen informatie op te slaan.

Wanneer je de bestelling pusht (of wanneer ze automatisch gepushed wordt), wordt het gekozen servicepunt gebruikt. Sommige verzendmethoden kunnen een geldig telefoonnummer vereisen. Sendcloud's API zal een bestelling weigeren die ongeldige verzendinformatie bevat, dus zorg dat je een goede validatie bouwt!

Bedenk dat het voorbeeld uit de `voorbeeld-templates` map alleen bedoeld is als demonstratie. Het is jouw verantwoordelijkheid om een front-end met een goede validatie voor je winkel te bouwen.

Shipping outside Europe (optional)

Deze plugin ondersteunt het genereren van Sendcloud douanedocumenten voor verzending buiten de EU. Gebruik de veldtoewijzing in de plugin instellingen om je bestaande productvelden te koppelen aan de velden die nodig zijn om douanedocumenten te genereren.

Zorg ervoor dat je aangepaste velden met HS Code en Country Of Origin hebt ingesteld voor producten of varianten in Craft. Vervolgens kun je overeenkomstige velden kiezen in de Sendcloud plugin instellingen:

Zorg ervoor dat het Country Of Origin veld alleen ISO2 landcode bevat (bijvoorbeeld "NL") en de HS Code plugin een geldige HS Code van het product bevat (bijvoorbeeld "6403919600").

Als de bestelling naar Sendcloud gepushed wordt, zoekt de plugin eerst naar de velden op variant niveau, dan op product niveau. Als een van de velden leeg is of ontbreekt, negeert de Sendcloud plugin ze gewoon en wordt de bestelling zonder de internationale verzendinformatie verstuurd.

Geef Sendcloud bestelinformatie weer op de voorkant (optioneel)

De Sendcloud plugin biedt extra Twig API die in je frontend gebruikt kan worden om:

• Sendcloud status en servicepunt informatie van de bestelling te tonen
• Traceernummer en Traceer URL te tonen
• Retourportaal URL te tonen

Zie het bestand variables/SendcloudVariable.php voor meer informatie.

Geavanceerde instellingen (optioneel)

• Verander de weergavenaam van de plugin in Craft
  Als je de weergavenaam van de plugin in Craft wilt veranderen, kun je dat doen in het Advanced tabblad van de plugin instellingen.

Problemen oplossen

Laatste order fout weergeven

Als een order niet correct naar Sendcloud wordt gepushed, kun je de foutmelding voor de laatste order bekijken om te zien waarom er een fout is opgetreden. In Craft kunt je het tabblad Sendcloud selecteren op de detailpagina van de bestelling. Klik op het pictogram ℹ️ om de volledige berichttekst te zien. 

Problemen bij het doorzenden van bestellingen en het maken van etiketten

Als de Sendcloud plugin er niet in slaagt een order naar Sendcloud door te sturen, of een verzendetiket te maken, kun je de laatste fout met betrekking tot de mislukte order bekijken door naar de order edit page te gaan in de Sendcloud tab in het zijbalk paneel. 

Het komt vaak voor dat een bestelling niet synchroniseert omdat een deel van de gegevens in de bestelling ongeldig is. Je moet er bijvoorbeeld voor zorgen dat adresgegevens van klanten (adresregels/telefoonnummervelden en postcodevelden, enz.) op je afrekenpagina goed worden vastgelegd en gevalideerd. Als een veld tekens bevat die de tekenlimieten overschrijden, of als er niet-herkende symbolen of tekens in voorkomen, treedt een fout op.

In het voorbeeld hierboven zie je dat de bestelling een fout geeft omdat in het veld HS Code te veel tekens zijn ingevoerd. 

Controleer bij internationale zendingen of de velden HS Code en Land van herkomst (indien ingeschakeld) geldige gegevens bevatten, en of je verzendmethoden juist zijn ingesteld. Zorg er bijvoorbeeld voor dat de servicepuntkiezer ingeschakeld is als je de mogelijkheid biedt om pakketten bij een servicepunt te laten afleveren. 

Als je alle problemen met een bestelling hebt opgelost, kun je proberen ze nog een keer handmatig naar Sendcloud door te sturen door op de overeenkomstige knop te klikken op de order details pagina

Fouten loggen

Deze plugin produceert zijn logs in Craft's logsysteem, gemarkeerd met een aparte categorie, 'sendcloud'. Inspecteer het toepassingslogboek om Sendcloud foutmeldingen te vinden. Bovendien kun je Sendcloud logberichten altijd in een apart logdoel extraheren. Om dit te laten werken, kun je je `config/app.php` bestand als volgt instellen:

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

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

Verbindingsproblemen

Als je de Craft plugin instellingen gebruikt om de verbinding met Sendcloud te verbreken, is de integratie nog steeds actief in Sendcloud. Je moet de integratie ook in Sendcloud handmatig ontkoppelen. Je kunt dit doen door in je Sendcloud account naar Instellingen > Integraties te gaan, en op de Ontkoppelenknop te klikken onder je Craft webshop verbinding.

Als je de integratie in Sendcloud ontkoppelt, zal de verbinding ook in Craft nog actief zijn. Je moet de integratie ook handmatig in Craft ontkoppelen. 

Sendcloud bestelling annuleren

Als een bestelling in Sendcloud geannuleerd wordt, wordt de Craft webhook geactiveerd en worden de Sendcloud gegevens ook verwijderd in de aangepaste tabel van de plugin. Hierdoor verschijnt de Push to Sendcloud knop weer op de detailpagina van de bestelling. De annulering van bestellingen in Sendcloud kan iets vertraagd worden, dus zolang de Sendcloud pakketstatus "Cancelation requested" is, wordt de bestelling niet uit de aangepaste tabel verwijderd.

Voor meer hulp kun je de documentatiehandleiding van Craft CMS documentation manual, of een ticket aanmaken via de support sectie van je Sendcloud account.