Check Peppol BIS Billing 3.0 invoices by REST API against selected rules, with returned findings explained. Klarbon does not send invoices.
This capability is in beta: it works and is tested, and we may still change details.
On this page
The Klarbon Peppol BIS validation API checks a Peppol BIS Billing 3.0 invoice or credit note against the selected Peppol and EN 16931 rules with one REST call, and explains returned findings in plain words. Use it before you hand a file to your access point. Klarbon is not an access point: it does not send, receive or register anything on the Peppol network.
What the API does
POST /api/v1/check selects rules from the file. To select Peppol explicitly, use ruleset=peppol-bis3-invoice for an invoice or ruleset=peppol-bis3-creditnote for a credit note.
Each finding has a rule id, a severity, the location in the XML and a message.
The same check runs in the browser tool, so a person can look at a failing file too.
What it does not do
Most searches for a Peppol API mean sending invoices. For that you need an access point; Klarbon checks the file before it goes there. Validation is in beta, and checks count towards your plan's daily checks.
Quick start
Each snippet is the same call. The end-to-end test runs these snippets against a local Klarbon server and the real validation engine.
Create a key on your account page and put it in KLARBON_API_KEY. Never put it in the address.
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?ruleset=peppol-bis3-invoice") { 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;
What comes back
The answer to the curl call above, recorded from that run with Klarbon synthetic fixture, CC0-1.0.
Prepaid API packs, bought by card on your account page: 1,000 calls for €39.00, 5,000 calls for €129.00, 25,000 calls for €449.00, 100,000 calls for €990.00, VAT included, never expiring. Your first key brings 25 free calls once per email address, excluding disposable addresses. Paid calls spend the API balance first, then the same credits as the site. A call that fails costs nothing.
Call
Cost
POST /open
Free, fair use 1,000 a day per account
POST /check
Free within your plan's daily checks (20 a day on the free plan)
POST /convert, POST /make
1 call, only when the written file validates
POST /bank/convert
1 call per started 500 transactions, only when converted
Limits
Files up to 20 MB, PDFs up to 50 pages.
60 requests a minute per key, 120 per account. A per-minute rate-limit refusal carries Retry-After.
Up to 10 keys per account. Idempotency-Key is honoured for 24 hours, so a retry never charges twice.
Errors
Every error is { ok: false, error, message }: a stable code and one plain sentence.
Status
Code
When
401
auth
No key, or an unknown or revoked key.
402
no_credits
The combined API balance and credits cannot cover this call. Nothing was charged; topUpUrl says where to buy.
413
too_large
Over 20 MB or 50 PDF pages.
415
unsupported
A file format the route does not take.
422
invalid
The file could not be read, or the written file did not validate. Not charged.
429
limit
A rate limit or the day's free calls.
503
engine_unavailable
Validation is briefly unavailable. Not charged.
Privacy
Files are processed for the request, without a document archive. Klarbon's application logs carry no file name, no content and no key. The full key is not stored, only an HMAC of it and a short display prefix.