Carrier-EDI und Visibility integrieren

Zweck und Einsatzbereich

NeuraPort besitzt zwei getrennte technische Eingangswege:

• Carrier-EDI nimmt EDIFACT-Nachrichten der Typen COPRAR, CODECO und BAPLIE entgegen. Der Eingang kann über einen Maschinenzugang, einen authentifizierten Dateiimport oder eine manuelle technische Übergabe erfolgen. Eindeutige Containerereignisse können Containerfelder einer Seefrachtakte ändern.
• Visibility nimmt bereits kanonisch strukturierte Trackingereignisse für See-, Luft-, Straßen- und Schienentransporte entgegen. Daraus können Lane-Kennzahlen, eine beratende ETA-Prognose und ein Leistungsnachweis für den 3-Way-Rechnungsabgleich entstehen.

Im Hauptfrontend gibt es derzeit keinen belegten Arbeitsbereich zum Hochladen oder Auflisten von Carrier-EDI, zum manuellen Erfassen oder Prüfen von Visibility-Events oder zum Anzeigen von Lane- und ETA-Daten. Diese Wege sind Integrationsgrenzen für einen technisch berechtigten Betrieb, keine frei bedienbaren Anwenderfunktionen. Erraten Sie keine technischen Adressen oder Objektkennungen. Sichtbar ist nur die Folgewirkung 3-Way unter Eingangsrechnungen.

Für Visibility ist genau ein kanonischer Adapter vorhanden. Unbekannte Providernamen werden akzeptiert, wenn der Absender bereits das kanonische NeuraPort-Format liefert. Ein Providername belegt daher weder einen fertigen Liveclient noch eine Mapping-, Polling- oder Vertragsintegration. Carrier-EDI besitzt ebenfalls nur einen bewusst kleinen EDIFACT-Parser und keinen vollständigen, providerzertifizierten EDI-Konverter.

Voraussetzungen und Berechtigungen

Carrier-EDI

• Carrier-EDI darf ausschließlich über ein vom Plattformbetrieb freigegebenes Gateway mit Nachrichtensignatur, Replay-Schutz, TLS und sicher verwaltetem Secret betrieben werden. Secrets dürfen nie in Nutzdaten, URLs, Dateien, Screenshots oder Tickets erscheinen.
• Der Zielmandant benötigt das Modul Public API mit Automationsfreigabe. Bei Bezug auf eine Seefrachtakte ist zusätzlich Ocean Export oder Ocean Import erforderlich.
• Mandant, Organisationseinheit und Zielakte müssen im Gateway fest gebunden sein. Der freigegebene Scope muss exakt zur tatsächlichen Organisationseinheit des Zielobjekts passen; ungebundene oder aktenlose Eingänge sind nicht für den Produktivbetrieb freigegeben.
• Ein angemeldeter Benutzer benötigt für Dateiimport oder manuelle technische Übergabe Public API sowie Akten bearbeiten. Mit Aktenbezug gilt zusätzlich das passende Ocean-Modul. Zum Lesen der Nachrichten werden Public API und Akten ansehen benötigt.

Visibility

• Für einen eingehenden Provider-Webhook muss der Plattformbetrieb je Mandant und Provider eine aktive Trackingkonfiguration mit verschlüsseltem Signatursecret einrichten. Die Konfiguration muss im Live-Modus stehen; Simulation wird für diesen Eingang ausdrücklich abgewiesen.
• Für jedes Zielobjekt müssen Public API und Tracking als Automation in dessen tatsächlicher Organisationseinheit aktiv sein.
• Eine angemeldete Person benötigt zum manuellen Erfassen Akten bearbeiten und über den gemeinsamen Bereich mindestens Tracking oder Finance. Lesen, Lane-Auswertung und ETA-Prognose verlangen zusätzlich Tracking ansehen; der Rechnungsabgleich verlangt Finanzen bearbeiten.
• Provider und NeuraPort müssen dieselbe Uhrzeitbasis verwenden. Der signierte Zeitstempel darf höchstens fünf Minuten von der Serverzeit abweichen.

Alle EDI- und Visibility-Daten sind mandantenbezogen. Carrier-EDI-Nachrichten und Visibility-Objekte tragen zusätzlich eine Organisationseinheit; Listen werden für normale Rollen auf zugewiesene Einheiten begrenzt. ADMIN und MANAGER können alle Einheiten ihres Mandanten erreichen. Datenbankrichtlinien trennen die Mandanten zusätzlich, ersetzen aber keine Organisationseinheitenprüfung im Integrationsweg.

Containerkennung, Aktenbezug, Standort, Koordinaten, Zeitstempel, Providerreferenz und ein optionales Rohpayload werden nicht anonymisiert. Klären Sie Vertrag, Rechtsgrundlage, Datenminimierung, Aufbewahrung, Unterauftragnehmer und Empfängerländer vor dem ersten Liveereignis.

Schritt-für-Schritt-Anleitung

Carrier-EDI kontrolliert abnehmen

1. Vereinbaren Sie mit Carrier oder Middleware exakt Nachrichtentyp, EDIFACT-Version, Segmenttrennzeichen, Statuscodes, Zeichenkodierung und Referenzen. Der geprüfte Parser akzeptiert nur UTF-8 und die drei genannten Nachrichtentypen; er ist kein vollständiger EDIFACT-Validator.
2. Lassen Sie den Plattformbetrieb Gateway, Nachrichtensignatur, Secret-Verwaltung, Rotation und Replay-Schutz nach dem freigegebenen Integrationsprofil einrichten. Ein direkter, nicht abgenommener Eingang ist unzulässig.
3. Verwenden Sie einen isolierten Testmandanten sowie vollständig fiktive Zielobjekte. Prüfen Sie, dass Mandant, Organisationseinheit und Zielakte fest an den freigegebenen Integrationsscope gebunden sind.
4. Senden Sie eine fachlich gültige Testnachricht und kontrollieren Sie den technischen Verarbeitungsnachweis, das erwartete Zielobjekt und die fachliche Folgewirkung.
5. Prüfen Sie Idempotenz, Manipulationsabwehr, Replay-Schutz und Scope-Abweisung gemäß Abnahmeplan, ohne produktive Kennungen oder Secrets zu verwenden.
6. Prüfen Sie IGNORED für eine Nachricht ohne passenden Container und APPLIED nur zusammen mit dem tatsächlich geänderten Container. APPLIED allein beweist keine fachlich richtige Meilensteinzuordnung.
7. Vergleichen Sie Ereigniszeit und Containerdatum manuell. Der aktuelle Parser übernimmt den EDIFACT-Zeitstempel nicht als Containerdatum, sondern setzt bei erkannten Begriffen das Verarbeitungsdatum. Verwenden Sie diese Automatik deshalb noch nicht unbeaufsichtigt im Livebetrieb.

Signierten Visibility-Eingang abnehmen

1. Definieren Sie mit dem Provider das kanonische Ereignisformat. Jedes Ereignis muss genau ein Logistikobjekt referenzieren und Transportmodus, externe Ereignis-ID, Ereigniscode sowie Ereigniszeit enthalten.
2. Lassen Sie eine aktive mandantenbezogene Trackingkonfiguration und ein eigenes, zufälliges Signatursecret einrichten. Ein Eintrag in der allgemeinen Providerliste genügt nicht.
3. Verwenden Sie ausschließlich das mit dem Provider vereinbarte Signatur- und Replay-Schutz-Profil. Der Plattformbetrieb stellt die technische Spezifikation und verwaltet die Secrets über den freigegebenen Kanal.
4. Führen Sie Positiv-, Manipulations-, Replay-, Idempotenz- und Scope-Tests im isolierten Testbetrieb nach dem dokumentierten Abnahmeplan aus.
5. Weisen Sie insbesondere Nachrichten für einen anderen Mandanten, eine nicht freigegebene Organisationseinheit oder ein unpassendes Zielobjekt ohne Folgewirkung ab.
6. Geben Sie den Providerkanal erst nach dokumentierter technischer und fachlicher Produktionsabnahme frei.
7. Prüfen Sie im technischen Nachweis Zielobjekt, Organisationseinheit, Provider, Ereigniscode, Ereigniszeit, Standort und optionale Provider-ETA. Eine angenommene Nachricht ändert den Aktenstatus nicht automatisch.

ETA, Lane und Folgewirkungen kontrollieren

1. Lassen Sie eine ETA-Prognose nur für ein berechtigtes vorhandenes Ereignis anfordern. Sie verwendet vorrangig eine Provider-ETA, sonst Plantermin plus historischen durchschnittlichen Lane-Verzug. Das Ergebnis ist immer als beratend markiert.
2. Prüfen Sie Basis, vorhergesagte Ankunft, Abweichung, Konfidenz und Stichprobenzahl. Das Modell ist eine Heuristik und keine KI-basierte Liveprognose des Providers.
3. Lane-Kennzahlen werden nur bei ARRIVED, DELIVERED oder POD fortgeschrieben. Prüfen Sie Provider, Route, Einheit und Stichprobengröße, bevor Sie daraus Leistungsentscheidungen ableiten.
4. Unter Eingangsrechnungen kann 3-Way ein Trackingereignis als Leistungsnachweis berücksichtigen. Verwenden Sie das Ergebnis erst nach intern abgenommener Prüfung von Herkunft, Lieferant, Kosten, Leistung und bisherigem Rechnungsstatus; bei jeder Abweichung Freigabe stoppen.
5. Falls ein ausgehender Kundenwebhook das Ereignis tracking.event.created oder invoice.match.completed erhalten soll, ist eine gesonderte technische Subscription nötig. Die sichtbare Webhook-Einstellung bietet diese beiden Ereignisse derzeit nicht zur Auswahl an.

Feldreferenz

Feld	Pflicht	Bedeutung	Validierung
Mandant	Ja	Eigentümer der eingehenden Nachricht	Muss im freigegebenen Gateway fest konfiguriert und zur lizenzierten Integration gehören; niemals aus frei wählbaren Absenderdaten übernehmen.
Organisationseinheit	Ja	Einheit, in der Automation und Daten wirken	Muss aktiv sein, zum Mandanten gehören, im Gateway fest gebunden sein und exakt der Einheit des Zielobjekts entsprechen.
Akte / Logistikobjekt	Ja für Visibility; für EDI dringend empfohlen	Ziel der Nachricht	Visibility verlangt genau eine See-/Schienenakte, Luftfrachtakte oder Straßenorder passend zum Transportmodus. Carrier-EDI sollte immer eine berechtigte Seefrachtakte angeben.
EDI-Secret	Ja für Carrier-EDI-Maschinenzugang	Geheimes Authentisierungsmaterial des freigegebenen Gateways	Ausschließlich im Secret-Management verwalten, regelmäßig rotieren und nie übertragen oder protokollieren. Gateway muss Signatur, Replay-Schutz und festen Scope durchsetzen.
EDI-Inhalt	Ja	EDIFACT-Nachricht	UTF-8, höchstens 5 MB und Typ COPRAR, CODECO oder BAPLIE. Vollständige Syntax- oder Providerzertifizierung ist nicht belegt.
Dateiname	Nein	Herkunftshinweis der EDI-Datei	Keine Zugangsdaten oder vertraulichen Freitexte verwenden; bei technischer manueller Übergabe auf 255 Zeichen begrenzt.
Containernummer	Für Containerwirkung ja	Fachliche Containerkennung im EDI-Payload	Nur zusammen mit fest gebundener Zielakte und freigegebener Organisationseinheit produktiv verwenden.
EDI-Status	Systemseitig	RECEIVED, danach APPLIED oder IGNORED	APPLIED heißt nur, dass ein passender Container verarbeitet wurde. Der sichtbare Code erzeugt bei Parsingfehlern keinen gespeicherten FAILED-Eintrag.
Provider	Ja für Visibility	Bezeichnung des Ereignislieferanten	Wird aus dem signierten Providerkanal übernommen. Unbekannte Namen nutzen trotzdem den kanonischen Adapter und belegen keinen Liveadapter.
Externe Ereignis-ID	Ja	Idempotenzschlüssel des Providers	Je Mandant und Provider eindeutig. Dieselbe ID darf nie für ein anderes Objekt oder korrigierten Inhalt wiederverwendet werden.
Transportmodus	Ja	OCEAN, AIR, ROAD oder RAIL	Muss zum gewählten Objektfeld passen; Schiene verwendet technisch eine Seefrachtakte als Objektart.
Ereigniscode	Ja	Kanonischer operativer Meilenstein	Zwei bis 50 Zeichen; keine fachliche Werteliste erzwungen. ARRIVED, DELIVERED und POD beeinflussen Lane und Leistungsnachweis.
Ereigniszeit	Ja	Zeitpunkt beim Provider	Zeitzonenbehafteten ISO-Zeitpunkt verwenden. Keine fachliche Grenze für Zukunft oder Vergangenheit belegt.
Standort / Koordinaten	Nein	Ort des Ereignisses	Breiten- und Längengrad werden auf gültige Zahlenbereiche begrenzt; Standortcode und -name fachlich prüfen.
Geschätzte Ankunft	Nein	Vom Provider gelieferte ETA	Wird in der Prognose gegenüber einer vorhandenen Plan-ETA bevorzugt. Keine externe Plausibilitätsprüfung belegt.
Rohpayload	Nein	Zusätzliche Providerprovenienz	Kann vollständig gespeichert und später ausgegeben werden. Auf erforderliche, datensparsame Felder begrenzen; keine Secrets mitsenden.
Signaturzeitstempel	Ja für Visibility-Webhook	Grundlage des Replay-Schutzes	Muss dem freigegebenen Signaturprofil entsprechen und aus einer synchronisierten Zeitquelle stammen.
Nachrichtensignatur	Ja für Visibility-Webhook	Sichert Authentizität und Integrität der Nachricht	Nach dem freigegebenen Providerprofil bilden und prüfen; Secret nie mitsenden oder protokollieren.
Toleranzbetrag / -prozent	Für 3-Way ja	Erlaubte Rechnungsabweichung	Betrag 0 bis 100.000, Prozent 0 bis 100. Eine passende Toleranz ersetzt Lieferanten- und Leistungsprüfung nicht.

Status und mögliche Übergänge

Ausgangszustand	Aktion oder Ereignis	Ergebnis
Gültige neue EDI-Nachricht	Gateway, Scope und fachliche Prüfung erfolgreich	RECEIVED, danach im selben Ablauf APPLIED oder IGNORED.
Bereits verarbeitete EDI-Nachricht erneut	Idempotenzprüfung greift	Keine zweite fachliche Verarbeitung.
EDI ungültig oder nicht unterstützt	Eingang	Abweisung ohne gespeicherten FAILED-Nachweis.
EDI findet passenden Container	Containerverarbeitung	Fachliche Quittung und erwartete Folgewirkung müssen vor der weiteren Nutzung übereinstimmen.
Visibility-Konfiguration fehlt, ist deaktiviert oder in Simulation	Provider-Webhook	Abweisung; kein Ereignis.
Signatur oder Zeitfenster ungültig	Provider-Webhook	Abweisung; kein Ereignis.
Neues kanonisches Visibility-Ereignis	Signatur, Objekt und Lizenzen gültig	Ereignis mit Quelle PROVIDER wird gespeichert; optionaler ausgehender Webhook wird bestmöglich ausgelöst.
Provider und externe Ereignis-ID bereits vorhanden	Erneuter Eingang	Vorhandenes Ereignis wird zurückgegeben; geänderter Inhalt wird nicht als Korrektur übernommen.
Ereignis ARRIVED, DELIVERED oder POD	Speicherung	Lane-Kennzahl wird fortgeschrieben und das Ereignis kann als Leistungsnachweis dienen.
ETA-Prognose angefordert	Provider-ETA vorhanden	Beratende Prognose auf Basis PROVIDER_ETA.
ETA-Prognose angefordert	Nur Plantermin vorhanden	Beratende Prognose aus Plantermin und Lane-Durchschnitt; ohne beides Abweisung.
3-Way meldet vollständigen Abgleich	Rechnungsabgleich	Ergebnis erst nach bestätigter Herkunfts-, Leistungs- und Statusprüfung freigeben.
Ausgehender Webhook scheitert	Auslieferungsversuch	Folgeprozess stoppen; Atomarität, Fehlerzustand und freigegebenen Wiederholungsweg intern prüfen.

Was im Hintergrund passiert

Carrier-EDI darf erst nach dokumentierter Gateway- und Providerabnahme produktiv verarbeitet werden. Das Gateway muss jede Nachricht signiert, gegen Replay geschützt und fest an Mandant, Organisationseinheit sowie Zielakte binden. Geheimnisse bleiben im zentralen Secret-Management; NeuraPort verarbeitet nur den freigegebenen, fachlich geprüften Nachrichtenstrom.

Die fachliche Verarbeitung muss Lizenz, Transportrichtung, Zielakte und tatsächliche Organisationseinheit konsistent prüfen. Aktenlose oder anderweitig nicht eindeutig gebundene Eingänge sind kein unterstützter Produktivweg. Jede Folgewirkung wird in der Abnahme mit fiktiven Daten und anschließend im kontrollierten Pilotbetrieb geprüft.

Vor der Produktivfreigabe müssen Authentizität, Mandant, Organisationseinheit, Zielobjekt und fachliche Provenienz für jeden Eingang eindeutig nachgewiesen sein. Stapelverarbeitung darf nur freigegeben werden, wenn vollständige Atomarität und ein eindeutiger Gesamtfehlerzustand im End-to-End-Test bestätigt sind. Bei einem Teilfehler wird die Folgeautomatik gestoppt und der gesamte Vorgang intern abgeglichen.

Manuelle und automatisierte Eingänge müssen im fachlichen Nachweis eindeutig unterscheidbar sein. Ereigniszeit und Provider-ETA sind vor einer status-, abrechnungs- oder kundenwirksamen Folge zu plausibilisieren.

Die Lane-Berechnung führt Stichproben je Modus, Route, Provider und Organisationseinheit. Der als p90 bezeichnete Wert ist im geprüften Stand tatsächlich nur der bisher größte Verzug. Die ETA-Heuristik sucht für eine Route die Lane mit der größten Stichprobe, ohne den Provider des Ausgangsereignisses zwingend beizubehalten. Beide Werte dürfen daher noch nicht als belastbare SLA- oder Providerbewertung verwendet werden.

Ausgehende Benachrichtigungen dürfen erst nach intern abgenommener Zustellquittung, Dublettenprüfung und Wiederholungsstrategie produktiv wirken. Ist eine Zustellung oder ihr fachlicher Zustand unklar, wird keine Fachaktion wiederholt; der Integrationsbetrieb klärt den Vorgang anhand des freigegebenen Nachweises.

Automatisierte Tests decken zentrale Integrationsgrundpfade ab, ersetzen aber keine Provider-, Gateway-, Scope- und End-to-End-Abnahme. Carrier-EDI und Visibility bleiben bis zum vollständig dokumentierten Positiv-, Negativ-, Replay-, Idempotenz- und Berechtigungstest für den jeweiligen Zielbetrieb gesperrt.

Typische Fehler und Lösungen

Meldung oder Beobachtung	Ursache	Lösung
Carrier-EDI-WebHook ist nicht konfiguriert	Zentrales Shared Secret fehlt.	Plattformbetrieb einbeziehen; niemals selbst ein Secret in URL oder Datei ergänzen.
Ungültiger EDI-WebHook-Schlüssel	Shared Secret fehlt oder stimmt nicht.	Integration stoppen, Secret über sicheren Kanal und richtigen Zielbetrieb abgleichen; bei Verdacht sofort rotieren.
Ungültige oder zu große EDI-Datei	Body leer oder größer als 5 MB.	Dateigröße und Export des Quellsystems prüfen; Inhalt nicht unkontrolliert aufteilen.
EDI-Datei muss UTF-8-kodiert sein	Andere Zeichenkodierung.	Providerseitig kontrolliert nach UTF-8 konvertieren und Prüfsumme neu bilden.
Unterstützt werden nur COPRAR, CODECO oder BAPLIE	Nachrichtentyp fehlt oder wird vom kleinen Parser nicht unterstützt.	Typ und UNH-Struktur prüfen; keine fremden Nachrichten durch Umbenennen einschleusen.
EDI ist APPLIED, aber Containerdatum ist falsch	Statusbegriff wurde breit interpretiert und das Verarbeitungsdatum statt der Ereigniszeit gesetzt.	Automatische Folge stoppen, Originalnachricht fachlich prüfen und Datum berechtigt korrigieren lassen.
EDI wirkt im falschen Organisationsbereich	Gateway-Scope oder Zielbindung ist nicht korrekt abgenommen.	Integration sofort stoppen, Vorfall dokumentieren und Gateway, Zielakte sowie tatsächliche Organisationseinheit vor Wiederfreigabe prüfen.
Tracking-Webhook ist nicht konfiguriert	Mandant oder Providername ungültig.	Freigegebenen Providerkanal und Mandantenzuordnung durch den Plattformbetrieb prüfen lassen.
Aktiver Tracking-Webhook ist nicht konfiguriert	Trackingkonfiguration fehlt, ist deaktiviert oder steht auf Simulation.	Nicht umgehen; mandantenspezifische Livekonfiguration, Secret und Abnahme prüfen.
Webhook-Zeitstempel fehlt oder ist ungültig	Zeitstempel fehlt, ist nicht numerisch oder Systemuhren weichen zu stark ab.	UTC-Zeit synchronisieren und mit frischem Zeitstempel neu signieren.
Webhook-Signatur ist ungültig	Nachricht entspricht nicht dem freigegebenen Signaturprofil.	Providerkanal stoppen, Signaturprofil und Secret-Verwaltung prüfen und bei Manipulationsverdacht rotieren.
Webhook muss 1 bis 100 Events enthalten	Leerer, falsch geformter oder zu großer Stapel.	Kanonisches Objekt oder Liste mit höchstens 100 Objekten senden.
Ereignis wird akzeptiert, erscheint aber nicht als Korrektur	Provider und externe Ereignis-ID existieren bereits.	Neue fachlich eindeutige Korrektur-ID gemäß Integrationsvertrag verwenden; vorhandenen Datensatz nicht still überschreiben.
Kein eigener Visibility-/EDI-Arbeitsbereich sichtbar	Die Funktionen sind im Hauptfrontend nicht eingebunden.	Keine direkten Aufrufe improvisieren; technischen Integrationsbetrieb und dokumentierten Nachweis verwenden.
3-Way-Ergebnis ist fachlich nicht eindeutig	Herkunft, Lieferant, Kosten, Leistung oder Rechnungsstatus sind nicht vollständig bestätigt.	Freigabe stoppen und Eingangsrechnungen kontrolliert erfassen beachten; Abgleich intern vollständig prüfen.
Ausgehendes Visibility-Ereignis kann in der Oberfläche nicht abonniert werden	Die sichtbare Ereignisauswahl enthält diese Ereignisnamen nicht.	Technische Subscription erst nach eigener Abnahme einrichten; keine leere Eventliste als undokumentierten Umweg verwenden.
Webhook-Zustellung bleibt unklar	Fachliche Quittung oder bestätigter Gesamtzustand fehlt.	Folgeprozess stoppen; Zustellung, Atomarität und freigegebenen Wiederholungsweg intern prüfen, ohne die Fachaktion erneut auszulösen.

Verwandte Themen

• Schnittstellenprovider konfigurieren, testen und überwachen
• Lizenzierte Systemzugriffe für Integrationen und Jobs
• Eingangsrechnungen kontrolliert erfassen
• Carrier-, Hafen- und Zollmeldungen mit Providern übermitteln
• Öffentliche Tracking-Links erstellen und widerrufen