Démarrage rapide

Statut : bêta. Valinvo transforme une facture JSON en Factur-X, CII ou UBL avec les règles françaises (France), en ZUGFeRD 2.5.2 / Factur-X 1.09.2 (PDF avec le XML intégré), en XRechnung 3.0.2 (Allemagne, UBL ou CII) ou en Peppol BIS Billing 3.0.21 (Belgique et réseau Peppol). Chaque facture générée est contrôlée selon les règles officielles de son format avant d'être renvoyée.

Conditions : l'API est réservée aux entreprises et soumise aux conditions d'utilisation et à l'accord de traitement des données (la version anglaise fait foi). Sans clé API, vous les acceptez en envoyant l'en-tête X-Accept-Terms: 1.0 (la version en vigueur) avec chaque requête ; les requêtes sans cet en-tête sont refusées avec 428 terms_not_accepted. Les titulaires d'une clé API acceptent par écrit lors de sa délivrance. Chaque réponse de l'API renvoie aux conditions dans l'en-tête Link: <…/terms>; rel="terms-of-service". L'essai sans clé API sert uniquement aux tests et à l'évaluation : utilisez des données d'exemple, pas de vraies factures contenant des données personnelles de tiers.

Support : n'envoyez jamais de vraies factures par e-mail. Envoyez le résultat de validation (identifiants de règles et emplacements des champs) ou une copie anonymisée avec des valeurs d'exemple à hello@bmk-hub.com, ou utilisez le formulaire de contact.

Lister les formats

curl https://valinvo.bmk-hub.com/v1/formats

Créer une facture

Envoyez le format et la facture dans un seul corps JSON. Deux exemples complets : XRechnung (Allemagne) et Peppol (Belgique).

curl -X POST https://valinvo.bmk-hub.com/v1/invoices \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/json' \
  -d @invoice.peppol-be.example.json \
  -o facture.xml -D -

La réponse est le fichier XML. Les en-têtes donnent le résultat du contrôle officiel :

X-Validation-Status: valid
X-Validation-Warnings: 0
X-Rule-Set: peppol-bis-3.0.21-ubl-invoice

Ajoutez -H 'Accept: application/json' pour recevoir le XML et le rapport de contrôle complet dans une seule réponse JSON.

Avec "format": "zugferd-en16931", la réponse est un PDF (enregistrez-le avec -o facture.pdf) ; les règles officielles contrôlent le XML qu'il contient. En mode JSON, le PDF est encodé en base64. Une facture sans date de livraison reçoit un avertissement (PEPPOL-EN16931-R008, élément de livraison vide) : le schéma ZUGFeRD impose cet élément, cet avertissement est donc normal.

Essai gratuit et clés d'API

Sans clé, vous pouvez créer 2 factures par jour (par adresse IP) pour essayer l'API ; les en-têtes X-Trial-Limit et X-Trial-Remaining indiquent où vous en êtes, puis vous recevez 429 trial_limit_reached. Les partenaires de conception reçoivent une clé bêta (Authorization: Bearer <clé>) sans limite quotidienne. Le valideur reste gratuit.

Sans clé, envoyez une requête à la fois (sinon 429 one_request_at_a_time). Limites de taille pour tous : JSON de facture jusqu'à 2 Mo et 2 000 lignes ; PDF ZUGFeRD jusqu'à 500 lignes et 5 000 caractères par champ de texte ; au plus 1 000 notes (100 dans les PDF) ; nombres d'au plus 15 chiffres avant et 10 après la virgule (400 invalid_invoice) ; documents à valider jusqu'à 20 Mo et 75 000 éléments XML, environ 3 000 lignes détaillées (413 document_too_large).

Règles simples

• Les montants, quantités et taux de TVA sont des chaînes JSON ("19.99"), jamais des nombres.
• Nous calculons les montants de ligne, la TVA et les totaux. Si vous envoyez aussi totals, nous les vérifions et indiquons la valeur qui diffère.
• Adresses électroniques : XRechnung accepte l'e-mail ({"scheme": "EM", "value": "factures@example.be"}). Peppol non ; utilisez un schéma Peppol comme 0208 (numéro d'entreprise belge) ou 9930 (numéro de TVA allemand).
• XRechnung exige buyerReference (le Leitweg-ID pour les acheteurs publics), un contact vendeur avec nom, téléphone et e-mail, et des instructions de paiement.
• Peppol exige buyerReference ou orderReference et n'autorise qu'une seule note.
• France (factur-x-fr, cii-fr, ubl-fr) : envoyez billingFrame, les trois mentions codedNotes PMT, PMD et AAB (vos conditions d'indemnité de recouvrement, de pénalités de retard et d'escompte), les deux SIREN en legalRegistrationId avec le schéma 0002, et les adresses électroniques avec le schéma 0225 (par ex. le SIREN ; pas d'adresse e-mail). Exemple. Cadres de facturation : B1 biens, S1 prestations, M1 mixte ; B2/S2/M2 déjà payée (prepaidAmount = total, dueDate = date du paiement) ; B4/S4/M4 facture définitive après acompte ; S5 sous-traitant ; S6 cotraitant ; B7/S7 vente déjà déclarée en e-reporting. Factures d'acompte : "type": "prepayment_invoice". Non pris en charge : S3 (acheteurs publics), factures multi-vendeurs B8/S8/M8, factures bidirectionnelles B9/S9/M9.
• Autres devises : une facture qui n'est pas en EUR peut indiquer le total de TVA dans votre devise de comptabilité, tel que votre comptabilité l'a converti : "taxCurrency": {"code": "EUR", "vatTotal": "54.12"}. Obligatoire en France (EUR).
• Avoirs : envoyez "type": "credit_note" avec des montants positifs et la facture corrigée dans precedingInvoice. Les formats UBL renvoient un CreditNote UBL ; la date d'échéance y fait partie des instructions de paiement, donc un avoir avec dueDate a besoin de payment (par ex. le compte du remboursement).
• Belgique (Peppol) : les entreprises belges utilisent le schéma 0208 avec leur numéro d'entreprise à dix chiffres (sans points), par exemple 0123456749.
• Danemark (Peppol) : les vendeurs danois indiquent legalRegistrationId avec leur numéro CVR et le schéma 0184 ; codes de paiement 1, 10, 31, 42, 48, 49, 50, 58, 59, 93 ou 97 (pas 30).
• Suède (Peppol) : numéros de TVA SE + 12 chiffres, numéros d'organisation à 10 chiffres (schéma 0007), taux de TVA 25, 12 ou 6 % ; code de paiement 30 entre parties suédoises.
• Norvège (Peppol) : les numéros d'organisation utilisent le schéma 0192 ; les sociétés immatriculées ajoutent taxRegistrationId: "Foretaksregisteret".
• Slovaquie (Peppol) : les entreprises slovaques utilisent le schéma 0245 avec le DIČ à dix chiffres (pas 9950). Si le vendeur et l'acheteur sont tous deux slovaques, nous exigeons aussi les deux adresses complètes et le motif d'exonération en texte ; envoyez taxPointDate (date de livraison) s'il diffère de issueDate.

En cas d'erreur

Vous recevez 400 avec tous les problèmes d'un coup, chacun avec le chemin JSON, la règle officielle et le terme métier EN 16931. Les messages de l'API sont en anglais :

{
  "code": "invalid_invoice",
  "message": "The invoice has 1 problem. Fix it and try again.",
  "problems": [{
    "path": "invoice.buyerReference",
    "message": "Peppol requires buyerReference or orderReference.",
    "rule": "PEPPOL-EN16931-R003",
    "businessTerm": "BT-10"
  }]
}

422 generated_invoice_invalid signifie que le XML généré ne respecte pas les règles officielles ; validation.errors en donne la raison. Le plus souvent, un champ exigé par une règle nationale manque.

Valider une facture existante

curl -X POST https://valinvo.bmk-hub.com/v1/validate \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/xml' \
  --data-binary @facture.xml

{"ruleSet": "peppol-bis-3.0.21-ubl-invoice", "valid": true, "errors": [], "warnings": []}

Le jeu de règles est détecté à partir du document : XRechnung 3.0 (UBL Invoice, UBL CreditNote, CII), Peppol BIS Billing 3.0 (UBL Invoice, UBL CreditNote) et ZUGFeRD 2.x / Factur-X en CII (profils MINIMUM, BASIC WL, BASIC, EN 16931 et EXTENDED, contrôlés selon les règles 2.5.2). Une facture invalide est un résultat 200 normal avec valid: false et la liste des erreurs.

Un PDF ZUGFeRD / Factur-X peut être envoyé tel quel. Nous contrôlons le XML de facture qu'il contient, le PDF lui-même selon PDF/A-3 (avec veraPDF) et que les métadonnées du PDF indiquent le même profil et la même pièce jointe que le XML ; le jeu de règles devient par exemple zugferd-2.5.2-en16931+pdf-a-3b. Les erreurs PDF/A ont des ID comme PDF/A-3 6.2.11.4.1-1 (section et test de l'ISO 19005-3), les erreurs de métadonnées commencent par ZF-XMP :

curl -X POST https://valinvo.bmk-hub.com/v1/validate \
  -H 'X-Accept-Terms: 1.0' \
  -H 'Content-Type: application/pdf' \
  --data-binary @facture.pdf

Un PDF sans pièce jointe de facture reçoit 400 no_embedded_invoice ; un PDF illisible ou protégé par mot de passe, 400 invalid_pdf.

OpenAPI

Toute l'API en description OpenAPI 3 : openapi.json. Importez-la dans Postman, Insomnia ou un générateur de code.

Démarrage rapide · Valideur Peppol · Valideur Factur-X · Codes d'erreur