Schnittstelle

Eine Gegenprüfung einreichen – mit einem einzigen Aufruf

Ein Aufruf mit den Unterlagen, eine Kennung zurück, danach nur noch abholen. Die REST-Schnittstelle von Gegenprüfung liegt unter /api/v1 und ist so geschnitten, dass ein Gutachter- oder Werkstattsystem für die Anbindung weder eine Statusmaschine nachbauen noch interne Abläufe kennen muss.

Vollständige Referenz Schlüssel anfordern

Schnellstart

In drei Aufrufen fertig

Die Beispiele sind vollständig. Setzen Sie einmal die beiden Umgebungsvariablen aus dem ersten Block, danach lässt sich jeder Befehl unverändert kopieren.

1. Einreichen

POST /api/v1/gegenpruefungen · multipart/form-data · Berechtigung vorgaenge:schreiben

# Adresse Ihrer Instanz und Ihr Schlüssel, einmal im Terminal setzen:
export GP_BASIS="https://ihre-instanz.example"
export GP_SCHLUESSEL="gp_test_a1b2c3d4_IHR-GEHEIMNIS"

curl -X POST "$GP_BASIS/api/v1/gegenpruefungen" \
  -H "Authorization: Bearer $GP_SCHLUESSEL" \
  -H "Idempotency-Key: 4f1c0a6e-2b57-4f0e-9c1a-8d3e6b2f7a10" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "referenz=WERKSTATT-2026-0042" \
  -F "schadennummer=SN-4711-2026" \
  -F "kennzeichen=B-XY-1234"

# Antwort: 202 mit id, aktenzeichen, status, weiter_abfragen, bericht_verfuegbar und links.

2. Status abfragen

GET /api/v1/gegenpruefungen/{id} · Berechtigung vorgaenge:lesen

# Abfrage über die zurückgegebene id …
curl "$GP_BASIS/api/v1/gegenpruefungen/case_7pQ2mR9tKx4nV6bZ3sYdA" \
  -H "Authorization: Bearer $GP_SCHLUESSEL"

# … oder über Ihre eigene Referenz, ohne eigene Zuordnungstabelle:
curl "$GP_BASIS/api/v1/gegenpruefungen/ref:WERKSTATT-2026-0042" \
  -H "Authorization: Bearer $GP_SCHLUESSEL"

# Auswerten müssen Sie genau zwei Felder:
#   "weiter_abfragen": false   -> nicht weiter abfragen
#   "bericht_verfuegbar": true -> Bericht abholen

3. Bericht holen

GET /api/v1/gegenpruefungen/{id}/bericht · Berechtigung berichte:lesen

# Als JSON zur Weiterverarbeitung:
curl "$GP_BASIS/api/v1/gegenpruefungen/ref:WERKSTATT-2026-0042/bericht" \
  -H "Authorization: Bearer $GP_SCHLUESSEL"

# Als PDF zur Ablage in Ihrer Akte:
curl -o Gegenpruefbericht.pdf \
  "$GP_BASIS/api/v1/gegenpruefungen/ref:WERKSTATT-2026-0042/bericht.pdf" \
  -H "Authorization: Bearer $GP_SCHLUESSEL"

Häufig genügt schon der erste Aufruf

Der Einreichungsaufruf antwortet erst, wenn die Auswertung durchgelaufen ist, und liefert das Ergebnis damit oft bereits in derselben Antwort. Verlassen Sie sich nicht darauf: Bei umfangreichen Unterlagen oder unter Last bleibt der Status in_bearbeitung, und es gilt weiter_abfragen.

Authentifizierung

Ein Schlüssel, ein Kopfzeilenfeld

Jede Anfrage trägt den Schlüssel im Kopf Authorization als Bearer-Token. Der Aufbau ist gp_<umgebung>_<praefix>_<geheimnis>. Das Präfix ist sichtbar und dient der Wiedererkennung in Oberfläche und Protokollen; das Geheimnis besteht aus 32 zufälligen Byte.

Authorization: Bearer gp_test_a1b2c3d4_IHR-GEHEIMNIS

Es gibt zwei Umgebungen: test für die Testumgebung, live für den Produktivbetrieb. Die Umgebung ist Bestandteil des Schlüssels und lässt sich damit nicht versehentlich verwechseln; GET /api/v1/status gibt sie zusätzlich aus.

Der Schlüssel wird nur einmal angezeigt

Gespeichert wird ausschließlich der SHA-256-Hash. Auch der Betreiber kann einen verlorenen Schlüssel nicht wiederherstellen – er wird dann widerrufen und ein neuer erzeugt. Legen Sie den Wert direkt nach der Ausgabe in Ihrer Geheimnisverwaltung ab, nicht im Quellcode.

Berechtigungen

Ein Schlüssel trägt genau die Berechtigungen, die ihm zugewiesen wurden. Fehlt eine, antwortet die Schnittstelle mit 403 und nennt die benötigte.

Berechtigung	Bedeutung	Endpunkte
vorgaenge:lesen	Vorgänge und Status lesen	GET /gegenpruefungen, GET /gegenpruefungen/{id}, GET /gegenpruefungen/{id}/dokumente, GET /webhooks, GET /status
vorgaenge:schreiben	Vorgänge anlegen und Unterlagen hochladen	POST /gegenpruefungen, POST /gegenpruefungen/{id}/dokumente, POST /webhooks, DELETE /webhooks
berichte:lesen	Gegenprüfberichte abrufen	GET /gegenpruefungen/{id}/bericht, GET /gegenpruefungen/{id}/bericht.pdf

Der eine Aufruf

POST /api/v1/gegenpruefungen im Detail

Der Anfragekörper ist multipart/form-data. Der Feldname bestimmt die Dokumentart – ein zusätzliches Typfeld gibt es deshalb nicht. Jedes Feld darf mehrfach vorkommen; die Schreibweise feld[] wird ebenfalls ausgewertet.

Dateifelder

Zulässig sind PDF, JPEG und PNG. Der Dateityp wird nicht aus der Endung, sondern aus der tatsächlichen Dateisignatur bestimmt.

Feld	Dokumentart	Erforderlich	Bemerkung
pruefbericht	PRUEFBERICHTPrüfbericht	erforderlich	Ohne eine Datei in diesem Feld wird die Anfrage mit 400 und dem Code anfrage-ungueltig abgewiesen.
gutachten	SCHADENGUTACHTENSchadengutachten	für die Auswertung	Fehlt es, wird der Vorgang trotzdem angelegt. Der Status ist dann unterlagen_unvollstaendig, bis Sie es nachreichen.
kalkulation	REPARATURKALKULATIONReparaturkostenkalkulation	optional	Verbessert die Zuordnung einzelner Positionen zur jeweiligen Kürzung im Prüfbericht.
versicherungsschreiben	VERSICHERUNGSSCHREIBENSchreiben der Versicherung	optional	Enthält häufig die Regulierungszusage und damit einen weiteren Abgleichspunkt für die Summen.
rechnung	REPARATURRECHNUNGReparaturrechnung	optional	Sinnvoll, wenn bereits repariert wurde.
kostenvoranschlag	KOSTENVORANSCHLAGKostenvoranschlag	optional	Alternative zur Kalkulation, wenn kein Gutachten mit Kalkulationsteil vorliegt.
vollmacht	VOLLMACHTVollmacht	optional	Wird für eine spätere anwaltliche Bearbeitung durch die Kanzlei benötigt, nicht für die technische Gegenüberstellung.
anlage	SONSTIGE_ANLAGESonstige Anlage	optional	Für alles Weitere. Mehrfachangabe ist hier der Regelfall.

Die geltende Höchstgröße je Datei und die Höchstzahl an Dokumenten je Vorgang liefert GET /api/v1/status; voreingestellt sind 25 MB je Datei und 40 Dokumente je Vorgang. Nachreichen können Sie Unterlagen jederzeit über POST /api/v1/gegenpruefungen/{id}/dokumente mit denselben Feldnamen.

Textfelder

Alle Textfelder sind optional. Leere Werte werden verworfen.

Feld	Bedeutung
referenz	Ihre eigene Kennung für den Vorgang. Sie können ihn danach über ref:<ihre-referenz> statt über die id abrufen.
schadennummer	Schadennummer der Versicherung, sofern bekannt.
kennzeichen	Amtliches Kennzeichen des beschädigten Fahrzeugs.
nachname	Nachname der geschädigten Person. Alternativ wird das Feld geschaedigter ausgewertet.
vorname	Vorname der geschädigten Person.
schadendatum	Datum des Schadenereignisses. Der Wert wird unverändert übernommen; verwenden Sie JJJJ-MM-TT.
webhook_url	Adresse für Benachrichtigungen zu diesem Vorgang. Muss mit https:// beginnen. Die Antwort enthält dann einmalig das zugehörige Geheimnis.

Antwort 202 Accepted

Vollständiges Beispiel. Dieselbe Struktur liefert auch die Statusabfrage; auswertung_gestartet und nicht_lesbare_dateien kommen nur bei einer Einreichung hinzu.

{
  "id": "case_7pQ2mR9tKx4nV6bZ3sYdA",
  "aktenzeichen": "GP-2026-000128",
  "externe_referenz": "WERKSTATT-2026-0042",
  "status": "bericht_verfuegbar",
  "status_beschreibung": "Der Gegenprüfbericht ist abrufbar.",
  "weiter_abfragen": false,
  "bericht_verfuegbar": true,
  "erstellt_am": "2026-08-19T09:14:22.418Z",
  "aktualisiert_am": "2026-08-19T09:14:24.902Z",
  "schadennummer": "SN-4711-2026",
  "fehlende_unterlagen": [],
  "unterlagen": [
    { "id": "doc_3kR8sT2vN5xW9yB4zC6dE", "art": "PRUEFBERICHT", "bezeichnung": "Prüfbericht", "dateiname": "pruefbericht.pdf",
      "seiten": 4, "groesse_bytes": 182734, "pruefsumme_sha256": "9f2c1ae7…", "eingegangen_am": "2026-08-19T09:14:23.101Z" }
  ],
  "zusammenfassung": {
    "anzahl_beanstandeter_positionen": 6, "summe_kuerzungen_cent": 84215, "summe_kuerzungen_formatiert": "842,15 €",
    "kalkuliert_cent": 412990, "anerkannt_cent": 328775, "rechnerisch_stimmig": true,
    "geringste_extraktionskonfidenz": 0.88, "geringste_zuordnungskonfidenz": 0.91, "anzahl_hinweise": 1
  },
  "hinweise": [
    { "code": "LOW_MATCH_CONFIDENCE", "bezeichnung": "Geringe Zuordnungskonfidenz", "beschreibung": "Position 14 …" }
  ],
  "links": {
    "selbst": "https://ihre-instanz.example/api/v1/gegenpruefungen/case_7pQ2mR9tKx4nV6bZ3sYdA",
    "bericht_json": "https://ihre-instanz.example/api/v1/gegenpruefungen/case_7pQ2mR9tKx4nV6bZ3sYdA/bericht",
    "bericht_pdf": "https://ihre-instanz.example/api/v1/gegenpruefungen/case_7pQ2mR9tKx4nV6bZ3sYdA/bericht.pdf",
    "dokumente": "https://ihre-instanz.example/api/v1/gegenpruefungen/case_7pQ2mR9tKx4nV6bZ3sYdA/dokumente"
  },
  "auswertung_gestartet": true,
  "nicht_lesbare_dateien": []
}

Haben Sie webhook_url mitgesendet, enthält die Antwort zusätzlich das Objekt webhook mit Adresse und Geheimnis. Das Geheimnis erscheint nur in dieser einen Antwort.

Status

Acht Werte – von denen Sie keinen kennen müssen

Intern durchläuft ein Vorgang zwanzig Zustände. Nach außen bleibt eine bewusst kleine, stabile Menge von acht Werten übrig, damit Änderungen an der Bearbeitung Ihr System nicht treffen. Für die Steuerung Ihrer Integration brauchen Sie diese Werte trotzdem nicht: Jede Antwort enthält weiter_abfragen und bericht_verfuegbar als Wahrheitswerte.

Die ganze Client-Logik

Solange weiter_abfragen wahr ist, später erneut abfragen. Sobald bericht_verfuegbar wahr ist, den Bericht holen. Ist beides falsch, ist von Ihrer Seite nichts mehr zu tun – dann sagt status_beschreibung in Klartext, woran es liegt.

Status	Bedeutung	weiter_abfragen	bericht_verfuegbar
angelegt	Der Vorgang ist angelegt. Die Auswertung hat noch nicht begonnen.	true	false
unterlagen_unvollstaendig	Für eine belastbare Gegenüberstellung fehlen Unterlagen. Reichen Sie sie über POST /dokumente nach.	false	false
in_bearbeitung	Die Unterlagen werden ausgewertet. Fragen Sie den Status erneut ab oder nutzen Sie einen Webhook.	true	false
pruefung_erforderlich	Die Auswertung liegt vor, enthält aber Punkte, die ein Mensch prüfen muss. Der Bericht ist bereits abrufbar.	false	true
bericht_verfuegbar	Der Gegenprüfbericht ist abrufbar.	false	true
anwaltlich_freigegeben	Die Partnerkanzlei hat den Vorgang geprüft und freigegeben. Der Gegenprüfbericht ist abrufbar.	false	true
abgeschlossen	Der Vorgang ist abgeschlossen.	false	true
abgelehnt	Der Vorgang wird nicht weiterverfolgt.	false	false

Abruf über die eigene Referenz: Haben Sie beim Einreichen das Feld referenz gesetzt, akzeptieren Statusabfrage und Berichtsabruf statt der id auch ref:<ihre-referenz>. Ihr System braucht dann keine eigene Zuordnungstabelle; gibt es mehrere Vorgänge mit derselben Referenz, wird der zuletzt angelegte geliefert.

Liste: GET /api/v1/gegenpruefungen liefert die Vorgänge Ihrer Organisation, neueste zuerst, mit den Parametern limit (1 bis 100, Vorgabe 25) und vor (ISO-8601-Zeitstempel). Die Antwort enthält naechste_seite als fertige Adresse.

Bericht

Ein Pfad, zwei Formate

/bericht liefert JSON zur Weiterverarbeitung, /bericht.pdf dasselbe Ergebnis als Dokument für die Akte; alternativ steuert der Kopf Accept: application/pdf auf dem JSON-Pfad die PDF-Ausgabe. Liegt noch kein Bericht vor, antwortet die Schnittstelle mit 409 und dem Code bericht-noch-nicht-verfuegbar; die Antwort nennt den aktuellen Status und die fehlenden Unterlagen.

Aufbau des JSON-Berichts

Feld	Inhalt
schema_version, art	Fassung des Berichtsschemas (derzeit 1.0.0) und die Konstante gegenpruefbericht.
id, aktenzeichen, externe_referenz	Kennungen des Vorgangs, einschließlich Ihrer eigenen Referenz.
erstellt_am, pipeline_version, status	Zeitpunkt und Fassung der Auswertung sowie der äußere Status.
hinweis	Fester Text: Der Bericht ist eine technische Gegenüberstellung ohne rechtliche Bewertung. Bitte in Ihre Darstellung übernehmen.
stammdaten	Schadennummer, Versicherung, Prüfdienstleister, Versicherungsnehmer, geschädigte Partei, Fahrzeug, Kennzeichen, Fahrgestellnummer, Schadendatum, Gutachtennummer und -datum, Prüfberichtdatum.
summen	kalkuliert_cent, anerkannt_cent, differenz_cent, im_pruefbericht_ausgewiesen_cent, rechnerisch_stimmig, waehrung. Alle Beträge sind ganzzahlige Cent-Werte.
positionen	Die beanstandeten Positionen mit Bezeichnung, Kategorie, kalkuliertem und anerkanntem Betrag, Differenz, Begründung laut Prüfbericht, beiden Fundstellen, Konfidenzwerten und Bearbeitungsstand.
kalkulationspositionen	Alle Positionen der Kalkulation mit Nettobetrag und dem Kennzeichen beanstandet.
fehlende_unterlagen, widersprueche	Fehlende Dokumentarten sowie Felder mit widersprüchlichen Angaben zwischen Dokumenten, mit Schwere, Werten und Seitenangabe.
hinweise	Punkte, die eine menschliche Prüfung auslösen, etwa geringe Zuordnungskonfidenz oder ein fehlendes Dokument.
auffaellige_dokumentstellen	Stellen im Dokumenttext, die wie eine versteckte Anweisung an ein Sprachmodell aussehen, mit Seite und Auszug.
unterlagen, links	Die zugrunde liegenden Dateien mit Seitenzahl und SHA-256-Prüfsumme sowie selbst, pdf und vorgang als absolute Adressen.

Jede Position ist belegt

Zu jeder beanstandeten Position stehen zwei Fundstellen im Bericht: die Stelle im Gutachten und die Stelle im Prüfbericht, jeweils mit Dokumentkennung, Seitenzahl und wörtlichem Zitat.

"positionsnummer": "14",
"bezeichnung": "Verbringungskosten",
"kalkuliert_cent": 14500,
"anerkannt_cent": 0,
"differenz_cent": 14500,
"begruendung_laut_pruefbericht": "Nicht erforderlich, Lackierung im Haus möglich.",
"fundstelle_gutachten": { "dokument_id": "doc_3kR8sT2vN5xW9yB4zC6dE", "seite": 12,
  "zitat": "Verbringung zur Lackiererei 145,00" },
"fundstelle_pruefbericht": { "dokument_id": "doc_8mN4bV6cX1zL3kJ5hG7fD", "seite": 3,
  "zitat": "Verbringungskosten werden nicht anerkannt." }

Was sich nicht bis zur Fundstelle belegen lässt, erscheint nicht als Ergebnis, sondern als Eintrag unter hinweise. Alle Beträge sind ganzzahlige Cent-Werte und werden deterministisch berechnet, nicht von einem Sprachmodell.

Webhooks

Benachrichtigen lassen statt nachfragen

Wer im Minutentakt den Status abfragt, verbraucht sein Anfragekontingent für Antworten, die sich nicht geändert haben. Hinterlegen Sie stattdessen eine Adresse: Sie wird benachrichtigt, sobald ein Bericht vorliegt oder Unterlagen fehlen. Die Adresse lässt sich beim Einreichen über webhook_url setzen oder dauerhaft über POST /api/v1/webhooks einrichten. Angenommen wird nur https://.

Einrichten und wieder abschalten

curl -X POST "$GP_BASIS/api/v1/webhooks" \
  -H "Authorization: Bearer $GP_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://ihr-system.example/eingang", "ereignisse": ["gegenpruefung.abgeschlossen"]}'

# 201 mit id, url, ereignisse, geheimnis und hinweis. Das Geheimnis wird nur einmal ausgegeben.
# Der Körper einer Zustellung enthält ereignis, gesendet_am und das Objekt gegenpruefung mit
# id, aktenzeichen, externe_referenz, status und bericht_verfuegbar.

# Adresse wieder abschalten:
curl -X DELETE "$GP_BASIS/api/v1/webhooks?id=whe_…" -H "Authorization: Bearer $GP_SCHLUESSEL"

Ohne Angabe von ereignisse erhalten Sie alle. GET /api/v1/webhooks listet Ihre Adressen, die letzten Zustellungen und die verfügbaren Ereignisse.

Ereignisse

Ereignis	Bedeutung
gegenpruefung.eingegangen	Der Vorgang wurde angenommen und die Auswertung hat begonnen.
gegenpruefung.abgeschlossen	Die Auswertung ist abgeschlossen, der Gegenprüfbericht ist abrufbar.
gegenpruefung.pruefung_erforderlich	Die Auswertung liegt vor, enthält aber Punkte, die ein Mensch prüfen muss. Der Bericht ist bereits abrufbar.
gegenpruefung.unterlagen_unvollstaendig	Für eine belastbare Gegenüberstellung fehlen Unterlagen.
gegenpruefung.abgelehnt	Der Vorgang wird nicht weiterverfolgt.

Signatur prüfen

Jede Zustellung trägt die Kopfzeile Gegenpruefung-Signatur im Format t=<zeitstempel>,v1=<hmac-sha256 über '<zeitstempel>.<körper>'>. Prüfen Sie sie, bevor Sie den Inhalt verarbeiten.

// Kopfzeile: Gegenpruefung-Signatur: t=1755594862,v1=6b1f…c4a9
import { createHmac, timingSafeEqual } from 'node:crypto';

export function pruefeSignatur(
  geheimnis: string,
  koerper: string,       // der ROHE Anfragekörper, nicht das geparste Objekt
  signaturKopf: string,  // Wert von "Gegenpruefung-Signatur"
  maximalesAlterSekunden = 300,
): boolean {
  const teile: Record<string, string> = {};
  for (const teil of signaturKopf.split(',')) {
    const [name, wert] = teil.split('=');
    teile[name?.trim() ?? ''] = wert?.trim() ?? '';
  }
  const zeitstempel = Number(teile.t);
  const gesendet = teile.v1 ?? '';
  if (!Number.isFinite(zeitstempel) || gesendet === '') return false;
  // Alte Zustellungen verwerfen: sonst liesse sich eine abgefangene
  // Nachricht beliebig spaeter erneut einspielen.
  if (Math.abs(Math.floor(Date.now() / 1000) - zeitstempel) > maximalesAlterSekunden) return false;

  const erwartet = createHmac('sha256', geheimnis).update(zeitstempel + '.' + koerper).digest('hex');
  const a = Buffer.from(erwartet);
  const b = Buffer.from(gesendet);
  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b); // zeitkonstant vergleichen
}

Zwei Punkte entscheiden über die Wirksamkeit: Der Zeitstempel geht in die Signatur ein und muss geprüft werden – ohne Altersprüfung ließe sich eine abgefangene Nachricht beliebig später erneut einspielen. Und der Vergleich erfolgt zeitkonstant, damit sich die richtige Signatur nicht zeichenweise erraten lässt.

Wiederholungssicherheit

Ein Verbindungsabbruch darf keinen zweiten Vorgang erzeugen

Der typische Fall: Ihr System sendet die Unterlagen, die Verbindung bricht vor der Antwort ab. War der Vorgang schon angelegt? Ohne Absicherung bleibt nur die Wahl zwischen einem verlorenen und einem doppelten Vorgang – beides muss anschließend jemand von Hand aufräumen.

Senden Sie deshalb bei jeder schreibenden Anfrage die Kopfzeile Idempotency-Key mit einem selbst erzeugten, einmaligen Wert; eine UUID genügt. Wiederholen Sie die Anfrage mit demselben Wert, erhalten Sie die ursprüngliche Antwort erneut, statt einen zweiten Vorgang anzulegen.

Die wiederholte Antwort trägt die Kopfzeile Idempotenz-Wiederholung: true. Daran erkennen Sie, dass nichts Neues entstanden ist.
Gesichert wird nur eine erfolgreiche Antwort (Status 2xx). Ein fehlgeschlagener Aufruf darf mit demselben Schlüssel wiederholt werden.
Der Schlüssel gilt je API-Schlüssel und Endpunkt. Verwenden Sie denselben Wert für einen anderen Endpunkt, antwortet die Schnittstelle mit 409 und idempotenz-konflikt.
Leiten Sie den Wert aus Ihrer eigenen Vorgangskennung ab und erzeugen Sie ihn nicht bei jedem Versuch neu – sonst hat er keine Wirkung.

Grenzen und Fehler

Ratenbegrenzung und Fehlerformat

Ratenbegrenzung

Gleitendes Fenster von 60 Sekunden, je Schlüssel gezählt.

Voreingestellt sind 120 Anfragen je Minute; für einzelne Schlüssel kann ein abweichender Wert hinterlegt sein. Den geltenden Wert nennt GET /api/v1/status.

RateLimit-Limit – die Obergrenze je Minute.
RateLimit-Remaining – wie viele Anfragen im laufenden Fenster noch frei sind.
Retry-After – nur bei 429: Wartezeit in Sekunden.
Gegenpruefung-Anfrage-Id – Kennung des Aufrufs; bitte bei Rückfragen angeben.

Diese Kopfzeilen trägt jede Antwort, deren Schlüssel gültig war. Fehlt der Schlüssel oder ist er ungültig, endet die Anfrage vorher mit 401 und der Kopfzeile WWW-Authenticate.

Fehlerformat nach RFC 9457

application/problem+json, in jedem Fehlerfall gleich aufgebaut.

HTTP/1.1 413 Content Too Large
Content-Type: application/problem+json; charset=utf-8

{
  "type": "/api/v1/fehler/datei-zu-gross",
  "title": "Datei überschreitet die zulässige Größe",
  "status": 413,
  "detail": "gutachten.pdf: Die Datei ist größer als zulässig.",
  "dateien": ["gutachten.pdf"]
}

Werten Sie ausschließlich type aus. Die Kennung ist stabil und lautet immer /api/v1/fehler/<code>. Der Text in title darf sich ändern, detail beschreibt den Einzelfall. Je nach Fehler kommen weitere Felder hinzu, etwa dateien oder fehlende_unterlagen.

Alle Fehlercodes

Vollständig. Andere Kennungen gibt die Schnittstelle nicht aus.

Kennung in type	HTTP	Empfohlene Reaktion des Clients
authentifizierung-fehlt	401	Kopfzeile Authorization ergänzen. Kein erneuter Versuch ohne Änderung.
schluessel-ungueltig	401	Schreibweise des Schlüssels prüfen. Kein automatischer Wiederholungsversuch.
schluessel-widerrufen	401	Neuen Schlüssel im Kanzleibereich erzeugen lassen.
schluessel-abgelaufen	401	Neuen Schlüssel erzeugen lassen.
berechtigung-fehlt	403	Die Antwort nennt die benötigte und die vorhandenen Berechtigungen. Schlüssel mit passendem Umfang verwenden.
nicht-gefunden	404	Kennung prüfen. Ein Schlüssel sieht ausschließlich Vorgänge der eigenen Organisation.
anfrage-ungueltig	400	Anfrage korrigieren; detail benennt den konkreten Punkt. Keine Wiederholung mit gleichem Inhalt.
datei-ungueltig	422	Datei prüfen: zulässig sind PDF, JPEG und PNG. Auch die überschrittene Höchstzahl je Vorgang meldet diesen Code.
datei-zu-gross	413	Datei verkleinern oder Unterlagen auf mehrere Anlagen aufteilen.
schadsoftware-erkannt	422	Die Datei wurde nicht gespeichert. Quelle prüfen, nicht erneut senden.
unterlagen-unvollstaendig	422	Fehlende Unterlagen über POST /gegenpruefungen/{id}/dokumente nachreichen.
bericht-noch-nicht-verfuegbar	409	Kein Fehler Ihres Aufrufs. Status erneut abfragen oder auf den Webhook warten; die Antwort nennt Status und fehlende Unterlagen.
idempotenz-konflikt	409	Derselbe Idempotency-Key wurde für einen anderen Endpunkt verwendet. Neuen Wert wählen.
zu-viele-anfragen	429	Retry-After abwarten und erst danach erneut senden.
nicht-zulaessig	403	Die Aktion ist über die Schnittstelle grundsätzlich nicht vorgesehen. Kein Wiederholungsversuch.
serverfehler	500	Mit wachsendem Abstand erneut versuchen. Bei Rückfragen die Kopfzeile Gegenpruefung-Anfrage-Id angeben.

Bewusste Grenze

Was die Schnittstelle nicht kann

Die Schnittstelle nimmt Vorgänge entgegen und gibt die technische Gegenüberstellung heraus. Eine anwaltliche Stellungnahme liefert sie nicht, und drei Dinge lässt sie bewusst nicht zu. Das ist keine Lücke im Funktionsumfang, sondern die Trennlinie des Betriebsmodells: Diese Schritte sind Rechtsdienstleistung und bleiben der Partnerkanzlei (PARTNERKANZLEI) vorbehalten.

Anwaltliche Freigabe eines Entwurfs

Ein Entwurf wird ausschließlich im Kanzleibereich durch eine anwaltliche Rolle freigegeben. Es existiert kein Endpunkt, über den ein Fremdsystem diese Freigabe erteilen oder auslösen könnte.

Aktivierung von Regelwerken

Welche Argumentationslinie zu welcher Kürzungskategorie gehört, ist eine anwaltliche Festlegung. Regelwerke werden von der Kanzlei geprüft und freigegeben, nicht über die Schnittstelle geschaltet.

Versand an Versicherungen

Die Kommunikation gegenüber der Versicherung ist Rechtsdienstleistung. Sie erfolgt ausschließlich durch die Partnerkanzlei und wird über die Schnittstelle weder angestoßen noch abgebrochen.

Dieselbe Liste gibt GET /api/v1/status unter nicht_verfuegbar maschinenlesbar aus, damit Ihre Integration nicht gegen eine Funktion plant, die es nicht geben wird.

Datenschutz und Sicherheit

In Kürze

Über die Schnittstelle laufen Schadengutachten und Prüfberichte – Unterlagen mit Namen, Anschrift, Kennzeichen und Unfallhergang. Die ausführliche Darstellung samt offener Punkte steht auf einer eigenen Seite.

Sicherheit und Datenschutz

Die Übertragung erfolgt über TLS. Adressen für Benachrichtigungen werden nur angenommen, wenn sie mit https:// beginnen.
Vom Schlüssel wird ausschließlich der SHA-256-Hash gespeichert. Sichtbar bleibt allein das Präfix zur Wiedererkennung in Oberfläche und Protokollen; der Vergleich läuft zeitkonstant.
Jeder Schlüssel gehört zu genau einer Organisation eines Mandanten. Die Zugehörigkeit steht in der Datenbankabfrage: Fremde Vorgänge werden nicht nachträglich gefiltert, sondern gar nicht erst geladen.
Jede hochgeladene Datei durchläuft eine Typprüfung anhand der tatsächlichen Dateisignatur und anschließend eine Virenprüfung. Als schadhaft eingestufte Dateien werden nicht gespeichert.
Protokolliert werden Zeitpunkt, Methode, Pfad, Statuscode, Dauer und der verwendete Schlüssel – nicht der Inhalt der Unterlagen.
Dokumenttext wird einem Sprachmodell nur als Datenblock übergeben, niemals als Anweisung. Im Analysepfad stehen dem Modell keinerlei Werkzeuge zur Verfügung.

Hinweis zu diesem System

Diese Anwendung ist eine Demonstrationsfassung und verarbeitet ausschließlich synthetische Daten. Reichen Sie über die Schnittstelle keine echten Schadenunterlagen ein. Es findet kein Versand an reale Empfänger statt; auch Webhook-Zustellungen werden im Demonstrationsbetrieb vollständig aufgebaut, signiert und protokolliert, verlassen das System aber nicht.

Weiterlesen

Die ausführliche Schnittstellenbeschreibung liegt als versioniertes Dokument im Quellcodeverzeichnis unter docs/API.md, die maschinenlesbare Fassung unter /api/v1/openapi.json. Welche Grenzen, Feldnamen und Statuswerte für Ihren Schlüssel tatsächlich gelten, beantwortet GET /api/v1/status – diese Auskunft veraltet nicht.

OpenAPI-Beschreibung Schlüssel anfordern