E-Rechnungen per API nach EN 16931, XRechnung, Peppol und Factur-X prüfen. Meldungen verständlich erklärt, kostenlos im Tageslimit.
Diese Funktion ist in der Beta: Sie funktioniert und ist getestet, Details können sich noch ändern.
Auf dieser Seite
Die API zur Prüfung von E-Rechnungen von Klarbon prüft UBL, CII, XRechnung, Peppol BIS, Factur-X und ZUGFeRD mit einem REST-Aufruf gegen die jeweils geltenden veröffentlichten Regeln. Sie erkennt das Regelwerk aus der Datei oder nimmt das, das Sie angeben, und liefert die Meldungen der gewählten Prüfungen mit Regel-ID, Schweregrad und Hinweisen zur Behebung. Die Dateien werden für die Anfrage verarbeitet, ohne Dokumentenarchiv.
Was die API macht
POST /api/v1/check nimmt die XML-Datei oder das hybride PDF, standardmäßig mit ruleset=auto.
country wählt ein verfügbares Länderregelwerk, wenn Sie das Ziel der Rechnung kennen. Empfängerspezifische Anforderungen prüft es nicht vollständig.
Die Routen, die E-Rechnungen schreiben, liefern ebenfalls Prüfergebnisse. Sehen Sie sich die Meldungen an, bevor Sie die Datei verwenden.
Was sie nicht macht
Ein gültiges Ergebnis heißt, dass die Datei die ausgewählten Prüfungen besteht. Es heißt nicht, dass der Empfänger sie annimmt, und es ist keine Steuer- oder Rechtsberatung. Die Prüfung ist in der Beta und im Tageslimit Ihres Tarifs kostenlos. Zum Umwandeln gibt es die API zur Umwandlung von E-Rechnungen.
Schnellstart
Jedes Beispiel macht denselben Aufruf. Vor der Veröffentlichung läuft jedes einzelne gegen einen lokalen Klarbon-Server und die echte Validierung.
Legen Sie auf Ihrer Kontoseite einen Schlüssel an und setzen Sie ihn als KLARBON_API_KEY. Der Schlüssel gehört nie in die Adresse.
using System.Net.Http.Headers;
using System.Text.Json;
using var http = new HttpClient();
var key = Environment.GetEnvironmentVariable("KLARBON_API_KEY");
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);
var upload = new ByteArrayContent(await File.ReadAllBytesAsync("invoice.xml"));
upload.Headers.ContentType = new MediaTypeHeaderValue("application/xml");
using var request = new HttpRequestMessage(HttpMethod.Post, "https://klarbon.app/api/v1/check") { Content = upload };
using var response = await http.SendAsync(request);
using var json = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var result = json.RootElement;
if (!result.GetProperty("ok").GetBoolean())
{
Console.Error.WriteLine($"{(int)response.StatusCode} {result.GetProperty("error")}: {result.GetProperty("message")}");
return 1;
}
var report = result.GetProperty("report");
Console.WriteLine(report.GetProperty("valid").GetBoolean() ? "valid" : "not valid");
foreach (var finding in report.GetProperty("findings").EnumerateArray())
Console.WriteLine($"{finding.GetProperty("severity")} {finding.GetProperty("ruleId")} {finding.GetProperty("message")}");
return 0;
Die Antwort
Die Antwort auf den curl-Aufruf oben, aufgezeichnet bei diesem Lauf mit KoSIT XRechnung test suite, business case 01.01a (UBL), Apache-2.0.
Vorausbezahlte API-Pakete, per Karte auf Ihrer Kontoseite gekauft: 1.000 Aufrufe für 39,00 €, 5.000 Aufrufe für 129,00 €, 25.000 Aufrufe für 449,00 €, 100.000 Aufrufe für 990,00 €, ohne Ablaufdatum. Ihr erster Schlüssel bringt 25 kostenlose Aufrufe. Kostenpflichtige Aufrufe verbrauchen zuerst das API-Guthaben, danach dieselben Credits wie die Website. Ein fehlgeschlagener Aufruf kostet nichts.
Aufruf
Kosten
POST /open
Kostenlos, faire Nutzung bis 1.000 am Tag pro Konto
POST /check
Kostenlos im Tageslimit Ihres Tarifs (20 am Tag im kostenlosen Tarif)
POST /convert, POST /make
1 Aufruf, nur wenn die erzeugte Datei gültig ist
POST /bank/convert
1 Aufruf je angefangene 500 Umsätze, nur bei erfolgreicher Umwandlung
Grenzen
Dateien bis 20 MB, PDFs bis 50 Seiten.
60 Anfragen pro Minute je Schlüssel, 120 je Konto. Eine 429 enthält Retry-After.
Bis zu 10 Schlüssel pro Konto. Idempotency-Key gilt 24 Stunden, ein erneuter Versuch wird also nie doppelt berechnet.
Fehler
Jeder Fehler ist { ok: false, error, message }: ein fester Code und ein klarer Satz.
Status
Code
Wann
401
auth
Kein Schlüssel oder ein unbekannter oder widerrufener Schlüssel.
402
no_credits
API-Guthaben und Credits reichen beide nicht. Nichts wurde ausgeführt; topUpUrl nennt die Kaufseite.
413
too_large
Über 20 MB oder 50 PDF-Seiten.
415
unsupported
Ein Dateiformat, das die Route nicht annimmt.
422
invalid
Die Datei war nicht lesbar oder die erzeugte Datei ist nicht gültig. Nicht berechnet.
429
limit
Ein Ratenlimit oder die kostenlosen Aufrufe des Tages.
503
engine_unavailable
Die Validierung ist kurz nicht erreichbar. Nicht berechnet.
Datenschutz
Dateien werden für die Anfrage verarbeitet, ohne ein Dokumentenarchiv anzulegen. Die Anwendungsprotokolle von Klarbon enthalten weder Dateinamen noch Inhalte noch Schlüssel. Der vollständige Schlüssel wird nicht gespeichert, nur ein HMAC davon und ein kurzes Anzeigepräfix.
EN 16931 in UBL und CII, XRechnung, Peppol BIS Billing, die Profile von ZUGFeRD und Factur-X, NLCIUS und die französischen CTC-Regeln. GET /api/v1/formats zeigt, was verfügbar ist.
Wie wählt die API das Regelwerk?
Aus der Customization-ID und dem Container der Datei, wenn Sie weder ruleset noch country angeben. Der Bericht nennt das verwendete Regelwerk.
Was ist der Unterschied zwischen Fehler, Warnung und Hinweis?
Ein Fehler bedeutet, dass die Datei eine Regel der gewählten Prüfung nicht besteht. Warnungen und Hinweise lassen diese Prüfung nicht scheitern, können für den Empfänger aber wichtig sein.
Nimmt mein Kunde eine gültige Rechnung sicher an?
Nicht sicher. Gültig heißt, dass die ausgewählten Prüfungen bestanden sind. Empfänger und Portale können eigene Anforderungen haben.