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. Import-Konfiguration

• Wählen Sie die passenden lokalen Gruppen für die Profile aus oder erstellen Sie neue

• Im Reiter Constants sehen Sie alle vordefinierten Konstanten. Bereits vorhandene Konstanten mit abweichenden oder identischen Werten werden standardmäßig nicht überschrieben.

• Im Reiter Partner channel können Sie auswählen, ob die vorkonfigurierten Partnerkanäle importiert oder überschrieben werden sollen. Ist das Überschreiben nicht aktiviert, ändert ein Update den Partnerkanal nicht – so können Sie den Connector sicher aktualisieren.

• Bestätigen Sie den Import über Import → Import Package

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.