ZUGFeRD-Verarbeitung

Der ZUGFeRD-Endpunkt ist fuer Pro und Business verfuegbar. Er liest eingebettetes XML aus einem PDF und gibt dieselbe Antwort-Huelle wie die Standard-Extraktionsendpunkte zurueck.

Verwenden Sie POST /v1/extract/zugferd fuer Hybrid-PDFs mit unterstuetzten eingebetteten XML-Anhaengen.

Fuer die AP-Dokument-Antworthuelle, eigenstaendige XML-Uploads oder Business-only XRechnung- und Peppol-Verarbeitung verwenden Sie stattdessen POST /v1/documents/extract/file. In dieser API bleibt document_type der fachliche Dokumenttyp wie invoice oder credit_note; source_format kennzeichnet das strukturierte Format wie zugferd, factur_x, xrechnung oder peppol_bis_billing.

Unterstuetzte Anhaenge

Der Parser sucht nach bekannten eingebetteten XML-Dateinamen:

Wenn kein unterstuetzter XML-Anhang gelesen werden kann, gibt die Anfrage einen Anwendungsfehler zurueck.

Anfrage

Der Locale-Hinweis ist ein Query-Parameter.

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

Antwort

{
  "invoice_id": "2f7d7f8a-32fb-4a7c-a3b1-53b61b64252f",
  "invoice": {
    "document_type": "invoice",
    "vendor": {
      "name": "Muster GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE123456789",
      "iban": null,
      "bank_name": null
    },
    "buyer": {
      "name": "Buyer GmbH",
      "address": null,
      "email": null,
      "phone": null,
      "tax_id": "DE987654321",
      "iban": null,
      "bank_name": null
    },
    "invoice_number": "2026-DE-0042",
    "issue_date": "2026-06-01",
    "due_date": "2026-07-01",
    "billing_period_start": null,
    "billing_period_end": null,
    "reference_numbers": [],
    "line_items": [],
    "subtotal": 2500.0,
    "discount_total": null,
    "tax_breakdown": [
      {
        "tax_type": "VAT",
        "rate": 0.19,
        "taxable_amount": 2500.0,
        "tax_amount": 475.0
      }
    ],
    "tax_total": 475.0,
    "total_amount": 2975.0,
    "amount_paid": null,
    "amount_due": 2975.0,
    "currency": "EUR",
    "payment_terms": null,
    "payment_instructions": null,
    "locale": "de",
    "confidence": 1.0,
    "field_confidence": {},
    "notes": []
  },
  "duplicate_risk": null,
  "anomalies": [],
  "confidence_low": false,
  "field_bboxes": null
}

Tarif-Gating und Fallback

ZUGFeRD-Verarbeitung ist nur auf Pro und Business verfuegbar. Unterhalb von Pro antwortet der Endpunkt mit 402 und feature_not_in_plan; diese Antwort verbraucht kein Extraktionskontingent.

Wenn Ihre Anwendung sowohl hybride E-Rechnungen als auch normale PDFs annimmt, pruefen Sie den Tarif vor dem Anzeigen der ZUGFeRD-Option. Fuer nicht unterstuetzte PDFs oder Tarife unter Pro verwenden Sie den Standard-Upload POST /v1/extract/file.