Controleer Peppol BIS Billing 3.0-facturen via de REST-API op geselecteerde regels, met uitleg bij de meldingen. Klarbon verstuurt geen facturen.
Deze functie is in bèta: ze werkt en is getest, maar details kunnen nog veranderen.
Op deze pagina
De Peppol BIS-validatie-API van Klarbon controleert een Peppol BIS Billing 3.0-factuur of creditfactuur met één REST-aanroep tegen de gekozen Peppol- en EN 16931-regels, met uitleg bij de meldingen waar beschikbaar. Gebruik de API voordat je het bestand aan je accesspoint geeft. Klarbon is geen accesspoint: het verstuurt, ontvangt en registreert niets op het Peppol-netwerk.
Wat de API doet
POST /api/v1/check kiest de regels op basis van het bestand. Kies Peppol expliciet met ruleset=peppol-bis3-invoice voor een factuur of ruleset=peppol-bis3-creditnote voor een creditfactuur.
Meldingen bevatten een regel-id en ernst, met een XML-locatie en uitleg waar beschikbaar.
Dezelfde controle zit in de online tool, zodat iemand een afgekeurd bestand ook zelf kan bekijken.
Wat de API niet doet
Wie naar een Peppol-API zoekt, wil meestal facturen versturen. Daarvoor is een accesspoint nodig; Klarbon controleert het bestand vooraf. Validatie is in bèta en telt mee voor de daglimiet van je abonnement.
Snel aan de slag
Elk voorbeeld doet dezelfde aanroep. Voor publicatie draait elk voorbeeld tegen een lokale Klarbon-server en de echte validatie.
Maak op uw accountpagina een sleutel aan en zet die in KLARBON_API_KEY. Zet de sleutel nooit in het adres.
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;
Het antwoord
Het antwoord op de curl-aanroep hierboven, vastgelegd bij die run met Klarbon synthetic fixture, CC0-1.0.
Vooraf betaalde API-pakketten, per kaart gekocht op uw accountpagina: 1.000 aanroepen voor € 39,00, 5.000 aanroepen voor € 129,00, 25.000 aanroepen voor € 449,00, 100.000 aanroepen voor € 990,00, zonder vervaldatum. Uw eerste sleutel geeft 25 gratis aanroepen. Betaalde aanroepen gebruiken eerst het API-saldo, daarna dezelfde credits als de site. Een mislukte aanroep kost niets.
Aanroep
Kosten
POST /open
Gratis, redelijk gebruik tot 1.000 per dag per account
POST /check
Gratis binnen de daglimiet van uw abonnement (20 per dag in het gratis abonnement)
POST /convert, POST /make
1 aanroep, alleen als het gemaakte bestand geldig is
POST /bank/convert
1 aanroep per begonnen 500 transacties, alleen na omzetting
Limieten
Bestanden tot 20 MB, pdf’s tot 50 pagina’s.
60 verzoeken per minuut per sleutel, 120 per account. Een 429 bevat Retry-After.
Tot 10 sleutels per account. Idempotency-Key geldt 24 uur, dus een nieuwe poging wordt nooit twee keer berekend.
Fouten
Elke fout is { ok: false, error, message }: een vaste code en één duidelijke zin.
Status
Code
Wanneer
401
auth
Geen sleutel, of een onbekende of ingetrokken sleutel.
402
no_credits
API-saldo en credits zijn allebei te laag. Er is niets gedaan; topUpUrl wijst naar de aankooppagina.
413
too_large
Meer dan 20 MB of 50 pdf-pagina’s.
415
unsupported
Een bestandsformaat dat de route niet aanneemt.
422
invalid
Het bestand was niet leesbaar, of het gemaakte bestand is niet geldig. Niet berekend.
429
limit
Een snelheidslimiet of de gratis aanroepen van de dag.
503
engine_unavailable
De validatie is even niet bereikbaar. Niet berekend.
Privacy
Bestanden worden voor het verzoek verwerkt, zonder documentarchief. De applicatielogs van Klarbon bevatten geen bestandsnaam, geen inhoud en geen sleutel. De volledige sleutel wordt niet bewaard, alleen een HMAC ervan en een kort weergaveprefix.
Verder
De documentatie voor ontwikkelaars is in het Engels.