Lobster CEP-Connector

Version 1.0.1

Der CEP-Connector bietet eine einheitliche Integration für KEP-Dienste (Kurier-, Express- und Paketdienstleister). Er unterstützt die Buchung von Sendungen, den Abruf von Labels und die Sendungsverfolgung über verschiedene Carrier. Integrieren Sie dafür das einheitliche Datenformat LobsterCEP. Den Rest übernimmt der CEP-Connector.

Zentrale Anwendungsfälle

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

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

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

Voraussetzungen

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

• Lobster Data Platform, Version 25.1 oder höher

• 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 mit der gesamten Funktionalität des CEP-Connectors. Sie enthalten die Mappings zwischen den API-Formaten der KEP-Dienstleister und dem einheitlichen Format LobsterCEP.

• TEMPLATE_LobsterCEP Profile sind vordefinierte Vorlagen. Sie vereinfachen die Integration über das Format LobsterCEP.

 WICHTIG: 

Ändern Sie keine CEP_CONNECTOR Profile. Änderungen beeinträchtigen die Funktionalität und Wartbarkeit des CEP-Connectors.

Sendungsbuchung

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

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. Diese Dateien enthalten Tracking-Details im CSV-Format. Die Polling-Logik ruft nur neue Tracking-Events ab und verhindert so redundante Datenabfragen. Wenn Sie den Buchungsprozess nutzen, erstellt und aktualisiert der CEP-Connector die Tracking-Konfigurationsdateien automatisch.

Sie können diese Dateien auch manuell befüllen, wenn Sendungen anderweitig gebucht wurden. Die Tracking-Dateien haben folgendes Format:

carrierTrackingNumber;customerShipmentId;latestEventTimestamp;shipmentCreationTimestamp

Das Feld latestEventTimestamp befüllt der Connector automatisch. Lassen Sie es beim erstmaligen Einrichten leer.

Beispiel: Verfolgen Sie die Sendung test123 mit der DHL-Sendungsnummer 1091847043 automatisch (erstellt am 08.09.2025 um 10:00:00 Uhr). Fügen Sie dazu folgende Zeile in ./conf/Connectors/CEP/Tracking/List_ShipmentTrackingNumbers_DHL.csv ein:

1091847043;test123;;1757318400000

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

Installation

Für Kunden der Lobster Data Platform stehen vorkonfigurierte Dataflows zur Verfügung. Sie vereinfachen die Integration mit Ihren KEP-Dienstleistern. Die 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 des CEP-Connectors

Paket importieren

1. Wählen Sie Start > Mit Vorlage starten.

2. Wählen Sie in der Kachel CEP Connector die Option Installieren.

   Sie wechseln automatisch zu Integration > DataFlow > Designer.

   Der Dialog Paket importieren wird geladen. Er enthält vier Tabs:

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

   • Konstanten: Zeigt die im Paket enthaltenen Konstanten an.

   • Partner/Kanäle: Zeigt die 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 1.01 enthält folgende Komponenten:

 HINWEIS:

Alle Profile in diesem Paket haben den Status Aktiv und sind nach dem Import sofort einsatzbereit.

Gruppenauswahl

Wählen Sie für jedes Profil eine lokale Gruppe aus oder erstellen Sie eine neue. Klicken Sie dazu auf das Ordnersymbol in der Spalte Gruppe (Lokal).

Konstanten

Der Tab Konstanten zeigt die vordefinierten Konstanten zur Anpassung des CEP-Connectors.

Sind diese Konstanten bereits vorhanden, werden sie beim Import standardmäßig nicht überschrieben.

Partner/Kanäle

Der Tab Partner/Kanäle zeigt die im Paket enthaltenen Partner und Partnerkanäle. Dieses Paket enthält einen Partner mit fünf Partnerkanälen. Wählen Sie, ob Sie die vorkonfigurierten Partnerkanäle importieren oder überschreiben möchten. Wenn Sie die Option zum Überschreiben nicht aktivieren, bleiben bestehende Konfigurationen bei Updates erhalten.

Folgende Optionen stehen zur Verfügung:

• Partner importieren: Importiert den CEP-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: 

Ist der CEP-Connector-Partner in Ihrer Umgebung bereits vorhanden und individuell angepasst? Lassen Sie die Option Partner/Kanäle überschreiben in diesem Fall deaktiviert.

Import abschließen

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

Zugangsdaten konfigurieren

Erforderliche Zugangsdaten pro Carrier

Partnerkanal konfigurieren

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

DHL_Express_HTTPS

• Tragen Sie den DHL-Express-Benutzernamen in das Feld Own ID ein.

• Tragen Sie das DHL-Express-Passwort in das Feld Own Password ein.

FedEx_HTTPS

1. Wählen Sie 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. Wählen Sie 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. Wählen Sie Configure OAuth 2.0….

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

3. Aktivieren 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 die Redirect URL ein. Verwenden Sie die interne Adresse Ihrer Lobster Data Platform:

   https://<your-server>:<your-port>/dw/oauth2/<your-Application-ID>

   Die Application-ID beginnt mit _data. Sie finden sie in Ihren OAuth 2.0-Einstellungen. Registrieren Sie diese URL auch im UPS Developer Portal unter den Anwendungseinstellungen.

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. Wählen Sie Fetch Access Token. Sie werden zu UPS weitergeleitet, um Ihre Developer-Account-Zugangsdaten einzugeben.

9. Nach erfolgreicher Weiterleitung erscheint eine leere Seite mit ok. Öffnen Sie den Kanal erneut. Die Token SYS_HTTP_OAUTH2 und SYS_HTTP_OAUTH2_REFRESH sind jetzt unter Additional IDs sichtbar.

10. 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 Tab Additional IDs hinzu.

GLS_HTTPS

1. Wählen Sie 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://api-sandbox.gls-group.net/oauth2/v2/token

   • Prod: https://api.gls-group.net/oauth2/v2/token

5. Wählen Sie Fetch Access Token.

6. Tragen Sie die OAuth2 Refresh URL ein:

   • Test: https://api-sandbox.gls-group.net/oauth/token?grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>

   • Prod: https://api.gls-group.net/oauth/token?grant_type=client_credentials&client_id=<clientId>&client_secret=<clientSecret>

Profil-Templates für benutzerdefinierte Mappings verwenden

Wichtig

Ändern Sie keine CEP_CONNECTOR Profile. Änderungen beeinträchtigen Funktionalität und Wartbarkeit des CEP-Connectors.

Konfigurationskonstanten

Die folgenden Systemkonstanten konfigurieren den CEP-Connector. (M) = erforderlich, (D) = abhängig, (O) = optional.

Eingabe-Datenstruktur: Sendungsbuchung

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

Ausgabe-Datenstruktur: Sendungsbuchung

Beispiel: 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: Fehlerantwort

{
  "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_ShipmentTrackingTrigger pollt den Carrier automatisch nach neuen Events. Es 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.

Beispiel: 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"
      }
    ]
  }
}