Exportschnittstelle

Ein Export erstellt eine Kopie. Er beendet keinen Vertrag, kündigt nichts und löst keine Löschung aus. Anbieterwechsel und Löschung sind eigene Vorgänge, die der Kunde ausdrücklich auswählt. Ein Abruf über diese Schnittstelle verändert am Konto nichts außer dem Abrufzähler des benutzten Zugangs.

Es gibt keinen unauthentifizierten Zugang. Zwei Wege sind möglich:

• Sitzung — der angemeldete Kontoinhaber lädt direkt herunter.
• Export-Token — der Kontoinhaber erzeugt einen Zugang und gibt ihn an den Zielanbieter weiter. Das Token ist 32 Byte Zufall (base64url) und wird serverseitig nur als SHA-256 gespeichert; es wird genau einmal ausgeliefert und lässt sich nicht erneut anzeigen.

Ein Token ist ausschließlich an das Konto gebunden, das es erzeugt hat. Es gibt keinen Parameter, mit dem sich ein anderes Konto ansprechen ließe.

# 1) Zugang erzeugen (als angemeldeter Kontoinhaber)
curl -X POST https://kurzhand.de/api/export/jobs \
  -H "content-type: application/json" \
  -d '{"gueltigkeit_minuten": 60, "max_abrufe": 3}'

# Antwort (gekürzt) — das Token erscheint nur hier:
# { "success": true, "data": {
#     "id": "…", "token": "…", "download_url": "https://kurzhand.de/api/export/paket?token=…",
#     "laeuft_ab_am": "2026-08-03T12:00:00.000Z", "max_abrufe": 3 } }

# 2) Paket abrufen (Zielanbieter, ohne Konto bei kurzhand)
# 1. Manifest holen (eroeffnet die Sitzung)
curl -s -H "x-export-token: $TOKEN" \
  "$SUPABASE/functions/v1/export-v2?aktion=manifest" > manifest.json

# 2. Je Bereich die Seiten abrufen, der Fortsetzung folgen
curl -s -D kopf.txt -H "x-export-token: $TOKEN" \
  "$SUPABASE/functions/v1/export-v2?aktion=seite&bereich=kunden" > kunden.ndjson
#    Fortsetzung: X-Export-Naechster-Cursor aus kopf.txt als &cursor=… anhaengen

# 3. Dateiliste holen und jede Datei direkt vom Dateispeicher laden
curl -s -H "x-export-token: $TOKEN" \
  "$SUPABASE/functions/v1/export-v2?aktion=dateien&bucket=rechnungen" > dateien.json

# 3) Zugang widerrufen, sobald der Wechsel abgeschlossen ist
curl -X POST https://kurzhand.de/api/export/jobs/widerruf \
  -H "content-type: application/json" -d '{}'

Es gibt zwei Wege, und beide liefern denselben Bestand.

Im Konto setzt der Browser ein ZIP-Archiv ohne Komprimierung zusammen (Methode STORE, Dateinamen in UTF-8). Die Daten kommen dabei aus der Datenbank, die Dateien aus dem Dateispeicher — ohne Umweg über einen Anwendungsserver.

kurzhand-export-JJJJ-MM-TT.zip
├── manifest.json       Verzeichnis: Bereiche, Zahlen, Grenzen
├── daten/<bereich>.ndjson   je Bereich eine Zeile je Datensatz
├── pruefsummen.json    SHA-256 je Datei
├── dateien/logos/     Firmenlogo
├── dateien/angebote/  Angebots-PDF
├── dateien/rechnungen/ Rechnungs-PDF und E-Rechnungs-XML
├── dateien/abnahmen/  Abnahmefotos
└── dateien/auftragsfotos/ Auftragsfotos

Über die Schnittstelle gibt es kein Archiv: Das Paket besteht aus dem Manifest, den seitenweise abrufbaren Bereichen als NDJSON und den Dateien, die über kurzlebige Downloadadressen direkt aus dem Dateispeicher kommen. Zusammen sind sie der vollständige Export. Genau so steht es auch in Anhang B § 5a Abs. 2a.

Die Dateipfade entsprechen den ursprünglichen Speicherpfaden ohne die vorangestellte Kontokennung — der Name trägt damit keine Kontobezüge.

{
  "exportiert_am": "2026-08-03T10:00:00.000Z",
  "format_version": "1.0",
  "nutzer": { "id": "…", "email": "…" },
  "hinweise": {
    "vollstaendigkeit": "…",
    "entfernte_felder": "…",
    "nicht_enthalten": { … },
    "unvollstaendige_bereiche": [],
    "fehlerhafte_bereiche": []
  },
  "bereiche": {
    "kunden": [ { … } ],
    "angebote": [ { … } ],
    …
  }
}

Die Felder innerhalb eines Bereichs entsprechen eins zu eins den Spalten der jeweiligen Tabelle. Sie sind nicht umbenannt — ein Zielanbieter sieht die Rohstruktur und muss nicht raten, welche Umbenennung was bedeutet.

Das Paket enthält die folgenden Bereiche, soweit im Konto vorhanden:

Datenseiten: Jede Seite trägt im Antwortkopf X-Export-Pruefsumme einen SHA-256 über ihren Rumpf — also über genau die Bytes, die übertragen wurden.

Dateien: Jeder Eintrag der Dateiliste nennt im Feld sha256 die Prüfsumme des Dateiinhalts. Sie entsteht dort, wo die Datei entsteht — im Browser vor dem Hochladen beziehungsweise serverseitig vor dem Speichern. Für Dateien aus der Zeit davor wird sie nachgetragen; solange sie fehlt, steht dort ausdrücklich null und kein Ersatzwert.

Der vom Dateispeicher vergebene ETag wird nicht als Prüfsumme ausgegeben. Er ist bei mehrteiligen Uploads kein Hash des Inhalts, und wer ihn nachrechnen wollte, käme auf ein anderes Ergebnis.

# Seite pruefen
curl -s -D kopf.txt -H "x-export-token: $TOKEN" "$URL&bereich=kunden" > kunden.ndjson
grep -i x-export-pruefsumme kopf.txt
shasum -a 256 kunden.ndjson

# Datei pruefen (sha256 aus der Dateiliste)
shasum -a 256 rechnung-2026-001.pdf

Jede Datenseite nennt im Kopf X-Export-Naechster-Cursor die Fortsetzungsmarke. Wer abbricht, merkt sich je Bereich die zuletzt gelesene Marke und setzt beim nächsten Lauf mit &cursor=… genau dort wieder an. Die Sortierung ist stabil, ein Nachrücken während des Abrufs verschiebt also keine Zeile.

Die Downloadadressen der Dateien sind wenige Minuten gültig. Laufen sie ab, liefert ein erneuter Aufruf der Dateiliste frische Adressen — solange der Zugang gilt.

Ein vollständiger Export ist EIN Abruf im Sinne der Abrufgrenze, nicht eine Anfrage je Seite: Gezählt wird das Manifest, die Folgeanfragen laufen innerhalb derselben Sitzung. Das Sitzungsfenster beträgt 60 Minuten.

Je Zugang und je Konto gilt ein Token-Bucket: 60 Anfragen als Spitze, danach fünf je Sekunde. Ein vollständiger Export mit rund 70 Anfragen geht damit ohne Wartezeit durch; eine Schleife wird gebremst. Wird die Grenze erreicht, antwortet die Schnittstelle mit 429 und einem Retry-After in Sekunden.

Kann eine Datei nicht gelesen werden, bricht der Export nicht ab. Sie erscheint im Manifest mit "status": "fehlt" samt Grund. So ist die Lücke sichtbar, statt dass ein scheinbar vollständiges Paket entsteht.

• Keine feste Zeilengrenze je Bereich; die Daten werden seitenweise vollständig geholt.
• Das Archiv ist auf 4 GiB begrenzt (ZIP ohne ZIP64). Darüber bricht der Export mit einer klaren Meldung ab.
• Höchstens fünf offene Exportzugänge je Konto gleichzeitig.
• Gültigkeit eines Zugangs: 5 Minuten bis 24 Stunden. Abrufe: 1 bis 10.
• Rate-Limit auf allen Exportendpunkten.
• Die Antwort wird gestreamt; eine Wiederaufnahme abgebrochener Downloads (Range-Requests) gibt es nicht.

• Zugriffstokens, Passwort-Hashes und Schlüssel. Sie sind Zugangsmittel, keine Nutzdaten; ein Export würde fremde Zugriffe auf Ihre Dokumente ermöglichen.
• Interne Support-, Vertriebs- und Bewertungsvermerke der Rolsing & Kokorin GbR (admin_*, leads). Sie sind eigene Aufzeichnungen des Anbieters und nicht vom Kunden bereitgestellt. Auskunft dazu auf Anfrage an datenschutz@kurzhand.de.
• Protokolle des internen Entwicklungswerkzeugs (agent_logs, agent_messages). Sie haben keinen Bezug zu Ihrem Konto.
• Rohereignisse des Zahlungsdienstleisters (billing_webhook_events). Ihre Abonnement- und Zahlungsdaten sind unter „abonnements" enthalten; die Originalbelege liegen bei Stripe.
• Das Cookie-Einwilligungsprotokoll. Es ist an eine pseudonyme Kennung im Browser gebunden und nicht Ihrem Konto zugeordnet.
• Daten anderer Betriebe. Alle Abfragen sind an Ihr Konto gebunden und zusätzlich durch Row Level Security begrenzt.
• E-Mail-Anhänge aus dem Mail-Eingang. kurzhand speichert davon nur Metadaten (Dateiname, Typ, Größe); die Datei selbst wird für die Auswertung nur vorübergehend abgerufen und nicht abgelegt.

Fehlerantworten haben stets die Form {"success": false, "error": "…", "code": "…"}.

Anlegen, Abruf, Abschluss, Fehlschlag und Widerruf eines Exportzugangs werden protokolliert. Das Protokoll enthält keine Tokens und keine Exportinhalte. Wird ein Konto gelöscht, werden offene Exportzugänge automatisch widerrufen — ein Token soll das Konto nicht überdauern.

Schreib uns an hallo@kurzhand.de. Nenne dabei die Kennung des Exportauftrags (nicht das Token) und den Zeitpunkt des Abrufs. Für Fragen zum Datenschutz: datenschutz@kurzhand.de.