Fleetiva API

Einführung

Was die API kann

Die Fleetiva API verbindet Ihr System mit Fahrdiensten, die mit Fleetiva arbeiten: Fahrdienste für Menschen mit Beeinträchtigungen, Schülerbeförderung, Kranken- und Seniorenfahrten. Ein angebundenes System legt dort Anfragen an, fragt ihren Bearbeitungsstand ab und liest Stammdaten wie Kunden.

Heute kann die API: Anfragen anlegen (POST /inquiries) und ihren Status abfragen (GET /inquiries/{id}) sowie Kunden lesen und abgleichen (GET /customers). Weitere Bereiche wie Fahrgäste, Fahrten und Touren kommen hinzu, ohne dass sich vorhandene Aufrufe ändern (siehe Versionen).

Begriffe

• Fahrdienst: das Unternehmen, das die Fahrten durchführt und Fleetiva nutzt. Ihm gehören die Anfragen.
• Zugang: die Zugangsdaten eines angebundenen Systems, angelegt vom Fahrdienst, mit einem Schlüssel und Bereichen.
• Anfrage: der Wunsch nach einer oder mehreren Fahrten, mit anfragender Person, Fahrgästen und Einwilligung.
• Kunde: Einrichtung, Behörde, Kostenträger oder Privatperson, für die der Fahrdienst fährt.
• Fahrgast: eine Person, die befördert werden soll. Jeder Fahrgast wird eine Position der Anfrage.
• Posteingang: die Liste in Fleetiva, in der der Fahrdienst neue Anfragen sieht und bearbeitet.
• Übernahme: der Fahrdienst übernimmt eine Anfrage in seine Planung.

Schnellstart

1. Zugang erhalten

Den Schlüssel legt der Fahrdienst in Fleetiva an: Einstellungen → Integrationen → API-Zugänge, mit dem Bereich „Anfragen anlegen“. Er beginnt mit flt_ und wird nur einmal angezeigt. Lassen Sie ihn sich auf sicherem Weg geben, nicht per E-Mail oder Chat, und speichern Sie ihn nur auf Ihrem Server, nie in einer Webseite oder App.

2. Basis-URL

Alle Aufrufe gehen an diese Adresse, immer mit https://. Verwenden Sie sie genau so: Folgt ein Client einer Weiterleitung auf einen anderen Host, lässt er den Header Authorization weg, und der Aufruf scheitert mit 401.

https://www.fleetiva.de/api/v1

3. Anfrage senden

Senden Sie die Anfrage als JSON, mit Ihrem Schlüssel und einem Idempotency-Key, den Sie für diese Anfrage selbst vergeben, zum Beispiel Ihre Buchungsnummer. Zum Ausprobieren senden Sie zusätzlich den Header Fleetiva-Dry-Run: true: Dann prüft Fleetiva alles und legt nichts an (siehe Nur prüfen).

curl -X POST 'https://www.fleetiva.de/api/v1/inquiries' \
  -H "Authorization: Bearer $FLEETIVA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: booking-2026-11-0042' \
  --data-binary @- <<'JSON'
{
  "requester": {
    "role": "institution",
    "first_name": "Petra",
    "last_name": "Schulz",
    "email": "p.schulz@example.org",
    "phone": "+49 30 1234567",
    "organization": "Tagesförderstätte Sonnenhof",
    "postal_address": {
      "street": "Lindenallee",
      "house_number": "12",
      "zip": "10115",
      "city": "Berlin"
    }
  },
  "passengers": [
    {
      "first_name": "Jonas",
      "last_name": "Weber",
      "birth_year": 2012,
      "pickup": {
        "street": "Gartenweg",
        "house_number": "4",
        "zip": "10117",
        "city": "Berlin"
      },
      "dropoff": {
        "street": "Lindenallee",
        "house_number": "12",
        "zip": "10115",
        "city": "Berlin"
      },
      "trip_kind": "recurring",
      "requested_date": "2026-12-01",
      "requested_time_window": "arrival by 8:00",
      "return_trip": true,
      "return_time_window": "15:30",
      "needs": {
        "wheelchair": true
      }
    }
  ],
  "message": "Monday to Friday, school days only.",
  "consent": {
    "given": true,
    "text_version": "2026-11"
  }
}
JSON

Dasselbe aus JavaScript oder TypeScript auf dem Server, etwa in einer Next.js-Route:

const response = await fetch('https://www.fleetiva.de/api/v1/inquiries', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FLEETIVA_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': booking.id, // your own ID, the same on every retry
  },
  body: JSON.stringify(inquiry),
});

if (response.status === 201 || response.status === 200) {
  const { id } = await response.json(); // store it with the booking
} else if (response.status === 429 || response.status === 503) {
  // 429: wait Retry-After seconds, 503: wait a moment — then send the same request again
} else {
  const problem = await response.json(); // problem.code, problem.issues, problem.request_id
}

4. Antwort auswerten

201 heißt: die Anfrage ist angelegt. Speichern Sie die id, damit Sie den Status abfragen können. 200 mit duplicate: true heißt: diese Anfrage kam schon einmal an, es entsteht keine zweite. Bei 429 warten Sie die Sekunden aus Retry-After, bei 503 einen Moment, und senden dieselbe Anfrage mit demselben Idempotency-Key erneut.

HTTP/1.1 201
Location: /api/v1/inquiries/0b7c6d1e-2f3a-4b5c-8d9e-0f1a2b3c4d5e

{
  "id": "0b7c6d1e-2f3a-4b5c-8d9e-0f1a2b3c4d5e",
  "duplicate": false
}

5. Status abfragen

Mit der id fragen Sie den Bearbeitungsstand ab. Sie sehen nur Anfragen, die über Ihren eigenen Zugang angelegt wurden.

curl 'https://www.fleetiva.de/api/v1/inquiries/0b7c6d1e-2f3a-4b5c-8d9e-0f1a2b3c4d5e' \
  -H "Authorization: Bearer $FLEETIVA_API_KEY"

HTTP/1.1 200

{
  "id": "0b7c6d1e-2f3a-4b5c-8d9e-0f1a2b3c4d5e",
  "status": "in_progress",
  "received_at": "2026-11-02T09:15:00+00:00"
}

6. Testen

Eine Sandbox gibt es nicht. Prüfen Sie Ihre Aufrufe zuerst mit Fleetiva-Dry-Run: true, am einfachsten in der Testkonsole. Für echte Testanfragen legt der Fahrdienst einen eigenen Test-Zugang an (siehe Test-Zugang).

Zugang und Testen

Schlüssel

Den Zugang legt der Fahrdienst in Fleetiva an: Einstellungen → Integrationen → API-Zugänge. Dafür braucht er den Tarif Professional oder Enterprise. Der Schlüssel beginnt mit flt_ und wird genau einmal angezeigt; Fleetiva speichert ihn nicht im Klartext.

Der Schlüssel ist ein Passwort für den Fahrdienst. Lassen Sie ihn sich auf sicherem Weg geben, nicht per E-Mail oder Chat, und hinterlegen Sie ihn nur auf Ihrem Server, nie im Quelltext einer Webseite oder App. Erneuert der Fahrdienst den Schlüssel, gilt der alte sofort nicht mehr; ein gesperrter Zugang bekommt 401.

Bereiche

Ein Zugang darf nur, was seine Bereiche erlauben. Fehlt der Bereich für einen Aufruf, antwortet die API mit 403 und dem Code forbidden.

• inquiries.create (in Fleetiva „Anfragen anlegen“): Anfragen anlegen und den Status der über diesen Zugang angelegten Anfragen abfragen.
• master_data.read (in Fleetiva „Stammdaten lesen“): Kunden und Fahrgäste lesen und abgleichen.
• accounting.read (in Fleetiva „Buchhaltung lesen“): zusammen mit include=billing die Abrechnungsdaten eines Kunden oder Fahrgasts, z. B. Bankverbindung, USt-IdNr. oder Rechnungsanschrift.
• health_data (in Fleetiva „Gesundheitsdaten“): zusammen mit include=health die Gesundheitsdaten eines Fahrgasts. Jeder Abruf wird für den Fahrdienst protokolliert.

Test-Zugang

Eine Sandbox gibt es nicht, getestet wird gegen das echte System. Für die Entwicklung legt der Fahrdienst einen eigenen Zugang an, zum Beispiel „Buchungsformular Test“. Echte Testanfragen erscheinen mit diesem Namen in seinem Posteingang; er lehnt sie ab und löscht den Test-Zugang, wenn Ihre Anbindung läuft. Für den Betrieb legt er einen eigenen Zugang an.

Nur prüfen

Mit dem Header Fleetiva-Dry-Run: true prüft ein anlegender Aufruf alles, was der echte Aufruf prüft: Schlüssel, Bereich, ob die API-Zugänge beim Fahrdienst aktiv sind, die Grenzen, alle Felder, Adressen und die Einwilligung. Angelegt, gespeichert oder gemeldet wird nichts. Bei Erfolg antwortet die API mit 204 ohne Inhalt, sonst mit demselben Fehler wie der echte Aufruf.

Nicht geprüft wird, ob der Idempotency-Key schon für eine andere Anfrage benutzt wurde. Ein Prüfaufruf zählt als lesender Aufruf. Ohne den Header oder mit false wirkt der Aufruf echt; jeder andere Wert wird mit 400 abgewiesen.

curl -X POST 'https://www.fleetiva.de/api/v1/inquiries' \
  -H "Authorization: Bearer $FLEETIVA_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: booking-2026-11-0042' \
  -H 'Fleetiva-Dry-Run: true' \
  --data-binary @- <<'JSON'
{
  "requester": {
    "role": "institution",
    "first_name": "Petra",
    "last_name": "Schulz",
    "email": "p.schulz@example.org",
    "phone": "+49 30 1234567",
    "organization": "Tagesförderstätte Sonnenhof",
    "postal_address": {
      "street": "Lindenallee",
      "house_number": "12",
      "zip": "10115",
      "city": "Berlin"
    }
  },
  "passengers": [
    {
      "first_name": "Jonas",
      "last_name": "Weber",
      "birth_year": 2012,
      "pickup": {
        "street": "Gartenweg",
        "house_number": "4",
        "zip": "10117",
        "city": "Berlin"
      },
      "dropoff": {
        "street": "Lindenallee",
        "house_number": "12",
        "zip": "10115",
        "city": "Berlin"
      },
      "trip_kind": "recurring",
      "requested_date": "2026-12-01",
      "requested_time_window": "arrival by 8:00",
      "return_trip": true,
      "return_time_window": "15:30",
      "needs": {
        "wheelchair": true
      }
    }
  ],
  "message": "Monday to Friday, school days only.",
  "consent": {
    "given": true,
    "text_version": "2026-11"
  }
}
JSON

HTTP/1.1 204

Testkonsole

In der Referenz hat jeder Aufruf ein Feld „Ausprobieren“. Geben Sie oben in der Referenz Ihren Schlüssel ein, passen Sie Parameter und Inhalt an und senden Sie den Aufruf. Die Konsole zeigt Status, Header und Antwort und den passenden curl-Befehl.

Der Schlüssel bleibt nur in diesem Browser-Tab, er wird nicht gespeichert und nur an /api/v1 dieser Adresse gesendet. „Nur prüfen“ ist voreingestellt. Im Betrieb gehört der Schlüssel weiter nur auf Ihren Server.

Konzepte

Von der Anfrage zur Fahrt

Eine Anfrage ist ein Wunsch, keine Buchung. Sie landet im Posteingang des Fahrdiensts, und alle mit dem Recht dazu werden benachrichtigt. Der Fahrdienst prüft die Anfrage und übernimmt sie in seine Planung oder lehnt sie ab.

Alles Weitere, etwa Rückfragen, Zusage und Fahrtzeiten, klärt der Fahrdienst mit der anfragenden Person. Die API meldet den Status der Anfrage.

Status

Der Status einer Anfrage ist immer einer dieser Werte:

Idempotenz

Netzwerke verlieren Antworten. Damit eine Wiederholung keine zweite Anfrage anlegt, trägt jeder anlegende Aufruf den Header Idempotency-Key: 1 bis 120 sichtbare ASCII-Zeichen, je Anfrage ein eigener Wert, zum Beispiel Ihre Buchungsnummer oder eine UUID.

Kommt derselbe Schlüssel mit demselben Inhalt noch einmal, antwortet die API mit 200, duplicate: true und der vorhandenen id. Mit anderem Inhalt weist sie den Aufruf mit 422 ab (idempotency_key_reused). Zum Inhalt zählen anfragende Person, Fahrgäste und Nachricht, nicht die Einwilligung. Ein Schlüssel gilt je Zugang und bleibt an seine Anfrage gebunden.

Einwilligung und Gesundheitsdaten

Die Bedarfe (needs) sind Gesundheitsdaten nach Art. 9 DSGVO. Holen Sie vor dem Absenden die Einwilligung der Person ein und senden Sie mit jeder Anfrage die Version des Einwilligungstexts mit, den sie gesehen hat (consent.text_version). Fleetiva speichert diese Version als Nachweis. Ohne Einwilligung nimmt die API keine Anfrage an.

consent.given_at ist optional; ohne Angabe gilt der Zeitpunkt des Eingangs. Liegt der Zeitpunkt mehr als 5 Minuten in der Zukunft, wird die Anfrage abgewiesen (in_future).

Listen und Abgleich

Eine Liste antwortet mit data und next_cursor. Für die nächste Seite schicken Sie next_cursor unverändert als cursor mit, mit denselben Filtern. null heißt: Es gibt keine weiteren Datensätze. Eine Seite hat 50 Einträge, mit limit bis zu 200.

Die Datensätze kommen nach ihrer letzten Änderung sortiert, die ältesten zuerst. Ändert sich ein Datensatz, während Sie blättern, kommt er weiter hinten noch einmal. Speichern Sie deshalb nach id: anlegen, wenn neu, sonst überschreiben.

So halten Sie eine Kopie aktuell:

• Merken Sie sich die Startzeit jedes Abgleichs. Beim nächsten Mal fragen Sie ab dieser Zeit minus ein paar Minuten, denn eine Änderung trägt den Zeitpunkt, an dem sie begonnen hat.
• GET /customers?updated_since=… blättern und jeden Datensatz nach id speichern.
• GET /customers/deleted?since=… mit derselben Zeit blättern und diese Datensätze bei sich löschen.

Für Fahrgäste gilt dasselbe mit /passengers und /passengers/deleted.

Löschungen bleiben 90 Tage abrufbar. Liegt since weiter zurück, antwortet die API mit 400 und dem Grund sync_window_exceeded. Dann laden Sie alle Datensätze neu.

Feldgruppen

Sensible Teile eines Datensatzes sind Feldgruppen. Sie kommen nur, wenn der Aufruf sie mit include anfordert und der Zugang den passenden Bereich hat. Ohne Anforderung fehlt der Schlüssel der Gruppe in der Antwort; mit Anforderung ist er immer da, leere Felder sind null.

• billing (Bereich accounting.read): Abrechnungsdaten eines Kunden (Steuernummer, USt-IdNr., Leitweg-ID, Zahlungsart, Bankverbindung) bzw. eines Fahrgasts (Name und Anschrift für Rechnungen, Steuersatz).
• health (Bereich health_data, nur für API-Zugänge): Gesundheitsdaten eines Fahrgasts – medizinische Hinweise, Allergien, Notfallkontakt, Hinweise zu den Bedarfen und die Häkchen Autismus, Seh- und kognitive Beeinträchtigung. Jeder Fahrgast, der mit dieser Gruppe ausgeliefert wird, landet im Protokoll des Fahrdiensts (Zugang, Zeitpunkt, request_id). Kann Fleetiva den Abruf nicht protokollieren, antwortet die API mit 503 statt mit Daten.

Fehlt der Bereich für eine angeforderte Gruppe, antwortet die API mit 403 (forbidden), ohne Daten zu lesen.

Technische Regeln

Basis-URL

Alle Pfade dieser Seite hängen an https://www.fleetiva.de/api/v1. Verwenden Sie die Adresse genau so: Folgt ein Client einer Weiterleitung auf einen anderen Host, lässt er den Header Authorization weg, und der Aufruf scheitert mit 401.

Nur HTTPS. Ein Aufruf über http:// wird zwar auf https:// umgeleitet, aber Schlüssel und Inhalt sind dann schon unverschlüsselt übertragen. Tragen Sie die Basis-URL deshalb immer mit https:// ein. Ist es doch passiert, lassen Sie den Schlüssel vom Fahrdienst erneuern. Die Zeilen HTTP/1.1 … in den Beispielen sind nur die Statuszeile der Antwort; die Verbindung ist immer HTTPS.

Anmeldung

Jeder Aufruf trägt den Header Authorization: Bearer <Schlüssel>. Fehlt er oder ist der Schlüssel falsch, gesperrt oder erneuert, antwortet die API mit 401 und dem Header WWW-Authenticate.

Inhalt und Zeichensatz

Anlegende Aufrufe senden ein JSON-Objekt mit Content-Type: application/json in UTF-8, höchstens 64 KB. Ein anderer Inhaltstyp ergibt 415, ein zu großer Inhalt 413, kein gültiges JSON 400 mit invalid_json. Unbekannte Felder werden abgewiesen (unknown_field), so fällt ein Tippfehler im Feldnamen sofort auf.

Lesende Aufrufe nehmen ihre Parameter aus der Adresse, zum Beispiel ?limit=100&include=billing. Auch hier werden unbekannte Parameter abgewiesen (unknown_field). Kommt ein Parameter mehrfach, gilt das nur für Listen wie include.

Leere Werte

In jedem optionalen Feld bedeuten null, eine leere Zeichenkette und reine Leerzeichen „nicht angegeben“. Sie müssen leere Felder also nicht entfernen.

In Antworten ist jedes Feld immer da, ein leeres Feld ist null. Ausgenommen sind Feldgruppen, die nur auf Anforderung kommen.

Adressen

Eine Adresse kann ganz fehlen. Ist ein Teil angegeben, braucht sie mindestens Straße und Ort, sonst weist die API sie mit dem Grund address_incomplete am fehlenden Feld ab. Hausnummer und PLZ sind optional.

Grenzen

Je Zugang sind 60 anlegende und 600 lesende Aufrufe pro Stunde möglich, je Fahrdienst über alle Zugänge 300 und 3000. Darüber antwortet die API mit 429 und nennt im Header Retry-After die Wartezeit in Sekunden. Zusätzlich gilt eine Grenze je IP-Adresse.

Versionen

/api/v1 wächst nur: Es können optionale Felder, neue Aufrufe und neue Gründe in issues hinzukommen, vorhandene behalten ihre Bedeutung. Ignorieren Sie unbekannte Felder in Antworten. Eine nicht verträgliche Änderung bekommt eine neue Version mit eigenem Pfad. Was sich geändert hat, steht unter Änderungen.

Request-ID

Jede Antwort trägt den Header X-Request-Id, Fehlerantworten zusätzlich das Feld request_id. Nennen Sie sie bei Rückfragen, damit findet der Support den Aufruf. Antworten werden nie zwischengespeichert (Cache-Control: no-store).

Fehlerbehandlung

Aufbau einer Fehlerantwort

Fehler kommen als application/problem+json (RFC 9457). Werten Sie das Feld code aus, nicht den Text. issues nennt bei ungültigen Eingaben Pfad und Grund, nie den gesendeten Wert. Geben Sie bei Rückfragen die request_id an. Die Felder stehen im Datenformat Fehlerantwort.

Fehlercodes

Gründe in issues

Bei invalid_input nennt issues je Abweichung den Pfad des Felds und einen festen Grund in message. Bei Längen, Mengen und Zahlen steht die verletzte Grenze in limit. Die Liste wächst nur; behandeln Sie einen unbekannten Grund wie invalid_value.

Beispiel einer Fehlerantwort

HTTP/1.1 400
Content-Type: application/problem+json

{
  "type": "tag:fleetiva.de,2026:api/problems/invalid_input",
  "title": "Invalid request",
  "status": 400,
  "code": "invalid_input",
  "request_id": "5f0d3c2a-7b1e-4c9d-a6f8-2e4b1c7d9a03",
  "issues": [
    {
      "path": "passengers.0.pickup.city",
      "message": "address_incomplete"
    }
  ]
}

Support

Ansprechpartner

• Zugang, Schlüssel und Bereiche: der Fahrdienst, für den Sie Anfragen anlegen. Nur er kann Zugänge anlegen, sperren und erneuern.
• Fragen zu einer Anfrage: ebenfalls der Fahrdienst, er bearbeitet sie in seinem Posteingang.
• Technische Fragen zur API: Fleetiva unter support@fleetiva.de. Nennen Sie die request_id, den Zeitpunkt und den Aufruf. Schicken Sie nie den Schlüssel.

Häufige Fragen

Warum bekomme ich 401, obwohl der Schlüssel stimmt?

Meist folgt der Client einer Weiterleitung auf einen anderen Host und lässt dabei den Header Authorization weg. Verwenden Sie die Basis-URL genau so. Sonst wurde der Schlüssel erneuert oder der Zugang gesperrt; fragen Sie den Fahrdienst.

Was passiert bei einem Aufruf über http://?

Der Server leitet ihn auf https:// um (308), aber Schlüssel und Inhalt sind dann schon unverschlüsselt übertragen. Korrigieren Sie die Basis-URL auf https:// und lassen Sie den Schlüssel vom Fahrdienst erneuern (siehe Basis-URL).

Warum bekomme ich 200 statt 201?

Die Anfrage mit diesem Idempotency-Key und diesem Inhalt ist schon angelegt. Die Antwort nennt ihre id mit duplicate: true; es entsteht keine zweite Anfrage.

Warum bekomme ich beim Wiederholen 422?

Derselbe Idempotency-Key kam mit anderem Inhalt. Eine Wiederholung braucht denselben Inhalt, eine neue Anfrage einen neuen Schlüssel (siehe Idempotenz).

Wie teste ich ohne Sandbox?

Mit Nur prüfen: Der Header Fleetiva-Dry-Run: true prüft alles und legt nichts an. Für echte Testanfragen gibt es einen eigenen Test-Zugang.

Warum bekomme ich beim Statusaufruf 404?

Sie sehen nur Anfragen, die über Ihren eigenen Zugang angelegt wurden. Anfragen anderer Zugänge, unbekannte und gelöschte sind alle „nicht gefunden“.

Was tue ich bei 429 oder 503?

Bei 429 warten Sie die Sekunden aus Retry-After, bei 503 einen Moment. Senden Sie dann dieselbe Anfrage mit demselben Idempotency-Key; eine zweite Anfrage entsteht dabei nicht.

Darf ich den Schlüssel im Browser verwenden?

Nein. Der Schlüssel gehört nur auf Ihren Server; ein Formular im Browser schickt seine Daten an Ihren Server, und der ruft die API. Die Testkonsole dieser Seite ist nur zum Ausprobieren gedacht.

Änderungen

Was sich an /api/v1 geändert hat, neueste zuerst. Vorhandene Felder und Aufrufe behalten ihre Bedeutung.

• 2. Nov. 2026 · Fahrgäste lesen und abgleichen (GET /passengers, GET /passengers/{id}, GET /passengers/deleted), Bereich health_data mit der Feldgruppe health (jeder Abruf wird protokolliert) und die Feldgruppe billing am Fahrgast.
• 2. Nov. 2026 · Kunden lesen und abgleichen (GET /customers, GET /customers/{id}, GET /customers/deleted), Bereiche master_data.read und accounting.read, Feldgruppe billing und die Gründe invalid_cursor und sync_window_exceeded.
• 2. Nov. 2026 · Erste Fassung: Anfragen anlegen (POST /inquiries) mit Postanschrift der anfragenden Person, Status abfragen (GET /inquiries/{id}), „nur prüfen“ mit Fleetiva-Dry-Run: true und feste Gründe in issues.