Convertissez vos factures entre UBL, CII, XRechnung et Peppol BIS en un appel REST. Facturé seulement si le fichier produit est valide.
Sur cette page
L’API de conversion de factures électroniques de Klarbon convertit vos factures entre UBL, CII, XRechnung et Peppol BIS en un appel REST. Elle lit la source dans le modèle de facture EN 16931, produit le format cible et valide le résultat avant de le renvoyer : vous ne payez que pour un fichier valide. Les fichiers sont traités pour la requête, sans archive de documents.
Ce que fait l’API
POST /api/v1/convert avec target égal à ubl, cii, xrechnung ou peppol-bis-billing.
La réponse contient le nouveau fichier, son rapport et un bloc credits indiquant la consommation. Les appels payants utilisent d'abord le solde API, puis les crédits de l'abonnement ou les crédits achetés.
losses indique les champs modifiés, omis ou supposés à l'écriture. Les champs non repris par le lecteur n'y figurent pas ; comparez le résultat à l'original.
Idempotency-Key sécurise les nouvelles tentatives : la même requête avec la même clé n’est pas refacturée pendant 24 heures.
Ce qu’elle ne fait pas
Elle ne transmet aucune facture et ne lit pas les PDF sans données structurées. Pour un PDF hybride, voyez l’API Factur-X.
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/convert?target=cii") { Content = upload };
request.Headers.Add("Idempotency-Key", "invoice-123456XX-cii");
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 written = result.GetProperty("file");
await File.WriteAllBytesAsync(written.GetProperty("filename").GetString()!,
Convert.FromBase64String(written.GetProperty("content").GetString()!));
Console.WriteLine($"{written.GetProperty("filename")} written, {result.GetProperty("credits").GetProperty("balance")} credits left");
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.
Raccourci pour la page: file.content: base64 cut
{
"ok": true,
"file": {
"content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgi...",
"filename": "123456XX-cii.xml",
"mime": "application/xml",
"bytes": 6867
},
"report": {
"detected": {
"syntax": "cii",
"customizationId": "urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0",
"profile": "xrechnung",
"container": "xml"
},
"ruleset": {
"id": "xrechnung-3.0-cii",
"name": "XRechnung 3.0 (CII)",
"version": "3.0.2"
},
"valid": true,
"engineVersion": "1.0.0",
"durationMs": 8,
"findings": [
{
"ruleId": "BR-DE-TMP-32",
"severity": "info",
"message": "[BR-DE-TMP-32] Eine Rechnung sollte zur Angabe des Liefer-/Leistungsdatums entweder BT-72 \"Actual delivery date\", BG-14 \"Invoicing period\" oder in jeder Rechnungsposition BG-26 \"Invoice line period\" enthalten.",
"location": "/rsm:CrossIndustryInvoice[1]/rsm:SupplyChainTradeTransaction[1]",
"test": "ram:ApplicableHeaderTradeDelivery/ram:ActualDeliverySupplyChainEvent/ram:OccurrenceDateTime or ram:ApplicableHeaderTradeSettlement/ram:BillingSpecifiedPeriod or (every $line in ram:IncludedSupplyChainTradeLineItem satisfies $line/ram:SpecifiedLineTradeSettlement/ram:BillingSpecifiedPeriod)",
"title": "BR-DE-TMP-32",
"what": "[BR-DE-TMP-32] Eine Rechnung sollte zur Angabe des Liefer-/Leistungsdatums entweder BT-72 \"Actual delivery date\", BG-14 \"Invoicing period\" oder in jeder Rechnungsposition BG-26 \"Invoice line period\" enthalten.",
"fix": "",
"link": null,
"officialUrl": null
}
]
},
"losses": [],
"credits": {
"spent": 1,
"balance": 197,
"plan": 0,
"bought": 197
}
}
Tarifs
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.
UBL, CII, XRechnung et Peppol BIS Billing, dans les deux sens. GET /api/v1/formats liste chaque format et ses conversions possibles.
Que deviennent les données que le format cible ne prévoit pas ?
La liste losses indique les champs modifiés, omis ou supposés à l'écriture du format cible. Elle n'inclut pas les champs qui n'ont pas été lus dans l'original ; comparez le résultat à la source.
Suis-je facturé si le fichier converti est invalide ?
Non. Un fichier invalide n’est pas renvoyé ; l’appel répond 422 avec le rapport, sans frais.
Comment relancer un appel sans payer deux fois ?
Avec l’en-tête Idempotency-Key. La même requête avec la même clé dans les 24 heures relance la conversion sans nouvelle facturation ; le fichier n'est pas forcément identique octet par octet.