DocSolved API-Dokumentation

DocSolved 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.

Extrahieren Sie Ihr erstes Dokument in unter 3 Minuten

1. Erstellen Sie einen API-Schlüssel in den Entwicklereinstellungen. Der Scope extract reicht für diesen Ablauf; der Schlüssel wird nur einmal angezeigt.
2. Senden Sie das Dokument als asynchronen Job, fragen Sie den Status ab, bis er fertig ist, und holen Sie das Ergebnis.
3. Jedes Feld in result.extracted_fields[] hat dieselben Schlüssel: confidence, page, evidence (der Quelltext), match_status und bounding_box. Auf dem OCR-Weg sind sie gefüllt, wenn der Wert auf der Seite lokalisiert werden konnte (match_status exact, fuzzy oder llm_located); ein Wert, den die OCR nicht verankern konnte, ist not_found mit leerem Rahmen. Strukturierte E-Rechnungen werden aus ihrem XML geparst, ihre Felder tragen daher weder Seite noch Rahmen.

cURL

export DOCAI_API_KEY="sk_docai_YOUR_KEY"

# 1. submit (a retried submit with the same Idempotency-Key returns the same job)
JOB_ID=$(curl -s -X POST https://docsolved.ai/api/v1/jobs \
  -H "Authorization: Bearer $DOCAI_API_KEY" \
  -H "Idempotency-Key: invoice-2026-0847" \
  -F "[email protected]" | python3 -c 'import json,sys; print(json.load(sys.stdin)["job_id"])')

# 2. poll until status is completed / review_required / failed
until curl -s https://docsolved.ai/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $DOCAI_API_KEY" | grep -qE '"status": ?"(completed|review_required|failed)"'; do sleep 2; done

# 3. result
curl -s https://docsolved.ai/api/v1/jobs/$JOB_ID/result \
  -H "Authorization: Bearer $DOCAI_API_KEY"

Python

import os, time, requests

BASE = "https://docsolved.ai/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['DOCAI_API_KEY']}"}

with open("invoice.pdf", "rb") as f:
    submit = requests.post(f"{BASE}/jobs", headers={**HEADERS, "Idempotency-Key": "invoice-2026-0847"},
                           files={"file": ("invoice.pdf", f, "application/pdf")}, timeout=60)
submit.raise_for_status()
job_id = submit.json()["job_id"]

while True:
    status = requests.get(f"{BASE}/jobs/{job_id}", headers=HEADERS, timeout=30).json()["status"]
    if status in ("completed", "review_required", "failed"):
        break
    time.sleep(2)

result = requests.get(f"{BASE}/jobs/{job_id}/result", headers=HEADERS, timeout=30).json()["result"]
for field in result["extracted_fields"]:
    print(field["field"], field["value"], field["confidence"], field.get("page"), field.get("evidence"))

JavaScript / Node.js 20+

import { readFile } from "node:fs/promises";

const BASE = "https://docsolved.ai/api/v1";
const headers = { Authorization: `Bearer ${process.env.DOCAI_API_KEY}` };

const form = new FormData();
form.append("file", new Blob([await readFile("invoice.pdf")], { type: "application/pdf" }), "invoice.pdf");
const submit = await fetch(`${BASE}/jobs`, { method: "POST", headers: { ...headers, "Idempotency-Key": "invoice-2026-0847" }, body: form });
const { job_id } = await submit.json();

let status;
do {
  await new Promise((r) => setTimeout(r, 2000));
  ({ status } = await (await fetch(`${BASE}/jobs/${job_id}`, { headers })).json());
} while (!["completed", "review_required", "failed"].includes(status));

const { result } = await (await fetch(`${BASE}/jobs/${job_id}/result`, { headers })).json();
for (const f of result.extracted_fields) console.log(f.field, f.value, f.confidence, f.page, f.evidence);

Danach: Webhooks statt Polling, idempotente Übermittlung, Prüfung und Freigabe, Exporte, E-Mail-Eingang oder dieselbe API aus einem Coding-Agenten über MCP.

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 Scope extract, um Jobs zu senden und ihre Ergebnisse zu lesen. Fügen Sie den Scope history hinzu, um gespeicherte Datensätze aufzulisten und Buchhaltungsexporte herunterzuladen, und den Scope webhooks, um Webhook-Endpunkte zu verwalten. Das sind die einzigen unterstützten Scopes für API-Schlüssel. Schlüssel laufen nicht ab; widerrufen Sie einen Schlüssel in den Entwicklereinstellungen, sobald er nicht mehr benötigt wird.

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.

Hilfsendpunkte (Validierungshelfer, Webhook anlegen/testen/erneut senden, öffentliche Freigabelinks) haben eine Burst-Grenze von 60 Anfragen pro Minute und IP, 600 für authentifizierte Aufrufer; jede 429-Antwort enthält Retry-After in Sekunden. Die aktuellen Werte veröffentlicht GET /api/v1/capabilities unter rate_limits.

Fehlerformat

{
  "detail": "File too large. Maximum upload size is 15 MB.",
  "request_id": "3f1c9d2e8b4a4c0e9a7d1b2c3d4e5f60",
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File too large. Maximum upload size is 15 MB.",
    "retryable": false,
    "request_id": "3f1c9d2e8b4a4c0e9a7d1b2c3d4e5f60"
  }
}

Verzweigen Sie anhand von error.code, nie anhand des Texts. Codes: INVALID_REQUEST, AUTHENTICATION_REQUIRED, PERMISSION_DENIED, NOT_FOUND, FILE_TOO_LARGE, UNSUPPORTED_DOCUMENT, RATE_LIMITED, QUOTA_EXCEEDED, IDEMPOTENCY_KEY_CONFLICT, PROCESSING_TIMEOUT, INTERNAL_ERROR. Wiederholen Sie nur, wenn retryable wahr ist, beachten Sie Retry-After und senden Sie denselben Idempotency-Key erneut. Geben Sie request_id (auch als Header X-Request-ID gesendet) an, wenn Sie den Support kontaktieren.

Kompatibilität

Innerhalb von /api/v1 sind Änderungen nur additiv: Pfade, Felder, Fehlercodes und Job-Status werden nie entfernt oder umtypisiert. Inkompatible Änderungen erscheinen als /api/v2 mit mindestens 12 Monaten Überlappung, angekündigt im Änderungsprotokoll und mit den Headern Deprecation und Sunset. Lesen Sie GET /api/v1/capabilities beim Start, statt Formate und Limits fest zu codieren.

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:

Beispiel

curl -X POST https://docsolved.ai/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://docsolved.ai/api/v1/jobs \
  -H "Authorization: Bearer sk_docai_..." \
  -F "[email protected]"

{ "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. DocSolved hostet kein Postfach und führt keine anbieterspezifische MIME-Analyse durch.

curl -X POST https://docsolved.ai/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 "[email protected];type=application/pdf" \
  -F "[email protected];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://docsolved.ai/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

Liefert das vollständige Extraktionsergebnis, sobald der Job-Status completed oder review_required ist. Akzeptiert den Scope extract oder history, sodass ein reiner extract-Schlüssel den gesamten Ablauf aus Senden, Abfragen und Ergebnis abdeckt.

curl https://docsolved.ai/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://docsolved.ai/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://docsolved.ai/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://docsolved.ai/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://docsolved.ai/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://docsolved.ai/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

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

DocSolved 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://docsolved.ai/api/v1/webhook-outbox/failed \
  -H "Authorization: Bearer sk_docai_..."

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

curl -X POST https://docsolved.ai/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.