Vérifiez vos factures Peppol BIS Billing 3.0 par API selon les règles sélectionnées. Klarbon n'est pas un point d'accès et n'envoie rien.
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 Peppol BIS de Klarbon contrôle une facture ou un avoir Peppol BIS Billing 3.0 selon les règles Peppol et EN 16931 sélectionnées, en un appel REST, et explique les résultats renvoyés. Utilisez-la avant de confier le fichier à votre point d’accès. Klarbon n’est pas un point d’accès : il n’envoie, ne reçoit et n’enregistre rien sur le réseau Peppol.
Ce que fait l’API
POST /api/v1/check choisit les règles d'après le fichier. Pour choisir Peppol explicitement, utilisez ruleset=peppol-bis3-invoice pour une facture ou ruleset=peppol-bis3-creditnote pour un avoir.
Chaque erreur indique l’identifiant de la règle, la gravité, l’emplacement dans le XML et un message.
Le même contrôle existe dans l’outil en ligne, pour qu’une personne puisse examiner un fichier refusé.
Ce qu’elle ne fait pas
La plupart des recherches d’API Peppol concernent l’envoi de factures, qui demande un point d’accès. Klarbon contrôle le fichier avant. La validation est en bêta, et chaque contrôle compte dans la limite quotidienne de votre offre.
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?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;
La réponse
La réponse à l’appel curl ci-dessus, enregistrée lors de cette exécution avec Klarbon synthetic fixture, CC0-1.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.