Carrier-API in die eigene Website integrieren: die vier wichtigen Aufrufe und die Fehler, die sich wiederholen

Wir haben Konnektoren für MRW, SEUR, Correos Express, DHL, GLS, UPS und CTT für Odoo veröffentlicht und Zusteller in Websites integriert, hinter denen kein Odoo läuft, etwa eclipseando.com. Die APIs unterscheiden sich in Namen und Format, die Arbeit bleibt aber immer dieselbe: vier Aufrufe, drei oder vier Fehler, die sich wiederholen, und eine Architekturentscheidung, die man besser vor der ersten Codezeile trifft. Dieser Artikel ist die Version für eine eigene Website; wenn Ihr Shop mit Odoo läuft, ist das meiste bereits in den Zusteller-Konnektoren gelöst.

Vor dem Programmieren: Anmeldung und Testumgebung

Kein Zusteller gibt Ihnen API-Zugang, nur weil Sie auf der Website ein Formular ausfüllen. Es braucht einen Transportvertrag mit einem Vertriebsmitarbeiter, und daraus ergeben sich die Zugangsdaten: ein Kunden- oder Teilnehmercode, ein Benutzername und ein Passwort oder Schlüssel, manchmal auch ein Franchise- oder Agenturcode. Fragen Sie vom ersten Tag an danach und verlangen Sie auch die Testumgebung, die nicht jeder hat und die sich nicht bei jedem wie die Produktion verhält. Manche APIs sind weiterhin SOAP mit XML (bei mehreren spanischen Zustellern historisch der Fall), andere sind REST mit JSON. Was zu tun ist, ändert sich dadurch nicht, nur der Aufwand, die Dokumentation zu lesen.

Die vier Aufrufe

Sendung anlegen: Die halbe Arbeit besteht darin, die Adresse zu bereinigen

Beim Anlegen häufen sich die Ablehnungen. Jeder Zusteller hat seine eigene Vorstellung von einer gültigen Adresse: maximale Länge der Straße, Postleitzahl mit genau fünf Ziffern, Provinz als Code statt als Text, Telefonnummer Pflicht und ohne Vorwahl, und bei mehreren nichts außerhalb von ASCII im Namen. Was funktioniert, ist die Normalisierung vor dem Aufruf: Straße und Hausnummer trennen, Felder auf das Maximum der jeweiligen API kürzen, Akzente ersetzen, wenn die API sie nicht akzeptiert, und prüfen, ob die Postleitzahl für dieses Land existiert. Und immer die vollständige Anfrage und Antwort, als XML oder JSON, zusammen mit der Bestellung speichern. Wenn ein Paket drei Wochen später verloren geht, ist dieses Protokoll der einzige Beweis dafür, was gesendet wurde.

Tracking: Abfragen mit Verstand, oder Webhook, falls vorhanden

Nur wenige Zusteller benachrichtigen per Webhook; bei den meisten muss man nachfragen. Richtig ist eine geplante Aktion, die nur offene Sendungen abfragt, in einem vernünftigen Intervall (stündlich genügt meist, am Zustelltag häufiger), die stoppt, sobald der Status final ist, und die die Limits der API einhält. Die Ereigniscodes werden in eine kleine Menge eigener Status übersetzt: angenommen, unterwegs, in Zustellung, zugestellt, Zwischenfall, zurückgesendet. Fünf oder sechs, nicht vierzig. Und jede Statusänderung löst die Benachrichtigung an den Kunden aus, wofür das alles gemacht wird.

Wenn Sie keine API haben, weil Ihr Lieferant versendet

Das kommt häufiger vor, als man denkt: Sie verkaufen, aber das Paket bereitet ein Lieferant mit eigenem Transportvertrag vor und versendet es. Sie haben keine Zugangsdaten, können die Sendung weder anlegen noch abfragen. Was Sie fast immer haben, sind die E-Mails, die der Zusteller bei jeder Bewegung an die Kontaktadresse schickt. Bei eclipseando.com haben wir es mit GLS so gelöst: Eine Aufgabe liest das Postfach alle zehn Minuten, erkennt die vier Arten von E-Mails (unterwegs, in Zustellung, an einer Abholstation mit Frist, Empfänger abwesend), entnimmt die Sendungsnummer und die zugehörige Bestellung und macht aus jeder einen Status und eine Benachrichtigung an den Käufer. Die letzten beiden sind die dringenden: Ein Paket an einer Abholstation geht an den Absender zurück, wenn es niemand abholt, und ein Kunde, der nicht weiß, dass es dort liegt, holt es nicht ab.

Die Fehler, die wir in der Produktion sehen

• Nur gegen die Sandbox testen. Mehrere Zusteller haben eine Testumgebung, die akzeptiert, was die Produktion ablehnt. Der Test, der zählt, ist eine echte Sendung an Ihr eigenes Büro.
• Die Sendung beim Bestätigen der Bestellung auf der Website anlegen. Sie wird angelegt, wenn das Paket vorbereitet wird. Wird sie früher angelegt, ist jede Stornierung eine Geistersendung, die manchmal berechnet wird.
• Anfrage und Antwort nicht speichern. Ohne das vollständige XML oder JSON bei der Bestellung steht bei einer Reklamation Ihr Wort gegen das des Zustellers.
• Eine einzige Sendungsnummer pro Bestellung. Das funktioniert bis zur ersten Bestellung mit zwei Packstücken oder zwei Lieferanten. Das Tracking wird pro Sendung modelliert.
• Alte Zertifikate und Verschlüsselung. Einige APIs laufen noch mit TLS und Verschlüsselungen, die moderne Bibliotheken standardmäßig ablehnen. Das fällt am ersten Tag auf, nicht am Tag der Inbetriebnahme.

Mit Odoo im Hintergrund wird fast nichts davon programmiert

Wenn der Shop mit Odoo läuft, sind die vier Aufrufe bereits in den Konnektoren geschrieben, die wir im App Store veröffentlichen, getestet auf Odoo 19, 18 und 17 auf echtem Odoo.sh: Das Label entsteht beim Validieren des Lieferscheins, das Tracking wird per Cron abgefragt und in den Lieferschein geschrieben, das Manifest wird direkt in Odoo abgeschlossen, und die Benachrichtigung an den Kunden geht per E-Mail oder SMS mit der Vorlage Ihrer Wahl hinaus. Die Website muss nur den Status des Lieferscheins lesen. Deshalb lautet die Antwort, wenn uns jemand bittet, einen Zusteller in eine Website zu integrieren, und bereits Odoo hat, meist: die Website mit dem ERP verbinden, statt die Integration neu zu schreiben.

Häufige Fragen

Nützliche Links innerhalb von FlexigoTech

Was wir dazu anbieten