Que vous soyez une petite entreprise, une grande entreprise ou un éditeur de logiciels, l'API de Qvalia vous offre un moyen unique et normalisé d'intégrer le réseau Peppol, avec un support optionnel pour des flux EDI supplémentaires, un traitement intelligent des documents et un enrichissement des données.
Grâce au service Invoicing API, vous pouvez utiliser les messages Peppol liés aux factures tels que BIS Billing (facture), BIS BIS Billing Credit Note (note de crédit), BIS Self-Billing Invoice, BIS Self-Billing Credit Note et BIS Invoice Response, et, si nécessaire, les compléter avec Message Level Response pour les accusés de réception techniques liés aux factures et aux autres messages Peppol.
L'API peut :
- Aider une petite entreprise à envoyer rapidement des factures Peppol
- Soutenir une grande entreprise avec des flux de messages structurés et volumineux
- Alimenter les logiciels de facturation et les ERP qui ont besoin d'une connectivité multi-tenant pour de nombreux clients
Dans ce guide, vous apprendrez à :
- Configurer l'API de Qvalia comme votre hub Peppol et EDI
- Échangez votre première facture Peppol via l'API
- Au-delà des factures, les commandes, les catalogues et bien d'autres choses encore.
- Permet aux éditeurs de logiciels de disposer de modèles évolutifs et multi-locataires.
- Ajouter des fonctions avancées de données pilotées par l'IA pour l'enrichissement des données et l'extraction des PDF
Vue d'ensemble : API pour Peppol et EDI
L'API Peppol fournit une interface unifiée pour les messages commerciaux électroniques via Peppol et l'EDI. Elle est conçue pour prendre en charge des scénarios de base 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
- Conseils d'expédition
- Réponses au niveau du message et mises à jour de l'état d'avancement
Un principe de conception commun est utilisé pour tous les points d'extrémité :
- Points d'extrémité 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 penser 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, il suffit de quelques notions de base :
Compte Qvalia
Votre organisation est intégrée en tant que client Qvalia. Vous recevez un numéro d'enregistrement de compte qui identifie votre compte de manière unique dans tous les appels de transaction.
Clé API
L'authentification est gérée par 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 TLS moderne.
Numéro d'enregistrement du compte dans le chemin d'accès à l'URL
Les appels de transaction incluent votre numéro d'enregistrement du compte dans le chemin d'accès. Par exemple, les appels de transaction incluent votre numéro de compte (accountRegNo) dans le chemin d'accès :
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 à tester le trafic Peppol avec Qvalia.
Étape par étape : intégration de votre premier flux de factures Peppol (envoi et réception)
Cette section décrit une première intégration typique entre votre système et l'API de transaction de Qvalia, couvrant à la fois l'envoi et la réception de factures Peppol.
Étape 1 : Démarrer dans le bac à sable
Commencez par l'intégrer dans l'environnement "bac à sable" :
- URL de base (exemple) : https://api-qa.qvalia.com
- Modèle d'authentification, points finaux et structure identiques à ceux de la production
Cela vous permet de construire et de tester sans affecter les clients réels ou les flux financiers.
Étape 2 : Utilisez votre clé API et votre compteRegNo
Dans votre configuration, stockez :
- Votre clé API (pour le bac à sable)
- Votre compteRegNo
Chaque demande doit comprendre
- En-tête d'autorisation avec la clé API
- accountRegNo dans le chemin d'accès, par exemple :
Factures sortantes :/transaction/{accountRegNo}/invoices/outgoing
Factures entrantes (pull) :/transaction/{accountRegNo}/invoices/incoming
Étape 3 : Choisir JSON ou XML (basé sur UBL)
Toutes les transactions utilisent l'UBL 2.1 comme norme sous-jacente.
Vous pouvez soit
- Générer UBL 2.1 XML, ou
- Utiliser la représentation JSON de l'UBL, en faisant correspondre la même structure à des 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.
Etape 4 : Mettez votre facture en correspondance avec l'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 du type de facture)
- Parties (PartieFournisseurComptable, PartieClientComptable)
- Totaux (Total fiscal, Total légal-monétaire)
- Lines (InvoiceLine, Item, Price, TaxCategory)
L'objectif est de s'assurer que
- Tous les champs obligatoires sont présents
- Les valeurs sont conformes au profil Peppol correspondant (par exemple, BIS Billing)
- Les exigences de votre entreprise (références, centres de coûts, codes de projet) sont respectées.
Vous sérialisez ensuite ces données en JSON ou en XML, selon le format que vous avez choisi. Pour les factures entrantes, vous utilisez la même structure UBL lorsque vous lisez, validez et mappez les données de Qvalia dans votre modèle interne.
Étape 5a : Envoyer une facture Peppol sortante
Étape 5.1 : Envoyer une facture Peppol sortante
La charge utile sortante étant prête, l'exemple du point de terminaison :
POST https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/outgoingInclure :
- En-tête d'autorisation avec votre clé API
- En-tête Content-Type correct (JSON ou XML)
- La charge utile de la facture basée sur l'UBL dans le corps de la demande
Qvalia valide la facture, l'achemine via le réseau Peppol ou VAN et renvoie une réponse avec les identifiants et le statut.
Étape 5.2 : Réception des factures de Peppol
Pour récupérer les factures entrantes de Qvalia via l'API, vous devez typiquement :
Appeler le point de terminaison entrant, par exemple :
GET https://api-qa.qvalia.com/transaction/{accountRegNo}/invoices/incomingEn option, vous pouvez :
- Filtre ou page de résultats (en fonction de votre configuration)
- Utiliser des points de terminaison "read" pour différencier les nouvelles factures des factures déjà traitées.
Le JSON ou le XML UBL renvoyé est ensuite mappé dans votre modèle de données interne en vue de la publication, de l'approbation ou d'un traitement ultérieur.
Étape 6 : Gestion du suivi, 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 des utilisateurs. Modèles typiques :
- 200 OK - La demande a abouti et les données sont renvoyées
- 204 No Content - La demande a été acceptée, mais il n'y a pas de corps disponible
- 400 / 422 - Données ou schéma non valides ; adaptez votre charge utile ou votre analyse.
- 401 / 403 - Problèmes d'authentification ou de permission
- 404 - Ressource non trouvée (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 demandes
- 500 - Erreur interne ; réessayer ou avertir le service d'assistance si l'erreur persiste
Les mêmes schémas s'appliquent que vous envoyiez ou receviez des factures.
Utiliser le journal des transactions pour le suivi opérationnel
En plus des réponses API, vous pouvez toujours vous connecter à Qvalia et examiner 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 :
- Envoi et réception de factures
- Statut des transactions individuelles
- Détails des erreurs et retour d'information sur la validation
- Horodatage technique et commercial
Le journal des transactions est utile pour
- Support de première ligne et équipes opérationnelles qui ne travaillent pas directement avec l'API
- Dépannage 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 déroulent comme prévu en production
Ensemble, les codes d'état HTTP et le journal des transactions fournissent une image 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 si nécessaire.
Au-delà des factures : élargissez votre cas d'utilisation de l'API Peppol
Une fois les factures en place, il est facile d'étendre votre intégration à un portefeuille complet de messages Peppol.
Les extensions typiques sont les suivantes :
Orders. Réception et envoi électronique de commandes structurées
Réponses aux commandes et modifications. Confirmation, modification ou annulation des commandes
Catalogues. Gestion des informations sur les produits et les prix dans les catalogues électroniques
Avis d'expédition. Communiquer les informations relatives à l'expédition
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 mettre en place de nouveaux cas d'utilisation au fur et à mesure de l'évolution des besoins de votre entreprise ou de vos clients.
C'est là que la promesse d'une "API Peppol unique, quels que soient les besoins" devient tangible : la même intégration sert les petits fournisseurs, les grandes entreprises et les scénarios de plateforme complexes.
API partenaire pour les logiciels de facturation et les ERP
Si vous êtes un éditeur de logiciels - exploitant une plateforme facturation, un ERP, une solution de comptabilité ou une plateformeintégration plateformevos besoins sont légèrement différents. Avec l'API partenaire de Qvalia, vous pouvez mettre en place une configuration multi-tenant pour l'échange de messages pour les utilisateurs finaux, y compris la gestion des enregistrements d'Peppol ID .
L'API partenaire pour Peppol est nécessaire si vous en avez besoin :
- Servir plusieurs clients finaux à partir d'une seule plateforme
- Séparer clairement les données et les transactions de chaque client
- Évitez d'exploiter votre propre point d'accès Peppol ou votre propre passerelle EDI.
Le modèle de Qvalia, axé sur les partenaires, est conçu spécifiquement à cette fin.
Fonctionnement du système de partenariat
- Votre entreprise est intégrée en tant que partenaire et reçoit un identifiant de partenaire.
- Vous avez le choix entre deux méthodes pour gérer les messages des utilisateurs finaux : 1) un compte utilisateur partagé et centralisé, ou 2) des comptes Qvalia individuels pour chaque utilisateur final, chacun disposant de son propre numéro de compte (accountRegNo).
- Les appels API incluent à la fois le contexte de votre partenaire et le compte spécifique du client, ce qui vous permet d'envoyer et de recevoir des messages en son nom.
Exemple : Mise en œuvre par un partenaire
Embarquement
- Votre organisation reçoit les informations d'identification et de configuration du partenaire, y compris un numéro d'enregistrement du partenaire et une clé API.
- Vous mettez en place une intégration unique vers l'API de Qvalia, en utilisant l'option
/partner/{partnerRegNo}pour tous les appels à l'échelle du partenaire.
L'accueil du client dans votre produit
- Lorsqu'un client active e-facturation dans votre interface utilisateur, un compte Qvalia est créé ou lié pour ce client.
- Vous enregistrez le numéro de compte du client en même temps que votre propre numéro de 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 données utiles UBL (factures, commandes, etc.) de la même manière qu'avec l'API de transaction standard. Pour envoyer ou recevoir des transactions au nom d'un client spécifique, vous appelez l'API Transaction par le biais du 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(GET) - Utilisation
readle 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é totale par compte.
Avantages pour les éditeurs de logiciels
- Une intégration technique, plusieurs clients, en utilisant un modèle de partenaire et de compte cohérent.
- Il n'est pas nécessaire d'exploiter et de maintenir votre propre réseau Peppol ou EDI.
- Évolution facile vers de nouveaux marchés, mandats et types de messages en réutilisant le même modèle d'intégration des partenaires.
Fonctionnalité supplémentaire : Enrichissement agentique par l'IA
Outre le transport et la connectivité, Qvalia propose également l'API d'enrichissement, qui permet d'enrichir les transactions avec la classification des postes, le traitement pré- et post-transaction, et plus encore, et d'extraire et de transformer les documents PDF en données riches, structurées et validées avec un minimum d'effort.
L'API d'enrichissement est conçue comme un service asynchrone :
- Vous soumettez un fichier de facture (par exemple, PDF ou XML) via l'API.
- Vous recevez un pollingId dans la réponse.
- Vous demandez le statut jusqu'à ce que l'enrichissement soit terminé.
- Vous récupérez un résultat JSON structuré avec 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 de gestion
- Champs normalisés adaptés à l'analyse, à l'automatisation et aux flux de travail de l'IA.
Modèle de mise en œuvre
Une intégration typique se présente comme suit :
Soumettre une facture pour enrichissement
Appeler un point d'accès, joindre le fichier de la facture et toutes les métadonnées pertinentes, et
Stocker le pollingId renvoyé.
POST /enrichment/{accountRegNo}/invoiceDemander l'achèvement
Appeler à des intervalles sûrs. Pendant le traitement, l'API confirme que le travail est toujours en cours. Lorsqu'elle est terminée, elle renvoie un état et des liens vers le résultat de l'enrichissement.
GET /enrichment/{accountRegNo}/{pollingId}Récupérer des types d'enrichissement spécifiques
Appeler pour obtenir un résultat d'enrichissement particulier - par exemple, des données de facture détaillées ou des résultats de validation Peppol. Alimentez votre moteur de comptabilité, votre pile d'analyse ou votre logique d'automatisation.
GET /enrichment/{accountRegNo}/{pollingId}/{enrichmentType}Cas d'utilisation
- Petites entreprises
Peut bénéficier d'un traitement intelligent des documents au niveau de l'entreprise, de données propres et structurées sans investir dans des outils complexes d'OCR ou de validation. - Large entreprises
Peut standardiser les données des factures et des documents entre les entités, les systèmes et les zones géographiques, et permettre un meilleur contrôle des données, des analyses et l'automatisation de la comptabilité. - Les éditeurs de logiciels et les partenaires
peuvent intégrer des capacité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 modèle de compte et de sécurité que l'API de transaction, et un petit ensemble de points d'extrémité bien définis.
Accès à l'API Peppol pour toutes les entreprises
L'API de Qvalia est conçue pour vous donner un point d'accès simplifié et évolutif au réseau Peppol, quel que soit le type de votre entreprise :
- Une petite entreprise qui a besoin d'échanger des factures électroniques conformes
- Une grande entreprise gérant des flux importants et multi-entités
- Un fournisseur de logiciels offrant des solutions de facturation, d'ERP ou de finance à de nombreux clients.
L'étape suivante est simple : connectez-vous au bac à sable, envoyez votre première facture test et commencez à planifier la façon dont Peppol, l'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.
