Que vous soyez une petite entreprise, une grande entreprise ou un fournisseur de logiciels, l'API de Qvalia vous offre un moyen unique et standardisé de vous intégrer au réseau Peppol, avec une prise en charge optionnelle des flux EDI supplémentaires, du traitement intelligent des documents et de l'enrichissement des données.
Grâce au service API de facturation, vous pouvez traiter les messages Peppol liés à la facturation, tels que BIS Billing facture), BIS Billing Note (note de crédit), BIS Self-Billing Invoice (facture d'autofacturation), BIS Self-Billing Credit Note (note de crédit d'autofacturation) et BIS Invoice Response à la facture), et, si nécessaire, les compléter par une réponse au niveau du message pour les accusés de réception techniques liés aux factures et autres messages Peppol.
L'API peut :
- Aidez une petite entreprise à commencer rapidement à envoyer des factures Peppol
- Prendre en charge une grande entreprise avec des flux de messages structurés et volumineux
- Logiciels de facturation et ERP qui nécessitent une connectivité multi-locataires pour de nombreux clients
Dans ce guide, vous apprendrez comment :
- Configurez l'API Transaction de Qvalia comme votre hub Peppol et EDI.
- Échangez votre première facture Peppol via API
- Allez au-delà des factures et passez aux commandes, catalogues et plus encore.
- Permet aux éditeurs de logiciels de mettre en place des modèles évolutifs et multi-locataires.
- Ajoutez des fonctionnalités avancées basées sur l'IA pour l'enrichissement des données et l'extraction de PDF.
Présentation : API pour Peppol et EDI
L'API Peppol fournit une interface unifiée pour les messages commerciaux électroniques via Peppol et EDI. Elle est conçue pour prendre en charge des scénarios clés tels que :
- Factures et notes de crédit
- Bons de commande et réponses aux commandes
- Modifications et annulations de commandes
- Catalogues et mises à jour des articles
- Avis d'expédition
- Réponses au niveau des messages et mises à jour de statut
Un principe de conception commun est utilisé pour tous les terminaux :
- Points de terminaison HTTP basés sur REST
- Prise en charge des formats JSON et XML
- UBL 2.1 comme modèle de données sous-jacent
- Gestion des erreurs à l'aide des codes d'état HTTP standard
Pour vous, cela signifie que vous pouvez raisonner en termes de messages commerciaux plutôt qu'en termes de réseaux et de protocoles. Vous créez des documents valides basés sur UBL ; Qvalia gère les couches Peppol et EDI en arrière-plan.
Pour commencer : conditions préalables et configuration
Pour commencer à utiliser l'API Peppol de Qvalia, quelques notions de base suffisent :
du compte Qvalia Votre organisation est enregistrée en tant que client Qvalia. Vous recevez un numéro d'enregistrement de compte qui identifie de manière unique votre compte dans tous les appels de transaction.
de la clé API L'authentification est gérée via une clé API, avec des clés distinctes pour les environnements de test et de production. Tous les appels sont effectués via HTTPS avec le protocole TLS moderne.
Numéro d'enregistrement du compte dans le chemin d'accès URL
Les appels de transaction incluent votre numéro d'enregistrement de compte dans le chemin d'accès. Par exemple :
POST /transaction/{accountRegNo}/invoices/outgoingChoix du format : JSON ou XML
Vous pouvez choisir JSON ou XML via les en-têtes HTTP standard (Content-Type et Accept). JSON est le format par défaut si aucun choix explicite n'est fait.
Une fois ces éléments en place, vous êtes prêt à commencer à tester le trafic Peppol avec Qvalia.
Étape par étape : intégrer votre premier flux de factures Peppol (envoi et réception)
Cette section décrit une première intégration type entre votre système et l'API Transaction de Qvalia, couvrant à la fois l'envoi et la réception de factures Peppol.
Étape 1 : Commencez dans le bac à sable
Commencez par l'intégration dans l'environnement sandbox :
- URL de base (exemple) : https://api-qa.qvalia.com
- Même modèle d'authentification, mêmes points de terminaison et même structure que la production
Cela vous permet de développer et de tester sans affecter les clients réels ni les flux financiers.
Étape 2 : Utilisez votre clé API et votre numéro d'enregistrement de compte (accountRegNo).
Dans votre configuration, enregistrez :
- Votre clé API (pour le bac à sable)
- Votre compteRegNo
Chaque demande doit inclure :
- En-tête d'autorisation avec la clé API
- accountRegNo dans le chemin d'accès au point de terminaison, par exemple :
Factures sortantes :/transaction/{accountRegNo}/invoices/outgoing
Factures entrantes (pull) :/transaction/{accountRegNo}/invoices/incoming
Étape 3 : Choisissez JSON ou XML (basé sur UBL)
Toutes les transactions utilisent la norme UBL 2.1 comme norme sous-jacente.
Vous pouvez soit :
- Générer un fichier XML UBL 2.1, ou
- Utilisez la représentation JSON UBL, en mappant la même structure dans les champs JSON.
Les en-têtes contrôlent le format :
JSON (par défaut)
Content-Type: application/jsonAccept: application/jsonXML
Content-Type: application/xmlAccept: application/xmlCette flexibilité vous permet d'intégrer l'API Peppol dans des environnements JSON-first et XML-first.
Étape 4 : Mappez votre facture à UBL
Ensuite, mappez votre modèle de facture interne aux éléments UBL. Les formats UBL JSON et UBL XML sont tous deux disponibles.
- Informations d'en-tête (Facture, Date d'émission, Code type de facture)
- Parties (Partie fournisseur comptable, Partie client comptable)
- Totaux (TaxTotal, LegalMonetaryTotal)
- Lignes (LigneFacture, Article, Prix, CatégorieTaxe)
L'objectif est de garantir que :
- Tous les champs obligatoires sont présents.
- Les valeurs sont conformes au profil Peppol pertinent (par exemple, BIS Billing)
- Vos propres exigences commerciales (références, centres de coûts, codes de projet) sont satisfaites.
Vous sérialisez ensuite ces données au format JSON ou XML, selon le format que vous avez choisi. Pour les factures entrantes, vous utilisez la même structure UBL lors de la lecture, de la validation et du mappage des données de Qvalia dans votre modèle interne.
Étape 5a : Envoyer une facture Peppol sortante
Étape 5.1 : Envoyer une facture Peppol sortante
Une fois votre charge utile sortante prête, exemple de point final :
POST https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/outgoingInclure :
- En-tête d'autorisation avec votre clé API
- Correction de l'en-tête Content-Type (JSON ou XML)
- La charge utile de la facture au format UBL dans le corps de la requête
Qvalia valide la facture, la transmet via le réseau Peppol ouVAN, puis renvoie une réponse avec les identifiants et le statut.
Étape 5.2 : Recevoir les factures Peppol entrantes
Pour récupérer les factures entrantes depuis Qvalia via l'API, vous devez généralement :
Appelez le point de terminaison entrant, par exemple :
GET https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/incomingVous pouvez également :
- Filtrer ou paginer les résultats (selon votre configuration)
- Utilisez les points de terminaison « read » pour différencier les factures nouvelles de celles déjà traitées.
Le fichier UBL JSON ou XML renvoyé est ensuite mappé dans votre modèle de données interne pour publication, approbation ou traitement ultérieur.
Étape 6 : Gestion de la surveillance, des réponses et des erreurs
L'API Transaction utilise des codes d'état HTTP prévisibles que vous pouvez associer aux journaux, à la surveillance et aux messages utilisateur. Modèles types :
- 200 OK – La requête a abouti et les données sont renvoyées.
- 204 Aucun contenu – Demande réussie, aucun corps disponible
- 400 / 422 – Données ou schéma non valides ; ajustez votre charge utile ou votre analyse syntaxique.
- 401 / 403 – Problèmes d'authentification ou d'autorisation
- 404 – Ressource introuvable (souvent un problème de chemin d'accès ou d'identifiant)
- 409 – Conflit, tel que les doublons
- 429 – Limite de débit atteinte ; ralentissez vos requêtes
- 500 – Erreur interne ; réessayez ou contactez le support technique si le problème persiste.
Les mêmes modèles s'appliquent, que vous envoyiez ou receviez des factures.
Utilisez le journal des transactions pour le suivi opérationnel.
En plus des réponses API, vous pouvez toujours vous connecter à Qvalia et consulter l'activité dans le journal des transactions. Cela vous donne une vue basée sur l'interface utilisateur de ce qui se passe dans votre intégration, y compris, par exemple :
- Factures envoyées et reçues
- Statut des transactions individuelles
- Détails de l'erreur et commentaires de validation
- Horodatages techniques et commerciaux
Le journal des transactions est utile pour :
- Équipes d'assistance de première ligne et équipes opérationnelles qui ne travaillent pas directement avec l'API
- Résolution des problèmes spécifiques signalés par les clients ou les utilisateurs internes
- Vérifier que les modifications apportées à votre intégration se comportent comme prévu en production
Ensemble, les codes d'état HTTP et le journal des transactions fournissent une vue d'ensemble complète : votre système peut réagir de manière programmatique aux réponses, tandis que votre équipe peut enquêter et assurer le suivi directement dans Qvalia lorsque cela est nécessaire.
Au-delà des factures : étendez votre utilisation de l'API Peppol
Une fois vos factures en place, il est facile d'étendre votre intégration à un portefeuille complet de messages Peppol.
Les extensions typiques comprennent :
Commandes. Réception et envoi électroniques de commandes structurées
Réponses et modifications de commandes. Confirmation, modification ou annulation de commandes
Catalogues. Gestion des informations sur les produits et les prix dans des catalogues électroniques
Avis d'expédition. Communication des informations relatives aux expéditions
Réponses au niveau des messages. Suivi des accusés de réception techniques et commerciaux
Comme tout cela utilise la même conception d'API, le même modèle d'authentification et le même modèle de données UBL 2.1, vous n'avez pas besoin de projets ou de passerelles distincts pour chaque type de document. Vous pouvez activer de nouveaux cas d'utilisation à mesure que votre entreprise ou les besoins de vos clients évoluent.
C'est là que la promesse « une seule API Peppol, quels que soient les besoins » devient tangible : la même intégration sert les petits fournisseurs, les grandes entreprises et les scénarios de plateformes complexes.
API partenaire pour logiciels de facturation et ERP
Si vous êtes un éditeur de logiciels (plateforme de facturation, ERP, solution comptable ou plateforme d'intégration), vos besoins sont légèrement différents. Grâce à l'API partenaire de Qvalia, vous pouvez mettre en place une configuration multi-locataires pour l'échange de messages destinés aux utilisateurs finaux, y compris la gestion Peppol ID .
L'API partenaire pour Peppol est nécessaire si vous devez :
- Servez de nombreux clients finaux à partir d'une seule plateforme
- Maintenez une séparation claire entre les données et les transactions de chaque client.
- Évitez d'exploiter votre propre point d'accès Peppol ou passerelle EDI.
Le modèle axé sur les partenaires de Qvalia est spécialement conçu à cette fin.
Comment fonctionne la configuration du partenaire
- Votre entreprise est intégrée en tant que partenaire et reçoit un identifiant partenaire.
- Vous pouvez choisir entre deux méthodes pour traiter les messages des utilisateurs finaux : 1) un compte utilisateur partagé consolidé, ou 2) des comptes Qvalia individuels pour chaque utilisateur final, chacun avec son propre numéro de compte (accountRegNo).
- Les appels API incluent à la fois votre contexte partenaire et le compte client spécifique, ce qui vous permet d'envoyer et de recevoir des messages en leur nom.
Exemple : mise en œuvre par un partenaire
Intégration
- Votre organisation reçoit les identifiants et la configuration du partenaire, y compris un numéro d'enregistrement partenaire (partnerRegNo) et une clé API.
- Vous configurez une seule intégration vers l'API de Qvalia, à l'aide du
/partner/{partnerRegNo}préfixe pour tous les appels au niveau du partenaire.
Intégration des clients dans votre produit
- Lorsqu'un client active Peppol/la facturation électronique dans votre interface utilisateur, un compte Qvalia est créé ou associé à ce client.
- Vous enregistrez le numéro d'enregistrement du compte client (accountRegNo) avec votre propre identifiant client afin de pouvoir traiter les transactions par client.
Envoi et réception de transactions par client
Votre application génère ou consomme des charges utiles UBL (factures, commandes, etc.) de la même manière qu'avec l'API Transaction standard. Pour envoyer ou recevoir des transactions au nom d'un client spécifique, vous appelez l'API Transaction via le modèle URI préfixé par le partenaire :
/partner/{partnerRegNo}/transaction/{accountRegNo}/{message-type}/{direction}Par exemple :
- Envoi d'une facture sortante :
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/outgoing(POST) - Récupération des factures entrantes :
/partner/{partnerRegNo}/transaction/{accountRegNo}/invoices/incoming(OBTENIR) - Utilisation
readvariantes, le cas échéant, en ajoutantreadsur le chemin.
Qvalia achemine et reçoit les messages comme s'ils étaient envoyés ou reçus directement par le client, avec une traçabilité complète par compte.
Avantages pour les éditeurs de logiciels
- Une intégration technique, de nombreux clients, utilisant un modèle de partenariat et de compte cohérent.
- Pas besoin de gérer et d'entretenir votre propre infrastructure Peppol ou EDI.
- Facilité d'adaptation à de nouveaux marchés, mandats et types de messages grâce à la réutilisation du même modèle d'intégration des partenaires.
Fonctionnalité supplémentaire : enrichissement agentique par IA
Outre le transport et la connectivité, Qvalia propose également l'API Enrichment, qui permet d'enrichir les transactions grâce à la classification des lignes, au traitement pré et post-transaction, etc., et qui peut extraire et transformer des documents PDF en données riches, structurées et validées avec un minimum d'effort.
L'API Enrichment est conçue comme un service asynchrone :
- Vous soumettez un fichier de facture (par exemple, au format PDF ou XML) via l'API.
- Vous recevez un pollingId dans la réponse.
- Vous interrogez le statut jusqu'à ce que l'enrichissement soit terminé.
- Vous récupérez un résultat JSON structuré contenant des informations enrichies.
Ce résultat peut inclure :
- Contenu de la facture analysé et extrait du fichier original
- Validation par rapport à Peppol ou à d'autres règles commerciales
- Champs normalisés adaptés à l'analyse, à l'automatisation et aux workflows d'IA
Modèle de mise en œuvre
Une intégration type se présente comme suit :
Soumettez une facture pour l'enrichissement
Appelez un point de terminaison, joignez le fichier de facture et toutes les métadonnées pertinentes, puis
Enregistrez le pollingId renvoyé.
POST /enrichment/{accountRegNo}/invoiceSondage pour l'achèvement
Appelez à intervalles réguliers. Pendant le traitement, l'API confirme que la tâche est toujours en cours d'exécution. Une fois terminée, elle renvoie un statut et des liens vers le résultat de l'enrichissement.
GET /enrichment/{accountRegNo}/{pollingId}Récupérer des types d'enrichissement spécifiques
Appelez cette fonction pour obtenir un résultat d'enrichissement particulier, par exemple des données de facturation détaillées ou les résultats de validation Peppol. Intégrez ces données dans votre moteur comptable, votre pile analytique ou votre logique d'automatisation.
GET /enrichment/{accountRegNo}/{pollingId}/{enrichmentType}Cas d'utilisation
- Les petites entreprises
peuvent bénéficier d'un traitement intelligent des documents de niveau entreprise, avec des données propres et structurées, sans avoir à investir dans des outils complexes d'OCR ou de validation.
pour Large Permet de normaliser les données des factures et des documents entre les entités, les systèmes et les zones géographiques, et d'améliorer le contrôle des données, l'analyse et l'automatisation de la comptabilité.- Les éditeurs de logiciels et les partenaires
peuvent intégrer des fonctionnalités d'enrichissement avancées directement dans leurs produits, sans avoir à développer leurs propres moteurs d'analyse et de règles.
Dans tous les cas, l'accès à cette technologie est simple : le même compte et le même modèle de sécurité que l'API Transaction, ainsi qu'un petit ensemble de points de terminaison bien définis.
Accès à l'API Peppol pour toutes les entreprises
L'API de Qvalia est conçue pour vous offrir un point d'accès simplifié et évolutif au réseau Peppol, quel que soit le type de votre entreprise :
- Une petite entreprise qui doit échanger des factures électroniques conformes
- Une grande entreprise gérant des flux volumineux et multi-entités
- Un éditeur de logiciels proposant des solutions de facturation, d'ERP ou de finance à de nombreux clients.
La prochaine étape est simple : connectez-vous au bac à sable, envoyez votre première facture test et commencez à planifier comment Peppol, EDI et l'enrichissement peuvent devenir une partie intégrante de vos opérations ou de votre produit, plutôt qu'un projet distinct et complexe.
