Datenimport – Import von Auftragsdaten
Ein umfassender Leitfaden zum Import von Aufträgen in Qargo.
Ein umfassender Leitfaden zum Import von Auftragsdaten. Dieser Import ermöglicht die Massenerstellung von Aufträgen sowohl für Sandbox- als auch für Live-Mandanten. Das ist nützlich für die Datenübernahme, die Systemintegration und für Testzwecke. Dieser Artikel beschreibt die konkreten Anforderungen, Best Practices und häufige Probleme.
📖 Wichtige Begriffe
- Auftrag: Eine Anfrage für einen Transportauftrag oder einen Service.
- Externe ID: Eine eindeutige Kennung eines Auftrags aus einem externen System.
- Stopp: Ein bestimmter Standort oder Punkt auf einer Fahrt, an dem eine Aufgabe ausgeführt wird.
- Produkt: Eine bestimmte Ware oder ein bestimmtes Gut, das transportiert wird.
- Service: Die Art des erbrachten Service (z. B. Transport).
✅ Wichtige Anforderungen für den Import von Aufträgen
Vor dem Import von Auftragsdaten müssen die folgenden Anforderungen und Hinweise beachtet werden, um die Datenintegrität sicherzustellen.
- Voraussetzung Nutzerberechtigung: Die Funktion für den manuellen Import von Auftragsdaten ist eingeschränkt. Nur Nutzer mit Superadmin-Rechten können den Auftragsimport durchführen.
- Voraussetzung Unternehmen: Alle für den Auftrag relevanten Kunden müssen bereits im Qargo-System vorhanden sein.
- Voraussetzung Produkte: Alle im Auftrag enthaltenen Produkte müssen bereits im Produktkatalog vorhanden sein.
- Eindeutige Identifizierung: Die Auftragsnummer oder die Externe ID dient als eindeutige Kennung des Auftrags.
- Datums- und Zeitformat: Alle Datums- und Zeitfelder müssen das in der Vorlage angegebene Format haben, damit der Import nicht fehlschlägt (JJ/MM/TT).
Validierungsregeln: Numerische Felder dürfen nur positive Werte enthalten (mit Ausnahme von Feldern wie absolute_min_temperature_value und absolute_max_temperature_value). Datumsfelder müssen das Format YYYY-MM-DD haben. Dropdown-Felder müssen den vordefinierten Werten entsprechen. Außerdem sind Importe auf 100 Zeilen pro Datei begrenzt.
🛠️ Auftragsimport Schritt für Schritt
Für einen erfolgreichen Import von Auftragsdaten sind die folgenden Schritte auszuführen.
Schritt 1: Importfunktion bestätigen (oder Aktivierungsstatus prüfen)
Ob die Funktion für den manuellen Datenimport aktiviert wurde, muss mit dem Account Manager abgeklärt werden.
Schritt 2: Vorlage herunterladen
Für das Hochladen von Auftragsdaten steht eine eigene Tabellenvorlage zur Verfügung. Um die Daten bearbeiten und hochladen zu können, muss eine Kopie der Vorlage heruntergeladen werden:
- Auf den Link klicken: Vorlage für den Import von Auftragsdaten
- Sobald die Vorlage geöffnet ist, Datei öffnen und Herunterladen auswählen
- Die Vorlage (im Format .xlsx oder .csv) auf dem Computer speichern und mit der Eingabe der Unternehmensdaten beginnen.

Schritt 3: Excel-Vorlage ausfüllen
Die Vorlage öffnen und mit den erforderlichen Daten befüllen. Die Vorlage enthält Spaltenüberschriften, die den Feldern in Qargo entsprechen.
-
Pflichtfelder: Um einen einfachen Auftrag zu erstellen, müssen die folgenden Felder enthalten sein:
transport_service,customer_code,order_reference_number(eindeutig für jede Zeile),pickup_date,delivery_date,pickup address(vollständige Adresse oder einzelne Bestandteile) mitpickup_namesowiedelivery address(vollständige Adresse oder einzelne Bestandteile) mitdelivery_name. -
Formatierung: Auf das vorgegebene Datenformat (z. B. Datumsangaben, Zahlen, Text) ist genau zu achten.
-
Benennung benutzerdefinierter Felder: Bei der Verwendung benutzerdefinierter Felder müssen die Spaltenüberschriften der Namenskonvention mit doppeltem Unterstrich folgen (z. B.
order_custom_field__FIELD_ID).
Anpassung der Vorlage mit benutzerdefinierten Feldern
Mit Mappings für benutzerdefinierte Felder lassen sich Daten in Felder importieren, die auf die Anforderungen bestimmter Kunden zugeschnitten sind. Diese Felder müssen vor der Konfiguration des Mappings angelegt und passend benannt werden. Die Namenskonvention für benutzerdefinierte Felder in Importdateien verwendet zwei Unterstriche im Spaltennamen (z. B. custom_fields__example).
- Benutzerdefiniertes Feld in Qargo erstellen: Zu
Configuration > Additional fieldsnavigieren, um ein neues benutzerdefiniertes Feld zu erstellen. Die zugewiesenefield IDnotieren. - Benutzerdefiniertes Feld zur Vorlage hinzufügen: Eine Spalte im Format
order_custom_field__FIELD_IDhinzufügen (z. B.order_custom_field__invoicegroup). - Tipps zur Formatierung: Auf exakt übereinstimmende Spaltenüberschriften achten, Daten mit vorangestelltem Apostroph vermeiden und die Namenskonvention für das Tabellenblatt „Import“ einhalten.
- Konfiguration testen: Eine Testdatei für den betreffenden Kunden importieren, um zu prüfen, ob die Daten korrekt in das benutzerdefinierte Feld übernommen werden.
Einschränkungen und Hinweise
- Kundenspezifische Konfiguration: Mappings für benutzerdefinierte Felder werden für bestimmte Kunden konfiguriert. Werden Daten für einen anderen Kunden importiert, wird das benutzerdefinierte Feld nicht befüllt.
- Änderungen am Mapping: Wird dasselbe Mapping für benutzerdefinierte Felder für weitere Kunden benötigt, muss eine Aktualisierung des Mappings angefordert oder das Mapping für jeden Kunden separat konfiguriert werden.
Schritt 4: Datei hochladen
Zum Hochladen der fertigen Datei zum Modul Aufträge navigieren, die Registerkarte Auftragsimporte auswählen und auf Aus Datei importieren klicken.

Anschließend muss die Quelle des Imports ausgewählt werden. Wenn die Quelle eine manuell hochgeladene Vorlage ist, die Quellintegration Manuell auswählen.

Danach kann das Dokument hochgeladen werden. Treten Fehler auf, erscheint eine Meldung mit den Problemen, und das System schlägt mögliche Lösungen vor.

Schritt 5: Prüfen und abschließen
Die vom System erkannten Validierungsfehler beheben und den Import abschließen, indem der Auftrag bzw. die Aufträge erstellt werden.

📝 Details zur Vorlage für den Auftragsimport
Dieser Abschnitt erläutert die Excel-Vorlage für den Auftragsimport Feld für Feld, einschließlich Datenformaten, Pflichtfeldern und Best Practices für das Befüllen der einzelnen Spalten.
| Spaltenname | Pflicht/optional | Anmerkungen | Beispiel |
|---|---|---|---|
| transport_service | Optional | In Qargo konfigurierter Transportservice | Transport 2 |
| customer_code | Optional | In der Anwendung verwendeter Kundencode. Muss exakt mit dem Kundencode eines bereits in Qargo importierten Kundendatensatzes übereinstimmen. Wird in Kombination mit dem Anzeigenamen verwendet, um die Eindeutigkeit des Auftrags sicherzustellen. | 2322 |
| customer_name | Optional | Muss exakt mit dem Anzeigenamen eines bereits in Qargo importierten Kundendatensatzes übereinstimmen. Wird in Kombination mit dem Kundencode verwendet, um die Eindeutigkeit des Auftrags sicherzustellen. | Qargo |
| customer_reference_number | Optional | Eine Referenznummer für die interne Nachverfolgung des Kunden. | CUST-REF-001 |
| order_reference_number | Pflichtfeld | Eine allgemeine Referenznummer für den Auftrag. | |
| order_requested_price | Optional | Der Wert muss eine numerische Darstellung des Preises sein. Die Währung richtet sich nach der für den Mandanten konfigurierten Währung. | 50 |
| order_service_level_code | Optional | Ein eindeutiger Code, der das Servicelevel kennzeichnet. | EXP-01 |
| pickup_date | Optional | JJ/MM/TT | 2026/01/20 |
| pickup_time_start | Optional | HH:MM:SS | 12:00:00 |
| pickup_time_end | Optional | HH:MM:SS | 13:00:00 |
| pickup_name | Optional | ||
| pickup_full_address | Optional | Die vollständige Hauptadresse des Abholstandorts. | 123 Transport Way, London, E16 2NZ |
| pickup_address_line_1 | Optional | ||
| pickup_address_line_2 | Optional | ||
| pickup_postcode | Optional | ||
| pickup_city | Optional | London | |
| pickup_country | Optional | GB | |
| pickup_notes | Optional | ||
| pickup_reference_number | Optional | ||
| delivery_name | Optional | ||
| delivery_date | Optional | Jahr/Monat/Tag | 2016/09/20 |
| delivery_time_start | Optional | HH:MM:SS | 13:00:00 |
| delivery_time_end | Optional | HH:MM:SS | 13:00:00 |
| delivery_full_address | Optional | Die vollständige Hauptadresse des Lieferstandorts. | 123 Transport Way, London, E16 2NZ |
| delivery_address_line_1 | Optional | ||
| delivery_address_line_2 | Optional | ||
| delivery_postcode | Optional | ||
| delivery_city | Optional | Brussels | |
| delivery_country | Optional | BE | |
| delivery_notes | Optional | ||
| delivery_reference_number | Optional | ||
| absolute_min_temperature_value | Optional | Niedrigste Temperatur, die das Produkt verträgt. | |
| absolute_max_temperature_value | Optional | Höchste Temperatur, die das Produkt verträgt. | |
| volume_lt | Optional | ||
| quantity | Optional | ||
| weight_kg | Optional | ||
| goods_description | Optional | ||
| pallet_spaces | Optional | Anzahl der Standard-Palettenstellplätze, die das Produkt belegt. | |
| loading_meters | Optional | ||
| adr_un_number | Optional | ||
| packaging_type | Optional | ||
| packaging_size | Optional | ||
| product_name | Optional | In Qargo angezeigter Produktname | Aardappelen |
🔎 Behebung häufiger Fehler beim Auftragsimport
Dieser Abschnitt behandelt konkrete Fehler, die beim Import von Auftragsdaten auftreten können.
-
Unternehmen nicht gefunden: Damit ein Auftrag in Qargo eindeutig identifiziert und verwaltet werden kann, muss die Kombination aus Externer ID und Kundenname eindeutig sein.
-
Standort nicht gefunden: Ein häufiger Fehler tritt auf, wenn die Standortadresse eines Stopps mit keinem vorhandenen Standort im System übereinstimmt.
-
Produkt nicht gefunden: Stimmt der Name eines Produkts im Auftrag mit keinem Produkt im Katalog überein, schlägt der Import fehl.
-
Falsches Datums-/Zeitformat: Ein häufiges Problem bei Auftragsimporten ist ein falsch formatiertes Datum oder eine falsch formatierte Uhrzeit. Dadurch schlägt der Import fehl.
-
Adressfelder: Das Feld Land erfordert einen zweistelligen Code (z. B. GB, nicht „UK“). Die Alpha-2-Codes sind in dieser Liste zu finden.
-
Groß-/Kleinschreibung bei Spaltenüberschriften: Spaltenüberschriften müssen in der korrekten Groß- und Kleinschreibung eingegeben werden (z. B.
vat_number, nichtVAT_number). Bei falscher Schreibweise werden die Daten in dieser Spalte ohne Hinweis ignoriert und nicht importiert, da das System die Überschrift nicht erkennt. -
Fehler durch vorangestellten Apostroph: Daten in einer Zelle dürfen nicht mit einem Apostroph (’) beginnen. Wird ein Apostroph verwendet, erkennt das System den Wert nicht, und es kann ein Fehler auftreten. Diese Regel gilt nur dann nicht, wenn der Artikel ausdrücklich angibt, dass für ein bestimmtes Feld ein Apostroph zu verwenden ist.- Benutzerdefinierte Felder werden nicht befüllt: Prüfen, ob das Mapping des Felds für dessen Entitätsebene korrekt ist (z. B. Stopp-Ebene, Auftragsebene, Sendungsebene). Felder auf Sendungsebene benötigen beispielsweise das Überschriftsformat
consignment_custom_field__[FIELD_ID]. Ebenso sicherstellen, dass die Spaltenüberschriften gemäß der Vorgabe formatiert sind (z. B.order_custom_field__[FIELD_ID]mit doppeltem Unterstrich). -
Abgleich des Dateiformats: Stimmen der ausgewählte Importtyp und das Format der hochgeladenen Datei nicht überein (z. B. Hochladen einer XLSX-Datei, wenn das System auf CSV eingestellt ist), kann der Import ohne konkrete Fehlermeldung fehlschlagen. Um Probleme zu vermeiden, sicherstellen, dass das Dateiformat den Konfigurationseinstellungen des Systems entspricht.
-
Importierter Wert wird nicht übernommen: Wird das benutzerdefinierte Feld beim Import nicht befüllt, Folgendes sicherstellen:
- Die Importdatei verwendet die korrekte Namenskonvention für das benutzerdefinierte Feld.
- Der Import wird für den Kunden durchgeführt, für den das Mapping konfiguriert wurde.
-
Test mit falschem Kunden: Beim Testen oder Importieren für einen anderen Kunden wird das Mapping nicht angewendet. Prüfen, ob die Testdatei dem richtigen Kunden zugeordnet ist.
-
Eindeutige Auftragskennungen: Jede Zeile muss in der Spalte
order_reference_numbereinen eindeutigen Wert haben, um Importfehler zu vermeiden. -
Transportservice erforderlich: In jeder Zeile muss die Art des Transportservice angegeben sein. Ein fehlender Wert führt zu Fehlern oder hängenden Importen.
✨ Best Practices für den Import von Aufträgen
Für einen reibungslosen und korrekten Import empfiehlt es sich, die folgenden Best Practices zu beachten.
- Voraussetzungen zuerst importieren: Vor dem Import von Aufträgen muss unbedingt sichergestellt sein, dass alle zugehörigen Unternehmen, Standorte und Produkte bereits erfolgreich in das System importiert wurden.
- Mit einer kleinen Charge testen: Es empfiehlt sich, den Importvorgang zunächst mit einer kleinen Stichprobe von 5–10 Aufträgen zu testen, um vor dem vollständigen Import zu prüfen, ob die Daten korrekt formatiert sind.
➡️ Nächste Schritte
Nach dem erfolgreichen Import stehen die Aufträge im Modul „Aufträge“ zur Verfügung. Dort können sie im Rahmen der Transportabwicklung geplant, Fahrern zugewiesen und übermittelt werden.
📈 Anwendungsfälle für den Auftragsimport
Der Auftragsimport ist ein wertvolles Werkzeug für mehrere zentrale Geschäftsprozesse.
- Tests in der Sandbox: Der wichtigste Anwendungsfall ist die schnelle Erstellung großer Mengen an Testdaten in einem Sandbox-Mandanten. So lassen sich Schulungen durchführen, Workflows testen und die Möglichkeiten der Plattform demonstrieren, ohne eine Live-Umgebung zu beeinträchtigen.
- Systemmigration: In manchen Fällen kann ein einmaliger Import genutzt werden, um historische oder offene Aufträge aus einem Altsystem zu migrieren.
