Integrationen – Aufträge in Qargo importieren
Aufträge über die API oder Partnerintegrationen in Qargo importieren. Mit Mapping, Validierung und Fehlerbehebung.
Inhaltsverzeichnis
Einführung
Qargo bietet mehrere Wege, um Aufträge in großem Umfang in die Plattform zu übernehmen. Dieser Artikel erklärt die wichtigsten Konzepte und die Importwege, die die meisten Kunden nutzen: Integrationspartner und die öffentliche API von Qargo. Außerdem enthält er Links zu Ressourcen für manuelle Importe und Workflows für Palettennetzwerke sowie eine Anleitung zur Fehlerbehebung mit häufigen Fehlern und deren Lösung.
Begriffe
| Begriff | Beschreibung |
|---|---|
| Auftrag | Ein Versand- oder Sendungsdatensatz in Qargo. Aufträge können einen oder mehrere Stopps und zugehörige Dokumente enthalten. |
| Import | Der Prozess, bei dem Aufträge in Qargo erstellt oder aktualisiert werden, indem strukturierte Daten aus einem externen System gesendet werden. |
| Quellsystem | Das System, aus dem die Daten stammen, z. B. das eigene TMS, ERP, WMS oder ein Marktplatz. |
| Mapping | Die Umwandlung von Feldern aus dem Quellsystem in das Auftragsschema von Qargo. |
| DTO (Data Transfer Object) | Die strukturierten Nutzdaten, mit denen Auftragsdaten über Integrationen, EDI oder API an Qargo übermittelt werden. |
| Validierung | Prüfungen von Qargo, um sicherzustellen, dass eingehende Daten vollständig, korrekt formatiert und mit den Geschäftsregeln konsistent sind. |
| Bestätigung | Die Antwort an den Absender, die einen Erfolg, einen teilweisen Erfolg mit Warnungen oder einen Fehlschlag mit Fehlern meldet. |
| Idempotenzschlüssel | Eine eindeutige Kennung, die vom Client erzeugt und mit einer Anfrage gesendet wird, in der Regel im HTTP-Header. Sie stellt sicher, dass eine Anfrage ohne unbeabsichtigte Nebenwirkungen (z. B. Duplikate) sicher wiederholt werden kann. |
Überblick über die Importwege
Qargo unterstützt mehrere Importmethoden. Dieser Artikel konzentriert sich auf die drei häufigsten automatisierten Wege.
- Integrationspartner (vorgefertigte Konnektoren)
- EDI-Partner (branchenübliche Dokumentenflüsse)
- Qargo API (direkte programmatische Integration)
Für manuelle Datei-Uploads und spezielle Abläufe für Palettennetzwerke siehe:
Import über Integrationspartner
Am besten geeignet für Unternehmen, die gängige ERP-Systeme, WMS oder Logistikplattformen nutzen, für die bereits ein von Qargo zertifizierter Konnektor existiert.
-
Funktionsweise
- Der Partner-Konnektor exportiert Auftragsdaten nach Zeitplan oder bei einem Ereignis.
- Der Konnektor ordnet das Schema des Partners dem Auftrags-DTO von Qargo zu.
- Die Daten werden über einen sicheren, vom Konnektor festgelegten Kanal an Qargo übermittelt.
- Qargo validiert und übernimmt die Daten und sendet Bestätigungen und Fehlerdetails zurück.
-
Typische Funktionen
- Vom Partner gepflegte Voreinstellungen für das Feld-Mapping
- Inkrementelle Aktualisierungen bei Auftragsänderungen
- Unterstützung von Anhängen, wenn der Partner Dokumente bereitstellt
- Automatische Wiederholungsversuche und Dead-Letter-Verarbeitung
-
Was konfiguriert wird
- Zugangsdaten oder API-Schlüssel, die von Qargo oder dem Partner bereitgestellt werden
- Optionale Feldüberschreibungen und Regeln zur Normalisierung von Werten
- Standardverhalten bei fehlenden optionalen Feldern
- Benachrichtigungseinstellungen für fehlgeschlagene Importe
-
Wann diese Option sinnvoll ist
- Der schnellste Weg zum Go-live mit möglichst wenig individuellem Code ist gewünscht
- Der Partner unterstützt bereits Qargo oder ein sehr ähnliches Schema
Import über die Qargo API
Am besten geeignet für Teams, die volle Kontrolle und sofortiges Feedback wünschen, oder wenn kein Partner-Konnektor verfügbar ist.
-
Endpunktmodell
- Auftrag erstellen
- Auftrag aktualisieren
- Dokumente und Referenzen anhängen
- Aufträge zur Bestätigung abrufen und suchen
-
Hinweise zu den Nutzdaten
- ISO 8601 für Datums- und Zeitangaben mit Zeitzonenversatz verwenden
- Einheitliche Einheiten für Gewichte, Volumen und Anzahlen angeben
- Stabile externe IDs für Idempotenz und Duplikaterkennung mitsenden
- Nach Möglichkeit vollständige Adressblöcke einschließlich Ländercodes senden
-
Muster für Zuverlässigkeit
- Idempotenzschlüssel verwenden, um Anfragen bei Netzwerkfehlern sicher zu wiederholen
- Exponentielles Backoff bei 429- und vorübergehenden 5xx-Antworten implementieren
- Validierungsfehler protokollieren und an die Operations-Teams weitergeben
-
Sicherheit
- API-Schlüssel mit eingeschränktem Geltungsbereich oder OAuth wie bereitgestellt verwenden
- Zugangsdaten regelmäßig erneuern und keine Geheimnisse fest im Code hinterlegen
-
Wann diese Option sinnvoll ist
- Das Quellsystem liegt in eigener Hand und kann schnell angepasst werden
- Eine fein abgestimmte Kontrolle über Aufbau der Nutzdaten, Zeitpunkt und Wiederholungsversuche ist erforderlich
Checkliste für das Daten-Mapping
Vor dem Go-live prüfen, ob folgende Punkte zwischen Quellsystem und Qargo abgestimmt sind:
| Beteiligte | Kunde, Versender, Empfänger, Zahler und Kontaktrollen einheitlich gemappt. |
|---|---|
| Standorte | Namen, Adressen, Ländercodes und optional Geodaten; mehrdeutigen Freitext vermeiden. |
| Datum und Uhrzeit | Zeitfenster für Abholung, Lieferung und Bereitstellung in ISO 8601 mit expliziten Zeitzonen. |
| Warendetails | Positionszeilen, Packstücke, Paletten, Abmessungen, Kennzeichnungen für Gefahrgut. |
| Zusatzleistungen und Add-ons | Zuschläge und Service-Level-Optionen, die dem Add-on-Modell von Qargo zugeordnet sind. |
| Referenzen | Auftragsnummern des Kunden, Bestellnummern und Referenzen von Handelspartnern. |
| Dokumente | Anhänge für CMR, POD, Etiketten und Zolldokumente, sofern vorhanden. |
Operative Steuerung
| Duplikaterkennung | Eine stabile externe ID angeben. Qargo kann Duplikate je nach Konfiguration ablehnen oder per Upsert übernehmen. |
|---|---|
| Teilaktualisierungen | Festlegen, ob Aktualisierungen ganze Objekte ersetzen oder nur bestimmte Felder ändern. |
| Statusverarbeitung | Abstimmen, welche Ereignisse durch den Import gesetzt werden können und welche durch Operations gesteuert werden. |
| Umstellungsstrategie | Einen Zeitraum festlegen, in dem altes und neues System parallel laufen können, und wie Doppelbuchungen vermieden werden. |
Best Practices zur Vermeidung von Problemen
-
Vor dem Senden validieren
Im Quellsystem eine Vorabprüfung auf Pflichtfelder, Datums- und Zeitformate sowie Einheiten durchführen. -
Codes standardisieren
Eine Zuordnungstabelle für Services, Ausrüstungstypen und Zusatzleistungen pflegen, die auf Qargo-Codes verweist. -
Idempotenz nutzen
Beim Erstellen immer Idempotenzschlüssel mitsenden. Die Zuordnung von Schlüssel zu Auftragsnummer protokollieren. -
Überwachen und benachrichtigen
Benachrichtigungen für fehlgeschlagene Importe einrichten und Fehlerprotokolle in die eigenen Monitoring-Tools einbinden. -
Mapping dokumentieren
Ein laufend aktualisiertes Mapping-Dokument führen, damit spätere Änderungen keine Importe beeinträchtigen. -
Sicherstellen, dass alle Daten, insbesondere Datumsangaben, gültigen Formaten entsprechen.
-
Eindeutige Kennungen für neue Aufträge verwenden, um Fehlzuordnungen zu vermeiden.
-
Importdateien regelmäßig auf Tippfehler oder inkonsistente Daten prüfen.
Fehlerbehebung
Im Folgenden sind häufige Fehler bei Auftragsimporten, ihre wahrscheinlichen Ursachen und deren Lösung aufgeführt. Der Fehlertext kann je nach Importweg leicht abweichen.
Vorbelegungen für Aufträge (von Qargo admin konfiguriert)
Wenn vorbelegte Auftragsdaten falsch oder nicht wie erwartet erscheinen, kann dies mit dem Mapping des Auftragsimports zusammenhängen.

- Felder, die im Mapping des Auftragsimports enthalten sind, haben Vorrang vor allen anderen Standardwerten in der Plattform, z. B. vor Vorbelegungen aus dem Kundenprofil.
- Wo andere Optionen definiert sind, die mehrere auswählbare Optionen umfassen (z. B. Extras), werden die Werte aus dem Auftragsimport zusätzlich zu den bereits ausgewählten Optionen übernommen.

FAQ – Vorbelegungen
F. Wie lässt sich bestimmten Vorbelegungen Vorrang geben, wenn sie für dasselbe Zielfeld aus verschiedenen Quellen stammen können?
Beispiel: Start-/End-Zeitfenster – Vorbelegungen können definiert werden für:
- Transportservice
- Kunde
- Standort
- Zeitfenster
A. Die spezifischste Vorbelegung wird angewendet. Im obigen Beispiel folgt die Logik der Granularität der Auswahl: Zuerst wird der Transportservice ausgewählt, dann Kunde und Standorte, gefolgt vom Zeitfenster für den Stopp. In diesem Fall wird die Vorbelegung daher aus der letzten Auswahl (Zeitfenster) übernommen, da diese als spezifischste Option gilt
F. Lassen sich die Öffnungszeiten des Standorts vorbelegen, oder müssen sie für jeden importierten Auftrag manuell eingegeben werden? Gibt es eine schnelle Möglichkeit, die Zeiten zu übernehmen, zu denen die Standorte für Abholung / Lieferung verfügbar sind?
A. Ja, beim Import von Aufträgen lassen sich die Öffnungszeiten von Standorten vorbelegen und in die Zeitfenstereinstellungen des Stopps übernehmen. So ist klar ersichtlich, wann die Stoppaktion abgeschlossen werden kann, falls kein bestimmter Termin und kein bestimmtes Zeitfenster erforderlich ist. Ein Feature-Flag kann aktiviert werden, das für Auftragsimporte automatisch die am Standort definierten Öffnungszeiten verwendet.
Best Practices zur Vermeidung von Problemen
-
Vor dem Senden validieren
Im Quellsystem eine Vorabprüfung auf Pflichtfelder, Datums- und Zeitformate sowie Einheiten durchführen. -
Codes standardisieren
Eine Zuordnungstabelle für Services, Ausrüstungstypen und Zusatzleistungen pflegen, die auf Qargo-Codes verweist. -
Idempotenz nutzen
Beim Erstellen immer Idempotenzschlüssel mitsenden. Die Zuordnung von Schlüssel zu Auftragsnummer protokollieren. -
Überwachen und benachrichtigen
Benachrichtigungen für fehlgeschlagene Importe einrichten und Fehlerprotokolle in die eigenen Monitoring-Tools einbinden. -
Mapping dokumentieren
Ein laufend aktualisiertes Mapping-Dokument führen, damit spätere Änderungen keine Importe beeinträchtigen.
