Valinvo

Schnellstart

Status: Beta. Valinvo erzeugt aus einer JSON-Rechnung eine XRechnung 3.0.2 (Deutschland, UBL oder CII), eine ZUGFeRD-2.5.2- / Factur-X-1.09.2-Rechnung (PDF mit eingebettetem XML), Factur-X, CII oder UBL mit den französischen Regeln (Frankreich) oder eine Peppol BIS Billing 3.0.21 (Belgien und das Peppol-Netzwerk). Jede erzeugte Rechnung wird vor der Rückgabe gegen die offiziellen Regeln ihres Formats geprüft.

Bedingungen: Die API ist nur für Unternehmen und unterliegt den Nutzungsbedingungen und dem Auftragsverarbeitungsvertrag (die englische Fassung ist maßgeblich). Ohne API-Schlüssel akzeptieren Sie sie, indem Sie bei jeder Anfrage den Header X-Accept-Terms: 1.0 (die aktuelle Version) senden; Anfragen ohne ihn werden mit 428 terms_not_accepted abgelehnt. Inhaber eines API-Schlüssels akzeptieren schriftlich bei der Ausgabe. Jede API-Antwort verweist im Header Link: <…/terms>; rel="terms-of-service" auf die Bedingungen. Die Testphase ohne API-Schlüssel dient nur zum Testen und Ausprobieren: Verwenden Sie Beispieldaten, keine echten Rechnungen mit personenbezogenen Daten anderer.

Support: Bitte senden Sie niemals echte Rechnungen per E-Mail. Schicken Sie das Prüfergebnis (Regel-IDs und Feldpositionen) oder eine anonymisierte Kopie mit Beispielwerten an hello@bmk-hub.com, oder nutzen Sie das Kontaktformular.

Formate anzeigen

curl https://valinvo.bmk-hub.com/v1/formats
Format-IDFormatEinsatz
xrechnung-ublXRechnung 3.0.2, UBL 2.1Öffentliche Auftraggeber in Deutschland; B2B in Deutschland
xrechnung-ciiXRechnung 3.0.2, UN/CEFACT CIIWie oben, für Empfänger, die CII wünschen
peppol-bis-ublPeppol BIS Billing 3.0.21, UBL 2.1B2B in Belgien; alle Empfänger im Peppol-Netzwerk
zugferd-en16931ZUGFeRD 2.5.2 / Factur-X 1.09.2, Profil EN 16931 (PDF/A-3 + CII-XML)B2B in Deutschland als PDF, das Menschen lesen und Software verarbeiten kann (Beta; die Zusatzfelder der französischen Reform werden noch nicht unterstützt)
factur-x-frFactur-X 1.09.2, EN 16931 + BR-FR (PDF/A-3 + CII)B2B in Frankreich: die Factur-X-Datei für Ihre plateforme agréée (Beta; der Versand über eine PA ist nicht enthalten)
cii-frCII D22B, EN 16931 + BR-FRDieselbe französische Rechnung als reines CII-XML (Beta)
ubl-frUBL 2.1, EN 16931 + BR-FRDieselbe französische Rechnung als UBL-XML (Beta)

Rechnung erstellen

Format und Rechnung werden in einem JSON-Body gesendet. Zwei vollständige Beispiele: XRechnung (Deutschland) und Peppol (Belgien).

curl -X POST https://valinvo.bmk-hub.com/v1/invoices \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/json' \
  -d @invoice.example.json \
  -o rechnung.xml -D -

Die Antwort ist die XML-Datei. Die Header zeigen das Ergebnis der offiziellen Prüfung:

X-Validation-Status: valid
X-Validation-Warnings: 0
X-Rule-Set: xrechnung-3.0.2-ubl-invoice

Mit -H 'Accept: application/json' erhalten Sie XML und vollständigen Prüfbericht in einer JSON-Antwort.

Mit "format": "zugferd-en16931" ist die Antwort ein PDF (speichern mit -o rechnung.pdf); die offiziellen Regeln prüfen das darin eingebettete XML. Im JSON-Modus kommt das PDF base64-kodiert. Eine Rechnung ohne Lieferdatum erhält eine Warnung (PEPPOL-EN16931-R008, leeres Lieferelement): das ZUGFeRD-Schema schreibt dieses Element vor, die Warnung ist also zu erwarten.

Kostenloser Test und API-Schlüssel

Ohne Schlüssel können Sie 2 Rechnungen pro Tag (pro IP-Adresse) zum Ausprobieren erstellen; die Header X-Trial-Limit und X-Trial-Remaining zeigen den Stand, danach folgt 429 trial_limit_reached. Design-Partner erhalten einen Beta-Schlüssel (Authorization: Bearer <Schlüssel>) ohne Tageslimit. Der Validator bleibt kostenlos.

Ohne Schlüssel bitte eine Anfrage nach der anderen senden (sonst 429 one_request_at_a_time). Größengrenzen für alle: Rechnungs-JSON bis 2 MB und 2.000 Positionen; ZUGFeRD-PDFs bis 500 Positionen und 5.000 Zeichen je Textfeld; höchstens 1.000 Hinweise (100 in PDFs); Zahlen mit höchstens 15 Stellen vor und 10 nach dem Komma (400 invalid_invoice); zu prüfende Dokumente bis 20 MB und 75.000 XML-Elemente, etwa 3.000 ausführliche Positionen (413 document_too_large).

Faustregeln

Wenn etwas fehlt

Sie erhalten 400 mit allen Problemen auf einmal, jeweils mit JSON-Pfad, offizieller Regel und EN-16931-Geschäftsbegriff. Die Meldungen der API sind auf Englisch:

{
  "code": "invalid_invoice",
  "message": "The invoice has 1 problem. Fix it and try again.",
  "problems": [{
    "path": "invoice.buyerReference",
    "message": "German invoices require buyerReference. For public buyers this is the Leitweg-ID.",
    "rule": "BR-DE-15",
    "businessTerm": "BT-10"
  }]
}

422 generated_invoice_invalid bedeutet, dass das erzeugte XML die offiziellen Regeln nicht erfüllt; validation.errors nennt den Grund. Meist fehlt ein Feld, das eine nationale Regel verlangt.

Bestehende Rechnung prüfen

curl -X POST https://valinvo.bmk-hub.com/v1/validate \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/xml' \
  --data-binary @rechnung.xml
{"ruleSet": "xrechnung-3.0.2-ubl-invoice", "valid": true, "errors": [], "warnings": []}

Das Regelwerk wird am Dokument erkannt: XRechnung 3.0 (UBL Invoice, UBL CreditNote, CII), Peppol BIS Billing 3.0 (UBL Invoice, UBL CreditNote) und ZUGFeRD 2.x / Factur-X in CII (Profile MINIMUM, BASIC WL, BASIC, EN 16931 und EXTENDED, geprüft nach den Regeln 2.5.2). Eine ungültige Rechnung ist ein normales Ergebnis 200 mit valid: false und der Fehlerliste.

Ein ZUGFeRD-/Factur-X-PDF können Sie direkt senden. Wir prüfen die eingebettete Rechnungs-XML, das PDF selbst auf PDF/A-3 (mit veraPDF) und ob die Metadaten des PDFs dasselbe Profil und denselben Anhang nennen wie die XML; das Regelwerk lautet dann z. B. zugferd-2.5.2-en16931+pdf-a-3b. PDF/A-Fehler haben Regel-IDs wie PDF/A-3 6.2.11.4.1-1 (Abschnitt und Test der ISO 19005-3), Metadaten-Fehler beginnen mit ZF-XMP:

curl -X POST https://valinvo.bmk-hub.com/v1/validate \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/pdf' \
  --data-binary @rechnung.pdf

Ein PDF ohne Rechnungsanhang erhält 400 no_embedded_invoice, ein unlesbares oder passwortgeschütztes 400 invalid_pdf.

OpenAPI

Die ganze API als OpenAPI-3-Beschreibung: openapi.json. Importieren Sie sie in Postman, Insomnia oder einen Code-Generator.

Schnellstart · XRechnung-Validator · ZUGFeRD-Validator · ZUGFeRD-csharp: Ihre Optionen · Fehlercodes