DB Schenker API ins TMS integrieren: Anleitung

Wer DB Schenker als Carrier in sein TMS einbindet, trifft zuerst auf eine technische Unschärfe: "die DB-Schenker-API" gibt es nicht als eine einzige Schnittstelle. Je nach Sendungsart landen Sie entweder bei der Partner-Services-API von Schenker AB (Schweden, Paketnetz) oder bei den Track-&-Trace- und EDI-Endpunkten für Stückgut und Komplettladung. Dieser Beitrag beschreibt den konkreten Weg, wie Sie die Partner-Services-API (RegisterEdi, TrackAndTraceAdvanced) technisch an Ihr TMS anbinden, von der Sandbox bis zur GoBD-konformen Archivierung der Statusdaten, inklusive des Fehlerfalls, der in der Praxis am häufigsten für Rückfragen sorgt: abgelehnte Tracking-Nummern.

Voraussetzungen, bevor Sie beginnen

Sie brauchen vier Dinge, bevor der erste API-Call sinnvoll ist: einen laufenden Kundenvertrag mit DB Schenker inklusive Kundennummer, eine Freigabe durch das Partner-Services-Team für den konkreten Use Case, ein TMS mit offener REST-Schnittstelle oder eine EDI-Middleware davor, und einen Entwicklerzugang zur Sandbox samt OpenAPI-Spezifikation.

Klären Sie zuerst, welchen Fall Sie überhaupt lösen wollen. Für Paketsendungen im nordischen Netz ist die Version 1 der Schenker AB (Sweden) Partner services API die Nordic-Parcel-Netzwerk-Oberfläche mit neun Operationen, die Service-Point-Lookup, Sendungsregistrierung über POST /Edi/v1/RegisterEdi und /Edi/v1/RegisterReturnEdi, QR-Codes, Sortiercode-Auflösung und Paket-Tracking per Barcode abdeckt. Für klassische Stückgut- oder Komplettladungssendungen über EDIFACT gilt ein anderer Integrationspfad, der nicht Gegenstand dieses Artikels ist. In Version 2 kommt TrackAndTraceAdvanced/v2/GetParcel hinzu, das einen Paket- und Ereignisverlauf aus Ländercode, Referenztyp und Referenz auflöst, allerdings nur als Read-only-Polling ohne Webhook-Operation. Das bedeutet in der Praxis: Sie müssen selbst einen Polling-Rhythmus bauen, DB Schenker schickt Ihnen keine Push-Benachrichtigung.

Die Integration in 9 Schritten

Der folgende Ablauf hat sich in DACH-Projekten als reproduzierbar erwiesen, unabhängig davon, ob Sie ein Standard-TMS oder eine Eigenentwicklung anbinden.

1. Zugang beantragen. Kontaktieren Sie das Partnerteam von DB Schenker und benennen Sie den Use Case explizit: reine Sendungsverfolgung, Versanderstellung oder beides. Die Freigabe entscheidet, welche der vier publizierten Verträge (darunter die Shipment Visibility & Tracking Management-Gruppe mit TrackAndTraceAdvanced2 und TrackAndTraceBoxes) Sie überhaupt erhalten.
2. Sandbox und Spezifikation anfordern. Fragen Sie konkret nach OpenAPI Specification, API Reference, Dokumentation, Sandbox-Zugang und, falls vorhanden, SDK. Ohne die aktuelle OpenAPI-Datei programmieren Sie gegen veraltete Beispiele aus Drittanbieter-Dokumentation, und das rächt sich spätestens bei Feldnamen.
3. Pflichtfelder im TMS mappen. Für Tracking-Abfragen benötigen Sie mindestens drei Felder: Packageid als ID des Pakets im Schenker-System, Customerref als Referenz vom Absender zum Kunden sowie Customerno als ID des Absenders im System. Legen Sie diese drei Felder als Pflichtfelder in Ihrem Auftragsobjekt an, bevor Sie die erste Sendung registrieren.
4. Versanderstellung koppeln. Binden Sie den Auftragsabschluss im TMS-Workflow an einen POST-Call gegen /Edi/v1/RegisterEdi. Für Retouren existiert mit /Edi/v1/RegisterReturnEdi ein eigener Endpunkt, verwechseln Sie beide nicht in der Routing-Logik Ihrer Middleware.
5. Status-Abfrage implementieren. Da es keine Webhooks gibt, müssen Sie GET TrackAndTraceAdvanced/v2/GetParcel per Polling ansteuern. Ein Intervall von 30 bis 60 Minuten pro aktiver Sendung ist für die meisten Mittelstandsszenarien ausreichend und schont gleichzeitig das Rate Limit der Schnittstelle.
6. Service-Point-Lookup einbinden. Wenn Paketshop-Zustellung relevant ist, nutzen Sie GetNearestServicePoint oder GetAllServicePoints aus DeliveryPoint/v2, um im TMS eine Shopauswahl für den Empfänger anzuzeigen, statt nur eine Hausadresse zu erfassen.
7. Eindeutigkeitsprüfung vorschalten. Bauen Sie eine Validierung der Tracking-Nummer direkt vor dem API-Call ein, bevor Sie zum nächsten Schritt kommen. Details zum konkreten Fehlerbild folgen im nächsten Abschnitt.
8. End-to-End-Test in der Sandbox. Erzeugen Sie eine Testsendung, lösen Sie den vollen Zyklus aus (Registrierung, Statuswechsel, Zustellung) und gleichen Sie jeden Statuswert im TMS mit der Ansicht im Schenker-Portal ab, bevor Sie Produktivzugänge beantragen.
9. Produktivschaltung mit Monitoring. Wechseln Sie auf eigene Produktiv-Credentials und richten Sie Monitoring für Fehlerquote, Antwortzeiten und abgelehnte Calls ein. Ohne diesen letzten Schritt bemerken Sie einen stillen Ausfall der Schnittstelle oft erst, wenn der Kunde anruft.

Woran Sie erkennen, dass die Integration funktioniert

Die Integration funktioniert, wenn eine Testsendung im TMS innerhalb Ihres definierten Polling-Zeitfensters denselben Status anzeigt wie im Schenker-Portal, und wenn alle relevanten Statuscodes korrekt gemappt sind. Das klingt banal, ist aber der Punkt, an dem die meisten Projekte unentdeckte Lücken haben.

Bauen Sie dafür eine Referenztabelle, gegen die Sie jeden eingehenden Status im TMS prüfen. Als Mindestmenge gelten laut veröffentlichter Statusliste für DB-Schenker-Tracking: pending für neu angelegte und noch nicht verfolgte Sendungen, transit für Sendungen unterwegs zum Ziel, delivered für erfolgreich zugestellte Sendungen, und exception für Sendungen mit ungewöhnlichem Transportverlauf, etwa durch Retoure, Zollproblem, Verlust oder Beschädigung. Ergänzend tauchen in erweiterten Checkpoint-Daten feingranularere Werte auf, darunter Pending, InfoReceived, InTransit, OutForDelivery, AttemptFail, Delivered, AvailableForPickup, Exception und Expired. Prüfen Sie vor Produktivstart explizit, ob Ihr TMS alle diese Werte kennt oder sie in einen generischen "Sonstiger Status" wirft, denn genau das führt später zu blinden Flecken in der Disposition.

Der häufigste Fehler: abgelehnte oder doppelte Tracking-Nummern

Der mit Abstand häufigste Fehlerfall bei der Anbindung ist die Ablehnung der Tracking-Nummer durch die API, meist aus zwei Gründen gleichzeitig: Doppelung oder falsches Format. Dokumentiert ist das Verhalten eindeutig: doppelte Tracking-Nummern sowie Tracking-Nummern mit ungültigem Format werden nicht akzeptiert, zulässig sind nur Längen zwischen 4 und 100 Zeichen.

Was das für Ihre Implementierung bedeutet: Bauen Sie die Prüfung clientseitig ein, bevor der Call überhaupt rausgeht. Zwei Regeln reichen für die meisten Fälle:

• Längenvalidierung: Tracking-Nummer muss zwischen 4 und 100 Zeichen liegen, sonst lokal abfangen statt den API-Call zu riskieren.
• Eindeutigkeitsprüfung gegen die eigene Auftragshistorie: Bevor Sie registrieren, gegen bereits vergebene Nummern im TMS abgleichen, nicht erst auf die Fehlerantwort der API warten.

Wenn der Call trotzdem abgelehnt wird, lösen Sie das nicht durch einen automatischen Retry mit identischer Nummer, das führt nur zur gleichen Ablehnung. Vergeben Sie stattdessen eine neue, im TMS generierte Referenz und registrieren Sie erneut.

Der zweite Fehlerfall, der in der Praxis für Verwirrung sorgt, ist der Status "notfound" beziehungsweise eine generische Exception-Meldung bei der Statusabfrage. Nach kurzer Zeit nach der Registrierung ist das normal, weil die Sendung im Schenker-System noch nicht gescannt wurde. Problematisch wird es, wenn der Status über mehrere Polling-Zyklen hinweg "notfound" bleibt. Pollen Sie in diesem Fall nicht blind weiter, sondern eskalieren Sie nach einer definierten Anzahl erfolgloser Abfragen (zum Beispiel drei Zyklen über jeweils eine Stunde) automatisch an die Disposition, damit ein Mitarbeiter die Referenz manuell im Schenker-Portal prüft. Das spart Ihnen stunden- oder tagelange stille Fehlzustände im Bestandssystem.

GoBD- und DSGVO-Aspekte bei der Carrier-API-Anbindung

Sendungs- und Statusdaten, die Sie über die API ziehen, sind in vielen Fällen Teil Ihrer Geschäftsbriefe oder Buchungsbelege und unterliegen damit den GoBD-Aufbewahrungsfristen. Seit der Reform durch das Vierte Bürokratieentlastungsgesetz gilt: die Aufbewahrungsfrist beginnt mit Ablauf des Kalenderjahres, in dem die letzte Eintragung gemacht, der Abschluss aufgestellt oder der Handelsbrief empfangen beziehungsweise abgesandt wurde, mit 10 Jahren für Bücher und Abschlüsse, 8 Jahren für Buchungsbelege seit 2025, und 6 Jahren für Geschäftsbriefe. Sendungsbestätigungen und Statusprotokolle aus der DB-Schenker-API fallen in der Regel unter die 6-Jahres-Frist für Geschäftsbriefe, es sei denn, sie dienen gleichzeitig als Buchungsbeleg, etwa bei Frachtkostenabrechnung, dann greift die 8-Jahres-Frist.

Stellen Sie sicher, dass Ihr TMS die abgerufenen Tracking-Events revisionssicher archiviert, nicht nur im Live-System vorhält, wo sie nach einer Zeit überschrieben oder gelöscht werden. Prüfen Sie außerdem, wo die Partner-Services-API technisch gehostet ist, da Schenker AB als schwedische Gesellschaft auftritt und damit EU-Datenschutzrecht greift, aber ein Auftragsverarbeitungsvertrag trotzdem separat zu prüfen ist. Parallel lohnt sich ein Blick auf die eFTI-Verordnung: Die EU-Verordnung 2020/1056 ist am 20. August 2020 in Kraft getreten und gilt seit dem 21. August 2024, mit voller Anwendung für Kontrollbehörden ab 2027. Strukturierte Sendungsdaten, wie Sie sie über die Schenker-API ziehen, werden damit mittelfristig auch für eFTI-Nachweise relevant, ein Thema, das wir in separaten Beiträgen auf diesem Blog vertiefen.

Direkte API-Anbindung vs. Multi-Carrier-Plattform

Eine Einzel-API wie die von DB Schenker selbst zu pflegen, lohnt sich, wenn dieser Carrier Ihr mit Abstand größtes Volumen trägt. Sobald Sie drei, vier oder mehr Carrier gleichzeitig bedienen müssen, wird der Wartungsaufwand pro Einzelanbindung schnell zum limitierenden Faktor, denn jede API hat eigene Feldnamen, eigene Statuslisten und eigene Fehlerfälle wie den oben beschriebenen.

Anbieter wie Cargoson, Sendcloud, nShift oder ShippyPro bündeln vorgefertigte Carrier-Konnektoren inklusive DB Schenker und reduzieren damit den Pflegeaufwand pro Einzel-API, allerdings auf Kosten einer zusätzlichen Abstraktionsschicht, die Sie bei sehr spezifischen Feldanforderungen (wie den oben genannten Packageid/Customerref/Customerno-Kombinationen) separat prüfen müssen.

Fazit und Checkliste

Die Anbindung der DB-Schenker-API ist technisch überschaubar, wenn Sie die drei Kernpunkte sauber abarbeiten: Pflichtfelder korrekt mappen, Eindeutigkeit der Tracking-Nummer vor dem Call prüfen, und Polling statt Webhook als Architekturrealität akzeptieren. Vor dem Produktivstart sollten Sie folgende Punkte abgehakt haben:

• Sandbox-Test mit vollständigem Sendungszyklus durchgeführt und mit dem Schenker-Portal abgeglichen
• Alle relevanten Statuscodes (mindestens pending, transit, delivered, exception, notfound) im TMS korrekt gemappt
• Längen- und Eindeutigkeitsprüfung der Tracking-Nummer clientseitig vor jedem RegisterEdi-Call implementiert
• GoBD-konforme Archivierung der Sendungs- und Statusdaten aktiv, mit korrekter Fristzuordnung (6 oder 8 Jahre)
• Monitoring für Fehlerquote und Antwortzeiten der Produktiv-Credentials eingerichtet

Wenn Sie parallel weitere Carrier anbinden müssen, lesen Sie dazu unseren Beitrag zur EDIFACT-Anbindung von Spediteuren sowie den Vergleich zur DHL-Paket-API-Integration für DACH-Versender, um die beiden gängigsten Integrationsmuster gegenüberzustellen.