---
title: "Integrationen – Aufträge in Qargo importieren"
description: "Aufträge über die API oder Partnerintegrationen in Qargo importieren. Mit Mapping, Validierung und Fehlerbehebung."
url: https://help.qargo.com/de/articles/450378-integrationen-auftraege-in-qargo-importieren
locale: de
updated: 2026-02-12
---

# Integrationen – Aufträge in Qargo importieren

## Einführung {#h_dd2958ae7f}

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 {#h_59ca24e154}

| **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 {#h_847e06915f}

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:

-   [Datenimport – Auftragsdaten importieren](https://help.qargo.com/de/articles/418636-data-import-importing-order-data)
-   [PalletLine-Auftragsimport](https://help.qargo.com/de/articles/143830-pn-palletline-order-import-export#h_34e1be7ccf)

### Import über Integrationspartner {#h_6e0d048f1b}

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 {#h_baa8e418df}

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

:::callout{tone="info"}
**🧰 Die technische Dokumentation zur Qargo API ist [hier](https://api.qargo.com/docs) verfügbar.**
:::

* * *

### Checkliste für das Daten-Mapping {#h_1e6174b22f}

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 {#h_d12ae0008a}

| 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 {#h_4c7206bfe1}

-   **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 {#h_b734cbfbc8}

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.

:::callout{tone="info"}
**_Missing required field: customer\_id_**

-   Symptom

    -   Fehler: Missing required field: customer\_id
-   Ursache

    -   Die Quelle hat keinen gemappten Kunden oder einen unbekannten Wert geliefert.
-   Lösung

    -   Sicherstellen, dass die Kundenstammdaten in Qargo vorhanden sind und das Mapping den richtigen externen Schlüssel verwendet.
    -   Bei Partnern das Mapping des Konnektors aktualisieren.
    -   Bei der API customer\_id oder eine auflösbare external\_customer\_ref mitsenden.
:::

:::callout{tone="info"}
**_Invalid date-time format for pickup\_window.start_**

-   Symptom

    -   Fehler: Invalid date-time. Expected ISO 8601 with timezone
-   Ursache

    -   Datum und Uhrzeit wurden ohne Zeitzone oder in einem Nicht-ISO-Format gesendet.
-   Lösung

    -   ISO-8601-Zeichenfolgen senden, z. B. 2025-03-12T08:00:00+01:00.
    -   Formate vor dem Senden im Quellsystem validieren.
:::

:::callout{tone="info"}
**_Unknown location: consignee\_address_**

-   Symptom

    -   Fehler: Location validation failed for consignee
-   Ursache

    -   Unvollständige oder mehrdeutige Adresse oder ein Verweis auf einen nicht vorhandenen gespeicherten Standort.
-   Lösung

    -   Vollständige Adresse einschließlich Ländercode angeben.
    -   Bei Verwendung von Standortreferenzen zuerst die Stammdaten synchronisieren.
:::

:::callout{tone="info"}
**_Unsupported addon code: LIFTGATE\_PREMIUM_**

-   Symptom

    -   Fehler: Addon code not recognised
-   Ursache

    -   Die Quelle verwendet einen Servicecode, der in Qargo nicht konfiguriert ist.
-   Lösung

    -   Den Code in Qargo hinzufügen oder einem unterstützten Add-on zuordnen.
    -   Codes vor der Übermittlung im Konnektor normalisieren.
:::

:::callout{tone="info"}
**_Duplicate order detected with external\_id=ABC-123_**

-   Symptom

    -   Fehler: Duplicate order
-   Ursache

    -   Die Idempotenzprüfung oder Duplikaterkennung hat ein wiederholtes Erstellen erkannt.
-   Lösung

    -   Bei einer beabsichtigten Wiederholung denselben Idempotenzschlüssel erneut verwenden und das vorherige Ergebnis prüfen.
    -   Bei einem echten Duplikat die external\_id ändern oder die Anfrage in eine Aktualisierung umwandeln.
:::

:::callout{tone="info"}
**_Document attachment rejected: file type not allowed_**

-   Symptom

    -   Fehler: File type not supported
-   Ursache

    -   Der Dateityp des Anhangs steht nicht auf der Liste der zulässigen Typen.
-   Lösung

    -   In ein unterstütztes Format konvertieren, in der Regel PDF oder die für den Workspace konfigurierten Bildtypen.
    -   Sicherstellen, dass die Integration MIME-Typen korrekt sendet.\
        ​
:::

:::callout{tone="info"}
**_API 429 Too Many Requests_**

-   Symptom

    -   HTTP-429-Antworten und Drosselungs-Header.
-   Ursache

    -   Lastspitzen überschreiten die Ratenbegrenzung.
-   Lösung

    -   Exponentielles Backoff implementieren und Retry-After-Header beachten.
    -   Batchgrößen gleichmäßiger gestalten und Importe in Zeiten geringer Auslastung planen.
:::

:::callout{tone="info"}
**_Hinweis „Fehler beheben?“ auf dem Auftragsimport-Bildschirm_**

-   Symptom

    -   Der Nutzer sieht während der Prüfung ein Banner oder Hinweise direkt im Formular.
-   Ursache

    -   Ein oder mehrere importierte Aufträge weisen Validierungsprobleme auf, die eine Eingabe durch den Disponenten erfordern.
-   Lösung

    -   Den Auftrag öffnen, die hervorgehobenen Felder prüfen und die Werte korrigieren.
    -   Wenn dasselbe Problem erneut auftritt, die Mapping-Regeln in der Quelle aktualisieren.
:::

### Vorbelegungen für Aufträge (von Qargo admin konfiguriert) {#h_3ac5923fbb}

Wenn vorbelegte Auftragsdaten falsch oder nicht wie erwartet erscheinen, kann dies mit dem Mapping des Auftragsimports zusammenhängen.

![](https://help.qargo.com/media/19487907ce21-image.png)

-   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.

![](https://help.qargo.com/media/d020757bc01f-image.png)

### FAQ – Vorbelegungen {#h_c3aa0333a8}

**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.

::video{src="/media/video/25c8b24b68d9-2025-11-17_11-49-48-1-.mp4"}

:::callout{tone="note"}
💬 Zur Aktivierung dieser Funktion den Qargo Support oder den zuständigen Account Manager kontaktieren.
:::

* * *

### Best Practices zur Vermeidung von Problemen {#h_c79fd5b2a4}

-   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.


## Verwandte Artikel

- [Integrationen – Qargo API – Was, warum und wie](https://help.qargo.com/de/articles/865547-integrationen-qargo-api-was-warum-und-wie.md)
- [Auftragsimport – vorlagenbasiertes Auftragsrouting – was, warum und wie.](https://help.qargo.com/de/articles/681640-auftragsimport-vorlagenbasiertes-auftragsrouting-was-warum-und-wie.md)
- [Datenimport – Standortdaten importieren](https://help.qargo.com/de/articles/413082-datenimport-standortdaten-importieren.md)
- [Datenimport: Was, warum, wie](https://help.qargo.com/de/articles/169976-datenimport-was-warum-wie.md)
- [Aufträge: Auftrag erstellen](https://help.qargo.com/de/articles/133885-auftraege-auftrag-erstellen.md)
