Rechnungsextraktions-API

Parsurai stellt Extraktionsendpunkte fuer Text, Datei-Uploads, Remote-URLs und Pro-ZUGFeRD-PDFs bereit. Standardextraktion verwendet fuer alle Eingabearten dieselbe Antwort-Huelle.

Endpunktuebersicht

Text extrahieren

{
  "text": "Rechnung von Supplier Inc. Rechnungsnummer INV-9812. Gesamt: 1500 EUR. USt: 19%.",
  "locale": "auto"
}

curl -X POST https://api.parsurai.com/v1/extract \
  -H "X-API-Key: $PARSURAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Rechnung von Supplier Inc. INV-9812. Gesamt: 1500 EUR. USt: 19%.", "locale": "auto"}'

Datei extrahieren

Senden Sie ein PDF oder Bild als Multipart-Daten. Der Locale-Hinweis wird aus der Query gelesen.

curl -X POST "https://api.parsurai.com/v1/extract/file?locale=de" \
  -H "X-API-Key: $PARSURAI_API_KEY" \
  -F "file=@invoice.pdf"

URL extrahieren

{
  "url": "https://example.com/invoices/inv-01.jpg",
  "locale": "auto"
}

Antwortschema

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Supplier Inc.",
      "address": "Main Street 1, 10115 Berlin",
      "email": null,
      "phone": null,
      "tax_id": "DE123456789",
      "iban": "DE89370400440532013000",
      "bank_name": null
    },
    "buyer": {
      "name": "Buyer GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE987654321",
      "iban": null,
      "bank_name": null
    },
    "invoice_number": "INV-9812",
    "issue_date": "2026-06-13",
    "due_date": "2026-07-13",
    "billing_period_start": null,
    "billing_period_end": null,
    "reference_numbers": [{ "type": "order", "value": "PO-7781" }],
    "line_items": [
      {
        "description": "Consulting",
        "quantity": 1,
        "unit": "hour",
        "unit_price": 1500.0,
        "discount": null,
        "total": 1500.0,
        "tax_rate": 0.19
      }
    ],
    "subtotal": 1500.0,
    "discount_total": null,
    "tax_breakdown": [
      {
        "tax_type": "VAT",
        "rate": 0.19,
        "taxable_amount": 1500.0,
        "tax_amount": 285.0
      }
    ],
    "tax_total": 285.0,
    "total_amount": 1785.0,
    "amount_paid": null,
    "amount_due": 1785.0,
    "currency": "EUR",
    "payment_terms": "Net 30",
    "payment_instructions": "Pay by bank transfer.",
    "locale": "de",
    "confidence": 0.97,
    "field_confidence": {},
    "notes": []
  },
  "duplicate_risk": null,
  "anomalies": [],
  "confidence_low": false,
  "field_bboxes": null
}

Feldreferenz

Locale-Unterstuetzung

Explizite Locale-Werte ausser auto erfordern Hobby, Starter, Pro oder Business.

Tarifabhaengige Antwortfelder

Die Top-Level-Antwort enthaelt immer duplicate_risk, anomalies, confidence_low und field_bboxes; die Werte haengen aber von Tarif und Eingabetyp ab.

Genauigkeitsmodus (Accuracy Mode)

Zur Unterstuetzung von Hochpraezisions-Workflows bietet Parsurai einen Genauigkeitsmodus (Enhanced Accuracy Mode), der exklusiv fuer die Tarife Pro und Business verfuegbar ist.

Parameter

• accuracy_mode (string): Standardmaessig auf standard oder enhanced.
  • Standardwert: standard
  • Unterstuetzt bei: JSON-Body fuer POST /v1/extract und POST /v1/extract/url; Query-Parameter accuracy_mode fuer POST /v1/extract/file.
  • Tarif-Beschraenkung: enhanced erfordert Pro oder Business. Anfragen mit enhanced Genauigkeitsmodus in niedrigeren Tarifen schlagen mit dem Fehler 402 feature_not_in_plan fehl.

Funktionsweise

Im Gegensatz zur Standardextraktion wendet der Enhanced Accuracy Mode Folgendes an:

1. Deterministische Validatoren: Pruefregeln werden ausgefuehrt (z.B. Abgleich, ob Einzelposten mit Zwischensummen und Gesamtbetraegen, USt/Steuerberechnungen sowie Rechnungsdaten uebereinstimmen).
2. Ein begrenzter Korrekturversuch: Wenn eine Validierungspruefung fehlschlaegt, unternimmt die Engine einen einzelnen Korrekturversuch ueber das LLM mit den Fehlerdetails.
3. Tradeoffs: Aufgrund der Validierungs- und Korrekturschleife fuehrt der Enhanced-Modus zu hoeherer Latenz und zusätzlichen Modellkosten (bis zu zwei LLM-Aufrufe pro Rechnungsextraktion).

Beispiel fuer das accuracy-Antwortobjekt

Wenn accuracy_mode angefordert wird (oder in einer tarifbeschraenkten Antwort enthalten ist), enthaelt die Top-Level-Extraktionsantwort ein accuracy-Metadatenobjekt mit detaillierten Ausführungsstatistiken:

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Supplier Inc.",
      "tax_id": "DE123456789",
      "iban": "DE89370400440532013000"
    },
    "subtotal": 1500.0,
    "tax_total": 285.0,
    "total_amount": 1785.0,
    "confidence": 0.97
  },
  "accuracy": {
    "mode": "enhanced",
    "correction_attempted": true,
    "correction_used": true,
    "validators_failed": [
      "subtotal_tax_match"
    ],
    "unresolved_warnings": [],
    "findings": [],
    "latency_ms": 1250,
    "model_calls": 2,
    "tokens_input": 1850,
    "tokens_output": 450
  }
}

Feldreferenz fuer das accuracy-Objekt

Dokumentgrenzen

Jeder Upload wird vor der Extraktion begrenzt. Ein Dokument oberhalb einer Grenze wird mit dem jeweiligen Code abgelehnt, statt teilweise verarbeitet zu werden.

100 Seiten sind eine absolute serverseitige Obergrenze, kein Tarifanspruch. Das fuer eine Anfrage geltende Seitenlimit ist der niedrigere Wert aus dieser Obergrenze und dem Kontingent Ihres Tarifs fuer den aufgerufenen Endpunkt. Kein Endpunkt und kein kuenftiger Tarif kann mehr als 100 Seiten senden.

Extrahierter Text ist auf 400.000 Zeichen begrenzt. Diese Grenze kuerzt, statt fehlzuschlagen: ein laengeres Dokument wird bis dahin extrahiert und normal verarbeitet.

Gescannte und reine Bild-PDFs

Ein aus einem Scan erzeugtes PDF enthaelt keine Textebene, sodass das Auslesen des PDFs nichts liefert. Parsurai erkennt das und liest dieselbe Datei vor der Extraktion per OCR erneut, sodass sich ein als PDF verpackter Scan wie derselbe Scan als JPEG oder PNG verhaelt.

Der OCR-Rueckfallpfad ist unabhaengig von den obigen Seitenlimits begrenzt: er laeuft auf Dokumenten mit hoechstens 10 Seiten. Ein laengerer Scan wird mit 422 pdf_no_extractable_text abgelehnt, statt zur Erkennung gesendet zu werden. Kann auch OCR die Datei nicht lesen oder ist die Erkennung momentan nicht verfuegbar, schlaegt die Anfrage mit 422 pdf_no_extractable_text bzw. 503 ocr_unavailable fehl -- die Anfrage erreicht das Modell nie mit einem leeren Dokument.

Haeufige Fehlerantworten

428 ist der einzige Fehler, den ein Retry nicht aufloest. Er bedeutet, dass der Kontoinhaber aktualisierte AGB oder eine aktualisierte Datenschutzerklaerung noch nicht akzeptiert hat. Jeder authentifizierte Endpunkt gibt ihn zurueck, bis das im Dashboard geschieht — ein API-Schluessel kann nicht stellvertretend akzeptieren. In einer unbeaufsichtigten Integration gehoert dieser Fall auf einen Alarm, nicht in die Retry-Schleife.

---

AP-Dokumentenextraktion (Pro und Business)

Die /v1/documents-Endpunkte extrahieren Accounts-Payable-Dokumente ueber Standardrechnungen hinaus. Sie unterstuetzen DACH-E-Rechnungen sowie Einkaufs-, Liefer-, Zahlungs- und Bankdokumente.

Endpunktuebersicht

Dokumenttypen und Quellformate

AP-Antworten verwenden eine eigene document-Huelle mit document_type und source_format. document_type beschreibt den Geschaeftsbeleg, zum Beispiel purchase_order, delivery_note, remittance_advice, payment_advice oder bank_statement. source_format beschreibt das Eingabeformat, zum Beispiel pdf, image, xrechnung, zugferd, factur_x oder peppol_bis_billing.

XRechnung, ZUGFeRD/Factur-X und Peppol BIS Billing 3.0 werden deterministisch geparst, wenn das Profil unterstuetzt ist. Nicht unterstuetzte XML-Profile liefern 422 unsupported_einvoice_profile.

{
  "document_id": "3a1b2c4d-...",
  "document_type": "invoice",
  "source_format": "xrechnung",
  "schema_version": "1.0",
  "document": {},
  "classification": {
    "document_type": "invoice",
    "confidence": 0.98,
    "signals": ["xml_profile_xrechnung"]
  },
  "warnings": []
}