API-Referenz

Mit dem TMS-Add-on kann ein anderes System von Ihnen (ein BI-Werkzeug, ein Buchhaltungsprogramm, eine Plattform zur Sendungsverfolgung) über die TMS-API die Aufträge, Geschäftspartner, Fahrzeuge und Rechnungen Ihrer Organisation lesen, und Ihr eigenes Telematiksystem kann Fahrzeugpositionen senden. In den Worten der App: „Ein Schlüssel lässt ein anderes System TMS-Daten lesen, zum Beispiel Aufträge für Berichte, oder Fahrzeugpositionen aus seiner Telematik senden. Außer diesen Positionen ändert er nichts.“

Alles andere in Quanty nutzen Sie über die App unter app.quanty.ai. Die interne API der App wird nicht für Integrationen angeboten: Sie braucht eine angemeldete Sitzung und ändert sich ohne Ankündigung.

Bevor Sie beginnen

• Die Organisation hat das TMS-Add-on und einen bezahlten Plan. Ohne das Add-on wird jede Anfrage mit addon_required abgelehnt, solange der Plan nicht bezahlt ist mit payment_required.
• Nur ein Administrator der Organisation erstellt und widerruft API-Schlüssel, in den TMS-Einstellungen, API und Webhooks.
• Das System, das die API aufruft, braucht den Schlüssel, die Adresse Ihrer Quanty-API (sie steht im Beispiel im Schlüsseldialog) und diese Seite.

API-Schlüssel

1. Öffnen Sie TMS-Einstellungen, API und Webhooks und klicken Sie unter API-Schlüssel auf Schlüssel erstellen.
2. Füllen Sie den Dialog aus und klicken Sie auf Schlüssel erstellen.
3. Der Schlüssel wird einmal gezeigt, mit Kopieren und Beispiel: die ersten 50 Aufträge (Beispiel kopieren): „Wir zeigen diesen Schlüssel nur einmal. In der Liste bleibt nur sein Anfang; geht er verloren, widerrufen Sie ihn und erstellen Sie einen neuen.“
4. Fügen Sie den Schlüssel in dem System ein, das ihn benutzen soll, und klicken Sie auf Fertig.

Die Liste der Schlüssel zeigt Name, Zugriff, Erstellt, Zuletzt benutzt („noch nicht“ bis zur ersten Anfrage) und Status: Aktiv oder Widerrufen (mit dem Namen der Person, die widerrufen hat). Widerrufen im Menü eines Schlüssels stoppt ihn sofort: „Systeme, die ihn benutzen, verlieren sofort den Zugriff. Das lässt sich nicht rückgängig machen.“

Daten lesen

Verwenden Sie die Adresse aus dem Beispiel im Schlüsseldialog und senden Sie den Schlüssel als Bearer-Token:

GET /api/v1/ext/tms/orders?limit=50
Authorization: Bearer qk_…

Abfrageparameter

Seiten und regelmäßiges Abfragen

Die Antwort ist eine Seite, älteste Änderung zuerst:

{
  "items": [ { "id": "…", "number": "…", "updated_at": "…" } ],
  "next_cursor": "…"
}

1. Lesen Sie die erste Seite, mit updated_since, wenn Sie nur die letzten Änderungen wollen.
2. Solange next_cursor nicht null ist, lesen Sie weiter mit cursor auf diesem Wert (mit demselben updated_since).
3. Um später Änderungen abzufragen, starten Sie den nächsten Lauf mit updated_since einige Minuten vor der Zeit Ihres letzten Laufs.

Zeilen, die in den letzten 10 Sekunden geändert wurden, werden noch nicht ausgeliefert; sie kommen beim nächsten Lesen, deshalb geht eine Abfrage einige Minuten zurück. Zeilen mit demselben updated_at werden zwischen Seiten nie übersprungen oder wiederholt. Gelöschte Zeilen fehlen; stornierte behalten ihren Status. Antworten werden nie zwischengespeichert.

Felder

Jede Zeile hat id, created_at und updated_at sowie die Felder der passenden Tabelle in TMS Daten (siehe Tabellen in Quanty). Geldbeträge und andere Dezimalzahlen kommen als Text ("1234.50"), ganze Zahlen als Zahlen, Datumsangaben als YYYY-MM-DD (der Tag in polnischer Zeit), Zeitpunkte in UTC und Auswahlwerte als Codes. Ein nicht gesetzter Wert ist null.

orders (Aufträge)

contractors (Geschäftspartner)

vehicles (Fahrzeuge)

invoices (Rechnungen)

Interne Notizen, Dateien, IDs von Personen und Koordinaten werden nicht ausgeliefert. Datensätze aus Marcos TMS sind wie alle anderen enthalten.

Fehler

Eine Ablehnung hat einen Code und einen Satz (error_code, message), nie etwas vom Schlüssel.

Grenzen

Falsche Schlüssel anderer bremsen einen gültigen Schlüssel nie aus.

Fahrzeugpositionen senden

Für eine Telematik, die Quanty nicht selbst liest, kann Ihr eigenes System die Positionen senden. Die ganze Anleitung, mit jedem Feld, der Zuordnung der Fahrzeuge und allen Antworten, steht auf Eigenes System (API). Kurz:

1. Ein Administrator verbindet Eigenes System (API) unter Telematik: „Hier ist nichts einzutragen.“ Die Verbindung zeigt Empfang: Über die API, Letzte Daten und So senden Sie Daten mit der Adresse, dem nötigen Schlüssel und einer Beispielanfrage.
2. Erstellen Sie einen API-Schlüssel mit Telematik: Senden.
3. Ihr System sendet die Positionen:

POST /api/v1/ext/tms/telematics/positions
Authorization: Bearer qk_…
Content-Type: application/json

{
  "items": [
    {
      "vehicle": { "plate": "PO 1AB12" },
      "at": "2026-11-01T10:00:00Z",
      "lat": 52.40,
      "lng": 16.92,
      "speed_kmh": 82,
      "heading": 270,
      "odometer_km": 423434.5,
      "fuel_pct": 61,
      "fuel_l": 410,
      "driver": { "id": "D-17", "name": "Jan Kowalski" },
      "trailer": { "plate": "PO 9TR" }
    }
  ]
}

• vehicle nennt das Fahrzeug über seine Quanty-id, seine FIN (vin) oder sein Kennzeichen (plate). Ein Fahrzeug ohne Telematik wird bei der ersten Position verbunden; eines, das seine Positionen aus einer anderen Telematikverbindung bekommt, wird für diese Position abgelehnt.
• at ist ein ISO-Zeitpunkt (ohne Zeitzone als UTC gelesen) oder Unix-Sekunden; eine Zeit mehr als 15 Minuten nach der Uhr von Quanty wird abgelehnt, prüfen Sie also die Uhr des Senders. lat und lng sind Pflicht, der Rest ist optional. Der Name des Fahrers ist ein personenbezogenes Datum, wie bei jeder Telematik.
• Ein Feld, das eine Position weglässt, behält den letzten Wert des Fahrzeugs (Kraftstoff, Fahrer), und null löscht ihn. Der Kilometerstand des Fahrzeugs steigt nur, senden Sie also einen echten Wert. Ein optionaler Wert, der kein Messwert ist (eine Geschwindigkeit von -1, ein Kilometerstand von 0, ein Kraftstoff von "n/a"), wird weggelassen und unter ignored aufgeführt; die Position zählt trotzdem.

Die Antwort ist 200, wenn mindestens eine Position gespeichert wurde:

{
  "accepted": 1,
  "positions_added": 1,
  "older_than_stored": 0,
  "vehicles_linked": 0,
  "rejected": [ { "index": 3, "status": 404, "error_code": "…", "message": "…" } ],
  "ignored": [ { "index": 0, "field": "speed_kmh" } ]
}

Jede Position wird für sich beantwortet: Eine abgelehnte steht unter rejected mit ihrem Index, die anderen werden gespeichert. Derselbe Inhalt zweimal gesendet wird einmal gespeichert, und eine Meldung, die älter ist als die neueste des Fahrzeugs, kommt in seine Spur, ohne das Fahrzeug zurückzusetzen.

Eine ganze Anfrage wird abgelehnt mit:

Andere Wege, Daten zu bewegen

• Google Sheets: Zeilen aus einer Google-Tabelle nach Zeitplan importieren, mit einer Schlüsselspalte gegen Duplikate, oder eine Tabelle in die andere Richtung exportieren.
• Export: Jede Tabelle lässt sich über Weitere Aktionen im Raster als CSV, Excel oder PDF exportieren (siehe Projekte, Tabellen und Ansichten), und die TMS-Listen und -Berichte haben ihren eigenen Export.
• Automatisierungen (Beta): E-Mails, WhatsApp-Nachrichten und KSeF-Rechnungen zu Datensätzen einer Tabelle machen und auf neue und geänderte Datensätze reagieren.
• Freigabelinks: Dashboards und Präsentationen lassen sich per Link schreibgeschützt teilen (siehe Dashboards und Präsentationen).

Fragen zur API: support@quanty.ai.