DocAI API-Dokumentation

DocAI bietet eine REST-API, um strukturierte Daten aus hochgeladenen Dokumenten oder normalisierten E-Mail-Anhängen zu extrahieren. Persistente Jobs, menschliche Genehmigung, signierte Webhooks und Buchhaltungsexporte unterstützen Automatisierungsabläufe in Make, n8n, Zapier oder eigenen Integrationen.

Entwickeln Sie eher mit einem Coding-Agenten als mit Anwendungscode? DocAI MCP verbindet Codex, Claude Code, Gemini CLI und andere MCP-kompatible Agenten mit derselben API.

Authentifizierung

Erstellen und verwalten Sie API-Schlüssel auf der Seite Entwicklereinstellungen. Senden Sie den Schlüssel als Bearer-Token; Scopes und das monatliche Seitenkontingent des Schlüssels werden bei jeder Anfrage durchgesetzt.

Authorization: Bearer sk_docai_<your_key>

API-Schlüssel beginnen mit sk_docai_. Halten Sie sie geheim. Sie werden nur einmal bei der Erstellung angezeigt.

Verwenden Sie den Bereich extract, um Aufträge zu übermitteln und zu überwachen. Fügen Sie den Bereich history hinzu, um gespeicherte Ergebnisse und Buchhaltungsexporte abzurufen. Dies sind die einzigen unterstützten API-Schlüssel-Bereiche.

Ratenbegrenzungen

Die Analysenutzung richtet sich nach dem Seitenkontingent und dem Speicherkontingent Ihres Tarifs. Es gibt keine separate Begrenzung pro Anfrage oder pro Tag.

API-Schlüssel verrechnen zusätzlich OCR-Seiten mit dem monatlichen Seitenkontingent des Schlüssels.

Anfragen ohne verbleibende Seiten oder Speicher geben HTTP 402 zurück; ein API-Schlüssel über seinem monatlichen Seitenkontingent gibt HTTP 429 mit einem Retry-After-Hinweis zurück.

Fehlerformat

{
  "detail": "File too large. Maximum upload size is 15 MB.",
  "request_id": "abc123"
}

Synchrone Dokumentextraktion

POST/api/v1/analyze

Laden Sie ein Dokument hoch und erhalten Sie die Extraktionsergebnisse synchron. Am besten für kleine Dokumente (< 2 Seiten).

Anfrage

Multipart-Formulardaten:

Feld	Typ		Beschreibung
`file`	file	erforderlich	PDF, PNG, JPG, HEIC, AVIF, TIFF, BMP oder WEBP (max. 15 MB)
`filename`	string	optional	Den angezeigten Dateinamen überschreiben

Beispiel

curl -X POST https://docai.synairo.com/api/v1/analyze \
  -H "Authorization: Bearer sk_docai_..." \
  -F "file=@purchase_order.pdf"

Antwort

{
  "request_id": "3fa8...",
  "filename": "purchase_order.pdf",
  "document_type": "purchase_order",
  "document_type_confidence": 0.94,
  "summary": "Purchase order from Acme Corp to Widget Co.",
  "language": "en",
  "extracted_fields": [
    {
      "field": "po_number",
      "value": "PO-2026-0042",
      "confidence": 0.97,
      "page": 1,
      "evidence": "PO-2026-0042"
    }
  ],
  "warnings": [],
  "ocr": { "pages": 1, "tokens": 312, "language": "eng+pol" },
  "llm": { "status": "success", "provider": "openai", "model": "gpt-4o-mini" }
}

Streaming-Extraktion (SSE)

POST/api/v1/analyze/stream

Wie die synchrone Variante, streamt jedoch Server-Sent Events, die den Verarbeitungsfortschritt anzeigen. Am besten für Echtzeit-Oberflächen.

Asynchronen Job erstellen

POST/api/v1/jobs

Laden Sie ein Dokument hoch und erhalten Sie eine Job-ID. Die Verarbeitung erfolgt im Hintergrund.

curl -X POST https://docai.synairo.com/api/v1/jobs \
  -H "Authorization: Bearer sk_docai_..." \
  -F "file=@invoice.pdf"

{ "job_id": "abc123", "status": "queued", "request_id": "xyz..." }

E-Mail-Anhänge erfassen

POST/api/v1/ingest/email

Anbieterneutrale Brücke für eingehende E-Mails. Postmark, Mailgun, SendGrid, Amazon SES, Make, n8n oder ein anderer Adapter müssen die Anbieternutzlast analysieren und akzeptierte Anhänge als Multipart-Formulardaten senden. DocAI hostet kein Postfach und führt keine anbieterspezifische MIME-Analyse durch.

Feld	Typ		Beschreibung
`message_id`	string	erforderlich	Stabile Nachrichtenkennung des Anbieters
`source_namespace`	string	erforderlich	Stabiler Anbieter-/Kontobereich, beispielsweise postmark:server-123
`files`	file[]	erforderlich	Für jeden unterstützten Anhang wiederholen
`organization_id`	string	optional	Zielarbeitsbereich; der Aufrufer muss über Upload-Berechtigung verfügen

curl -X POST https://docai.synairo.com/api/v1/ingest/email \
  -H "Authorization: Bearer sk_docai_..." \
  -F "message_id=provider-message-42" \
  -F "source_namespace=postmark:server-123" \
  -F "organization_id=org_..." \
  -F "files=@invoice.pdf;type=application/pdf" \
  -F "files=@receipt.jpg;type=image/jpeg"

{
  "message_id": "provider-message-42",
  "source_namespace": "postmark:server-123",
  "accepted_count": 1,
  "duplicate_count": 1,
  "jobs": [
    {"job_id": "job-new", "status": "queued", "filename": "invoice.pdf", "duplicate": false},
    {"job_id": "job-old", "status": "completed", "filename": "receipt.jpg", "duplicate": true}
  ]
}

Die Idempotenz umfasst den authentifizierten Eigentümer, den Anbieter-/Kontonamensraum, das Ziel, die Nachrichten-ID, den normalisierten Dateinamen, den Dateiinhaltswert und das Vorkommen unter identischen Anhängen. Neu geordnete Wiederholungsversuche des Anbieters geben die ursprünglichen Auftrags-IDs zurück. Eine fehlgeschlagene Erfassung kann denselben Auftrag mit neuen Bytes bis zu insgesamt drei Mal erneut in die Warteschlange stellen; aktive und abgeschlossene Aufträge werden nie zweimal verarbeitet.

Job-Status abrufen

GET/api/v1/jobs/{job_id}

curl https://docai.synairo.com/api/v1/jobs/abc123 \
  -H "Authorization: Bearer sk_docai_..."

{
  "id": "abc123",
  "status": "completed",
  "progress_pct": 100,
  "document_type": "invoice",
  "pages_processed": 2
}

Mögliche Status: queued, processing, review_required, completed, failed, cancelled.

Job-Ergebnis abrufen

GET/api/v1/jobs/{job_id}/result

Gibt das vollständige Extraktionsergebnis zurück, sobald der Job-Status completed oder review_required ist. Für API-Schlüssel ist der Bereich history erforderlich.

curl https://docai.synairo.com/api/v1/jobs/abc123/result \
  -H "Authorization: Bearer sk_docai_..."

JSON exportieren

POST/api/v1/export/json

Senden Sie das Extraktionsergebnis als JSON-Body und erhalten Sie eine bereinigte Exportdatei.

curl -X POST https://docai.synairo.com/api/v1/export/json \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_docai_..." \
  -d '{"request_id":"...","extracted_fields":[...]}' \
  -o export.json

CSV exportieren

POST/api/v1/export/csv

curl -X POST https://docai.synairo.com/api/v1/export/csv \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_docai_..." \
  -d '{"request_id":"...","extracted_fields":[...]}' \
  -o fields.csv

XLSX exportieren

POST/api/v1/export/xlsx

Gibt eine Excel-Arbeitsmappe mit den Tabellenblättern Zusammenfassung, Felder, Positionen, Warnungen und Metadaten zurück.

Verlauf auflisten

GET/api/v1/history

curl https://docai.synairo.com/api/v1/history \
  -H "Authorization: Bearer sk_docai_..."

Prüf- und Genehmigungsablauf

POST/api/v1/history/{record_id}/workflow

Wenden Sie einen kontrollierten Workflow-Übergang auf einen gespeicherten Datensatz an. Diese Route erfordert eine interaktive Clerk-Sitzung: API-Schlüssel können keine Dokumente genehmigen. Arbeitsbereichsmitglieder können prüfen; Arbeitsbereichsadministratoren können genehmigen, Änderungen anfordern oder ablehnen. Der Eigentümer eines persönlichen Datensatzes nimmt beide Rollen wahr.

{
  "action": "approve",
  "comment": "Ready to post"
}

Aktionen: start_review, complete_review, reopen_review, submit_for_approval, approve, request_changes, reject und accept_partial_analysis. Die Genehmigung schreibt das Workflow-Audit-Ereignis und das Outbox-Ereignis document.approved gemeinsam.

Gesamten Verlauf löschen

DELETE/api/v1/history

Löscht alle gespeicherten Analysen Ihres Kontos dauerhaft.

API-Schlüssel auflisten

GET/api/v1/keys

API-Schlüssel erstellen

POST/api/v1/keys

curl -X POST https://docai.synairo.com/api/v1/keys \
  -H "Authorization: Bearer <clerk_session_token>" \
  -H "Content-Type: application/json" \
          -d '{"name": "My automation key", "scopes": "extract,history"}'

{
  "id": "...",
  "name": "My automation key",
  "key": "sk_docai_...",   // shown ONCE - save it now
  "prefix": "sk_docai_abc",
  "scopes": "extract,history",
  "created_at": "2026-06-10T12:00:00Z"
}

API-Schlüssel widerrufen

DELETE/api/v1/keys/{key_id}

Webhook erstellen

POST/api/v1/webhooks

curl -X POST https://docai.synairo.com/api/v1/webhooks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
          -d '{"name": "My webhook", "endpoint_url": "https://my.app/hook", "event_types": ["document.completed", "document.review_required", "document.approved", "document.failed"]}'

Die Antwort enthält ein secret zur Signaturverifizierung. speichern Sie es jetzt, es wird nicht erneut angezeigt.

Webhook-Ereignistypen

Ereignis	Wann es ausgelöst wird
`document.completed`	Extraktion abgeschlossen und Ergebnis gespeichert
`document.review_required`	Validierung oder Konfidenz-Routing erfordert eine menschliche Prüfung; wird auch mit document.completed ausgelöst
`document.approved`	Ein berechtigter Genehmigender hat die Genehmigungsentscheidung bestätigt; verwenden Sie dies für Buchungsvorgänge
`document.failed`	Verarbeitung fehlgeschlagen; per E-Mail erfasste Aufträge enthalten Metadaten zur Wiederholbarkeit und zu Versuchen

Verwenden Sie document.approved und nicht document.completed als Kontrollpunkt für die Übertragung von Daten an ein Buchhaltungssystem. Die Extraktion kann abgeschlossen sein, obwohl Felder noch korrigiert werden müssen.

Webhook testen

POST/api/v1/webhooks/{webhook_id}/test

Webhook-Signatur verifizieren

Jede Zustellung enthält diese Header:

X-DocAI-Event. Ereignistyp (z. B. document.completed)
X-DocAI-Timestamp. ISO-8601-UTC-Zeitstempel
X-DocAI-Signature. sha256=<hmac>

import hashlib, hmac

def verify(secret, body_str, timestamp, signature_header):
    msg = f"{timestamp}.{body_str}"
    digest = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={digest}", signature_header)

Fehlgeschlagene dauerhafte Ereignisse

DocAI wiederholt ausgehende Zustellungen automatisch. Wenn ein dauerhaftes Outbox-Ereignis nach fünf Versuchen nicht erweitert werden kann, wird es zu einem unzustellbaren Ereignis. Der Eigentümer kann Metadaten prüfen, ohne die gespeicherte Nutzlast offenzulegen, und das Ereignis nach Behebung der Ursache erneut abspielen.

GET/api/v1/webhook-outbox/failed

curl https://docai.synairo.com/api/v1/webhook-outbox/failed \
  -H "Authorization: Bearer sk_docai_..."

POST/api/v1/webhook-outbox/{event_id}/replay

curl -X POST https://docai.synairo.com/api/v1/webhook-outbox/EVENT_ID/replay \
  -H "Authorization: Bearer sk_docai_..."

Dieselben Steuerungsmöglichkeiten finden Sie unter Entwicklereinstellungen → Ereignisse, die Aufmerksamkeit erfordern. Zustellungs- und abgeschlossene Outbox-Datensätze werden 30 Tage lang aufbewahrt.

Verwendung mit Make / n8n / Zapier

Für direkte Uploads rufen Sie /api/v1/jobs auf. Bei eingehenden E-Mails lassen Sie den Anbieter die Anhänge analysieren und /api/v1/ingest/email mit einer stabilen Nachrichten-ID und einem Quellnamensraum aufrufen. Beide Routen erstellen dieselben dauerhaften Aufträge und verwenden denselben Prüfablauf.

Abonnieren Sie Abschluss- und Prüfereignisse für Statusinformationen und verwenden Sie anschließend document.approved, um kontrollierte nachgelagerte Buchhaltungsaktionen auszulösen. Signierte Webhooks machen Abfragen überflüssig.