Skip to main content
Qargo

Integrationen – Qargo API – Was, warum und wie

Qargo mit externen Systemen für Aufträge, Fahrtaktualisierungen, Stammdaten und Buchhaltung verbinden, einschließlich API-Einrichtung, Zugangsdaten, Tests und Fehlerbehebung.

Inhaltsverzeichnis
  1. Einführung
  2. Voraussetzungen
  3. Integrationstypen
  4. Anwendungsfälle
  5. Begriffe
  6. API-Verbindung einrichten
  7. Auftrags-API testen
  8. Konfiguration des Auftragsimports
  9. Prüfen, ob ein Auftragsimport erfolgreich war
  10. Buchhaltungs-API und Abrechnungsstellen
  11. Fehlerbehebung
  12. Häufige Fragen
  13. Weiterführende Dokumentation

Einführung

Was ist die Qargo API?

  • Eine Reihe von Verbindungen, über die andere Systeme Daten an Qargo senden und Daten von Qargo empfangen können.
  • Sie umfasst Auftragseingabe und Status, die Ausführung von Fahrten mit Subunternehmern, das Synchronisieren von Stammdaten und die Buchhaltung.

Warum sie nutzen?

  • Sie vermeidet doppelte Eingaben zwischen Qargo und den anderen Systemen, mit denen ein Transportunternehmen arbeitet, z. B. Kundensysteme, Systeme von Subunternehmern, Buchhaltungssoftware sowie Flotten- oder HR-Tools.
  • Die Daten bleiben in beiden Systemen ohne manuelle Importe auf dem neuesten Stand.

Wie funktioniert sie?

  • Qargo weist der Partei, die die Verbindung aufbaut, eine Integrator-ID zu.
  • Ein Super admin erstellt einen API-Client für die passende Rolle und gibt die Zugangsdaten sicher weiter.
  • Qargo schließt die erforderliche Einrichtung im Konto ab. Anschließend wird die Integration getestet und live geschaltet.

Voraussetzungen

  • Super admin-Rechte in Qargo.
  • Eine von Qargo vergebene Integrator-ID (siehe Schritt 1 unten).
  • Für die Rolle Kunde: Zugang zum Kundenportal muss für den betreffenden Kunden aktiviert sein.
  • Für Buchhaltungs-Clients, die Rechnungen buchen: eine eingerichtete Buchhaltungs-API-Integration, die mit der richtigen Abrechnungsstelle verknüpft ist.

Integrationstypen

Es gibt drei Integrationstypen. Der Typ bestimmt, wie die Integration eingerichtet wird.

  • Mandant: eine direkte Verbindung zwischen Qargo und einem Drittsystem, das das Transportunternehmen nutzt, z. B. einer Buchhaltungssoftware.
  • Kunde: eine Verbindung vom eigenen System eines Kunden zu Qargo, z. B. um Aufträge über das Kundenportal zu übermitteln.
  • Subunternehmer: eine Verbindung vom eigenen System eines Subunternehmers zu Qargo, z. B. um Fahrtaktualisierungen aus dem eigenen TMS an Qargo zurückzusenden.

Anwendungsfälle

  • Ein Kunde möchte Aufträge direkt aus dem eigenen System an Qargo senden, statt sie im Kundenportal einzugeben.
  • Ein Subunternehmer möchte Fahrtzuweisungen empfangen und Stopp-Aktualisierungen sowie PODs aus dem eigenen TMS zurücksenden.
  • Ein neuer Fahrer oder ein neues Fahrzeug, der bzw. das in einem externen Flotten- oder HR-System angelegt wird, soll automatisch in den Ressourcen von Qargo erscheinen.
  • Die Finanzabteilung möchte, dass Rechnungen und Gutschriften in die Buchhaltungssoftware übertragen und Zahlungsstatus an Qargo zurückgemeldet werden.
  • Eine Unternehmensgruppe mit mehreren juristischen Personen möchte, dass das Buchhaltungssystem jeder Einheit nur die eigenen Rechnungen bucht.

Begriffe

Begriff Definition
API Eine Möglichkeit für zwei Systeme, automatisch Daten auszutauschen.
Mandant Das Qargo-Konto selbst, also das Transportunternehmen, das Qargo nutzt.
Integrationstyp Für wen die Verbindung eingerichtet wird: für den Mandanten, einen seiner Kunden oder einen seiner Subunternehmer.
API-Client Ein Satz Anmeldedaten (eine Client-ID und ein Secret), mit dem ein externes System sich für eine Rolle mit Qargo verbinden kann.
Rolle Die Art des Zugriffs eines API-Clients: Auftragsverwaltung, Kunde, Stammdatenverwaltung oder Buchhaltung.
Integrator-ID Eine eindeutige ID von Qargo, die angibt, wer die Integration erstellt, damit bei einem Problem die richtige Person kontaktiert werden kann.
Secret Der private Schlüssel, der beim Erstellen eines API-Clients einmalig angezeigt wird. Er kann nicht erneut angezeigt werden.
Stammdaten Zentrale Datensätze wie Kunden, Subunternehmer, Fahrer und Fahrzeuge.
Abrechnungsstelle Das rechtliche oder interne Unternehmen der Gruppe, das eine Rechnung ausstellt.
POD Liefernachweis: das unterschriebene Dokument oder Foto, das eine Lieferung bestätigt.
Auftragsexport Ein Endpunkt, der die vollständigen Daten eines bestehenden Auftrags zurückgibt und als Vorlage für neue Auftragsanfragen dient.
Konfiguration des Auftragsimports Von Qargo verwaltete Einstellungen auf Kontoebene, die steuern, wie über die API empfangene Aufträge in Qargo übernommen werden.
API-Prüfung Der erste Schritt eines Auftragsimports. Qargo prüft, ob die Nachricht korrekt aufgebaut ist (Validierung der Nutzlast).
Qargo-Import Der zweite Schritt eines Auftragsimports. Qargo übernimmt die Daten in das Konto (Validierung im Mandanten).

API-Verbindung einrichten

Schritt 1: Integration und Integrator-ID anfordern

  1. Eine E-Mail an success@qargo.com senden, um die Integrationsanfrage zu starten.

  2. Folgende Angaben machen:

    • Integrationspartner: Unternehmensdaten sowie Name und E-Mail-Adresse des Hauptansprechpartners, mit dem Qargo zusammenarbeitet. Wenn ein Drittanbieter oder externer Integrator die Verbindung erstellt, dessen Angaben statt der des Qargo-Kontoinhabers mitteilen.
    • Typ und Umfang: der benötigte Integrationstyp (z. B. Auftragseingabe) und die erwartete Funktionalität. Siehe Weiterführende Dokumentation am Ende dieses Artikels.
    • Besondere Anforderungen: alle spezifischen funktionalen Anforderungen.
  3. Warten, bis sich ein Integrations Delivery Manager (IDM) meldet. Qargo vergibt dann die Integrator-ID.

Schritt 2: API-Client für die benötigte Rolle hinzufügen

  1. Zu Konfiguration > Organisationseinstellungen > Nutzer navigieren und bis zum Ende der Seite scrollen.
  2. Auf API-Client hinzufügen klicken.

  1. Die benötigte Rolle auswählen:

Schritt 3: Client-Details ausfüllen

  • Integrator-ID: immer erforderlich. Die von Qargo erhaltene ID eingeben.

  • Unternehmen: nur für die Rolle Kunde erforderlich.

‼️ Schritt 4: Secret vor dem Speichern kopieren‼️

Schritt 5: Zugangsdaten sicher weitergeben

Client-ID und Secret sicher an die Partei weitergeben, die die Integration erstellt.

Schritt 6: Qargo informieren

Qargo informieren, sobald die Clients eingerichtet sind. Vor Beginn der Tests kann eine zusätzliche Einrichtung auf Kontoebene nötig sein, z. B. das Mapping für den Auftragsimport bei der Auftrags-API oder die Einrichtung der Buchhaltungs-API.


Auftrags-API testen

Am einfachsten ist es, zunächst einige typische Testaufträge manuell in Qargo zu erstellen und diese dann als Vorlage für die API-Anfragen zu verwenden.

Vorlage mit dem Auftragsexport abrufen

  1. Einen Testauftrag in Qargo öffnen und die order_id aus der URL kopieren (den Teil nach orders/).

  2. Den Endpunkt Auftragsexport aufrufen:
    GET<https://api.qargo.com/v1/orders/order/{order_id}/export>

  3. Die zurückgegebenen Daten prüfen. Der Vergleich eines echten Qargo-Auftrags mit seiner Datenstruktur zeigt, wie jedes Feld auszufüllen ist.

Neuen Auftrag erstellen

  1. Automatisch generierte Felder wie Barcodes entfernen.
  2. Den Code der Importkonfiguration angeben (standardmäßig API).
  3. Eindeutige Kennungen wie die Referenznummer des Kunden und order_identifier ändern.
  4. Den Auftrag hochladen: POST <https://api.qargo.com/v1/orders/order/upload>

Der Auftrag erscheint dann je nach Konfiguration des Auftragsimports entweder im Tab Aufträge oder im Tab Auftragsimporte.


Konfiguration des Auftragsimports

Die Konfiguration des Auftragsimports wird auf Kontoebene festgelegt und kann nur von Qargo geändert werden. Diese Einstellungen steuern, wie sich über die API empfangene Aufträge verhalten.

Einstellung Funktion
Aufträge automatisch erstellen Sendet importierte Aufträge direkt in den Tab Aufträge oder in den Tab Auftragsimporte, wo sie zuerst bestätigt werden müssen.
Aktualisierungen aktivieren Steuert, ob Aktualisierungen über die API angenommen werden.
Duplikaterkennung aktivieren Markiert doppelte Importe automatisch, damit sie nicht zweimal importiert werden.
Änderungen automatisch übernehmen Übernimmt Änderungen ohne manuelle Prüfung. Kann auf einen gewählten Auftragsstatus begrenzt werden; danach müssen Aktualisierungen wieder manuell genehmigt werden.
Stornierungen automatisch übernehmen Funktioniert wie Änderungen automatisch übernehmen, jedoch für Stornierungen.

Prüfen, ob ein Auftragsimport erfolgreich war

Qargo prüft einen über die API gesendeten Auftrag in zwei Schritten. Ein Bestehen von Schritt 1 bedeutet nicht, dass der Auftrag in Qargo vorhanden ist.

Schritt Was passiert Wo das Ergebnis angezeigt wird
1. API-Prüfung Qargo prüft, ob die Nachricht korrekt aufgebaut ist. In der Validierungsantwort, die an das externe System zurückgesendet wird.
2. Qargo-Import Qargo übernimmt die Daten in das Konto. Der Auftrag wird erstellt oder aktualisiert. Dies läuft nach Schritt 1 im Hintergrund. Im Importstatus und am Auftrag in Qargo.

Was die API-Prüfung bestätigt

  • Die Nachricht folgt der erwarteten Struktur (JSON oder XML).
  • Pflichtfelder sind vorhanden und haben die richtigen Datentypen und Formate.
  • Werte wie Einheiten und Auftragsarten sind zulässig.

Was die API-Prüfung nicht bestätigt

  • Ob die Kunden, Standorte, Produkte und Ressourcen im Auftrag im Qargo-Konto vorhanden sind.
  • Ob Geschäftsregeln und Kontokonfiguration das Erstellen oder Ändern des Auftrags zulassen.
  • Ob die Auftragsreferenz korrekt zugeordnet wird, sodass Qargo einen neuen Auftrag erstellt oder den richtigen bestehenden Auftrag aktualisiert.
  • Ob sich ein bestehender Auftrag noch in einem Status befindet, der Änderungen zulässt.

Ein Qargo-Import kann fehlschlagen oder abgelehnt werden, auch wenn die API-Prüfung bestanden wurde.

Erfolgreichen Import bestätigen

  1. Eine positive API-Prüfung nicht als Bestätigung werten, dass der Auftrag vorhanden ist.
  2. Den Importstatus des Auftrags prüfen. Der Status Fehler bedeutet, dass der Qargo-Import fehlgeschlagen ist. Eine manuelle Korrektur in Qargo ist erforderlich.
  3. Den Tab Auftragsimporte oder den Auftrag in Qargo öffnen, um das Ergebnis zu prüfen.
  4. Wenn der Import weiterhin fehlschlägt, Auftragsreferenz, Zeitstempel und Fehlermeldung an den Qargo-Support senden.

Beispiele: Ergebnisse von API-Prüfung und Qargo-Import

API-Fehler (= API-Validierung fehlgeschlagen)

API-Erfolg

API-Status Upsert-Fehler (= Import in der Oberfläche fehlgeschlagen)

Fehleransicht beim Auftragsimport (= Import in der Oberfläche fehlgeschlagen)

Auftragsimport korrigieren (Oberfläche)

Auftragsimport korrigieren (API)


Buchhaltungs-API und Abrechnungsstellen

Die Buchhaltungs-API unterstützt mehrere Abrechnungsstellen. Das sorgt für mehr Sicherheit und eine genauere Zugriffskontrolle bei Unternehmensgruppen, die aus mehreren Unternehmen heraus fakturieren.

Enthaltene Funktionen

  • Abrechnungsstelle auf Rechnungen: Die Rechnungs-Endpunkte enthalten einen Abschnitt billing_entity, der angibt, zu welcher Abrechnungsstelle eine Rechnung gehört.
  • Mehrere Integrationen: Es können mehrere Buchhaltungs-API-Integrationen erstellt werden, die jeweils mit einer Abrechnungsstelle verknüpft sind.
  • Filter: Rechnungen und Aufgaben können nach ihrer Abrechnungsstelle gefiltert werden.
  • Eigene API-Clients: Buchhaltungs-API-Clients werden auf der Einstellungsseite Buchhaltungs-API-Integration erstellt. Diese Clients werden für den vollen Funktionsumfang benötigt.

Auswirkungen auf externe Integrationen

  • Eingeschränktes Buchen: Ein Integrator kann Rechnungen nur für die Abrechnungsstelle abschließen (buchen), die mit seinen Zugangsdaten verknüpft ist.

  • Anzeigen: Rechnungen anderer Abrechnungsstellen bleiben im Rahmen der normalen Anzeigeberechtigungen sichtbar, können aber nicht gebucht werden.

  • Wo die Zugangsdaten erstellt werden, ist entscheidend:

    • Um Rechnungen zu buchen (Status auf Abgeschlossen setzen), müssen die Zugangsdaten auf der Einstellungsseite Buchhaltungs-API-Integration erstellt und mit der richtigen Abrechnungsstelle verknüpft werden.
    • Zugangsdaten, die unter Organisationseinstellungen erstellt wurden, können eine Rechnung nicht auf Abgeschlossen setzen und keine Rechnungen auflisten, die noch auf die Synchronisierung warten.

Fehlerbehebung

Problem Lösung
Testaufträge erscheinen nicht im Tab Aufträge Wenn Aufträge automatisch erstellen deaktiviert ist, gehen Importe in den Tab Auftragsimporte und müssen dort bestätigt werden.
Die API-Prüfung war erfolgreich, aber der Auftrag ist nicht in Qargo Der Qargo-Import ist möglicherweise fehlgeschlagen. Den Importstatus und den Tab „Auftragsimporte“ prüfen. Siehe „Prüfen, ob ein Auftragsimport erfolgreich war“.
Die API-Prüfung war erfolgreich, aber der Auftrag ist nicht in Qargo Der Qargo-Import ist möglicherweise fehlgeschlagen. Den Importstatus und den Tab Auftragsimporte prüfen. Siehe Prüfen, ob ein Auftragsimport erfolgreich war.
Ein über die API importierter Auftrag zeigt in Qargo einen Fehler Fehler, die die API nicht blockieren, landen im Tab Auftragsimporte. Ein Key-User oder Admin kann sie dort prüfen und beheben. Der Importstatus „Fehler“ bedeutet, dass der Qargo-Import fehlgeschlagen ist und eine manuelle Korrektur nötig ist.
Das Secret ging nach dem Schließen der Ansicht verloren Das Secret kann nicht wiederhergestellt werden. Einen neuen API-Client erstellen und das Secret vor dem Speichern kopieren.
Für die Rolle Kunde kann kein API-Client erstellt werden Zuerst Zugang zum Kundenportal für diesen Kunden aktivieren.
Ein Buchhaltungs-Client kann keine Rechnungen buchen Den Client unter Accounting API Integration settings erstellen und mit der richtigen Abrechnungsstelle verknüpfen. Clients aus Organisation settings können nicht buchen.
Ein Integrator kann einige Rechnungen nicht buchen Diese Rechnungen gehören zu einer anderen Abrechnungsstelle. Zugangsdaten verwenden, die mit dieser Abrechnungsstelle verknüpft sind.
Es werden wiederholt doppelte Aufträge importiert Qargo bitten, Duplikaterkennung aktivieren einzuschalten.
Aktualisierungen über die Kunden-API werden nicht automatisch übernommen Das ist so vorgesehen. Kundenaktualisierungen folgen den Regeln des Kundenportals und müssen in der Ansicht für den Auftragsimport genehmigt werden.

Häufige Fragen

F. Bietet Qargo eine API an?
A. Ja! Qargo bietet APIs für Auftragseingabe und Status, die Ausführung von Fahrten, das Synchronisieren von Stammdaten und die Buchhaltung, für die Integrationstypen Mandant, Kunde und Subunternehmer.


F. Kann eine API-Verbindung ohne Qargo eingerichtet werden?
A. Nein. Für die Einrichtung einer Integration sind Super admin-Rechte und die Unterstützung des Qargo-Teams erforderlich. Der erste Schritt ist eine E-Mail an success@qargo.com.


F. Kann eine Buchhaltungsintegration Rechnungen für alle Abrechnungsstellen buchen?
A. Nein. Jeder Buchhaltungs-API-Client kann nur Rechnungen für die Abrechnungsstelle buchen, mit der er verknüpft ist. Rechnungen anderer Abrechnungsstellen bleiben sichtbar, können aber nicht gebucht werden.


Weiterführende Dokumentation

API-Referenzdokumentation (api.qargo.com)