API-Dokumentation

Überblick

Alle kostenpflichtigen REST-API-Endpunkte liegen unter dem versionierten Pfad /api/v1. Für manuelle Einzelprüfungen ohne API-Schlüssel steht unser kostenloser Browser-Validator bereit (bis zu 5 Prüfungen pro UTC-Tag). Die Beispiele verwenden die Shell-Variablen $BELEGBRIDGE_URL und $BELEGBRIDGE_API_KEY.

• Verarbeitung nur im Arbeitsspeicher: Hochgeladene Rechnungen werden ausschließlich im Arbeitsspeicher verarbeitet und verworfen, sobald die Antwort gesendet wurde. Nichts wird auf Festplatte, in einer Datenbank oder in Logs gespeichert.
• Inhaltstypen: Antworten sind application/json; charset=utf-8, sofern nicht anders angegeben. Der Visualizer kann zusätzlich HTML oder PDF liefern (siehe Visualisieren).
• Versionierung: Inkompatible Änderungen erscheinen nur unter einem neuen Pfad (z. B. /api/v2). Neue optionale Felder können jederzeit in v1-Antworten ergänzt werden – bitte ignorieren Sie unbekannte Felder.

export BELEGBRIDGE_URL="<adresse-dieser-website>"
export BELEGBRIDGE_API_KEY="bb_live_..."

Authentifizierung

Alle REST-API-Endpunkte unter /api/v1/* erfordern einen API-Schlüssel im Header Authorization: Bearer bb_live_... und setzen keine Cookies. Der API-Zugang ist in den Tarifen Pro und Agency enthalten. Alle Details finden Sie unter Preise.

Authorization: Bearer bb_live_...

Anfragen ohne gültigen API-Schlüssel erhalten 401 Unauthorized mit dem Header WWW-Authenticate: Bearer realm="BelegBridge API":

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="BelegBridge API"
Content-Type: application/json; charset=utf-8

{
  "valid": false,
  "legal_ustg14_compliant": false,
  "status": "UNAUTHORIZED",
  "message": "Missing or invalid API key. Pass 'Authorization: Bearer bb_live_...' — REST API access is included in the Pro and Agency plans (see /#pricing).",
  "pricing_url": "/#pricing"
}

Ratenbegrenzung

Öffentliche Endpunkte sind durch einen Token-Bucket pro Client geschützt. Der Client wird über einen gesalzenen Hash seiner IP-Adresse erkannt; das Salz wechselt täglich, sodass IP-Adressen nie im Klartext gespeichert werden – weder im Arbeitsspeicher noch in Logs.

Wird das Limit überschritten, antwortet die API mit 429 Too Many Requests und dem Header Retry-After: 60. Warten Sie mindestens die angegebene Anzahl Sekunden, bevor Sie es erneut versuchen.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json; charset=utf-8

{
  "valid": false,
  "legal_ustg14_compliant": false,
  "status": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded for public validation endpoint. Please try again shortly."
}

Rechnung prüfen

POST /api/v1/validate

Erkennt das Format, prüft das XML mit dem offiziellen KoSIT-Validator (EN-16931- und XRechnung-Geschäftsregeln) und prüft bei PDFs zusätzlich die PDF/A-3-Konformität. Jeder Befund wird auf Deutsch und Englisch mit einem konkreten Lösungsvorschlag übersetzt.

Anfrage

• multipart/form-data mit der Datei im Feld file (alternativ werden die Feldnamen invoice und document akzeptiert), oder
• die Rohdatei als Request-Body mit Content-Type: application/xml, application/pdf oder application/octet-stream.
• Maximale Größe: 15 MB. Größere Anfragen werden mit 413 abgelehnt.

Unterstützte Eingaben:

• UN/CEFACT Cross Industry Invoice (CII) – XRechnung CII, ZUGFeRD-2.x- / Factur-X-XML
• OASIS UBL 2.1 Invoice und CreditNote – XRechnung UBL, Peppol BIS Billing 3.0
• Hybride PDF/A-3-Dateien mit eingebettetem Anhang factur-x.xml, xrechnung.xml oder zugferd-invoice.xml (ZUGFeRD 2.x / Factur-X)

# multipart upload
curl -sS -X POST "$BELEGBRIDGE_URL/api/v1/validate" \
  -H "Authorization: Bearer $BELEGBRIDGE_API_KEY" \
  -F "file=@rechnung.xml"

# raw body (PDF)
curl -sS -X POST "$BELEGBRIDGE_URL/api/v1/validate" \
  -H "Authorization: Bearer $BELEGBRIDGE_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary "@rechnung.pdf"

Antwortfelder

Wann ist eine Rechnung valid?

valid ist nur dann true, wenn alle folgenden Bedingungen erfüllt sind:

• es gibt keinen einzigen FATAL-Verstoß,
• der KoSIT-Prüfbericht empfiehlt die Annahme,
• das erkannte Profil ist nach § 14 UStG zulässig (siehe Profile) und
• bei PDFs: die Datei ist PDF/A-3-konform.

Beispiel: Rechnung ohne Käuferreferenz (BT-10) und Verkäuferkontakt (BG-6)

{
  "valid": false,
  "legal_ustg14_compliant": false,
  "detected_container": "XML",
  "detected_syntax": "UN_CEFACT_CII",
  "detected_profile": "XRECHNUNG_3_0_2",
  "document_type": "380_INVOICE",
  "pdfa_compliant": false,
  "summary": {
    "errors_count": 2,
    "warnings_count": 0
  },
  "violations": [
    {
      "rule_id": "BR-DE-2",
      "severity": "FATAL",
      "bt_reference": "BG-6",
      "xpath": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement/ram:SellerTradeParty",
      "raw_message": "[BR-DE-2] Die Gruppe \"SELLER CONTACT\" (BG-6) muss übermittelt werden.",
      "title_de": "Kontaktdaten des Verkäufers (BG-6) fehlen",
      "title_en": "Seller contact details (BG-6) are missing",
      "fix_de": "Ergänzen Sie Ansprechpartner (BT-41), Telefonnummer (BT-42) und E-Mail-Adresse (BT-43) des Verkäufers.",
      "fix_en": "Add the seller's contact person (BT-41), phone number (BT-42) and email address (BT-43)."
    },
    {
      "rule_id": "BR-DE-15",
      "severity": "FATAL",
      "bt_reference": "BT-10",
      "xpath": "/rsm:CrossIndustryInvoice/rsm:SupplyChainTradeTransaction/ram:ApplicableHeaderTradeAgreement",
      "raw_message": "[BR-DE-15] Das Element \"Buyer reference\" (BT-10) muss übermittelt werden.",
      "title_de": "Käuferreferenz bzw. Leitweg-ID (BT-10) fehlt",
      "title_en": "Buyer reference / Leitweg-ID (BT-10) is missing",
      "fix_de": "Tragen Sie die Leitweg-ID des öffentlichen Auftraggebers oder eine andere Käuferreferenz in BT-10 ein.",
      "fix_en": "Enter the public-sector routing ID (Leitweg-ID) or another buyer reference in BT-10."
    }
  ]
}

Titel und Lösungsvorschläge werden redaktionell gepflegt und können sich verbessern; für die automatisierte Verarbeitung verwenden Sie bitte rule_id und severity.

Profile & § 14 UStG

Das Feld detected_profile gibt an, welcher Spezifikation die Rechnung folgt. Nur Profile mit dem vollständigen EN-16931-Datensatz (einschließlich Rechnungspositionen) gelten als E-Rechnung nach § 14 UStG.

Rechnung visualisieren

POST /api/v1/visualize

Wandelt eine XRechnung- oder ZUGFeRD-Rechnung in eine einheitliche, lesbare Darstellung um und rechnet die Summen nach. Akzeptiert dieselben Anfrageformate und dieselbe Größenbegrenzung wie /api/v1/validate.

Parameter

# JSON
curl -sS -X POST "$BELEGBRIDGE_URL/api/v1/visualize?format=json&lang=de" \
  -H "Authorization: Bearer $BELEGBRIDGE_API_KEY" \
  -F "file=@rechnung.xml"

# PDF herunterladen
curl -sS -X POST "$BELEGBRIDGE_URL/api/v1/visualize?format=pdf&lang=de" \
  -H "Authorization: Bearer $BELEGBRIDGE_API_KEY" \
  -F "file=@rechnung.xml" \
  -o invoice-preview.pdf

JSON-Antwort

Beispiel (gekürzt):

{
  "valid_math": true,
  "syntax": "UN_CEFACT_CII",
  "profile_level": "XRECHNUNG_3_0_2",
  "source_container": "XML",
  "invoice": {
    "invoice_number": "RE-2026-0042",
    "issue_date": "2026-11-02",
    "type_code": "380",
    "currency": "EUR",
    "buyer_reference": "04011000-12345-67",
    "seller": { "name": "Muster Webagentur", "city": "Berlin", "country_code": "DE" },
    "buyer": { "name": "Beispielkunde AG", "city": "Hamburg", "country_code": "DE" },
    "payment": { "means_code": "58", "iban": "DE02120300000000202051", "payment_terms": "14 Tage netto" },
    "lines": [
      { "id": "1", "name": "Webentwicklung", "quantity": "10", "unit_code": "HUR", "net_price": "95.00", "line_net_amount": "950.00", "line_net_cents": 95000, "vat_category": "S", "vat_rate": "19" }
    ],
    "taxes": [
      { "category_code": "S", "rate": "19", "taxable_amount": "950.00", "taxable_cents": 95000, "tax_amount": "180.50", "tax_cents": 18050 }
    ],
    "totals": {
      "line_total": "950.00", "line_total_cents": 95000,
      "tax_basis_total": "950.00", "tax_basis_total_cents": 95000,
      "tax_total": "180.50", "tax_total_cents": 18050,
      "grand_total": "1130.50", "grand_total_cents": 113050,
      "due_payable": "1130.50", "due_payable_cents": 113050
    },
    "penny_math": {
      "valid": true,
      "br_co_10_valid": true,
      "br_co_13_valid": true,
      "br_co_14_valid": true,
      "br_co_15_valid": true
    }
  },
  "html_preview": "<div class=\"bb-invoice\">…</div>"
}

Fehler & Statuscodes

Hinweis: Eine Rechnung mit Prüffehlern ist kein HTTP-Fehler – sie wird mit 200 OK und "valid": false beantwortet. HTTP-Fehler bedeuten, dass die Anfrage selbst nicht verarbeitet werden konnte. Sie haben diesen Aufbau:

{
  "valid": false,
  "legal_ustg14_compliant": false,
  "status": "UNSUPPORTED_FORMAT",
  "message": "…"
}

Sicherheit & Datenschutz

• Schutz vor XXE: XML-Dokumente mit <!DOCTYPE- oder <!ENTITY-Deklarationen werden vor dem Parsen abgelehnt.
• Größenbegrenzung: Anfragen sind auf 15 MB begrenzt.
• Nur Arbeitsspeicher: Rechnungsinhalte werden nie auf Festplatte, in eine Datenbank oder in Logs geschrieben.
• Keine Cookies, kein Tracking: Weder Website noch API setzen Cookies.
• Strikte Content Security Policy: Alle Skripte, Stylesheets und Schriften werden von unserer eigenen Domain ausgeliefert – keine externen CDNs.

Weitere Details: Datenschutzerklärung und Auftragsverarbeitungsvertrag (AVV).

Geplante Endpunkte

Die folgenden Endpunkte gehören zur kostenpflichtigen Bridge und sind noch nicht verfügbar. Pfade und Schemata können sich noch ändern.