Documents
Factures et notes de crédit
Plus autofacturation et réponses aux factures
Formats
JSON ou XML UBL
Basé sur la norme UBL 2.1, un document par requête
Événements
Webhooks signés
Reçu, livré, en retard et en échec
Disponibilité
99,8 % par mois
Contractuel, avec crédits de service
Envoyer une facture avec une seule demande
Envoyez la facture au format JSON ou UBL XML vers le point de terminaison sortant de votre compte. Qvalia la valide, recherche le destinataire sur Peppol et la transmet. Les notes de crédit, les documents d'autofacturation et les réponses aux factures suivent le même processus.
- Environnement de test sur api-test.qvalia.com, environnement de production sur api.qvalia.com
- Une clé API dans l'en-tête « Authorization », ou un jeton à durée de vie limitée (JWT)
- Un en-tête « Idempotency-Key » garantit la sécurité des tentatives de réessai
● ● ●
Demande dans l'environnement de test : envoyer une facture
curl -X POST \
"https://api-test.qvalia.com/transaction/$ACCOUNT_REG_NO/invoices/outgoing" \
-H "Authorization: $QVALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @invoice.jsonParcours d'une facture via l'API
Votre système fonctionne avec une seule API. Qvalia gère le point d'accès Peppol qui se trouve en arrière-plan.
1. Envoyer
Envoyez un seul document par requête. Si les données ne sont pas valides ou si le destinataire n'est pas enregistré sur Peppol, l'API renvoie un code d'erreur 422 (erreur stable) avant que quoi que ce soit ne soit envoyé.
2. Valider et livrer
Qvalia vérifie la conformité du document aux règles Peppol applicables, identifie le point d'accès du destinataire et transmet le document via AS4.
3. Suivre l'état d'avancement
Les webhooks signalent la remise des documents, les tentatives de réenvoi en cours et les échecs. Le point de terminaison « status » renvoie le dernier statut de chaque document sans la charge utile de celui-ci.
4. Recevoir
Les factures entrantes et les réponses sont mises en attente sur les points de terminaison d'arrivée. Le point de terminaison de lecture renvoie les documents non lus et les marque comme lus ; ainsi, l'appel suivant ne renvoie que les nouveaux documents.
Documents de facturation et points de terminaison
Chaque chemin commence par /transaction/{accountRegNo}, le numéro d'enregistrement de votre compte. Chaque type de document dispose de points de terminaison de sortie et d'entrée, d'un point de terminaison de lecture pour les documents non lus et d'un point de terminaison d'état.
| Document | Point d'extrémité | Spécification Peppol |
| Facture | /invoices | Peppol BIS Billing 3.0 |
| Note de crédit | /creditnotes | Peppol BIS Billing 3.0 |
| Facture d'autofacturation | /selfbillinginvoices | Auto-facturation Peppol BIS |
| Note de crédit en autofacturation | /selfbillingcreditnotes | Auto-facturation Peppol BIS |
| Réponse à la facture | /invoiceresponses | Peppol BIS Invoice Response |
| Réponse au niveau du message | /messagelevelresponses | Peppol BIS Message Level Response |
Les types de documents utilisés par votre compte dépendent du service et de la formule souscrite. Les schémas des requêtes et des réponses figurent dans les documentations de référence de l'API Facture et de l'API Avis de crédit. Pour toutes les API de Qvalia, consultez la section « API Peppol et outils de développement ».
Vérifiez le destinataire avant d'envoyer le message
Effectuez une recherche d'Peppol ID s avant d'envoyer la facture. La réponse indique si le destinataire est enregistré sur Peppol et quels types de documents il peut recevoir ; votre système peut ainsi signaler un identifiant manquant ou erroné avant que le réseau ne rejette la facture.
- Limitez la vérification à un seul type de document à l'aide de
docTypeRoot, par exempleInvoiceouCreditNote - L'« Peppol ID » correspond au schéma et à l'identifiant, par exemple
0007:1234567890 - Mêmes URL de base et mêmes modalités d'authentification que pour l'API Transaction
● ● ●
Demande dans l'environnement de test : rechercher un destinataire
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"Conçu pour les intégrations en production
Les détails qui déterminent si une intégration tient la route à grande échelle sont tous documentés dans la documentation de référence de l'API.
- Nouvelles tentatives sécurisées
Envoyez une clé d'idempotence : une requête répétée renverra la réponse d'origine au lieu de créer une deuxième facture. - Webhooks signés
Chaque événement est associé à un identifiant d'événement et, une fois que vous avez défini une clé de signature, à une signature que vous pouvez vérifier. - Rediffusion des événements pendant 30 jours
Récupérez n'importe quel événement déjà transmis à l'aide de son identifiant, par exemple après une interruption de service de votre côté. - Statut sans données utiles
Effectuez un rapprochement à grande échelle à l'aide d'enregistrements d'état allégés, filtrés par date, identifiant de document ou heure de mise à jour. - Limites de fréquence
Les limites sont comptabilisées par compte, et une réponse 429 vous indique le temps d'attente. - Pièces jointes
Ajoutez des fichiers PDF et des images à l'intérieur du message. La requête dans son ensemble, pièces jointes comprises et encodées en Base64, doit rester en dessous de la limite de 100 Mo fixée par Peppol.
Une seule facture, adaptée au format dont chaque destinataire a besoin
Envoyez la facture une seule fois. Qvalia la valide, identifie le destinataire et la transmet via le réseau Peppol au format « Peppol BIS Billing 3.0 » ou « Peppol PINT ». Lorsque le destinataire n’est pas connecté au réseau Peppol, Qvalia peut effectuer la transmission via EDI, au format PDF par e-mail, sous forme imprimée ou via des services bancaires en ligne B2C sur certains marchés. Il s’agit là de canaux de transmission supplémentaires, qui ne relèvent pas des spécifications Peppol. Découvrez les formats de messages commerciaux pris en charge par Qvalia.
Si votre système ne permet pas de générer des fichiers Peppol BIS, téléversez la facture dans le format dans lequel elle est déjà créée : Svefaktura 1.0, EDIFACT INVOIC, cXML, Finvoice 3.0, XRechnung, CII ou le format XML de ZUGFeRD et Factur-X. Qvalia la convertit au format Peppol BIS Billing 3.0, la valide et l'envoie. Consultez la section « Envoi de factures dans votre format actuel ».
Choisissez votre point de départ
Plateformes logicielles
Peppol intégré
Proposez « e-facturation » à vos propres clients. L’API Partenaire crée leurs comptes et leurs identifiants Peppol, tandis que l’API Facturation prend en charge leurs documents.
Équipes ERP et financières
Point d'accès de Peppol
Connectez votre ERP ou votre système financier à Peppol via l'API, le protocole SFTP ou un connecteur prêt à l'emploi.
Développeurs
Guide de démarrage rapide
Passez de la clé API à votre première facture en environnement de test, étape par étape, avec des exemples de requêtes.
FAQ sur l'API de facturation
Qu'est-ce qu'une API « e-facturation » ?
Une API d'e-facturation e permet à votre logiciel d'envoyer et de recevoir des factures électroniques structurées sans avoir à établir lui-même la connexion réseau. Grâce à l'API de facturation de Qvalia, votre système envoie les factures au format JSON ou UBL XML, et Qvalia les valide avant de les transmettre via le réseau Peppol.
Quels types de factures puis-je envoyer et recevoir ?
Factures, notes de crédit, factures et notes de crédit en autofacturation, ainsi que réponses aux factures, chacune disposant de points de terminaison « sortants » et « entrants ». Les types de documents pris en charge par votre compte dépendent du service et de la formule souscrite.
Dois-je connaître le standard Peppol BIS pour utiliser l'API ?
Vos documents sont conformes à la norme Peppol BIS Billing 3.0, au format JSON ou XML basé sur UBL 2.1. Les exemples de données disponibles sur api.qvalia.io présentent une facture complète, et les erreurs de validation indiquent la règle à corriger. Consultez la section « Comment fonctionne la validation Peppol ».
Y a-t-il un bac à sable ?
Oui. L'environnement de test disponible à l'adresse api-test.qvalia.com utilise sa propre clé API, ce qui vous permet de tester vos systèmes sans affecter les clients réels. L'accès à l'API et à l'environnement de test est inclus dans le forfait « Connect » Medium .
Comment éviter d'envoyer deux fois la même facture ?
Envoyez un en-tête « Idempotency-Key » à chaque envoi. Si vous répétez la requête, par exemple après un délai d'expiration, l'API renvoie la réponse d'origine au lieu de créer un deuxième document. Un nouvel envoi avec le même identifiant de document et le même destinataire renvoie un code d'erreur 409 (Conflit), sauf si vous choisissez de remplacer le document existant.
Comment savoir si une facture a bien été envoyée ?
Abonnez-vous aux webhooks pour les événements de livraison et d'erreur, ou consultez le point de terminaison d'état. Un webhook que votre point de terminaison ne parvient pas à accepter n'est pas renvoyé ; veillez donc à effectuer une vérification périodique de l'état à titre de mesure de sécurité. Tout événement livré peut être récupéré à nouveau pendant 30 jours.
Comment puis-je recevoir les factures ?
Abonnez-vous au webhook « nouveau document », puis récupérez la facture via le point de terminaison « incoming ». Le point de terminaison de lecture renvoie les factures non lues et les marque comme lues.
Combien coûte l'API de facturation ?
L'accès à l'API est inclus à partir de la formule « Connect » Medium . Les tarifs pour les partenaires et les entreprises dépendent du volume et du modèle de prestation. Consultez la rubrique « Formules et tarifs ».
