Vérifiez vos factures électroniques par API selon les règles sélectionnées, avec les indications disponibles. Gratuit dans la limite quotidienne.
Cette fonction est en bêta : elle fonctionne et elle est testée, mais des détails peuvent encore changer.
Sur cette page
L’API de validation de factures électroniques de Klarbon contrôle les factures UBL, CII, Factur-X et Peppol BIS selon les règles applicables, en un appel REST. Elle déduit le jeu de règles du fichier ou prend celui que vous indiquez, et renvoie les résultats des contrôles sélectionnés avec les codes de règle, les gravités et les indications disponibles. Les fichiers sont traités pour la requête, sans archive documentaire.
Ce que fait l’API
POST /api/v1/check accepte le XML ou le PDF hybride, avec ruleset=auto par défaut.
country=FR applique les règles attendues en France, dont les règles CTC.
Les routes de production de factures électroniques renvoient aussi des résultats de vérification ; consultez-les avant d'utiliser le fichier.
Ce qu’elle ne fait pas
Un résultat valide signifie que le fichier a passé les contrôles sélectionnés. Il ne garantit pas l’acceptation par le destinataire et ne constitue pas un conseil fiscal ou juridique. La validation est en bêta et gratuite dans la limite quotidienne de votre offre. Pour convertir, voyez l’API de conversion de factures électroniques.
Démarrage rapide
Chaque exemple fait le même appel. Avant publication, chacun est exécuté contre un serveur Klarbon local et le vrai moteur de validation.
Créez une clé sur la page de votre compte et placez-la dans KLARBON_API_KEY. Ne la mettez jamais dans l’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;
La réponse
La réponse à l’appel curl ci-dessus, enregistrée lors de cette exécution avec KoSIT XRechnung test suite, business case 01.01a (UBL), Apache-2.0.
Des packs API prépayés, achetés par carte sur la page de votre compte : 1 000 appels pour 39,00 €, 5 000 appels pour 129,00 €, 25 000 appels pour 449,00 €, 100 000 appels pour 990,00 €, sans date d’expiration. Votre première clé apporte 25 appels gratuits. Les appels payants consomment d’abord le solde API, puis les mêmes crédits que le site. Un appel qui échoue ne coûte rien.
Appel
Coût
POST /open
Gratuit, usage raisonnable jusqu’à 1 000 par jour et par compte
POST /check
Gratuit dans la limite quotidienne de votre offre (20 par jour avec l’offre gratuite)
POST /convert, POST /make
1 appel, seulement si le fichier produit est valide
POST /bank/convert
1 appel par tranche entamée de 500 opérations, seulement après conversion
Limites
Fichiers jusqu’à 20 Mo, PDF jusqu’à 50 pages.
60 requêtes par minute et par clé, 120 par compte. Une réponse 429 indique Retry-After.
Jusqu’à 10 clés par compte. Idempotency-Key est respecté pendant 24 heures : une nouvelle tentative n’est jamais facturée deux fois.
Erreurs
Chaque erreur a la forme { ok: false, error, message } : un code stable et une phrase claire.
Statut
Code
Quand
401
auth
Aucune clé, ou une clé inconnue ou révoquée.
402
no_credits
Solde API et crédits tous deux insuffisants. Rien n’a été fait ; topUpUrl indique où en acheter.
413
too_large
Plus de 20 Mo ou de 50 pages PDF.
415
unsupported
Un format de fichier que la route n’accepte pas.
422
invalid
Le fichier est illisible, ou le fichier produit n’est pas valide. Non facturé.
429
limit
Une limite de débit, ou les appels gratuits du jour.
503
engine_unavailable
La validation est brièvement indisponible. Non facturé.
Confidentialité
Les fichiers sont traités pour la requête, sans archive de documents. Les journaux de l'application Klarbon ne contiennent ni nom de fichier, ni contenu, ni clé. La clé complète n'est pas conservée, seulement son empreinte HMAC et un court préfixe d'affichage.
Pour aller plus loin
La documentation pour les développeurs est en anglais.
EN 16931 en UBL et CII, les profils Factur-X et ZUGFeRD, Peppol BIS Billing, XRechnung, NLCIUS et les règles CTC françaises. GET /api/v1/formats liste ce qui est disponible.
Comment l’API choisit-elle le jeu de règles ?
D’après l’identifiant de personnalisation et le conteneur du fichier, sauf si vous passez ruleset ou country. Le rapport indique le jeu utilisé.
Quelle différence entre erreur bloquante, avertissement et information ?
Une erreur bloquante fait échouer le contrôle sélectionné. Les avertissements et informations ne le font pas échouer, mais peuvent rester importants pour le destinataire.
Klarbon remplace-t-il ma plateforme agréée ?
Non. Klarbon contrôle et convertit les fichiers ; la transmission dans la réforme passe par une plateforme agréée.