OpexGuard ersetzt nichts, was bei Ihnen funktioniert. Sendungsdaten kommen aus Ihrem Shop-, ERP- oder Warenwirtschaftssystem – auf einem von vier Wegen. Diese Seite beschreibt jeden davon so genau, dass Ihre IT den Aufwand einschätzen kann.
1 · REST-Schnittstelle
| Basis | https://<umgebung>/api/v1/… – Version im Pfad; eine neue Hauptversion bekommt einen neuen Pfad, v1 bleibt |
| Authentifizierung | Kopfzeile X-API-Key mit einem Schlüssel, der je Kunde und Rolle ausgestellt wird (gespeichert nur als SHA-256-Hash, jederzeit widerrufbar). Menschen nutzen dieselbe Schnittstelle mit ihrem Entra-Token |
| Beschreibung | OpenAPI 3, aus dem Code generiert (/openapi/v1.json), dazu eine interaktive Referenz. Beide sind heute zugangsgeschützt – den Zugang erhalten Sie mit dem Pilotvertrag |
| Fehler | Problem Details (RFC 9457): ein einheitliches JSON mit Status, Titel, Detail und – bei Validierungsfehlern – dem betroffenen Feld |
| Ratenbegrenzung | 100 Anfragen je Schlüssel und Minute; dazu eine Obergrenze von 3 000 je Minute über den gesamten externen Verkehr als Schutz gegen Missbrauch. Darüber antwortet die Schnittstelle mit 429 und Retry-After. Andere Werte je Vertrag |
| Mandant | ergibt sich aus dem Schlüssel – ein Schlüssel sieht genau einen Mandanten; ein Mandantenwechsel per Parameter ist nicht möglich |
Was die Schnittstelle abdeckt: Sendungen anlegen, lesen, suchen; Tracking-Ereignisse; Vorgänge und Claims; Dokumente hochladen, versionieren, herunterladen; Ablieferbelege an Sendungen; Auswertungen; das Änderungsprotokoll des eigenen Mandanten.
2 · CSV-Import
Für Systeme ohne Schnittstelle. Die Plattform stellt eine Vorlage mit den exakten Spaltenüberschriften und Beispielzeilen zum Download bereit; die Vorlage wird aus demselben Schema erzeugt, das der Import liest – beides kann nicht auseinanderlaufen. Der Import läuft asynchron; sein Status (angenommen, verarbeitet, Fehler je Zeile) ist abrufbar.
Die Spalten:
ShipmentNumber, TrackingId, Carrier, CarrierName, ServiceType, Status, Weight,
DimensionLengthCm, DimensionWidthCm, DimensionHeightCm, ShippedAt, EstimatedDeliveryAt,
IsReturnShipment, CarrierTrackingUrl, Tags,
SenderName, SenderStreet, SenderCity, SenderPostalCode, SenderCountry, SenderCompany, SenderEmail, SenderPhone,
RecipientName, RecipientStreet, RecipientCity, RecipientPostalCode, RecipientCountry, RecipientCompany,
RecipientEmail, RecipientPhonePflicht sind Sendungsnummer, Tracking-Nummer, Carrier sowie Name, Straße, Ort, Postleitzahl und Land von Absender und Empfänger; alles andere ist optional und macht die Sendung vollständiger. Trennzeichen ist das Komma, Werte stehen in Anführungszeichen, fehlende optionale Spalten sind erlaubt. Jede Zeile wird einzeln geprüft; eine fehlerhafte Zeile hält die übrigen nicht auf. Ein abweichendes Spalten-Mapping je Kunde richten wir beim Onboarding ein.
3 · SFTP-Abruf
Sie legen die CSV-Dateien auf Ihrem SFTP-Server ab, die Plattform holt sie ab:
- je Mandant konfiguriert: Host, Port, Benutzer, Passwort (bei uns mit AES-256-GCM verschlüsselt, der Schlüssel liegt im Key Vault), Quellverzeichnis, Archivverzeichnis und Abrufintervall in Minuten
- nach dem Abruf wird die Datei in Ihr Archivverzeichnis verschoben (oder auf Wunsch gelöscht), damit nichts doppelt importiert wird
- der Abruf geht von uns aus; Sie öffnen keinen Zugang in Ihr Netz, außer dem SFTP-Server selbst
4 · E-Mail
Carrier-Mails – Zustellhinweise, Belege, Rückfragen – kommen ohne Schnittstelle in die Plattform:
- Sie leiten das betreffende Postfach weiter oder setzen eine Ingest-Adresse in Kopie, die es je Mandant auf unserer Domäne gibt
- die Plattform ruft das Postfach im Minutentakt über Microsoft Graph ab (kein Webhook) und ordnet jede Mail zu: nach Ingest-Adresse, nach einer Sendungs- oder Vorgangsreferenz im Inhalt, sonst in den Posteingang für die manuelle Zuordnung. Mails, deren Absender die DMARC-Prüfung nicht besteht, werden nicht automatisch zugeordnet
- Anhänge werden als Dokumente an der Sendung abgelegt; Fristen und Wiedervorlagen daraus landen als Termine im Outlook-Kalender (Microsoft Graph)
Die Anbindung eines eigenen Postfachs in Ihrem Microsoft-365-Mandanten (statt Weiterleitung) ist in Vorbereitung – siehe Microsoft 365.
5 · Carrier
Tracking-Ereignisse kommen per Webhook und ergänzendem Abruf über einen Tracking-Dienstleister herein (dessen Namen nennen wir auf Anfrage, nicht öffentlich): für DHL, UPS, FedEx und USPS mit Tracking und Label-Erzeugung, für Hermes mit Ereignisempfang. Weitere Carrier betreuen wir im Prozess – Nachforschung, Claim, Beleg – ohne technische Anbindung; die Übersicht steht unter Carrier. Claims werden über das Carrier-Portal oder per Mail eingereicht und mit der Carrier-Referenz erfasst; eine Claim-API der Carrier gibt es nicht.
Für die Netzwerkfreigabe
- Richtung: Ihre Systeme rufen die Schnittstelle auf. Die Plattform selbst verbindet sich nur nach außen – zu Ihrem SFTP-Server, wenn Sie den Abruf nutzen – und nie in Ihr Netz.
- Keine ausgehenden Webhooks: Änderungen holen Ihre Systeme über die Schnittstelle ab; es gibt keine Verbindung von uns zu Ihnen, die Sie freigeben müssten.
- Erreichbarkeit: Die Schnittstelle ist über HTTPS öffentlich erreichbar und über Schlüssel, Token und Ratenbegrenzung geschützt – ohne IP-Allowlisting und ohne private Endpunkte.