Controleer e-facturen via de REST-API op geselecteerde EN 16931-, XRechnung-, Peppol- en Factur-X-regels. Gratis binnen de daglimiet.
Deze functie is in bèta: ze werkt en is getest, maar details kunnen nog veranderen.
Op deze pagina
De e-factuur-validatie-API van Klarbon controleert UBL-, CII-, XRechnung-, Peppol BIS-, Factur-X- en ZUGFeRD-facturen met één REST-aanroep tegen de geldende gepubliceerde regels. Hij leidt de regelset af uit het bestand of neemt de set die je opgeeft, en geeft meldingen uit de gekozen controles terug met regel-id en ernst, met uitleg waar beschikbaar. Bestanden worden voor het verzoek verwerkt, zonder documentarchief.
Wat de API doet
POST /api/v1/check neemt het XML-bestand of de hybride pdf, standaard met ruleset=auto.
country kiest de beschikbare regelset voor een land als je weet waar de factuur naartoe gaat. Daarmee worden niet alle eisen van een specifieke ontvanger gecontroleerd.
Routes die e-facturen schrijven, geven ook controleresultaten terug. Bekijk de meldingen voordat je het bestand gebruikt.
Wat de API niet doet
Een geldig resultaat betekent dat het bestand de gekozen controles doorstaat. Het betekent niet dat de ontvanger het accepteert, en het is geen fiscaal of juridisch advies. Validatie is in bèta en gratis binnen de daglimiet van je abonnement. Omzetten doet de e-factuur-conversie-API.
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") { 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 KoSIT XRechnung test suite, business case 01.01a (UBL), Apache-2.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.
EN 16931 in UBL en CII, XRechnung, Peppol BIS Billing, de profielen van Factur-X en ZUGFeRD, NLCIUS en de Franse CTC-regels. GET /api/v1/formats toont wat beschikbaar is.
Hoe kiest de API de regelset?
Uit de customization-id en de container van het bestand, tenzij je ruleset of country meegeeft. Het rapport noemt de gebruikte set.
Wat is het verschil tussen fout, waarschuwing en informatie?
Een fatale melding betekent dat het bestand niet voldoet aan een regel van de gekozen controle. Waarschuwingen en informatie laten die controle niet mislukken, maar kunnen wel van belang zijn voor de ontvanger.
Accepteert mijn klant een geldige factuur altijd?
Niet altijd. Geldig betekent dat het bestand de gekozen controles heeft doorstaan. Ontvangers en platforms kunnen eigen eisen stellen.