M0132 Parcello-Sendungsverfolgung für Gambio
Handbuch
1. Was das Modul für Sie leistet
Parcello ist ein Dienst für Sendungsverfolgung, der Ihren Kunden anzeigt, wo sich ein Paket gerade befindet und wann es voraussichtlich ankommt – über alle Paketdienste hinweg, in einer einheitlichen Darstellung und ohne dass Ihr Kunde die Seite des jeweiligen Zustellers aufsuchen muss.
Damit Parcello das kann, braucht der Dienst zu jedem Paket die Sendungsnummer, den Zusteller und die Empfängerdaten. Genau diese Übergabe nimmt Ihnen das Modul ab: Sie erfassen die Sendungsnummer wie gewohnt in Ihrer Bestellverwaltung, alles Weitere geschieht im Hintergrund.
Im Einzelnen:
- Neue Sendungsnummern werden automatisch an Ihr Parcello-Konto übergeben – wahlweise über die Parcello-Schnittstelle oder über eine WebHook-Adresse.
- Der Paketdienst aus Ihrer Bestellung wird automatisch in die passende Parcello-Kennung übersetzt.
- Auf Wunsch wird nur übertragen, wenn die Bestellung einen bestimmten Bestellstatus erreicht hat – zum Beispiel erst bei „Versendet“.
- Jede Sendung wird genau einmal übergeben. Schlägt eine Übergabe fehl, wird sie beim nächsten Durchgang erneut versucht, statt verloren zu gehen.
- Für Ihren Shop wird eine Seite mit der Parcello-Sendungsverfolgung angelegt, die Sie beliebig verlinken können.
Was das Modul nicht tut: Es verschickt selbst keine Benachrichtigungen an Ihre Kunden. Ob und wie Ihre Kunden über den Sendungsstand informiert werden, legen Sie in Ihrem Parcello-Konto fest.
2. Voraussetzungen
- Ein Parcello-Geschäftskonto (parcello.org). Ohne Zugangsdaten von Parcello kann das Modul nichts übergeben.
- Je nach gewähltem Übertragungsweg entweder Ihren API-Key oder Ihre WebHook-ID aus dem Parcello-Konto.
- Eine eingerichtete zeitgesteuerte Aufgabe in Ihrem Shop (Kapitel 4). Ohne sie bleibt die Übergabe aus.
- Sie erfassen Sendungsnummern in Ihrer Bestellverwaltung. Nur erfasste Sendungsnummern können übergeben werden.
3. Das Setup
3.1 Wo Sie das Setup finden
Das Setup erreichen Sie über das Menü „Xycons-Module“ ▶ „Kundenkonto / Setups“ und dort über den TAB „Parcello Sendungsverfolgung“.
Ganz oben steht der Modulstatus. Solange er auf „Modul inaktiv“ steht, bleibt das Modul vollständig untätig – auch dann, wenn die zeitgesteuerte Aufgabe bereits eingerichtet ist. Das ist der Schalter, mit dem Sie das Modul jederzeit stilllegen können, ohne etwas zu deinstallieren.
3.2 Die Einstellungen im Einzelnen
| Einstellung | Bedeutung |
|---|---|
| Modulstatus | Schaltet das Modul ein oder aus. Steht der Schalter auf „Modul inaktiv“, wird nichts übertragen. |
| Letzter Cronjob | Zeigt an, wann die zeitgesteuerte Aufgabe zuletzt gelaufen ist. Ein Wert „./.“ oder ein altes Datum ist der erste Hinweis darauf, dass die Aufgabe nicht läuft. Das Feld können Sie nicht selbst ändern. |
| Kommunikations-Modus | Der Weg, auf dem die Daten zu Parcello gelangen: „WebHook“ oder „API“. Siehe Abschnitt 3.3. |
| Parcello WebHook-ID | Nur für den Modus „WebHook“. Tragen Sie hier ausschließlich den Schlüssel am Ende Ihrer Webhook-Adresse ein, nicht die vollständige Adresse. |
| Parcello API-Key | Nur für den Modus „API“. Aus Sicherheitsgründen wird der gespeicherte Schlüssel nur verkürzt angezeigt. Lassen Sie die Maskierung stehen, bleibt der hinterlegte Schlüssel unverändert; zum Austauschen tragen Sie den neuen Schlüssel vollständig ein, zum Entfernen leeren Sie das Feld. |
| Reaktion auf Status | Wählen Sie hier einen Bestellstatus, wird eine Sendung erst übergeben, wenn die zugehörige Bestellung diesen Status hat – sinnvollerweise „Versendet“. Wählen Sie „./.“, wird jede erfasste Sendungsnummer sofort beim nächsten Durchgang übergeben, unabhängig vom Bestellstatus. |
| Contentseite Parcello | Die Nummer der Shopseite, auf der die Sendungsverfolgung angezeigt wird. Die Seite wird bei der Installation angelegt und hier automatisch eingetragen. Ändern müssen Sie den Eintrag nur, wenn Sie eine eigene Seite verwenden möchten. |
Empfehlung zum Auslösestatus: Arbeiten Sie mit „Versendet“. Dann erfährt Ihr Kunde erst dann von der Sendung, wenn das Paket tatsächlich unterwegs ist. Ohne Auslösestatus wird bereits die bloße Erfassung einer Sendungsnummer übergeben – auch dann, wenn das Paket noch im Lager steht.
3.3 WebHook oder API – was Sie wählen sollten
Beide Wege übergeben dieselben Daten. Unterschiede gibt es trotzdem:
| API (empfohlen) | WebHook | |
|---|---|---|
| Zugangsdaten | API-Key | WebHook-ID |
| Rückmeldung | Parcello bestätigt jede Sendung einzeln und liefert eine Vorgangsnummer zurück | nur die technische Bestätigung des Aufrufs |
| Übertragung | die Daten stehen im Nachrichtenteil des Aufrufs | die Daten stehen in der Adresszeile des Aufrufs |
| Empfängername | wird mit übergeben | wird nicht übergeben |
Wählen Sie den Modus „API“, wenn Ihr Parcello-Vertrag das zulässt. Er liefert aussagekräftigere Rückmeldungen, überträgt den Namen des Empfängers und stellt die Kundendaten nicht in die Adresszeile des Aufrufs, wo sie in Zwischenstationen protokolliert werden könnten.
Tragen Sie immer die Zugangsdaten ein, die zum gewählten Modus gehören. Steht der Modus auf „API“, aber es ist nur eine WebHook-ID hinterlegt, bleibt die Übertragung vollständig aus. Im Protokoll finden Sie dann den Hinweis, dass keine Zugangsdaten hinterlegt sind.
4. Die zeitgesteuerte Aufgabe einrichten
Die Übergabe an Parcello läuft nicht beim Speichern einer Sendungsnummer, sondern in regelmäßigen Abständen im Hintergrund. Diesen Hintergrundlauf richten Sie im Admin-Bereich unter „Toolbox“ ▶ „Zeitgesteuerte Aufgaben“ ein.
Zweierlei muss dort stimmen:
- Der Gesamtstatus oben auf der Seite muss aktiv sein. Steht er auf „inaktiv“, läuft überhaupt keine Hintergrundaufgabe Ihres Shops.
- Die Aufgabe „Parcello Sendungsverfolgung Cronjob“ muss aktiviert und mit einem Abrufintervall versehen sein.
Als Intervall hat sich stündlich bewährt. Kürzere Abstände bringen wenig, weil auch Parcello die Zustelldaten nicht sekundengenau nachführt; längere Abstände verzögern die Benachrichtigung Ihrer Kunden unnötig.
Ob die Aufgabe wirklich läuft, sehen Sie am schnellsten im Setup: Das Feld „Letzter Cronjob“ muss sich im eingestellten Takt fortschreiben.
5. So arbeiten Sie täglich damit
5.1 Sendungsnummer zur Bestellung erfassen
Am Arbeitsablauf ändert sich für Sie nichts. Sie erfassen die Sendungsnummer wie gewohnt in der Bestellverwaltung unter „Bestellungen“, zusammen mit dem Paketdienst, der das Paket befördert.
Wichtig ist nur eines: Der Paketdienst muss richtig ausgewählt sein. Aus ihm leitet das Modul ab, welcher Zusteller das Paket befördert – und ohne diese Angabe kann Parcello die Sendung nicht verfolgen. Welche Paketdienste erkannt werden, steht in Kapitel 7.
Mehrere Pakete zu einer Bestellung sind kein Problem. Jede Sendungsnummer wird einzeln übergeben und bekommt bei Parcello eine eigene laufende Nummer.
5.2 Was danach geschieht
- Beim nächsten Durchgang der zeitgesteuerten Aufgabe sammelt das Modul alle noch nicht übergebenen Sendungsnummern ein – sofern Sie einen Auslösestatus gewählt haben, nur die zu Bestellungen mit diesem Status.
- Für jede Sendung wird der Paketdienst in die Parcello-Kennung übersetzt und der Vorgang an Parcello übergeben.
- Bestätigt Parcello die Übernahme, wird die Sendung als erledigt vermerkt und nie wieder übergeben.
- Schlägt die Übergabe fehl – etwa weil die Verbindung gestört war –, bleibt die Sendung offen und wird beim nächsten Durchgang erneut versucht. Nach mehreren erfolglosen Versuchen bleibt sie liegen, damit nicht dauerhaft gegen einen falschen Zugangsschlüssel angelaufen wird.
Alles, was bei einem Durchgang geschieht, steht im Protokoll Ihres Shops unter „Toolbox“ ▶ „Protokolle“ in der Datei M0132Cronjob – mit Bestellnummer, Paketdienst, Sendungsnummer und im Fehlerfall dem Grund.
Bei der ersten Einrichtung gilt der bereits vorhandene Bestand an Sendungsnummern als erledigt. Das ist Absicht: Ihre Altbestellungen sollen nicht nachträglich an Parcello übergeben werden, weil Ihre Kunden sonst Benachrichtigungen zu längst zugestellten Paketen erhalten würden. Übertragen wird alles, was ab der Einrichtung neu erfasst wird.
6. Die Sendungsverfolgungsseite in Ihrem Shop
Bei der Installation legt das Modul in Ihrem Shop eine Inhaltsseite „Parcello Tracking“ an. Auf ihr wird die Parcello-Sendungsverfolgung angezeigt – mit erwartetem Zustellzeitpunkt, Zustelladresse, Kartenansicht und dem Verlauf der Sendung.
Die Seite finden und bearbeiten Sie im Admin-Bereich unter „Inhalte“ ▶ „Content Manager“. Titel, Überschrift und Position in der Navigation passen Sie dort an Ihren Shop an. Die Nummer der Seite steht im Setup im Feld „Contentseite Parcello“.
Die Seite benötigt die Vorgangsnummer der Sendung, um etwas anzeigen zu können – sie wird beim Aufruf mitgegeben. Rufen Sie die Seite ohne diese Angabe auf, erscheint der Hinweis, dass die Paket-ID fehlt. Das ist kein Fehler, sondern der erwartete Zustand einer Seite, die ohne Sendungsbezug geöffnet wird.
Üblicherweise gelangt Ihr Kunde über die Benachrichtigung aus Ihrem Parcello-Konto zur Sendungsverfolgung. Die Seite in Ihrem Shop ist dann die Möglichkeit, dieselbe Ansicht im eigenen Shopdesign anzubieten, statt Ihre Kunden auf eine fremde Seite zu schicken.
7. Unterstützte Paketdienste
Aus dem Namen des in der Bestellung gewählten Paketdienstes leitet das Modul ab, welcher Zusteller das Paket befördert. Erkannt werden:
| Paketdienst in Ihrer Bestellung | wird übergeben als |
|---|---|
| DHL (auch DHL Express, DHL Paket) | DHL |
| Deutsche Post | DHL |
| DPD | DPD |
| GLS | GLS |
| Hermes (auch MyHermes, Hermes HSI) | Hermes |
| UPS | UPS |
| FedEx | FedEx |
| TNT | TNT |
| Amazon | Amazon |
| USPS | USPS |
| Österreichische Post (auch Post AT) | Post AT |
Die Erkennung arbeitet über den Namen und verträgt Zusätze und Schreibweisen – „Hermes Paket“, „hermes-versand“ und „MyHermes“ führen alle zum selben Ergebnis.
Haben Sie in Ihrem Shop einen eigenen Paketdienst angelegt, dessen Name keinen dieser Begriffe enthält, kann das Modul ihn nicht zuordnen. Die Sendung wird dann nicht an Parcello übergeben, und im Protokoll steht der Hinweis „Paketdienst nicht unterstützt“ mit dem von Ihnen vergebenen Namen.
Der einfachste Weg bei eigenen Paketdiensten: Nehmen Sie den Namen des tatsächlichen Zustellers in die Bezeichnung mit auf – also „Spedition DHL Express“ statt „Expressversand“. Dann greift die Zuordnung ohne weiteres Zutun.
8. Datenschutz
Damit Parcello eine Sendung verfolgen und Ihren Kunden benachrichtigen kann, werden zu jedem Paket folgende Angaben an Parcello übergeben:
- Ihre Bestellnummer (mit laufender Nummer, wenn mehrere Pakete zur Bestellung gehören)
- die Sendungsnummer und den Paketdienst
- die E-Mail-Adresse des Kunden
- die Lieferanschrift
- im Modus „API“ zusätzlich Vor- und Nachname des Empfängers
Das ist eine Weitergabe personenbezogener Daten an einen Dritten. Nehmen Sie Parcello deshalb in Ihre Datenschutzerklärung auf und schließen Sie mit Parcello eine Vereinbarung zur Auftragsverarbeitung. Welche Angaben dafür nötig sind, erfahren Sie von Parcello.
Der Modus „API“ ist auch aus dieser Sicht die bessere Wahl: Dort stehen die Kundendaten im Nachrichtenteil des Aufrufs. Im Modus „WebHook“ stehen sie in der Adresszeile und können dadurch in Protokollen von Zwischenstationen auftauchen.
9. Texte ändern
Modultexte können Sie – wie bei allen Modulen von uns – über die Shopfunktion „Texte ändern“ im Admin-Bereich an eigene Bedürfnisse anpassen. Das betrifft etwa die Beschriftungen und Hilfetexte im Setup oder den Titel der zeitgesteuerten Aufgabe.
Den Inhalt der Sendungsverfolgungsseite in Ihrem Shop ändern Sie dagegen nicht über „Texte ändern“, sondern direkt im Content Manager (siehe Kapitel 6).
10. Shopupdate und Modulpflege
Vor jedem Shopupdate: Prüfen Sie auf unserer Seite www.xycons.de, ob das Modul für die neue Shopversion freigegeben ist.
Beim Shopupdate installieren Sie bitte immer auch die neuesten Fassungen des Moduls und der Modulumgebung – nicht nur den Shop selbst aktualisieren. Ein älteres Modul passt sich nicht von allein an eine neue Shopversion an; Sie hätten danach ein Modul, das nicht mehr arbeitet, und würden die Ursache an der falschen Stelle suchen.
Nach einem Shopupdate lohnt ein Blick ins Setup auf das Feld „Letzter Cronjob“. Schreibt es sich nicht mehr fort, wurde die zeitgesteuerte Aufgabe beim Update abgeschaltet und muss neu aktiviert werden.
11. Wenn etwas nicht funktioniert
| Beobachtung | Prüfen Sie |
|---|---|
| Es wird gar nichts übertragen | Steht der Modulstatus auf aktiv? Ist die zeitgesteuerte Aufgabe eingerichtet und der Gesamtstatus der Hintergrundaufgaben aktiv? Schreibt sich „Letzter Cronjob“ fort? |
| „Letzter Cronjob“ schreibt sich fort, aber Parcello kennt die Sendungen nicht | Passen Modus und Zugangsdaten zusammen? Für „API“ braucht es den API-Key, für „WebHook“ die WebHook-ID. Das Protokoll nennt den Grund. |
| Nur manche Sendungen kommen an | Haben Sie einen Auslösestatus gewählt? Dann werden nur Bestellungen mit genau diesem Status übergeben. Prüfen Sie außerdem den gewählten Paketdienst (Kapitel 7). |
| Im Protokoll steht „Paketdienst nicht unterstützt“ | Der Name des Paketdienstes enthält keinen erkennbaren Zusteller. Benennen Sie den Paketdienst in Ihrem Shop eindeutiger (Kapitel 7). |
| Im Protokoll steht „FEHLGESCHLAGEN“ | Hinter dem Eintrag steht der Grund, den Parcello gemeldet hat. Die Sendung bleibt offen und wird beim nächsten Durchgang erneut versucht. |
| Die Shopseite meldet, die Paket-ID fehle | Die Seite wurde ohne Sendungsbezug aufgerufen. Das ist der erwartete Zustand (Kapitel 6). |
Das Protokoll finden Sie unter „Toolbox“ ▶ „Protokolle“ in der Datei M0132Cronjob. Dort steht zu jedem Durchgang, welche Sendungen übergeben wurden und was bei den übrigen im Wege stand.
12. Häufige Fragen
Muss ich alte Bestellungen nachträglich übertragen?
Nein, und es ist auch nicht vorgesehen. Bei der Einrichtung gilt der vorhandene Bestand als erledigt, damit Ihre Kunden keine Benachrichtigungen zu längst zugestellten Paketen erhalten.
Kann eine Sendung versehentlich zweimal übergeben werden?
Nein. Jede Sendungsnummer wird nach der bestätigten Übergabe als erledigt vermerkt und beim nächsten Durchgang übersprungen.
Was passiert, wenn ich eine Sendungsnummer nachträglich korrigiere?
Die bereits übergebene Sendung bleibt bei Parcello mit der alten Nummer bestehen. Legen Sie in einem solchen Fall besser eine zusätzliche Sendungsnummer an, statt die bestehende zu überschreiben – die neue wird dann als eigener Vorgang übergeben.
Kann ich den Übertragungsweg später wechseln?
Ja. Tragen Sie die Zugangsdaten des neuen Weges ein und stellen Sie den Modus um. Bereits übergebene Sendungen bleiben unberührt; alles Neue läuft über den neuen Weg.
Wie oft sollte die zeitgesteuerte Aufgabe laufen?
Stündlich. Häufiger bringt keinen Gewinn, seltener verzögert die Benachrichtigung Ihrer Kunden.
Ich habe mehrere Shops. Brauche ich je Shop ein eigenes Parcello-Konto?
Das klären Sie bitte mit Parcello. Das Modul arbeitet mit den Zugangsdaten, die Sie im jeweiligen Shop hinterlegen – technisch können mehrere Shops dieselben oder unterschiedliche Zugangsdaten verwenden.
