Ortung REST-API: Fahrzeugdaten als JSON sicher in ERP, Zeiterfassung und Disposition einbinden

9. November 2026  |  Ortung  |  Schnittstellen und Integration

Fahrzeugdaten sind nur dann wirklich nützlich, wenn sie dort ankommen, wo Ihr Unternehmen arbeitet: im ERP-System, in der Zeiterfassung, in der Disposition, in Auswertungen und in den Programmen Ihrer Geschäftspartner. Die Ortungsplattform von Biricon IT Services bietet dafür ab sofort eine REST-Schnittstelle. Ihre eigene Software holt sich Fahrzeuge, Gruppen, Geozäune, Arbeitszeiten und Ereignisse als JSON – abgesichert mit OAuth 2.0 (Client Credentials) und signierten JWT-Token, beschrieben nach OpenAPI 3.1.

Dieser Beitrag zeigt, wie Sie die Schnittstelle im Kundenportal aktivieren, wie ein Abruf Schritt für Schritt abläuft, welche Endpunkte es gibt, wie sich die Ortung mit anderen Systemen verbinden lässt und welche Datenschutz- und Sicherheitsregeln dabei gelten.

Kurzfassung

Warum eine Schnittstelle? Interoperabilität statt Insellösung

Eine Ortungsplattform mit schöner Karte ist schnell eine Insel: Disponenten tippen Kilometerstände ab, die Personalverrechnung rechnet Arbeitszeiten nach, und im Reporting stehen Fahrzeugnamen, die es im ERP so nicht gibt. Jede dieser Handarbeiten kostet Zeit und ist eine Fehlerquelle.

Eine standardisierte Schnittstelle löst das, weil sie auf Standards setzt, die nahezu jede moderne Software spricht:

• HTTP und REST: Jede Programmiersprache, jedes Skript und jede Automatisierungsplattform kann Web-Abrufe absetzen.
• JSON: Das Datenformat ist lesbar, kompakt und in praktisch allen Umgebungen ohne Zusatzbibliothek verarbeitbar.
• OAuth 2.0: Das gängige Verfahren für den Zugriff von Programm zu Programm – ohne dass ein Passwort weitergegeben wird.
• OpenAPI 3.1: Die Schnittstellenbeschreibung ist maschinenlesbar. Entwickler erzeugen daraus Clients, Testfälle und Dokumentation, statt Felder von Hand nachzubauen.

Die Ortung bleibt dabei das führende System für Positions- und Fahrtdaten. Ihre anderen Systeme lesen diese Daten und ordnen sie über stabile Kennungen (vehicle_id, tracker_id, group_id) den eigenen Stammdaten zu.

Schritt 1: Zugang im Kundenportal aktivieren

Die Schnittstelle schalten Sie selbst frei, ohne Support-Ticket. Im Ortungsportal öffnen Sie den Bereich Verwaltung → REST-API und legen einen neuen Zugang an:

1. Bezeichnung: Ein sprechender Name, etwa der Name der Anwendung, die den Zugang nutzt. So erkennen Sie später, welcher Zugang wofür gedacht ist.
2. Token gültig für: Die Laufzeit der ausgestellten Token: 5 Minuten, 15 Minuten, 1 Stunde, 8 Stunden, 24 Stunden, 1 bis 5 Jahre oder unbegrenzt. Wir empfehlen Zugänge mit Ablauf; unbegrenzt ist die Ausnahme.
3. Erlaubte Bereiche: vehicles:read für Fahrzeuge, Gruppen und Geozäune, events:read für Ereignisse (Alarmtabelle) und Arbeitszeiten. Vergeben Sie nur, was die Anwendung wirklich braucht.

Nach dem Anlegen zeigt das Portal die Client-ID und das Client-Geheimnis. Das Geheimnis wird nur dieses eine Mal angezeigt: Speichern Sie es sofort in Ihrem Passwort- oder Geheimnisspeicher. Geht es verloren, erzeugen Sie ein neues – das macht allerdings alle bisher ausgestellten Token ungültig. Die Abbildung zeigt einen Testzugang; die Werte sind frei erzeugt und ohne Bedeutung.

Die Beschreibung der Schnittstelle finden Entwickler direkt auf der REST-API-Seite im Portal, sobald der Bereich freigeschaltet ist.

Schritt 2: Token holen (OAuth 2.0)

Ihre Anwendung tauscht Client-ID und Geheimnis gegen ein kurzlebiges Zugriffstoken. Das ist der Standardablauf Client Credentials:

curl -s -X POST https://IHRE-DOMAIN/ortung/api/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=IHRE_CLIENT_ID \
  -d client_secret=IHR_GEHEIMNIS

Die Antwort enthält access_token, token_type (Bearer), scope und, bei Zugängen mit Ablauf, expires_in in Sekunden. Bei Zugängen mit der Laufzeit unbegrenzt fehlt expires_in, das Token läuft nicht ab. Optional lässt sich per scope-Parameter einschränken, welche Bereiche das Token tragen soll.

Schritt 3: Daten abrufen

Mit dem Token rufen Sie die Endpunkte per GET auf. Das Token reist im Authorization-Header:

curl -s -H "Authorization: Bearer TOKEN" \
  "https://IHRE-DOMAIN/ortung/api/v1/tracker"

Dasselbe als kurzes Python-Beispiel, wie es in einem nächtlichen Abgleichsjob stehen könnte:

import requests

BASIS = "https://IHRE-DOMAIN/ortung/api/v1"

antwort = requests.post(BASIS + "/oauth/token", data={
    "grant_type": "client_credentials",
    "client_id": "IHRE_CLIENT_ID",
    "client_secret": "IHR_GEHEIMNIS",
}, timeout=30)
antwort.raise_for_status()
token = antwort.json()["access_token"]

kopf = {"Authorization": "Bearer " + token}
fahrzeuge = requests.get(BASIS + "/tracker", headers=kopf, timeout=30).json()
for f in fahrzeuge["trackers"]:
    print(f["vehicle_id"], f["name"])

Die Endpunkte im Überblick

Beispiele: Fahrzeuge, Gruppen, Arbeitszeit, Ereignisse

Fahrzeuge und Gruppen: /tracker und /groups

Die beiden Endpunkte liefern die Stammdaten Ihres Fuhrparks. Jedes Fahrzeug trägt eine vehicle_id und eine tracker_id; die Gruppen verweisen über vehicle_ids auf ihre Mitglieder. Damit bilden Sie Ihre Struktur in einem anderen System ab. Das Feld owned zeigt, ob das Fahrzeug Ihnen gehört oder Ihnen freigegeben wurde. Bei freigegebenen Fahrzeugen fehlen interne Felder wie die IMEI.

Arbeitszeit je Fahrzeug und Tag: /workinghours

Mit ?date=JJJJ-MM-TT erhalten Sie für jedes sichtbare Fahrzeug die Arbeitszeitauswertung des Tages: Sollstunden aus der hinterlegten Dienstzeit, Iststunden aus den Firmenfahrten, Differenz, erster Start und letztes Ende, Anzahl der Fahrten und die betrieblichen Kilometer. Feiertage, Urlaub und freie Tage sind über day_type gekennzeichnet. Private Fahrten fließen nicht ein, private Kilometer werden nicht ausgegeben. Mit vehicle_id lässt sich die Auswertung auf einzelne Fahrzeuge beschränken.

Ereignisse: /events

Der Endpunkt liefert die Alarmtabelle Ihrer Fahrzeuge mit dem Fahrzeugnamen und allen Werten (Zeitpunkt, Alarmart, Werte 1 bis 3, Adresse, Notizen, Position, Geschwindigkeit, Richtung). Der Zeitraum steuert sich über from und to (Datum oder Zeitpunkt, höchstens 31 Tage je Abruf); mit vehicle_id und alert lässt sich nach Fahrzeugen und Alarmarten filtern, mit limit die Menge je Fahrzeug begrenzen. Die Antwort nennt den abgedeckten Zeitraum, damit Ihre Software erkennt, ob sie vollständig ist. Die Werte im Bild sind frei gewählte Beispielwerte.

Einsatzszenarien: ERP, Zeiterfassung, Disposition, BI, Automatisierung

Die Schnittstelle ist bewusst allgemein gehalten. Sie nutzen sie überall, wo ein Programm Web-Abrufe und JSON versteht:

• ERP und Buchhaltung: Fahrzeuge und Gruppen als Stammdaten übernehmen, damit Kostenstellen und Fahrzeugnamen übereinstimmen. Betriebliche Kilometer je Fahrzeug und Tag fließen in die Kostenrechnung ein.
• Zeiterfassung und Lohnverrechnung: /workinghours liefert Soll und Ist je Tag. Erster Start und letztes Ende (in UTC) ersparen das manuelle Nachrechnen.
• Disposition und Transportmanagement: Gruppen und Geozäune spiegeln Ihre Touren- und Kundenstruktur; Ereignisse zeigen, was unterwegs passiert ist.
• Reporting und Business Intelligence: Die Daten lassen sich zeitgesteuert in Datenlager und Auswertungen laden. Die stabilen IDs erleichtern das Zusammenführen mit anderen Quellen.
• Automatisierung: Skripte und Workflow-Plattformen können Ereignisse abfragen und daraus eigene Abläufe starten, etwa eine interne Benachrichtigung bei einem Geschwindigkeitsalarm.
• Partner- und Kundenportale: Fahrzeuge, die Ihnen von Geschäftspartnern freigegeben wurden, sind über Ihren Zugang ebenfalls abrufbar – mit genau den Einschränkungen, die der Partner festgelegt hat.

Weil die Schnittstellenbeschreibung nach OpenAPI 3.1 vorliegt, erzeugen Entwickler aus ihr in den meisten Sprachen fertige Client-Bibliotheken. Das spart Zeit und verringert Tippfehler bei Feldnamen.

Sicherheit und Datenschutz

Eine Schnittstelle zu Positionsdaten verlangt klare Regeln. Diese gelten durchgängig:

• Gleiche Sichtbarkeit wie im Portal: Ihr Zugang sieht Ihre eigenen Fahrzeuge und die Ihnen freigegebenen – nicht mehr. Hat ein Partner bestimmte Felder (etwa Adresse oder Geschwindigkeit) für Sie ausgeblendet, fehlen sie auch in der Schnittstelle.
• Private Fahrten bleiben privat: Ziele, Notizen und Koordinaten privater Fahrten werden ausgeblendet, private Fahrten fließen nicht in die Arbeitszeit ein.
• Keine internen Felder: Berechtigungen und Livedaten werden nicht ausgegeben. Die IMEI sehen Sie nur bei eigenen Fahrzeugen.
• Minimale Rechte: Die Bereiche vehicles:read und events:read sind getrennt vergebbar, beide sind rein lesend.
• Geheimnis nur einmal sichtbar: Gespeichert wird nur ein Hash. Ein neues Geheimnis entwertet alle bisherigen Token; ein abgeschalteter Zugang lässt sich sofort nicht mehr verwenden.
• Signierte Token: Die Token sind mit einem serverseitigen Schlüssel signiert und tragen Bereich und Ablaufzeit.
• Abwehr von Fehlversuchen: Der Token-Endpunkt bremst wiederholte falsche Anmeldungen je Herkunftsadresse.

Für die Verarbeitung der Daten in Ihrem eigenen System bleiben Sie verantwortlich, besonders wenn Fahrerdaten betroffen sind. Klären Sie Betriebsvereinbarung und Zweckbindung, bevor Sie Auswertungen mit Personenbezug einrichten.

Kontingent und sinnvolle Abrufintervalle

Damit die Schnittstelle für alle Kunden verlässlich bleibt, gilt je Zugang ein Kontingent von 7 Abrufen je Minute und 30 Abrufen je Stunde. Jeder Datenabruf zählt als ein Abruf; das Holen des Tokens zählt nicht. Abgewiesene Abrufe verbrauchen kein Kontingent. Wird das Kontingent überschritten, antwortet die Schnittstelle mit HTTP 429 und dem Header Retry-After, der die Wartezeit in Sekunden nennt.

Mit 30 Abrufen je Stunde lässt sich gut planen. Ein Beispiel, das im Rahmen bleibt:

Lesen Sie die Retry-After-Angabe aus, statt sofort erneut zu versuchen, und fragen Sie nur den Zeitraum seit dem letzten erfolgreichen Abruf ab. Brauchen Sie mehr Durchsatz, richten Sie einen weiteren Zugang für eine andere Anwendung ein – das Kontingent gilt je Zugang.

Fehlercodes und Fehlerbehandlung

Die Fehlerantworten sind ebenfalls JSON mit einem Fehlercode (error) und einer lesbaren Beschreibung (error_description). So lassen sich Fehler in Ihrer Software sauber protokollieren.

Häufige Fragen

Wie aktiviere ich die REST-API der Ortung?

Im Kundenportal unter Verwaltung → REST-API einen neuen Zugang anlegen: Bezeichnung vergeben, die Token-Laufzeit wählen und die erlaubten Bereiche festlegen. Das Portal zeigt danach Client-ID und Client-Geheimnis. Das Geheimnis wird nur einmal angezeigt.

Welche Authentifizierung verwendet die Schnittstelle?

OAuth 2.0 mit dem Grant-Typ Client Credentials. Die Anwendung tauscht Client-ID und Geheimnis gegen ein signiertes JWT, das sie als Bearer-Token mitschickt.

Wie lange ist ein Token gültig?

Das stellen Sie je Zugang ein: 5 Minuten, 15 Minuten, 1 Stunde, 8 Stunden, 24 Stunden, 1 bis 5 Jahre oder unbegrenzt. Unbegrenzte Token gelten, bis das Geheimnis erneuert oder der Zugang abgeschaltet wird.

Welche Daten kann ich abrufen?

Fahrzeuge (/vehicles, /tracker), Gruppen (/groups), Geozäune (/geozones), Arbeitszeiten je Fahrzeug und Tag (/workinghours) und Ereignisse der Alarmtabelle (/events). Sichtbar sind Ihre eigenen und die Ihnen freigegebenen Fahrzeuge.

Sehe ich über die Schnittstelle mehr als im Portal?

Nein. Die Sichtbarkeit und die Feldfreigaben sind dieselben wie im Portal. Private Fahrten werden ausgeblendet.

Wie viele Abrufe sind erlaubt?

7 Abrufe je Minute und 30 Abrufe je Stunde und Zugang. Darüber antwortet die Schnittstelle mit HTTP 429 und nennt per Retry-After die Wartezeit.

In welches Format liefert die Schnittstelle die Daten?

JSON, mit Zeitangaben im ISO-8601-Format in UTC. Die Schnittstelle ist nach OpenAPI 3.1 beschrieben, sodass Entwickler Clients automatisch erzeugen können.

Kann ich mehrere Anwendungen anbinden?

Ja. Legen Sie je Anwendung einen eigenen Zugang an, bis zu fünf je Benutzer. Jeder Zugang hat eigene Bereiche, eine eigene Laufzeit und ein eigenes Kontingent und lässt sich einzeln abschalten.

Unterstützung durch Biricon IT Services

Sie möchten Ihre Fahrzeugdaten in bestehende Systeme einbinden, wissen aber nicht, wo Sie anfangen sollen? Wir unterstützen bei der Planung der Anbindung, bei der Umsetzung von Abgleichsjobs und bei der Auswahl der passenden Abrufintervalle.

Jetzt Kontakt aufnehmen

Stand: 9. November 2026. Funktionsumfang und Kontingent können sich ändern; maßgeblich ist die Beschreibung im Kundenportal.