CEP Connector Schemas

Version: 1.0.0

Dieses Dokument beschreibt die internen Datenstrukturen, die zwischen Ihren Profilen und den CEP-Connector-Profilen innerhalb der Lobster Data Platform ausgetauscht werden.

Eingabedatenstruktur

Sendungsbuchung

Übergeben Sie die folgende LobsterCEP-Datenstruktur an das Profil CEP_CONNECTOR_ShipmentBooking. Der Connector wandelt die Daten in das jeweilige KEP-Dienstleister-Format um, übermittelt sie an den Dienstleister und gibt das Ergebnis an Ihr Bestätigungsprofil zurück.

LobsterCEP

Wurzelstruktur für KEP-Versandvorgänge.

Pflichtfelder: header, shipment

Beispiel

{
  "LobsterCEP": {
    "header": {
      "carrierId": "DHL_EXPRESS",
      "action": "CREATE",
      "requestedDocuments": [
        "LABEL",
        "COMMERCIAL_INVOICE"
      ]
    },
    "shipment": {
      "shipmentId": "SHP12345678",
      "shipperReference": "ORD-987654321",
      "carrierReference": "CARRIER-REF-001",
      "consigneeReference": "PO-12345",
      "orderNumbers": {
        "salesOrderNumbers": [
          "SO-123456",
          "SO-123457"
        ],
        "purchaseOrderNumbers": [
          "PO-87654",
          "PO-87655"
        ]
      },
      "serviceType": "P",
      "additionalServices": [
        {
          "serviceCode": "INSURANCE",
          "serviceDescription": "Additional insurance coverage"
        },
        {
          "serviceCode": "SIGNATURE_REQUIRED",
          "serviceDescription": "Signature required on delivery"
        }
      ],
      "shippingDateTime": "2023-10-15T08:30:00.000Z",
      "incoTerm": "DAP",
      "incoTermLocation": "Destination Warehouse",
      "movementType": "OUTBOUND",
      "pickupRequestedFlag": true,
      "dropOffFlag": false,
      "accountNumber": {
        "value": "123456789"
      },
      "paymentInformation": {
        "transportation": {
          "paymentType": "SENDER"
        },
        "dutiesAndTaxes": {
          "paymentType": "RECEIVER",
          "accountNumber": "987654321",
          "countryCode": "DE"
        }
      },
      "parties": {
        "shipper": {
          "addressIdentifiers": [
            {
              "identifierValue": "DE123456789",
              "identifierType": "VAT"
            },
            {
              "identifierValue": "DE987654321",
              "identifierType": "EOR"
            }
          ],
          "reference": "SHIPPER-001",
          "name1": "Global Trading GmbH",
          "name2": "Logistics Department",
          "name3": "Building A",
          "street1": "Industriestrasse 45",
          "street2": "Floor 3",
          "zipcode": "10557",
          "city": "Berlin",
          "countryCode": "DE",
          "countryName": "Germany",
          "stateCode": "BE",
          "stateName": "Berlin",
          "contacts": [
            {
              "name": "Hans Schmidt",
              "email": "hans.schmidt@globaltrading.de",
              "phone": "+49 30 12345678",
              "fax": "+49 30 12345679"
            }
          ]
        },
        "recipient": {
          "addressIdentifiers": [
            {
              "identifierValue": "FR12345678900",
              "identifierType": "VAT"
            }
          ],
          "reference": "RECIPIENT-002",
          "name1": "Tech Innovations SARL",
          "name2": "Receiving Department",
          "street1": "25 Rue de la Paix",
          "street2": "Batiment C",
          "zipcode": "75002",
          "city": "Paris",
          "countryCode": "FR",
          "countryName": "France",
          "contacts": [
            {
              "name": "Marie Dubois",
              "email": "marie.dubois@techinnovations.fr",
              "phone": "+33 1 23456789"
            }
          ]
        },
        "importer": {
          "name1": "Tech Innovations SARL",
          "street1": "25 Rue de la Paix",
          "zipcode": "75002",
          "city": "Paris",
          "countryCode": "FR"
        },
        "exporter": {
          "name1": "Global Trading GmbH",
          "street1": "Industriestrasse 45",
          "zipcode": "10557",
          "city": "Berlin",
          "countryCode": "DE"
        }
      },
      "packages": [
        {
          "packageId": "PKG001",
          "shipperReference": "PKG-REF-001",
          "carrierReference": "CARRIER-PKG-001",
          "packageType": "BOX",
          "dimensions": {
            "length": { "value": 40, "unit": "cm" },
            "width": { "value": 30, "unit": "cm" },
            "height": { "value": 20, "unit": "cm" },
            "grossWeight": { "value": 5.2, "unit": "kg" },
            "netWeight": { "value": 4.8, "unit": "kg" }
          },
          "lineItems": [
            {
              "lineItemPos": "1",
              "itemNumber": "SKU-12345",
              "itemDescription": "Premium Wireless Headphones",
              "price": { "value": 199.99, "currency": "EUR" },
              "quantity": { "quantity": "2", "quantityUnit": "PCS" },
              "manufacturingCountry": "CN",
              "dimensions": {
                "grossWeight": { "value": 0.35, "unit": "kg" }
              },
              "customsInformation": {
                "hsCodes": [ "8518.30.95" ]
              }
            },
            {
              "lineItemPos": "2",
              "itemNumber": "SKU-67890",
              "itemDescription": "Bluetooth Speakers",
              "price": { "value": 149.99, "currency": "EUR" },
              "quantity": { "quantity": "3", "quantityUnit": "PCS" },
              "manufacturingCountry": "CN",
              "dimensions": {
                "grossWeight": { "value": 0.5, "unit": "kg" }
              },
              "customsInformation": {
                "hsCodes": [ "8518.22.00" ]
              }
            }
          ],
          "dangerousGoods": [
            {
              "dangerousGoodsFlag": true,
              "dangerousGoodsDetails": {
                "dangerousGoodsReference": "DG-REF-001",
                "unNumber": "UN3481",
                "name": "LITHIUM ION BATTERIES CONTAINED IN EQUIPMENT",
                "unClass": "9",
                "unPackingGroup": "II"
              }
            }
          ]
        },
        {
          "packageId": "PKG002",
          "packageType": "BOX",
          "dimensions": {
            "length": { "value": 25, "unit": "cm" },
            "width": { "value": 20, "unit": "cm" },
            "height": { "value": 15, "unit": "cm" },
            "grossWeight": { "value": 2.3, "unit": "kg" }
          },
          "lineItems": [
            {
              "lineItemPos": "1",
              "itemNumber": "SKU-54321",
              "itemDescription": "USB-C Charging Cables",
              "price": { "value": 19.99, "currency": "EUR" },
              "quantity": { "quantity": "10", "quantityUnit": "PCS" },
              "manufacturingCountry": "VN"
            }
          ]
        }
      ],
      "customsInformation": {
        "goodsDescription": "Electronic Accessories and Equipment",
        "goodsValue": { "value": 849.95, "unit": "EUR" },
        "hsCodes": [ "8518.30.95", "8518.22.00", "8544.42.90" ],
        "exportDeclarationNumber": "EXP20231015001",
        "invoiceNumber": "INV-20231015-001",
        "invoiceDate": "2023-10-14"
      },
      "labelSpecifications": {
        "fileFormat": "PDF",
        "template": "STANDARD_LABEL"
      },
      "metaInformation": {
        "entry": [
          {
            "key": "PRINTER_ID",
            "value": "12.345.678.910"
          }
        ]
      }
    }
  }
}

Tracking-Eingabe

Für die Sendungsverfolgung liest der Connector CSV-Konfigurationsdateien mit den vom Dienstleister vergebenen Sendungsnummern. Diese Dateien befinden sich unter ./conf/Connectors/CEP/Tracking/. Die Tracking-Antworten werden über das Vorlagenprofil TEMPLATE_LobsterCEP_ShipmentTracking verarbeitet.

Jede Zeile in der Tracking-CSV hat folgende Struktur:

carrierTrackingNumber;customerShipmentId;latestEventTimestamp;shipmentCreationTimestamp

Das Feld latestEventTimestamp wird automatisch vom Connector befüllt und sollte bei der Ersteinrichtung leer bleiben.

CSV-Datei je Dienstleister

CSV-Beispieleintrag

Um die Sendung test123 mit der DHL-Sendungsnummer 1091847043 (erstellt am 08.09.2025, 10:00 Uhr) zu verfolgen, fügen Sie folgende Zeile an List_ShipmentTrackingNumbers_DHL.csv an:

1091847043;test123;;1757318400000

Hinweis

Wenn Sie den Sendungsbuchungsprozess verwenden, werden die Tracking-Konfigurationsdateien automatisch erstellt und aktualisiert. Eine manuelle Bearbeitung ist nur für Sendungen erforderlich, die außerhalb des Connectors gebucht wurden.

Ausgabedatenstruktur

Die folgenden Strukturen gibt das CEP-Connector-Profil an Ihr empfangendes Profil zurück.

Ausgabedatenstruktur – Bestätigte Buchung

Wird zurückgegeben, wenn eine Sendung erfolgreich beim Dienstleister gebucht wurde. Die Verarbeitung erfolgt über TEMPLATE_LobsterCEP_ShipmentTransportorderAcknowledgement.

Beispiel

{
  "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": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nO=="
        },
        {
          "type": "INVOICE",
          "name": "INVOICE_987654321.pdf",
          "format": "PDF",
          "content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nO=="
        }
      ],
      "trackingUrl": "https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking"
    },
    "metaInformation": {
      "entry": [
        {
          "key": "PRINTER_ID",
          "value": "12.345.678.910"
        }
      ]
    }
  }
}

Sendungsbuchung – Fehler

Wird zurückgegeben, wenn der Dienstleister die Sendungsbuchung ablehnt. Die spezifische Fehlermeldung des Dienstleisters ist in der Antwort enthalten.

Beispiel

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

Sendungsverfolgung

Wird vom Tracking-Connector-Profil mit Statusaktualisierungen und optionalen Zustellnachweisen (Proof-of-Delivery) zurückgegeben. Die Verarbeitung erfolgt über TEMPLATE_LobsterCEP_ShipmentTracking.

Beispiel

{
  "LobsterCEP": {
    "header": {
      "carrierId": "DHL_EXPRESS"
    },
    "shipment": [
      {
        "shipmentId": "ABC123456789",
        "carrierReference": "987654321",
        "estimatedDeliveryDate": "2025-08-18T23:59:00Z",
        "trackingEvents": [
          {
            "owner": "DHL_EXPRESS",
            "creationDateTime": "2025-09-01T10:30:25+02:00",
            "eventDateTime": "2025-09-01T01:43:03Z",
            "eventLocation": "CPH (Copenhagen-DK)",
            "statusDetails": [
              {
                "code": "OK",
                "statusDescription": "Delivered"
              }
            ]
          },
          {
            "owner": "DHL_EXPRESS",
            "creationDateTime": "2025-09-01T10:30:25+02:00",
            "eventDateTime": "2025-09-01T01:43:08Z",
            "eventLocation": "CPH (Copenhagen-DK)",
            "statusDetails": [
              {
                "code": "DF",
                "statusDescription": "Shipment has departed from a DHL facility COPENHAGEN-DENMARK"
              }
            ]
          }
        ],
        "documents": [
          {
            "type": "POD",
            "name": "POD_987654321.pdf",
            "format": "PDF",
            "content": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSL0ZpbHRlci9GbGF0ZURlY29kZT4+CnN0cmVhbQp4nO=="
          }
        ],
        "trackingUrl": "https://express.api.dhl.com/mydhlapi/test/shipments/987654321/tracking"
      }
    ]
  }
}

Schema-Referenz

Die folgenden Abschnitte beschreiben alle Datenstrukturen des LobsterCEP-Formats im Detail.

Header

Dienstleister-Auswahl, Aktionstyp und angeforderte Dokumente.

Pflichtfelder: carrierId, action

Shipment

Vollständige Sendungsdetails einschließlich Beteiligte, Packstücke und Zollinformationen.

Pflichtfelder: shipmentId, shipperReference, serviceType, shippingDateTime, accountNumber, parties, packages

Versandprodukt-Werte je Dienstleister

Incoterm-Werte

EXW, FCA, CPT, CIP, DAP, DPU, DDP

Transportrichtung-Werte

INBOUND, OUTBOUND

OrderNumbers

Auftragsnummern auf Sendungs-, Packstück- oder Positionsebene.

AdditionalService

Zusatzleistung für die Sendung. Wird derzeit nur für DHL Express verwendet. Eine vollständige Auflistung der Codes finden Sie in den DHL-Express-Referenzdaten (ExpressReferenceData).

Pflichtfelder: serviceCode

AccountNumber

Kundennummer für den Versand.

Pflichtfelder: value

PaymentInformation (Wrapper)

Container für die Zahlungsinformationen zu Transport- und Zollkosten.

PaymentInformation

Zahlungs- und Abrechnungsdetails.

Parties

Alle an der Sendung beteiligten Parteien.

Pflichtfelder: shipper, recipient

Address

Adress- und Kontaktdaten einer beteiligten Partei.

Pflichtfelder: name1, street1, zipcode, city, countryCode

AddressIdentifier

Zusätzliche Adresskennung.

Pflichtfelder: identifierValue, identifierType

Contact

Kontaktdaten eines Ansprechpartners.

Pflichtfelder: name, phone

Package

Packstück mit Abmessungen, Positionen und Gefahrgutinformationen.

Pflichtfelder: packageId, shipperReference, dimensions

Dimensions

Physische Abmessungen einschließlich Gewicht und Volumen.

Pflichtfelder: grossWeight

Measurement

Maßangabe mit Wert und Einheit.

Pflichtfelder: value, unit

Weight

Gewichtsangabe mit Wert und Einheit.

Pflichtfelder: value, unit

Volume

Volumenangabe mit Wert und Einheit.

Pflichtfelder: value, unit

LineItem

Einzelne Position innerhalb eines Packstücks.

Pflichtfelder: itemNumber

Werte für Ausfuhrgrund (nur DHL Express)

permanent, temporary, return, used_exhibition_goods_to_origin, intercompany_use, commercial_purpose_or_sale, personal_belongings_or_personal_use, sample, gift, return_to_origin, warranty_replacement, diplomatic_goods, defence_material

DangerousGoods

Gefahrgut-Klassifizierung und -Details.

Pflichtfelder: dangerousGoodsFlag

DangerousGoods – Details

CustomsInformation (Sendungsebene)

Zollinformationen auf Sendungsebene.

PackageCustomsInformation

Zollinformationen auf Packstückebene.

LineItemCustomsInformation

Zollinformationen auf Positionsebene.

LabelSpecifications

Dateiformat und Vorlage für das Versandlabel.

ResponseHeader

Header-Informationen, die der Connector in Buchungsbestätigungen und Tracking-Antworten zurückgibt.

Pflichtfelder: carrierId

ProcessingStatus

Verarbeitungsergebnis mit Code und Zeitstempel.

Pflichtfelder: code, realizationDateTime

ShipmentAcknowledgement

Bestätigungsdaten einer erfolgreichen Sendungsbuchung.

Pflichtfelder: shipmentId, carrierReference

ShipmentErrorAcknowledgement

Fehlerantwort bei fehlgeschlagener Sendungsbuchung. Die Fehlerdetails befinden sich im processingStatus des Headers.

Pflichtfelder: shipmentId

ShipmentTracking

Sendungsverfolgungsdaten, die vom Tracking-Connector zurückgegeben werden.

Pflichtfelder: shipmentId, carrierReference

TrackingEvent

Einzelnes Tracking-Statusereignis.

Pflichtfelder: eventDateTime, statusDetails

StatusDetails

Pflichtfelder: statusCode

Document

Versandlabel, Rechnung oder Zustellnachweis (Proof-of-Delivery) als Base64-codiertes Dokument.

Pflichtfelder: type, name, format, content

MetaInformation

Schlüssel-Wert-Metadaten, die durch den Connector durchgereicht werden. Dient der temporären Speicherung von Werten, die in der Antwort wiederverwendet werden können.

Pflichtfelder: entry

MetaEntry

Pflichtfelder: key, value