Lobster CEP-Connector

Version 1.0.0

Der CEP-Connector bietet eine einheitliche Integration zur Buchung von Sendungen, zum Abruf von Labels und zur Sendungsverfolgung über verschiedene Kurier-, Express- und Paketdienstleister (KEP). Individuelle Carrier-Endpunkte oder Payload-Formate müssen nicht separat angebunden werden. Es genügt, das einheitliche Datenformat LobsterCEP zu integrieren – den Rest übernimmt der CEP Connector.

Zentrale Anwendungsfälle

• Sendungen buchen und Versandlabels in den Formaten PDF, ZPL oder PNG erzeugen

• Nahezu in Echtzeit Tracking-Updates während des gesamten Zustellprozesses abrufen

• Zustellnachweise (Proof-of-Delivery, POD) nach erfolgter Zustellung abrufen

Voraussetzungen

Stellen Sie vor Beginn sicher, dass folgende Anforderungen erfüllt sind:

• Unterstützte Version der Lobster Data Platform (mindestens 25.1)

• CEP-API-Zugang und Zugangsdaten für jeden Carrier (Benutzername/Passwort oder Client-ID/Client-Secret)

Funktionsweise

Der CEP-Connector enthält ein Paket von Profilen zweier unterschiedlicher Typen:

• CEP_CONNECTOR Profile sind feste Implementierungen, die die gesamte Funktionalität des CEP Connectors enthalten. Sie beinhalten die Mappings zwischen den API-Formaten der jeweiligen KEP-Dienstleister und dem abstrahierten, einheitlichen Format LobsterCEP.    

•  WARNUNG  Diese Profile dürfen nicht verändert werden, um Funktionalität und Wartbarkeit des Connectors sicherzustellen.

• TEMPLATE_LobsterCEP Profile sind vordefinierte Vorlagen, um die Connector-Profile einfach über das Format LobsterCEP zu integrieren.

Sendungsbuchung

Der Buchungsprozess bucht Carrier-Sendungen über deren öffentliche APIs. Der CEP Connector ruft ein Mapper-Profil auf, um den LobsterCEP-Transportauftrag in das vom Carrier geforderte Format zu konvertieren. Anschließend sendet er die Daten an das KEP-System, das eine synchrone Antwort zurückliefert. Der Connector wandelt diese Antwort mithilfe eines spezifischen CEP-Mapper-Profils zurück in die LobsterCEP-Struktur. Schließlich leitet er die verarbeiteten Daten als Transportauftragsbestätigung an Ihr Kundenprofil weiter – entweder als Bestätigung inklusive Versandlabel oder als Fehlerantwort mit spezifischem Feedback des Carrier-Endpunkts.

Sendungsverfolgung

Der Tracking-Prozess ruft Sendungsstatus-Updates von den KEP-Dienstleistern über deren öffentliche APIs ab. Er liest Konfigurationsdateien der Lobster Integration unter ./conf/Connectors/CEP/Tracking, die Tracking-Details im CSV-Format enthalten. Die Polling-Logik ruft nur neue Tracking-Events ab und verhindert so redundante Datenabfragen. Wenn Sie den Buchungsprozess nutzen, werden die Tracking-Konfigurationsdateien automatisch erstellt und aktualisiert.

Sie können diese Dateien auch manuell befüllen, wenn Sendungen anderweitig gebucht wurden. Die Tracking-Dateien sind wie folgt aufgebaut:

carrierTrackingNumber;customerShipmentId;latestEventTimestamp;shipmentCreationTimestamp

Das Feld latestEventTimestamp wird vom Connector automatisch befüllt und sollte beim erstmaligen Einrichten leer gelassen werden.

Beispiel: Um die Sendung test123 mit der DHL-Sendungsnummer 1091847043 (erstellt am 08.09.2025 um 10:00:00 Uhr) automatisch zu verfolgen, hängen Sie folgende Zeile an ./conf/Connectors/CEP/Tracking/List_ShipmentTrackingNumbers_DHL.csv an:

1091847043;test123;;1757318400000

Für FedEx, UPS oder PostNL verwenden Sie statt DHL.csv entsprechend die Datei FEDEX.csv, UPS.csv oder PostNL.csv.

Installation

Für Kunden der Lobster Data Platform stehen vorkonfigurierte Dataflows zur Verfügung, die die Integration mit Ihren KEP-Dienstleistern vereinfachen. Diese Dataflows enthalten:

• CEP Connector Profile zur Anbindung verschiedener KEP-APIs

• Template-Profile für Ihre Mappings von oder in die LobsterCEP-Sendungsstruktur

• Partnerkanäle für Ihre KEP-Dienstleister

• Systemkonstanten zur Anpassung Ihres CEP Connectors

1. Klicken Sie Start → Mit Vorlage starten.

2. Klicken Sie in der Kachel des Templates Peppol Access Point API auf Installieren.

   Sie wechseln nun automatisch zu Integration → DataFlow → Designer.

   Der Dialog Paket importieren wird geladen. Er ist in vier Reiter gegliedert:

   • Inhaltsverzeichnis — Listet alle enthaltenen Profile und DataFlows mit Typ, Name, Status und Version auf.

   • Konstanten — Zeigt im Paket enthaltene Konstanten an (in diesem Paket: 0).

   • Partner/Kanäle — Zeigt die im Paket enthaltenen Partner und Partnerkanäle mit Importoptionen an.

   • Information — Enthält ergänzende Informationen zum Paket.

Inhaltsverzeichnis

Der Tab Inhaltsverzeichnis zeigt alle im Paket enthaltenen Komponenten:

Das Paket enthält folgende Komponenten:

Hinweis

Alle Profile in diesem Paket haben den Status Aktiv und sind nach dem Import sofort einsatzbereit. Die Badges an den Tabs zeigen an: Inhaltsverzeichnis (17 Einträge), Konstanten (5), Partner/Kanäle (1/3).

Gruppenauswahl

Wählen Sie die passenden lokalen Gruppen für die Profile aus oder erstellen Sie neue, indem Sie auf jedes Ordnersymbol in der Spalte Gruppe (Lokal) klicken.

Konstanten

Auf diesem Tab finden Sie die vordefinierten Konstanten zur Anpassung Ihres CEP-Connectors.

Falls diese Konstanten bereits mit anderen oder denselben Werten vorhanden sind, werden sie standardmäßig nicht überschrieben.

Partner/Kanäle

Der Tab Partner/Kanäle zeigt die im Paket enthaltenen Partner und Partnerkanäle an. In diesem Paket ist ein Partner mit drei Partnerkanälen enthalten. Sie können auswählen, ob Sie die vorkonfigurierten Partnerkanäle importieren oder überschreiben möchten. Wenn die Option zum Überschreiben nicht aktiviert ist, wird der Partnerkanal durch ein Update nicht verändert, sodass Sie den Connector bedenkenlos aktualisieren können.

Folgende Optionen stehen zur Verfügung:

• Partner importieren — Importiert den im Paket enthaltenen Partner (CEP Partner) mit dem zugehörigen HTTPS-Kanal. Diese Option ist standardmäßig aktiviert.

• Partner/Kanäle überschreiben — Überschreibt bereits vorhandene Partner und Kanäle mit gleichem Namen. Aktivieren Sie diese Option nur, wenn Sie eine bestehende Konfiguration bewusst ersetzen möchten.

Wichtig

Wenn der Partner CEP Connector bereits in Ihrer Umgebung existiert und Sie individuelle Anpassungen vorgenommen haben, lassen Sie die Option Partner/Kanäle überschreiben deaktiviert, um Ihre Konfiguration nicht zu überschreiben.

Import abschließen

Prüfen Sie die angezeigten Komponenten in allen Tabs und klicken Sie auf Importieren, und bestätigen Sie, um den Import zu starten.

2. Zugangsdaten konfigurieren

Erforderliche Zugangsdaten pro Carrier

Partnerkanal-Konfiguration

Navigieren Sie zu Administration → Partner → Partners/Channels → CEP Connector.

DHL_Express_HTTPS

• Tragen Sie den DHL-Express-Benutzernamen als „Own ID“ ein

• Tragen Sie das DHL-Express-Passwort als „Own Password“ ein

FedEx_HTTPS

1. Klicken Sie auf „Configure OAuth 2.0…“

2. Tragen Sie Ihre Client-ID und Ihr Client-Secret ein

3. Wählen Sie als Grant Type „Client Credentials“

4. Tragen Sie die „Endpoint URL“ ein:    

   • Test: https://apis-sandbox.fedex.com/oauth/token

   • Prod: https://apis.fedex.com/oauth/token

5. Klicken Sie auf „Fetch Access Token“

6. Tragen Sie die „OAuth2 Refresh URL“ ein:    

   • Test: https://apis-sandbox.fedex.com/oauth/token?grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>

   • Prod: https://apis.fedex.com/oauth/token?grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>

UPS_HTTPS

1. Klicken Sie auf „Configure OAuth 2.0…“

2. Tragen Sie Ihre Client ID und Ihr Client Secret ein

3. Wählen Sie „Send 'client credentials' in header“

4. Wählen Sie als Grant Type „Authorization Code“

5. Tragen Sie die „Endpoint URL“ ein:    

   • Test: https://wwwcie.ups.com/security/v1/oauth/token

   • Prod: https://onlinetools.ups.com/security/v1/oauth/token

6. Tragen Sie Ihre „Redirect URL“ ein (die interne Adresse Ihrer Lobster Data Platform):
       https://<your-server>:<your-port>/dw/oauth2/<your-Application-ID>
       Die Application-ID finden Sie in Ihren OAuth2.0-Einstellungen; sie beginnt mit _data.
       Diese URL muss auch in den Anwendungseinstellungen im UPS Developer Portal registriert werden (erforderlich für Test und Prod in derselben Anwendung).

7. Tragen Sie die „OAuth URL“ ein:    

   • Test: https://wwwcie.ups.com/security/v1/oauth/authorize

   • Prod: https://onlinetools.ups.com/security/v1/oauth/authorize

8. Klicken Sie auf „Fetch Access Token“. Sie werden zu UPS weitergeleitet, um Ihre Developer-Account-Zugangsdaten einzugeben. Bei erfolgreicher Weiterleitung wird eine leere Seite mit ok angezeigt. Nach erneutem Öffnen des Kanals sollten die Token SYS_HTTP_OAUTH2 und SYS_HTTP_OAUTH2_REFRESH unter „Additional IDs“ sichtbar sein.

9. Tragen Sie die „OAuth2 Refresh URL“ ein:    

   • Test: https://wwwcie.ups.com/security/v1/oauth/refresh?grant_type=refresh_token&refresh_token=<refreshToken>&client_id=<clientId>&client_secret=<clientSecret>&useCredentialsInHeader

   • Prod: https://onlinetools.ups.com/security/v1/oauth/refresh?grant_type=refresh_token&refresh_token=<refreshToken>&client_id=<clientId>&client_secret=<clientSecret>&useCredentialsInHeader

PostNL_HTTPS

• Fügen Sie Ihren API-Key als „SYS_HTTP_apikey“ im Reiter „Additional IDs“ hinzu.

3. Profil-Templates für benutzerdefinierte Mappings verwenden

Warnung

Änderungen an CEP_CONNECTOR Profilen können Funktionalität und Wartbarkeit beeinträchtigen.

Konfigurationskonstanten

Die folgenden Systemkonstanten können angepasst werden, um den Connector zu konfigurieren. (M) = obligatorisch, (D) = abhängig, (O) = optional.

Eingabe-Datenstruktur: Sendungsbuchung

Übergeben Sie die folgende LobsterCEP-Datenstruktur an das Profil CEP_CONNECTOR_ShipmentBooking. Der Connector mappt sie in das Carrier-Format, ruft intern die Carrier-API auf und leitet das Ergebnis an Ihr Bestätigungsprofil weiter.

Ausgabe-Datenstruktur

Beispiel Ausgabe-Datenstruktur: Bestätigte Buchung

{
  "LobsterCEP": {
    "header": {
      "carrierId": "DHL_EXPRESS",
      "processingStatus": {
        "code": "CONFIRMED",
        "realizationDateTime": "2025-08-13T09:33:59+02:00"
      }
    },
    "shipment": {
      "shipmentId": "ABC123456789",
      "carrierReference": "987654321",
      "estimatedDeliveryDate": "2025-08-18T23:59:00Z",
      "documents": [
        {
          "type": "LABEL",
          "name": "LABEL_987654321.pdf",
          "format": "PDF",
          "content": "<base64-encoded content>"
        }
      ],
      "trackingUrl": "https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking"
    }
  }
}

Beispiel Ausgabe-Datenstruktur: Fehler

{
  "LobsterCEP": {
    "header": {
      "carrierId": "DHL_EXPRESS",
      "processingStatus": {
        "code": "ERROR",
        "reason": "1001: The requested product(s) (P) not available based on your search criteria.",
        "realizationDateTime": "2025-08-13T09:33:59+02:00"
      }
    },
    "shipment": {
      "shipmentId": "ABC123456789"
    }
  }
}

Ausgabe-Datenstruktur: Sendungsverfolgung

Das Profil CEP_CONNECTOR_Tracking pollt den Carrier automatisch nach neuen Events und liefert die folgende LobsterCEP‑Struktur an Ihr Tracking-Zielprofil. Ein Aufruf Ihrerseits ist nicht erforderlich. Konfigurieren Sie die Tracking-CSV-Dateien wie im Abschnitt Sendungsverfolgung beschrieben – das Polling übernimmt der Connector automatisch.

Beispiel Ausgabe-Datenstruktur: Tracking

{
  "LobsterCEP": {
    "header": { "carrierId": "DHL_EXPRESS" },
    "shipment": [
      {
        "shipmentId": "ABC123456789",
        "carrierReference": "987654321",
        "estimatedDeliveryDate": "2025-08-18T23:59:00Z",
        "trackingEvents": [
          {
            "owner": "DHL_EXPRESS",
            "eventDateTime": "2025-09-01T01:43:03Z",
            "eventLocation": "CPH (Copenhagen-DK)",
            "statusDetails": [{ "code": "OK", "statusDescription": "Delivered" }]
          }
        ],
        "documents": [
          {
            "type": "POD",
            "name": "POD_987654321.pdf",
            "format": "PDF",
            "content": "<base64-encoded content>"
          }
        ],
        "trackingUrl": "https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking"
      }
    ]
  }
}

LobsterCEP-Datenformat

Das LobsterCEP-Objekt ist das einheitliche Datenformat für alle Operationen des CEP Connectors. Nachfolgend finden Sie eine vollständige Feldreferenz.

Header

Enthält die Carrier-Auswahl, den Aktionstyp und die Dokumentanforderungen.

Shipment

Enthält alle Sendungsdetails.