CheckVertrag
Prüfen
API-Integration

Vertragsanalyse-API: Integration Schritt für Schritt

Die Analyse-Engine hinter CheckVertrag lässt sich als REST-API in Ihr Produkt einbinden: Dokument hochladen, Status abfragen oder Webhook empfangen, strukturiertes Ergebnis verarbeiten. Diese Seite beschreibt den Ablauf, das Antwortformat und die typischen Stolpersteine.

Demo & Preise anfragenEngine live testen

Der Ablauf in vier Schritten

  • 1. Authentifizieren: API-Key im Header, getrennte Keys für Test- und Produktivumgebung.
  • 2. Analyse anlegen: Dokument als Multipart-Upload (PDF, DOCX, JPG/PNG-Scan) inklusive Rechtsraum DE oder AT.
  • 3. Ergebnis abholen: entweder per Polling auf die Analyse-ID oder per Webhook, sobald der Status auf completed wechselt.
  • 4. Weiterverarbeiten: JSON in Akte, CRM oder Dashboard schreiben und im eigenen Branding darstellen.

Endpunkte

POST   /v1/analyses          Analyse starten (multipart: file, jurisdiction)
GET    /v1/analyses/{id}     Status und Ergebnis abrufen
GET    /v1/analyses          Liste mit Filter auf Zeitraum und Status
POST   /v1/webhooks          Callback-URL registrieren
DELETE /v1/analyses/{id}     Dokument und Ergebnis sofort löschen

Antwortformat

Jede abgeschlossene Analyse liefert dieselbe Struktur – Sie können also gegen ein festes Schema entwickeln.

{
  "id": "an_8f2c…",
  "status": "completed",
  "contract_type": "arbeitsvertrag",
  "risk_score": 68,
  "summary": "Befristung ohne Sachgrund, weite Versetzungsklausel …",
  "term": { "end_date": "2027-03-31",
            "notice_period_days": 90,
            "auto_renew": true },
  "findings": [
    {
      "severity": "critical",
      "category": "clause",
      "title": "Kurze Ausschlussfrist, erhöhter Prüfbedarf",
      "quote": "Ansprüche verfallen, wenn sie nicht innerhalb von zwei Monaten …",
      "recommendation": "Diesen Punkt vor Unterzeichnung prüfen und bei Bedarf rechtlich beraten lassen.",
      "legal_reference": "§ 307 BGB"
    }
  ]
}

Statuswerte und Fehlerbehandlung

Status / CodeBedeutungEmpfohlene Reaktion
queued / processingAnalyse läuft, typischerweise unter 30 SekundenPolling im Abstand von 2–3 Sekunden oder Webhook abwarten
completedErgebnis vollständig verfügbarfindings verarbeiten und anzeigen
partialNur ein Teil des Dokuments war lesbar (z. B. schlechter Scan)Ergebnis anzeigen und Hinweis auf eingeschränkte Textbasis einblenden
422 unsupported_fileDateityp oder Größe außerhalb der LimitsNutzer zu PDF/DOCX oder kleinerer Datei führen
429 rate_limitedKontingent im Zeitfenster erschöpftBackoff und Wiederholung, Volumenpaket prüfen
5xxTemporärer Fehler in der VerarbeitungIdempotenter Retry mit derselben Referenz-ID

Limits und Verarbeitung

  • Dateiformate: PDF, DOCX und Bild-Scans; gescannte Dokumente laufen automatisch durch OCR.
  • Antwortzeit typischerweise unter 30 Sekunden, bei sehr langen Verträgen mit OCR entsprechend länger.
  • Bulk: Analysen können parallel angelegt werden, das Volumenkontingent gilt pro Monat, nicht pro Minute.
  • Testzugang mit eigenem Key und Beispielverträgen, damit Sie ohne Produktivdaten entwickeln können.
  • Kein eigenes Modell-Hosting nötig: Modelle, Prompts und juristische Redaktion werden laufend gepflegt.

Häufige Fragen

Wie lange dauert eine API-Integration?
Teams setzen die Anbindung erfahrungsgemäß in ein bis zwei Wochen um: Upload, Statusabfrage oder Webhook und die Darstellung der Fundstellen. Wer keine eigene Oberfläche bauen will, nutzt stattdessen das gebrandete Modul und ist an einem Tag live.
Gibt es Webhooks oder muss ich pollen?
Beides ist möglich. Für Server-zu-Server-Integrationen empfehlen wir Webhooks auf den Status completed; im Frontend ist kurzes Polling auf die Analyse-ID meist einfacher.
Kann ich Scans und Fotos schicken?
Ja. Bild-Scans und fotografierte Verträge werden per OCR verarbeitet. Ist nur ein Teil lesbar, liefert die API den Status partial statt eines Fehlers, sodass Sie das Teilergebnis trotzdem anzeigen können.
Wie werden Analysen abgerechnet?
Volumenbasiert: monatliche Plattformgebühr plus Preis pro abgeschlossener Analyse. Fehlgeschlagene Analysen werden nicht berechnet.

Weiterlesen