Craft Commerce Integration

Zweck: Lerne, wie du deinen Craft Webshop mit Sendcloud verbindest.

Voraussetzungen

• Dieses Plugin erfordert Craft CMS 3.3 oder neuer
• Dieses Plugin erfordert Craft Commerce Version 3.1 oder neuer (Version 3.2 oder höher wird benötigt, um das Seitenpanel der Bestellseite anzuzeigen)
• Die Craft Website muss öffentlich abrufbar sein.
• Damit das Plugin eingerichtet werden kann, sollte das Ändern von Einstellungen in Craft erlaubt sein ("allow admin changes). Daher wird auch ein Nutzer mit Admin-Berechtigung in Craft benötigt. Klicke hier, um auf die Einstellungen zuzugreifen.
• Das Plugin sollte in der Lage dazu sein, benutzerdefinierte Tabellen in deiner Datenbank anzulegen
• Dieses Plugin ist kompatibel mit Composer 2.0

Schritt 1: Installiere das Sendcloud Plugin

Folge diesen Schritten, um das Sendcloud Plugin für Craft CMS zu installieren:

1. Öffne Dein Terminal und navigiere zu Deinem Craft Projekt:
   

   cd /path/to/project

2. Weise den Composer an, das Sendcloud Plugin zu laden:
   

   composer require white-nl/craft-commercesendcloud

3. Installiere das Plugin über die CLI:
   

    ./craft install/plugin commercesendcloud 

Schritt 2: Aktiviere Deine Lizenz

Dieses Plugin erfordert eine kommerzielle Lizenz. Nachdem du das Plugin installiert hast, siehst du eine Hinweismeldung in Craft. Klicke auf diese Meldung, um deine Lizenz in Craft Plugin Store mithilfe deiner Craft ID zu aktivieren.

Schritt 3: grundlegendes Setup 

Öffne nach dem Installieren die Einstellungen in deinem Craft Projekt und schließe die Einrichtung von Sendcloud in Craft ab.

1. Verbinde Craft mit Sendcloud
   Stelle sicher, dass die Sendcloud Server auf Deine Craft Website zugreifen können. Klicke danach auf Register, um die Verbindung mit Sendcloud herzustellen. Du wirst dann zur Sendcloud Website weitergeleitet, um dort die Anbindung zu bestätigen. Nachdem du die Verbindung hergestellt hast, solltest der Verbindungsstatus in Craft als "Active" angezeigt werden. (Unter Umständen musst du die Website einmal neu laden, damit die Änderungen einsehbar sind)
   
   
   
2. Erstelle Versandmethoden
   Als Nächstes musst du Versandmethoden für Sendcloud in Craft erstellen. Die Liste unter dem Verbindungsstatus zeigt dir an, welche Sendcloud Versandmethoden für aktivierte Länder in deinen Craft Commerce Store Settings zur Verfügung stehen. Wenn du einige Versandmethoden nicht siehst, stelle sicher, dass du die entsprechenden Länder in Craft Commerce aktiviert hast.
   
   Um eine Versandmethode zu erstellen, klicke einfach auf den + Button oder lege manuell eine Versandmethode mit dem exakt selben Namen der Sendcloud Versandmethode an. Du musst außerdem Versandregeln für die neu erstellte Versandmethode einrichten, damit diese im Frontend auftauchen.
   
   
   
3. Wähle den Bestellstatus, mit dem Bestellungen an Sendcloud übermittelt werden
   Im Order Sync Tab deiner Sendcloud Plugin Einstellungen, kannst du nun den Bestellstatus auswählen, mit dem Bestellungen automatisch nach Sendcloud übermittelt werden (du kannst hier auch mehr als einen Bestellstatus auswählen)
   
   Bitte beachte, dass die Versandmethode nicht an Sendcloud übermittelt werden kann, bevor das Label erstellt wird. Wenn du die Bestellung an Sendcloud sendest, bevor du ein Versandlabel erstellt, wird in Sendcloud die Standard-Versandmethode verwendet.
   
   Wenn du es bevorzugst, Labels automatisch bei dem Wechsel auf einen bestimmten Bestellstatus zu erstellen zu lassen, kannst du das tun, indem du den entsprechenden Status bei der "Create Labels for Orders" Option auswählst. Bevor ein Labe erstellt wird, stellt das Plugin sicher, dass die Bestellung korrekt an Sendcloud übermittelt wird.
   
   
   
4. Ordne Sendcloud Sendungsstatus zu Craft Bestellstatus zu
   Wenn du automatisch den Bestellstatus Deiner Craft Bestellungen anpassen möchtest, sobald das Sendcloud Paket einen bestimmten Status erhält, kannst du bestimmte Sendcloud Sendungsstatus zu Craft Bestellstatus zuordnen. Die Bestellstatus werden dann automatisch aktualisiert, wenn sich die Sendungsstatus ändern. Wenn Craft einen nicht-zugeordneten Sendungsstatus erhält, wird er ignoriert. Wenn du keine Sendungsstatus zuordnest, werden Deine Bestellstatus nicht aktualisiert.
   
   
   
5. Wähle aus, ob die Integration die Craft-Ordernummer oder die Order-ID verwenden soll.
   Wenn du mit verschiedenen Mappings und anderen Systemen als Sendcloud und Craft arbeitest, kannst du zwischen diesen beiden wählen, was dir mehr Flexibilität bietet.
   
6. Vergiss nicht, Deine Plugin-Einstellungen in Craft zu speichern.
   Klicke auf den roten Save Button, wenn du fertig bist.

Versandlabel herunterladen

Nachdem Du die Einrichtung abgeschlossen hast, werden Bestellungen mit dem gewählten Bestellstatus in Sendcloud importiert und die Versandlabels werden automatisch erstellt. Es gibt nun zwei Wege, wie Du die Bestellungen in Craft herunterladen kannst – mehrere Labels auf einmal oder jedes Label einzeln.

1. Commerce Bestellübersicht
   Benutze die Alukreuzfelder, um eine oder mehrere Bestellungen auszuwählen. Klicke dann auf Print Sendcloud Labels im Optionsmenü. Die resultierende PDF-Datei enthält dann die Labels aller ausgewählten Bestellungen. 
   
   
   
2. Commerce Bestelldetails
   Öffne eine bestimmte Bestellung in Craft. Du findest die Sendcloud Informationen dann in der rechten Seitenleiste (verfügbar ab Craft Commerce Version 3.2). Klicke auf den Print Label Button. Die resultierende PDF-Datei enthält das Label der gewählten Bestellung.
   
   Wenn Du versuchst ein Label für eine Bestellung zu drucken, für welche noch kein Label in Sendcloud erstellt wurde, wird automatisch ein Label für Dich erstellst.
   

Bestellungen manuell übermitteln

Es ist ebenfalls möglich, eine Bestellung manuell an Sendcloud zu übermitteln. Das kann nützlich sein, wenn die Bestellung einen anderen Bestellstatus hat oder falls die Bestellung nicht direkt übermittelt worden ist. Es gibt zwei Wege, wie Du eine Bestellung manuell an Sendcloud übermitteln kannst – Mehrere Bestellungen auf einmal oder jede Bestellung einzeln.

1. Commerce Bestellübersicht
   Benutze die Alukreuzfelder, um eine oder mehrere Bestellungen auszuwählen. Klicke dann auf Push to Sendcloud im Optionsmenü.
   
   Wenn Du mehrere Bestellungen auf einmal übermittelst, kann es passieren, dass der Webserver die Anfrage blockiert, was dann einen Timeout-Fehler verursacht. Wir empfehlen daher, nicht mehr als 50 Bestellungen auf einmal zu übermitteln. Stattdessen wird empfohlen, die automatische Übermittlung zu verwenden (siehe vorherige Schritte)
   
   
   
2. Commerce Bestelldetails
   Wenn die Bestellung noch nicht an Sendcloud übermittelt wurde, siehst Du den Push to Sendcloud Button. (Verfügbar ab Craft Commerce Version 3.2).
   
   
   Nachdem Du den Button anklickst, erhältst Du weitere Informationen und einen Button zum Herunterladen des Labels.
   
   Bitte beachte, dass nicht automatisch ein Label erstellt wird, wenn Du die Bestellung manuell an Sendcloud übermittelst. Ein Label wird erst dann erstellt, wenn Du versuchst, das Label zu drucken. Die Versandmethode und Adresse werden nicht an Sendcloud übermittelt, außer Du erstellt ein Versandlabel, daher taucht Deine Bestellung stattdessen mit der Standard-Versandmethode auf.

Service Point Versand (Optional)

Dieses Plugin unterstützt den Versand an Service Points (Paketshops). Das Einrichten ist etwas komplexer und erfordert eine individuelle Entwicklung, um den Service Point Checker in dem Checkout Deines Webshops zu implementieren. Da jedes Craft Projekt einen anderen Front-End Stack, Template Code und Ansatz haben kann, erhält dieses Plugin nur ein Beispiel für den Sendcloud Service Point Pickup für die standardmäßigen Craft Commerce Demo Shop Front-End Templates.

Nachdem Du die Installation abgeschlossen hast, findest Du ein Drop-In-Ersatz für die Versandvorlagen von Craft Commerce in dem `example-templates` Ordner. Kopiere diesen Ordner einfach in Deinen `templates` Ordner. Danach kannst Du diesen Schritten folgen:

1. Aktiviere Service Points in Sendcloud 
   Um Service Points (bzw. den Service Point Versand) in Craft einzurichten, stelle sicher, dass du Service Points in Sendcloud aktiviert hast und die Versanddienstleister, die im Service Point Picker angezeigt werden sollen, ausgewählt hast. 
   • Um Service Points in Sendcloud zu aktivieren, melde Dich in Deinem Konto an und navigiere zu Einstellungen > Integrationen.
   • Finde in der Liste der verbundenen Webshops Deine Craft Commerce Integration und klicke auf Bearbeiten.
   • Setze als Nächstes den Haken bei Service Points und wähle die Versanddienstleister aus, die Du verwenden möchtest.
   • Klicke auf Speichern, wenn Du fertig bist. 
     
     
     
     
2. Erstelle eine Service Point Versandmethode in Craft
   Nachdem Du die Service Points in Sendcloud aktiviert hast, zeigt die Plugin-Einstellungs-Seite den Status für Service Points als aktiviert (grün) an und die Liste der verfügbaren Versandmethoden wird angezeigt.
   Um eine Craft Versandmethode zu erstellen, klicke auf das Plus (+). Du kannst auch manuell Versandmethoden mit dem exakt selben Namen wie in Sendcloud erstellen. Du musst ebenfalls Versandregeln für die neu angelegten Versandmethoden erstellen, damit diese im Front-End auftauchen.
   
   
   
3. Integriere den Service Point Picker in Dein Front-End.
   Wenn Du die Standard Craft Commerce Demo Shop Vorlagen verwendest, kannst Du einfach die Vorlagen aus dem `example-templates` Ordner des Plugins in den `templates` Deiner Website kopieren.
   
   

Unsere Beispielvorlage macht Folgendes:

• Sie zeigt den Service Point Auswählen Button für Versandmethoden mit Service Point Zustellung an.
• Wenn Du auf den Button klickst, öffnet sich das Sendcloud Service Point Auswahl iframe. Service Points werden hier nach Versanddienstleister, der Versandmethode und Lieferadresse gefiltert.
• Nachdem Du einen Service Point ausgewählt hast, wird dieser im Front-End angezeigt und im Hintergrund wird eine AJAX Anfrage an das Sendcloud Plugin mit der gewählten Information gesendet.

Wenn Du die Bestellung übermittelst (oder sie automatisch übermittelt wird), wird dann der gewählte Service Point verwendet. Einige Versandmethoden erfordern eine gültige Telefonnummer. Die Sendcloud API lehnt Bestellungen ab, die ungültige Informationen enthält, stelle daher sicher, dass Du Deine Bestellungen vorab gut validieren lässt.

Bitte beachte, dass die Beispiele aus dem `example-templates` Ordner nur zur Veranschaulichung dienen. Es ist Deine Verantwortung, ein Front-End mit einer funktionieren Validierung für Deinen Shop zu entwickeln.

Versand außerhalb Europas (optional)

Dieses Plugin unterstützt die Erstellung von Zolldokumenten über Sendcloud für Sendungen außerhalb der EU. Nutze die Felder-Zuordnung in den Plugin-Einstellungen, um Deine Produktfelder korrekt zuzuordnen, damit die Zolldokumente erstellt werden können.

Stelle sicher, dass Du die benutzerdefinierten Felder mit dem HS Code und dem Ursprungsland für Deine Produkte und Varianten in Craft eingerichtet hast. Als nächstes, kannst Du die entsprechenden Felder in den Sendcloud Plugin Einstellungen auswählen:

Bitte stelle sicher, dass das Feld für das Ursprungsland nur ISO2 Ländercodes enthält (zum Beispiel „DE“) und das HS Code Plugin einen gültigen HS Code für das Produkt enthält (zum Beispiel „6403919600“).

Wenn die Bestellung dann an Sendcloud übermittelt wird, sucht das Plugin zunächst nach dem Feld auf der Variantenebene und danach auf Produktebene. Wenn eines der Felder leer ist oder fehlt, ignoriert das Sendcloud Plugin diese und übermittelt die Bestellung ohne Informationen für den internationalen Versand.

Zeige Sendcloud Bestellinformationen im Front-End an (optional)

Das Sendcloud Plugin biete zusätzlich die Twig API an, die für folgende Funktionen verwendet werden kann:

• Zeige den Sendcloud Bestellstatus und Informationen zum Service Point an
• Zeige die Trackingnummer und die URL zur Trackingseite an
• Zeige die URL zum Retourenportal an

In der variables/SendcloudVariable.php Datei findest Du weitere Informationen hierzu.

Fortgeschrittene Einstellungen (optional)

• Ändere den Anzeigenamen des Plugins in Craft
  Falls Du den Anzeigenamen des Plugin in Craft ändern möchtest, kannst Du das in dem Advanced Tab bei den Plugin-Einstellungen erledigen. 

Problemlösung

Fehler der letzten Bestellung anzeigen 

Wenn eine Bestellung nicht korrekt an Sendcloud übermittelt wird, kannst Du die Fehlermeldung der letzten Bestellung einsehen, um zu sehen, warum der Fehler aufgetreten ist. In Craft kannst Du den Sendcloud Tab auf der Bestelldetails Seite auswählen. Klicke dort auf das ℹ️ Icon, um die vollständige Fehlermeldung zu sehen.

Probleme beim Übermitteln von Bestellungen und dem Erstellen von Labels

Wenn das Sendcloud Plugin eine Bestellung nicht an erfolgreich übermitteln kann oder beim Erstellen eines Versandlabels Probleme auftreten, kannst Du die dazugehörige Fehlermeldung in der Bestellbearbeitungs-Seite in dem Sendcloud Tab in der Seitenleiste einsehen.

Oft passiert es, dass eine Bestellung nicht synchronisiert werden kann, da einige Informationen der Bestellung ungültig sind. Beispielsweise musst Du sicherstellen, dass die Daten der Lieferadresse (Adresse, Telefonnummer, Postleitzahl, etc.) korrekt übertragen und validiert werden. Wenn ein Feld mehr Zeichen als zugelassen enthält, oder dort ein unbekanntes Symbol oder Zeichen auftaucht, tritt ein Fehler auf. 

Im obenstehenden Beispiel kannst Du sehen, dass die Bestellung einen Fehler aufweist, da der HS Code zu viele Zeichen enthält.

Bei internationalen Sendungen solltest Du sicherstellen, dass die Felder für HS Code und Ursprungsland (falls aktiviert) korrekte Informationen enthalten und dass Du Deine Versandmethoden korrekt eingerichtet hast. Wenn Du beispielsweise die Lieferung an Service Points anbietest, sollte der Service Point Picker aktiviert und korrekt eingerichtet werden.

Wenn Du die Probleme einer Bestellung korrigiert hast, kannst Du sie manuell erneut an Sendcloud übermitteln, indem Du den entsprechenden Button in den Bestelldetails anklickst.

Error logging

Dieses Plugin trägt Logs in Crafts logging System ein und werden dort mit der separaten Kategorie ‘sendcloud’ markiert. Sieh Dir das Log genauer an, um die Sendcloudfehlermeldungen zu finden. Zusätzlich kannst Du die Sendcloud Fehlermeldungen in ein seperates Log-Ziel extrahieren. Um das zu erreichen, musst Du Deine `config/app.php` Datei wie folgt konfigurieren:

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' => [],
                        ]);
                    }
                ],
            ],
        ]
    ],
];

Verbindungsprobleme

Wenn Du die Craft Plugin Einstellungen verwendest, um Sendcloud zu trennen, wird die Integration immer noch in Sendcloud aktiv sein. Du musst die Integration daher auch manuell in Sendcloud trennen. Navigiere dazu einfach in Sendcloud zu Einstellungen > Integrationen und klicke auf den Trennen Button bei Deiner Craft Webshop Anbindung.

Wenn Du die Integration nur in Sendcloud trennst, wird sie weiterhin in Craft aktiv sein. Trenne die Integration also auch dort.

Stornierte Bestellungen in Sendcloud

Wenn Du eine Bestellung in Sendcloud stornierst, wird der Craft Webhook aktiviert und die Sendcloud Daten werden auch in der benutzerdefinierten Tabelle vom Plugin gelöscht. Dadurch wird der Push to Sendcloud Button auf der Bestelldetails-Seite erneut angezeigt. Die Stornierung von Bestellungen in Sendcloud kann leicht verzögert sein, solange der Paketstatus auf „Cancellation requestes“ bzw. „Stornierung angefragt“ steht, wird die Bestellung nicht von der benutzerdefinierten Tabelle gelöscht.

Für weitere Informationen kannst Du einen Blick in die Craft CMS documentation manual werden oder Du erstellst ein Ticket in dem Support Abschnitt Deines Sendcloud Kontos.