Serverseitige API für Validierung und UBL-Erstellung

Anfrage

Der Endpunkt akzeptiert genau eine Datei pro Request. Nutzen Sie Multipart-Upload und senden Sie Ihren API-Schlüssel im Header. Reichen Sie nur Dateien ein, die Sie selbst außerhalb der Plattform archivieren und verwalten.

• Form-Feld `file`: XML oder ZUGFeRD/Factur-X PDF
• Query `lang`: `de` oder `en` für rehydrierte Fehlermeldungen
• Unterstützte Formate: UBL XML, CII XML, ZUGFeRD-/Factur-X-PDF mit EN16931-kompatiblem eingebettetem XML. ZUGFeRD 2.5 / Factur-X 1.09 ist als aktueller Hybridstandard vermerkt; die Prüfung bewertet den eingebetteten XML-Datensatz.
• Dateigröße: maximal 10 MB

curl -X POST \
  "https://e-rechnung-check.de/api/external/validate?lang=de" \
  -H "X-API-Key: erk_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "file=@invoice.xml"

Antwort

Der Endpunkt gibt aktuell JSON zurück: Status, erkannte Syntax/Profile, Fehler, Warnungen und eine optionale strukturierte Rechnungszusammenfassung. Dieses JSON ist das primäre Format für SAP-, ERP- und Backend-Integrationen.

{
  "status": "done",
  "is_valid": false,
  "xrechnung_version": "3.0.1",
  "validation_profile": "XRechnung",
  "validation_format": "UBL",
  "processing_time_ms": 842,
  "errors": [
    {
      "code": "BR-DE-14",
      "severity": "fatal",
      "validation_layer": "cius",
      "section": "Seller",
      "title": "Seller VAT ID is missing",
      "explanation": "The invoice is missing a required seller VAT identifier.",
      "fix": "Add the seller VAT ID in the seller party block.",
      "bt_field": "BT-31",
      "xpath": "/Invoice/..."
    }
  ],
  "warnings": [],
  "validation_details": {
    "invoice_identity": {
      "syntax": "UBL",
      "declared_profile": "XRechnung",
      "declared_version": "3.0",
      "customization_id": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0"
    },
    "validation_stack": {
      "mode": "current",
      "status": "current",
      "en16931": "EN16931 UBL/CII XSLT rules v1.3.16",
      "xrechnung": "KoSIT-compatible Schematron bundle 2.5.0"
    }
  },
  "invoice_summary": {
    "invoice_number": "RE-2026-001",
    "invoice_date": "2026-04-13",
    "format": "UBL"
  },
  "artifacts": {
    "validation_report_pdf": {
      "available": true,
      "url": "https://e-rechnung-check.de/api/external/artifacts/abc123/report.pdf",
      "expires_in_seconds": 3600
    },
    "readable_invoice_pdf": {
      "available": true,
      "url": "https://e-rechnung-check.de/api/external/artifacts/abc123/invoice.pdf",
      "expires_in_seconds": 3600
    }
  }
}

UBL aus JSON erstellen

Der Generate-Endpunkt nimmt einen strukturierten Rechnungsentwurf entgegen, erzeugt UBL-XML, validiert diese XML sofort und gibt XML, Validierung, Rechnungszusammenfassung und kurzlebige PDF-Links zurück.

• Erste Version: `format` ist bewusst auf `UBL` begrenzt.
• Die erzeugte XML wird immer validiert; bei Fehlern bleibt `is_valid` false und die Fehlerliste muss vom aufrufenden System behandelt werden.
• Die API verwaltet keine Rechnungsnummern, Stammdaten, Entwürfe oder Archive.

curl -X POST \
  "https://e-rechnung-check.de/api/external/generate?lang=de" \
  -H "X-API-Key: erk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  --data @invoice-draft.json

Beispiel-JSON

{
  "invoice_number": "RE-2026-001",
  "issue_date": "2026-06-03",
  "due_date": "2026-06-17",
  "format": "UBL",
  "buyer_reference": "991-12345-06",
  "seller": {
    "name": "Muster GmbH",
    "street": "Musterstrasse 1",
    "postal_code": "10115",
    "city": "Berlin",
    "country_code": "DE",
    "tax_id": "DE123456789"
  },
  "buyer": {
    "name": "Beispiel AG",
    "street": "Markt 2",
    "postal_code": "20095",
    "city": "Hamburg",
    "country_code": "DE"
  },
  "payment": {
    "iban": "DE02120300000000202051",
    "payment_means_code": "58",
    "payment_reference": "RE-2026-001"
  },
  "lines": [
    {
      "line_id": "1",
      "name": "Beratung",
      "quantity": "2",
      "unit_code": "C62",
      "unit_price": "100.00",
      "tax_category": "S",
      "tax_rate": "19.00"
    }
  ]
}

Beispiel-Antwort

{
  "status": "done",
  "schema_version": "1.0.0",
  "format": "UBL",
  "is_valid": true,
  "xml": "<?xml version=\"1.0\" encoding=\"utf-8\"?>...",
  "invoice_summary": {
    "invoice_number": "RE-2026-001",
    "invoice_date": "2026-06-03",
    "format": "UBL"
  },
  "validation": {
    "is_valid": true,
    "xrechnung_version": "3.0.1",
    "validation_profile": "XRechnung",
    "validation_format": "UBL",
    "errors": [],
    "warnings": [],
    "validation_details": {
      "invoice_identity": {
        "syntax": "UBL",
        "declared_profile": "XRechnung",
        "declared_version": "3.0"
      },
      "validation_stack": {
        "mode": "current",
        "status": "current",
        "en16931": "EN16931 UBL/CII XSLT rules v1.3.16",
        "xrechnung": "KoSIT-compatible Schematron bundle 2.5.0"
      }
    }
  },
  "artifacts": {
    "validation_report_pdf": {
      "available": true,
      "url": "https://e-rechnung-check.de/api/external/artifacts/abc123/report.pdf",
      "expires_in_seconds": 3600
    },
    "readable_invoice_pdf": {
      "available": true,
      "url": "https://e-rechnung-check.de/api/external/artifacts/abc123/invoice.pdf",
      "expires_in_seconds": 3600
    }
  }
}

JSON-Schema für Rechnungsentwürfe

Nutzen Sie den Schema-Endpunkt, um Pflichtfelder, erlaubte Formate und die aktuelle Draft-Schema-Version maschinenlesbar abzurufen.

curl \
  "https://e-rechnung-check.de/api/external/schemas/invoice-draft.json" \
  -H "X-API-Key: erk_live_xxxxxxxxxxxxxxxxxxxx"

Tarif- und Rechte-Endpunkt

Nutzen Sie diesen Endpunkt für einen schnellen Integrationscheck. Er bestätigt den API-Schlüssel und liefert Tarifrechte, Upload-Limits und verfügbare Routen zurück.

curl \
  "https://e-rechnung-check.de/api/external/capabilities" \
  -H "X-API-Key: erk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "status": "ok",
  "plan_type": "business",
  "entitlements": {
    "plan_type": "business",
    "daily_usage_limit": null,
    "daily_validation_limit": null,
    "can_view_structured_invoice": true,
    "can_generate_invoice": true,
    "can_download_readable_pdf": true,
    "can_export": false,
    "can_autofix": true,
    "can_batch": true,
    "can_use_api": true,
    "can_use_inbound_email": true
  },
  "limits": {
    "max_upload_size_bytes": 10485760,
    "max_upload_size_mb": 10.0,
    "batch_max_files": 10
  },
  "supported_formats": ["UBL XML", "CII XML", "ZUGFeRD / Factur-X PDF with EN16931-compatible embedded XML"],
  "supported_generation_formats": ["UBL XML"],
  "supported_languages": ["de", "en"],
  "endpoints": {
    "validate": "https://e-rechnung-check.de/api/external/validate",
    "validate_batch": "https://e-rechnung-check.de/api/external/validate/batch",
    "generate": "https://e-rechnung-check.de/api/external/generate",
    "invoice_draft_schema": "https://e-rechnung-check.de/api/external/schemas/invoice-draft.json",
    "artifact_report": "https://e-rechnung-check.de/api/external/artifacts/{token}/report.pdf",
    "artifact_invoice": "https://e-rechnung-check.de/api/external/artifacts/{token}/invoice.pdf",
    "capabilities": "https://e-rechnung-check.de/api/external/capabilities",
    "error_catalog": "https://e-rechnung-check.de/api/external/errors/catalog"
  }
}

Batch-Validierung

Für Business-Zugänge steht zusätzlich ein Batch-Endpunkt zur Verfügung. Senden Sie mehrere Dateien im selben Multipart-Request über das wiederholte Feld `files`, wenn Sie höheren Verarbeitungsdurchsatz benötigen.

curl -X POST \
  "https://e-rechnung-check.de/api/external/validate/batch?lang=de" \
  -H "X-API-Key: erk_live_xxxxxxxxxxxxxxxxxxxx" \
  -F "files=@invoice-1.xml" \
  -F "files=@invoice-2.xml"

{
  "status": "done",
  "count": 2,
  "items": [
    {
      "filename": "invoice-1.xml",
      "status": "done",
      "is_valid": true,
      "xrechnung_version": "3.0.1",
      "validation_profile": "XRechnung",
      "validation_format": "UBL",
      "processing_time_ms": 615,
      "errors": [],
      "warnings": [],
      "invoice_summary": null,
      "validation_details": {
        "invoice_identity": {
          "syntax": "UBL",
          "declared_profile": "XRechnung",
          "declared_version": "3.0"
        },
        "validation_stack": {
          "scenario_id": "xrechnung-3.0-ubl",
          "status": "current",
          "en16931": "EN16931 UBL/CII XSLT rules v1.3.16 (validation artefacts v1.3.16, effective 2026-05-15)",
          "xrechnung": "KoSIT-compatible Schematron bundle 2.5.0 (3.0.2-compatible)"
        },
        "compatibility": {
          "status": "current",
          "message": null
        }
      }
    },
    {
      "filename": "invoice-2.xml",
      "status": "done",
      "is_valid": false,
      "xrechnung_version": "3.0.1",
      "validation_profile": "XRechnung",
      "validation_format": "UBL",
      "processing_time_ms": 702,
      "errors": [{ "code": "BR-10" }],
      "warnings": [],
      "invoice_summary": null,
      "validation_details": {
        "invoice_identity": {
          "syntax": "UBL",
          "declared_profile": "XRechnung",
          "declared_version": "3.0"
        },
        "validation_stack": {
          "scenario_id": "xrechnung-3.0-ubl",
          "status": "current"
        },
        "compatibility": {
          "status": "current",
          "message": null
        }
      }
    }
  ]
}

Fehlerkatalog-Endpunkt

Dieser Endpunkt liefert den gepflegten Regelkatalog maschinenlesbar zurück. Damit können Integrationen Regelcodes vorab mappen oder eigene Hilfetexte vorbereiten.

curl \
  "https://e-rechnung-check.de/api/external/errors/catalog?lang=de" \
  -H "X-API-Key: erk_live_xxxxxxxxxxxxxxxxxxxx"

{
  "status": "ok",
  "catalog_version": "1.0.0",
  "xrechnung_version": "3.0.1",
  "rule_count": 183,
  "language": "de",
  "items": [
    {
      "code": "BR-01",
      "severity": "fatal",
      "section": "General Information",
      "title": "Missing invoice number",
      "explanation": "Every invoice must contain a unique invoice number.",
      "fix": "Add a unique invoice number in field BT-1.",
      "bt_field": "BT-1",
      "xpath": "/Invoice/ID",
      "examples": ["INV-2026-001"]
    }
  ]
}

Fehlerverhalten

Diese HTTP-Statuscodes sind aktuell für den externen Endpunkt relevant.