Skip to main content
Qargo

Datenimport – Import von Auftragsdaten

Ein umfassender Leitfaden zum Import von Aufträgen in Qargo.

Inhaltsverzeichnis
  1. Anpassung der Vorlage mit benutzerdefinierten Feldern
  2. Einschränkungen und Hinweise

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:

  1. Auf den Link klicken: Vorlage für den Import von Auftragsdaten
  2. Sobald die Vorlage geöffnet ist, Datei öffnen und Herunterladen auswählen
  3. 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) mit pickup_name sowie delivery address (vollständige Adresse oder einzelne Bestandteile) mit delivery_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).

  1. Benutzerdefiniertes Feld in Qargo erstellen: Zu Configuration > Additional fields navigieren, um ein neues benutzerdefiniertes Feld zu erstellen. Die zugewiesene field ID notieren.
  2. Benutzerdefiniertes Feld zur Vorlage hinzufügen: Eine Spalte im Format order_custom_field__FIELD_ID hinzufügen (z. B. order_custom_field__invoicegroup).
  3. Tipps zur Formatierung: Auf exakt übereinstimmende Spaltenüberschriften achten, Daten mit vorangestelltem Apostroph vermeiden und die Namenskonvention für das Tabellenblatt „Import“ einhalten.
  4. 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, nicht VAT_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_number einen 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.