Das Fahrdesk-Exportformat

Aufbau des Pakets

Das Paket ist ein ZIP-Archiv (Deflate) mit dem Namen fahrdesk-export-JJJJ-MM-TT.zip. Es ist nicht verschlüsselt und nicht passwortgeschützt — der Empfänger soll es lesen können. Jede Entität liegt zweimal vor: als .json mit Typen und verschachtelten Werten und als .csv für Tabellenkalkulationen. Beide Dateien entstehen aus derselben Zeilenmenge.

manifest.json                     Inhalt, Satzzahlen je Entität, Dateiliste, Prüfsummen, Konventionen.
liesmich.md                       Dieselbe Beschreibung in Kurzform, für den Menschen.
schema/datenwoerterbuch.json      Typ, Format und Bedeutung jedes Feldes, Schlüssel "entitaet.feld".
schema/beziehungen.json           Welches Feld auf welche Entität verweist.
dokumente/index.json              Verzeichnis der beigelegten Dateien mit ihrer Zuordnung.
dokumente/dateien/                Die Dateien selbst, im Originalformat.

organisation/                     Fahrschule und Standorte
  fahrschule.{json,csv}           Fahrschule
  standorte.{json,csv}            Standorte
schueler/                         Fahrschüler
  schueler.{json,csv}             Fahrschüler
  ausbildungen.{json,csv}         Ausbildungsvorgänge
  kontakte.{json,csv}             Kontaktpersonen
personal/                         Mitarbeiter und Fahrlehrer
  mitarbeiter.{json,csv}          Mitarbeiter
  fahrlehrer.{json,csv}           Fahrlehrer
ausbildung/                       Fahrstunden, Theorie und Prüfungen
  fahrstunden.{json,csv}          Fahrstunden
  theorieunterricht.{json,csv}    Theorieunterricht
  theorieteilnahmen.{json,csv}    Theorieteilnahmen
  theorieanwesenheit.{json,csv}   Anwesenheit am Theorieunterricht
  pruefungen.{json,csv}           Prüfungen
finanzen/                         Leistungen, Rechnungen und Zahlungen
  leistungen.{json,csv}           Leistungsarten
  kostenarten.{json,csv}          Weitere Kostenarten
  preislisten.{json,csv}          Preislisten
  preispositionen.{json,csv}      Preispositionen
  rechnungen.{json,csv}           Rechnungen
  rechnungspositionen.{json,csv}  Rechnungspositionen
  zahlungen.{json,csv}            Zahlungen
  schuelerkosten.{json,csv}       Berechnete Kosten je Fahrschüler
  ausgaben.{json,csv}             Betriebsausgaben
  mahnungen.{json,csv}            Mahnungen
  mahnsperren.{json,csv}          Mahnsperren
  inkasso_faelle.{json,csv}       Inkassofälle
fahrzeuge/                        Fuhrpark
  fahrzeuge.{json,csv}            Fahrzeuge
  fahrzeugservice.{json,csv}      Wartung und Prüfungen
  fahrzeugkosten.{json,csv}       Fahrzeugkosten
sonstiges/                        Notizen
  notizen.{json,csv}              Notizen

Eine Datei kann leer sein, weil die Fahrschule dort keine Daten hat — oder weil der Bestand beim Export nicht gelesen werden konnte. Diese beiden Fälle sind unterscheidbar: Der zweite steht in manifest.json unter nichtEnthalten mit Grund. Bitte werten Sie das aus, bevor Sie einem Kunden mitteilen, er habe keine Rechnungen.

Konventionen: Datum, Zeit, Beträge

Dieselben Sätze stehen im Paket selbst, in manifest.json unter konventionen. Ein Importeur kann sie also auch maschinell prüfen, statt sich auf diese Seite zu verlassen.

Beziehungen

Jede Entität hat ein Feld "id". Verweisende Felder enden auf "_id" und tragen die id des Ziels; welches Ziel gemeint ist, steht in schema/beziehungen.json.

Datum

JJJJ-MM-TT

Zeitpunkte

ISO 8601 mit Zeitzonenangabe, z. B. 2026-03-12T14:30:00+01:00

Beträge

Ganzzahlen in Cent. 12550 bedeutet 125,50 €.

Listen

In JSON als Array, in CSV mit senkrechtem Strich getrennt.

Leere Werte

In JSON null, in CSV ein leeres Feld.

Zeichensatz und Sprache

UTF-8, Sprache de-DE. Feldnamen und die von Fahrdesk vergebenen Schlüsselwerte (Status, Typen) sind deutsch — Fahrdesk führt seine Daten durchgehend deutsch, und eine Übersetzungsschicht nur für den Export hieße, dass Sie die Namen gegen das rückübersetzen müssten, was Ihre Kunden in der Oberfläche sehen.

Zeitzone

Die Zeitzone der Fahrschule steht in manifest.json unter zeitzone und zusätzlich im Feld fahrschule.zeitzone. Zeitpunkte tragen ihre Zeitzone selbst; reine Datumswerte tun das nicht und sind in der Zeitzone der Fahrschule zu lesen.

CSV (Trennzeichen „;“)

• Trennzeichen ist das Semikolon, Zeilenende CRLF, Zeichensatz UTF-8 ohne BOM.
• Werte, die ein Semikolon, ein Anführungszeichen oder einen Zeilenumbruch enthalten, stehen in Anführungszeichen; enthaltene Anführungszeichen sind verdoppelt.
• Werte, die mit "=", "+", "-" oder "@" beginnen, tragen ein vorangestelltes Apostroph, damit Tabellenprogramme sie nicht als Formel auswerten. Das Apostroph gehört nicht zum Wert.
• Verschachtelte Werte (Typ "objekt") stehen in der CSV als JSON-Text. Wer sie auswerten will, nimmt die JSON-Datei derselben Entität.

Feldtypen

Jedes Feld im Katalog weiter unten trägt einen dieser Typen. Denselben Typ nennt auch schema/datenwoerterbuch.json im Paket, dort je Feld unter dem Schlüssel entitaet.feld.

text

Zeichenkette.

zahl

Zahl. In JSON als Zahlwert, in CSV mit Punkt als Dezimaltrennzeichen.

betrag

Ganzzahl in Cent. 12550 bedeutet 125,50 €. Kein Dezimaltrennzeichen, keine Währung im Wert.

datum

Datum ohne Uhrzeit im Format JJJJ-MM-TT.

zeitpunkt

Zeitpunkt nach ISO 8601 mit Zeitzonenangabe, z. B. 2026-03-12T14:30:00+01:00.

wahrheitswert

In JSON true oder false, in CSV der Text "true" bzw. "false".

liste

In JSON ein Array, in CSV die Werte mit senkrechtem Strich getrennt.

objekt

In JSON ein verschachteltes Objekt, in CSV dasselbe Objekt als JSON-Text in einer Zelle.

id

Kennung eines Datensatzes, in Fahrdesk eine UUID. Siehe Abschnitt „Kennungen“.

Kennungen und Export-IDs

• Die Export-ID eines Datensatzes ist sein Feld id. Es gibt keine zweite, nur für den Export erzeugte Nummer: Die Kennung im Paket ist unverändert die, unter der der Datensatz in Fahrdesk geführt wurde — eine UUID.
• Damit sind die Kennungen innerhalb eines Pakets eindeutig und über mehrere Exporte derselben Fahrschule hinweg stabil. Ein zweiter Export nach einer Woche trägt für dieselben Datensätze dieselben Kennungen; das erlaubt einen erneuten Abgleich, ohne über Namen und Geburtsdaten zu raten.
• Verweise auf andere Datensätze stehen in Feldern, die auf _id enden. Welche Entität gemeint ist, steht im Beziehungsmodell weiter unten und maschinenlesbar in schema/beziehungen.json.
• Kennungen sind über Mandanten hinweg nicht vergleichbar: Ein Paket enthält genau eine Fahrschule.

Beziehungsmodell

55 Verweise. Dieselbe Liste liegt dem Paket als schema/beziehungen.json bei, dort als Einträge aus von, feld und nach. Ein Verweisfeld kann leer sein. Findet sich zu einer gefüllten Kennung kein Datensatz in der Zieldatei, prüfen Sie bitte nichtEnthalten im Manifest, bevor Sie den Verweis verwerfen.

Dokumente

Hinterlegte Dateien liegen mit ihrem Inhalt im Paket, nicht als Verweis auf unseren Speicher — ein solcher Verweis wäre genau dann wertlos, wenn er gebraucht wird: nach dem Wechsel. Sie stehen unter dokumente/dateien/ im Originalformat. Der Dateiname ist die Kennung des Dokumentdatensatzes plus die ursprüngliche Endung, weil Originalnamen doppelt vorkommen, Umlaute tragen und Pfadtrenner enthalten können.

Die Zuordnung steht in dokumente/index.json — eine Liste mit diesen Feldern:

Die Zuordnung läuft über entitaet und entitaet_id: Der Wert von entitaet ist ein Entitätsname aus dem Katalog unten, entitaet_id die id des Datensatzes in der zugehörigen Datei.

Manifest und Prüfsummen

manifest.json ist die Datei, mit der ein Importeur beginnen sollte. Sie nennt die Formatversion, die Fahrschule, die Konventionen, je Bereich und Entität die Anzahl der Datensätze, die Zahl und Gesamtgröße der Dokumente, nicht gelesene Bereiche samt Grund sowie zu jeder Datei des Pakets ihre Größe in Bytes und ihre Prüfsumme.

Prüfsummenverfahren ist sha256, notiert als Hexadezimaltext. Das Manifest führt jede andere Datei des Pakets auf, seine eigene Prüfsumme kann es nicht enthalten. Wer prüfen will, ob unterwegs etwas beschädigt wurde, rechnet die Prüfsummen der Dateien nach; die Vollständigkeit prüft er, indem er die Dateiliste des Manifests gegen das Archiv hält.

Was nicht enthalten ist

Der Katalog oben ist abschließend: Was dort nicht steht, verlässt Fahrdesk nicht. Ausdrücklich nicht enthalten sind

• Zugangsdaten, Passwort-Hashes sowie Sitzungs-, Kalender- und Dokumenttoken — sie sind für die Weiterverarbeitung ohne Wert, und ihre Weitergabe wäre ein Sicherheitsrisiko für die betroffenen Fahrschüler;
• Suchindizes und interne Hilfswerte;
• Kennungen des Zahlungsdienstleisters — sie gehören zum Vertrag der Fahrschule mit diesem Dienstleister, nicht zum übertragbaren Datenbestand;
• Beschäftigtendaten der Mitarbeiter wie Bankverbindung, Steuer- und Sozialversicherungsnummer — eigene Zweckbindung, kein Gegenstand eines Portabilitätsexports;
• Daten anderer Fahrschulen; ein Paket enthält genau einen Mandanten.

Bitte behandeln Sie diese Lücken nicht als Datenverlust und fordern Sie sie nicht beim Kunden nach.

Versionierung

Jedes Paket nennt seine Formatversion in manifest.json unter exportFormatVersion. Aktuell ist Version 1.

Die Version steigt, wenn sich Aufbau oder Bedeutung so ändern, dass ein bestehender Leser angepasst werden muss. Neue Felder oder neue Entitäten allein tun das nicht — sie sind additiv, und ein Leser, der Unbekanntes überspringt, merkt nichts davon. Bauen Sie Ihren Import deshalb bitte so, dass er unbekannte Felder ignoriert, statt an ihnen zu scheitern.

Abholung durch den Zielanbieter

Im Regelfall lädt die Fahrschule das Paket selbst herunter und gibt es Ihnen. Alternativ kann sie Ihnen einen befristeten, jederzeit widerrufbaren Zugangsschlüssel ausstellen, mit dem Sie das Paket selbst abholen — ohne dass jemand Kontozugangsdaten weitergibt. Der Schlüssel gilt für eine Fahrschule und trägt genau eine Berechtigung: Portabilitätsdaten lesen.

GET  /api/v1/portabilitaet/exporte               vorhandene Pakete
POST /api/v1/portabilitaet/exporte               neues Paket anfordern
GET  /api/v1/portabilitaet/exporte/:id           Zustand
GET  /api/v1/portabilitaet/exporte/:id/download  Weiterleitung auf den Downloadlink

Authorization: Bearer <vom Kunden ausgestellter Schlüssel>

Ein Downloadlink funktioniert genau einmal; ein erzeugtes Paket verfällt nach 7 Tagen und wird dann gelöscht. Laden Sie es also herunter, wenn Sie es abholen.