REST-API für Ihre eigenen Systeme

Überblick

Die REST-API v1 von fleetfeat gibt Ihren eigenen Systemen — ERP, HR, Buchhaltung — lesenden Zugriff auf die Daten Ihrer Firma. Sie legen in fleetfeat einen Zugang an, wählen, welche Daten er lesen darf, und holen sich damit per OAuth2 ein Zugriffstoken. Die API ist in allen Paketen inklusive.

• Nur lesend: Außer dem Token-Endpunkt ist jeder Endpunkt ein GET; über die API ändern Sie keine Daten in fleetfeat.
• Ein Zugang gehört genau einer Firma und sieht nur deren Daten — immer die ganze Firma.
• JSON, Feldnamen in snake_case, alle Zeitangaben in UTC nach ISO 8601, Beträge in Cent.
• Listen mit Cursor-Paginierung und Filtern nach Zeitraum, Kennzeichen oder FIN.
• Höchstens 300 Aufrufe pro Minute je Zugang.

Schnellstart

Drei Schritte bis zur ersten Antwort. Die Beispiele nutzen curl; jede andere HTTP-Bibliothek funktioniert genauso.

1. Zugang anlegen

Melden Sie sich in fleetfeat an und öffnen Sie Einstellungen → API-Zugang. Den Bereich sieht nur, wer Zugriff auf die ganze Firma und das Recht „Berichte erstellen & exportieren“ hat — in der Regel der Super Admin.

Geben Sie dem Zugang eine Bezeichnung (z. B. „SAP Produktiv“) und wählen Sie unter „Freigegebene Daten“ nur die Scopes, die Ihre Anbindung braucht.

Nach dem Anlegen zeigt fleetfeat die Client-ID und das Client-Secret. Das Secret erscheint genau einmal; wir speichern es nur als Prüfsumme. Geht es verloren, erneuern Sie es an derselben Stelle („Secret erneuern“). „Entziehen“ sperrt den Zugang samt aller Tokens sofort.

2. Token holen

Ihr System tauscht Client-ID und Secret gegen ein Zugriffstoken (OAuth2 Client Credentials). Das Token gilt 60 Minuten; danach holen Sie einfach ein neues.

curl -s -X POST https://fleetfeat.de/api/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials

Antwort:

{
  "access_token": "ffat_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "vehicles:read service-orders:read"
}

3. Erste Abfrage

Mit dem Token im Header Authorization: Bearer … fragen Sie die Fahrzeuge Ihrer Firma ab:

curl -s "https://fleetfeat.de/api/v1/vehicles?limit=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Antwort (gekürzt):

{
  "data": [
    {
      "id": "…",
      "fin": "…",
      "license_plate": "…",
      "make": "…",
      "model": "…",
      "mileage_km": …,
      "updated_at": "…"
    }
  ],
  "next_cursor": "…"
}

Steht in der Antwort ein next_cursor, holen Sie die nächste Seite mit ?cursor=<Wert>. Auf der letzten Seite ist next_cursor null.

Scopes und Rechte

Ein Scope ist eine Datenart, die ein Zugang lesen darf. Beim Anlegen wählen Sie die Scopes; beim Token-Abruf kann Ihr System mit scope eine Teilmenge anfordern. Ohne Scope antwortet ein Endpunkt mit 403 insufficient_scope.

Ein Zugang gibt nie mehr heraus, als sein Anleger in der Oberfläche sieht. Deshalb verlangen einige Scopes beim Anlegen zusätzlich den passenden Rechteschalter aus der Teamverwaltung:

• tasks:read → „Fristen & Führerscheinkontrolle verwalten“
• cost-centers:read → „Kosten & TCO sehen“
• invoices:read → „Rechnungen & Belege sehen“

Ohne diesen Schalter lässt fleetfeat den Scope beim Anlegen nicht zu.

Limits und Paginierung

• Rate-Limit: 300 Aufrufe pro Minute je Zugang. Jede Antwort der Daten-Endpunkte auf einen gültigen Token trägt X-RateLimit-Limit und X-RateLimit-Remaining; beim Überschreiten kommt 429 mit Retry-After (Sekunden).
• Auch abgelehnte Aufrufe (403, 400) zählen gegen das Limit.
• Seitengröße: limit von 1 bis 200, ohne Angabe 50 Einträge.
• Download-Links für Dokumente, Rechnungs-PDFs und E-Rechnungen sind 5 Minuten gültig und werden ohne Bearer-Token abgerufen.
• Unbekannte Parameter lehnt die API mit 400 ab, statt sie still zu übergehen.

Fehlerformat

Jeder Fehler der Daten-Endpunkte hat dasselbe Format: ein Objekt error mit maschinenlesbarem code, einer englischen message und — bei Parameterfehlern — dem Feld field.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the scope \"drivers:read\"."
  }
}

Der Token-Endpunkt antwortet nach OAuth2-Standard (RFC 6749 §5.2) mit error und error_description, z. B. invalid_client bei falscher Client-ID oder falschem Secret.

Datenschutz

Über einen Zugang gelangen Daten Ihrer Firma in ein anderes System, je nach Scope auch personenbezogene Daten Ihrer Beschäftigten. Für dieses System und seinen Betreiber sind Sie verantwortlich: Es gehört in Ihr Verzeichnis der Verarbeitungstätigkeiten, und mit seinem Betreiber braucht es einen Auftragsverarbeitungsvertrag (AVV).

Fahrerdaten — Fahrerzuweisungen, der aktuelle Fahrer am Fahrzeug, Fahrer an Aufgaben, die Fahrerzuordnung bei Bußgeldern — gibt die API nur mit dem Scope drivers:read heraus.

Nie über die API: Führerscheindaten, Anhörungen zum Bußgeld, Notizen, Mailadressen.

Jeder authentifizierte Aufruf wird mit Zugang, Endpunkt (ohne Suchparameter), Status und Zeit protokolliert und nach 12 Monaten automatisch gelöscht.

Stabilitätszusage und Changelog

Unsere Zusage für Ihre Anbindung:

/v1 bleibt rückwärtskompatibel; neue Felder kommen ohne Vorwarnung, Entfernen/Umbenennen nur mit neuer Hauptversion und mindestens 6 Monaten Ankündigung.

Changelog

• Ergänzung ohne neue Version · 25.10.2026 — 403 driver_data_not_available an Fahrer-Endpunkten (/drivers, /fines), wenn die Person, die den Zugang angelegt hat, keine Fahrerdaten sehen darf oder nicht mehr zur Firma gehört; Fahrerfelder an den übrigen Endpunkten fehlen dann.
• Ergänzung ohne neue Version · 22.10.2026 — 403 module_not_available auch dann, wenn die Firma das Modul in ihren Einstellungen ausgeblendet hat (Bußgelder, Kostenstellen).
• Ergänzung ohne neue Version · 15.10.2026 — Neuer Aufgabenstatus erledigt_ausstehend (gemeldet, Freigabe durch die Fuhrparkleitung steht aus).
• Ergänzung ohne neue Version · 06.10.2026 — Neue Fahrzeugfelder max_speed_kmh und work_machine_kind.
• Ergänzung ohne neue Version · 03.10.2026 — Neue Fahrzeugfelder für Nutzfahrzeuge (z. B. gross_weight_kg, axle_count) und E-Fahrzeuge (z. B. battery_capacity_kwh, wltp_range_km).
• 1.2.0 · 27.09.2026 — Belegarten: /api/v1/invoices liefert neben Service-Rechnungen auch Abo-Rechnungen, Storno- und Korrekturbelege, mit kind und dem Verweis corrects_invoice_id.
• 1.1.0 · 26.09.2026 — Aufgaben, Dokumente der Fahrzeugakte (mit Download-Link), Bußgelder, Kostenstellen und Rechnungen (mit PDF und E-Rechnung), jeweils mit eigenem Scope.
• 1.0.0 · 26.09.2026 — Erste Fassung: Token-Endpunkt (OAuth2 Client Credentials), Fahrzeuge, Fahrerzuweisungen und Service-Aufträge.

Endpunkte

Alle Endpunkte der Version, erzeugt aus derselben Spezifikation, die der Server unter /api/v1/openapi.json ausliefert.

Datenmodelle

Fragen zur Anbindung? Schreiben Sie an info@fleetfeat.de.