Lobster CEP-Connector

Version 1.0.0

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: Um die Sendung test123 mit der DHL-Sendungsnummer 1091847043 (erstellt am 08.09.2025 um 10:00:00 Uhr) automatisch zu verfolgen, fügen Sie folgende Zeile in ./conf/Connectors/CEP/Tracking/List_ShipmentTrackingNumbers_DHL.csv ein:

1091847043;test123;;1757318400000

Für FedEx, UPS oder PostNL verwenden Sie statt DHL.csv entsprechend FEDEX.csv, UPS.csv oder PostNL.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

Schritt 1: 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 Reiter:

   • 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.

Reiter Inhaltsverzeichnis

Der Reiter 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.

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).

Reiter Konstanten

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

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

Reiter Partner/Kanäle

Der Reiter Partner/Kanäle zeigt die im Paket enthaltenen Partner und Partnerkanäle. Dieses Paket enthält einen Partner mit drei 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

Wenn der CEP-Connector-Partner bereits in Ihrer Umgebung vorhanden ist und Sie individuelle Anpassungen vorgenommen haben, lassen Sie die Option Partner/Kanäle überschreiben deaktiviert.

Import abschließen

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

Schritt 2: 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 Reiter Additional IDs hinzu.

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

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.

serviceType-Werte je Carrier

Parteien und Adressen

Alle an der Sendung beteiligten Parteien. shipper und recipient sind erforderlich.

Adressfelder

Zahlungsinformationen

Pakete und Positionen

Paketfelder

Abmessungen

Alle Messwerte bestehen aus einem value-Feld (Zahl) und einem unit-Feld.

Positionsfelder

Zollinformationen

Verfügbar auf Sendungs-, Paket- und Positionsebene.

Dokumente

Dokumente werden in der Buchungsbestätigung und in Tracking-Antworten zurückgegeben.

Tracking-Antwort

Tracking-Event-Felder

Support

Bei Fragen zur DataFlow-Konfiguration wenden Sie sich an das Lobster-Support-Team.

• Website: www.lobster-world.com

• E-Mail: support@lobster.cloud