|
|
|
|
|
|
|
|
|
|
- Présentation
- Découverte du portail Chorus Pro
- Le portail
- Création d'un compte de test et téléchargement des données de test
- Activation des API
- Nécessité d'utiliser un certificat
- Programmation des API REST de Chorus Pro en WLangage
- Présentation
- Construction de l'entête
- Manipulation des paramètres ou des résultats
- Exécution de la requête REST
- Callback pour la mise au point
- Parcours de résultats JSON
- Encodage PDF
Chorus Pro : Automatiser le dépôt de factures
La France rend obligatoire la facturation électronique pour facturer les services de l'état. Pour le dépôt et le suivi des factures, la France a mis en place le système Chorus Pro. C'est l'outil de gestion des dépenses et des recettes non fiscales des services de l'État français. A partir du 01/01/2019, toutes les sociétés de plus de 10 personnes doivent facturer les services de l'état via un dépôt des factures (au format PDF) sur Chorus Pro. Et à partir de 2020, toutes les sociétés doivent utiliser Chorus Pro. Le portail "Chorus Pro" permet de gérer les factures avec les services publics français. Il est possible de réaliser manuellement ces opérations par le portail, mais il est surtout possible d'automatiser ces tâches par un ensemble d'API. Le portail "Chorus Pro" permet deux types d'intégration?: - un mode EDI (échange XML),
- un mode API (API REST).
Le mode EDI propose un sous-ensemble limité des fonctionnalités du mode API. Cette page d'aide présente : - La découverte du portail Chorus Pro (avec les outils nécessaires pour utiliser les API).
- La programmation des API Chorus Pro en WLangage.
Vous trouverez dans la LST 115 un exemple d'utilisation des API pour envoyer des factures PDF sur le portail Chorus Pro. Découverte du portail Chorus Pro Le portail Le portail "Chorus Pro" et ses fonctionnalités sont destinés à deux types d'utilisateurs : - les services destinataires des factures : les administrations,
- les services émetteurs de factures auprès des administrations.
Remarque : L'ensemble des documentations concernant le fonctionnement du portail "Chorus Pro" mais également des API est disponible depuis l'adresse suivante : https://communaute.chorus-pro.gouv.fr/Chorus Pro propose : - Un environnement de test
Cet environnement de test est appelé "Portail de qualification".
Le portail de qualification est disponible à l'adresse : https://chorus-pro.gouv.fr/qualif. Il est reconnaissable rapidement grâce à sa couleur verte. - Un environnement de production
Le portail de production est disponible à l'adresse : https://chorus-pro.gouv.fr/. Il est reconnaissable rapidement grâce à sa couleur bleue.
Note : les environnements de test et de production peuvent être "liés" mais restent indépendants. Il est donc nécessaire de créer un compte pour chaque environnement. Dans la suite de cette page, les manipulations sont effectuées dans l'environnement de test. Création d'un compte de test et téléchargement des données de test Etape 1 : Création d'un compte Chorus Pro : Avant toute opération, il est nécessaire de créer un compte Chrorus Pro (dans l'environnement de test et/ou de production selon vos besoins). La création d'un compte Chorus n'est pas immédiate (jusqu'à plusieurs jours), il faut donc anticiper cette étape en cas de besoin. En effet, pour créer un compte Chorus, il est nécessaire d'être une société (appelée "structure" dans l'interface Chorus) et d'indiquer en plus d'une adresse email, des renseignements spécifiques à la société (tel que le numéro de SIRET par exemple). Ces informations sont vérifiées avant la création du compte. Remarque : l'adresse associée au compte doit être une adresse email valide et consultée. Cette adresse sera utilisée par Chorus pour communiquer sur les évolutions et les périodes de maintenances des différents environnements. Etape 2 : Environnement de test : Récupération des données de test
Lorsque le compte Chorus pour l'environnement de test est créé, il est possible (voire très rapidement indispensable) de demander à récupérer des données de test (appelées "Matelas de données" dans le vocabulaire "Chorus Pro").
Pour cela : - Dans le portail de qualification, sélectionnez l'option "Mon Compte .. Mon matelas de données .. Créer".
- La génération du matelas de données se lance. Attention, cette opération peut être très longue et dépasser 1 heure.
- A la fin de la génération, cliquez sur "télécharger pièces jointes".
- Le fichier obtenu est un fichier ".csv" contenant des factures, des fournisseurs, etc.
- Déconnectez-vous du portail de qualification.
- Connectez-vous au portail de qualification à l'aide des identifiants fournis dans le fichier téléchargé (Fournisseur partenaire : login et mot de passe).
- Vous accédez ainsi à l'environnement avec les données de test en tant que "Gestionnaire principal de la structure". Un ensemble de factures a été automatiquement généré pour réaliser vos tests. Vous pouvez avoir des factures en attente, en échec comme pour un usage "en production".
Activation des API Par défaut, les API ne sont pas accessibles pour un compte sur les portails "Chorus Pro" (portail de test ou de production). Dans le vocabulaire "Chorus Pro", le terme employé est "raccordement". Raccordement des API
Il est nécessaire d'autoriser (raccorder) explicitement l'accès aux API avant de pouvoir réaliser des appels d'API. Dans l'environnement de test, la manipulation à réaliser est la suivante : - Sélectionnez l'option "Activités du gestionnaire".
- Descendez au choix "Mes structures".
- Sur la ligne de la structure, cliquez sur le "crayon" de la colonne "Actions".
- Cliquez sur le bouton "Ajoutez des espaces" dans la partie "Espaces".
- Sélectionnez le ou les services et activez l'option "Raccordement EDI et API".
- Déconnectez-vous du portail.
- Connectez-vous au portail à l'aide des identifiants fournis dans le fichier téléchargé (Fournisseur partenaire : login et mot de passe).
- Une nouvelle option "Raccordements EDI et API" apparaît dans le menu.
- Sélectionnez cette option et validez.
- Il faut désormais indiquer le certificat à utiliser pour utiliser les API dans l'option "Créer fiche API". Vous pouvez trouver plus de détails sur la page : https://communaute.chorus-pro.gouv.fr/documentation/raccordement-a-chorus-pro/
Compte technique
Pour utiliser les API, il est nécessaire de créer un compte "technique" dans le portail "Chorus Pro". Dans le portail de test, ce compte technique est créé à partir du compte gestionnaire.
L'identité (email et mot de passe) de ce compte technique sera passée "en paramètres" aux API REST.
La création de ce compte technique permet de dissocier l'utilisation "par API" et l'utilisation classique du portail Chorus Pro par le compte du gestionnaire par exemple.
Note : il est possible de créer plusieurs comptes techniques et de leur donner un accès limités à certaines API. Nécessité d'utiliser un certificat Identification par certificatPour authentifier les appels par API, le portail Chorus Pro impose l'identification par certificat client. Ce type d'identification est présenté comme une sorte de "carte d'identité numérique" dans la documentation Chorus Pro. Ce certificat va permettre au portail d'identifier et d'authentifier chaque appel. Chaque client (donc chaque société voulant se connecter au portail Chorus Pro par API) va devoir acheter un certificat auprès d'organismes reconnus, Achat d'un certificatDans le cadre d'une utilisation des API (et non EDI), un seul type de certificat est nécessaire pour Chorus Pro : un certificat d'authentification serveur de type client de figure conforme RGS* a minima. Pour cela, une liste de prestataires est fournie depuis la documentation de "Chorus Pro" (attention de bien prendre l'offre permettant une figure conforme RGS* a minima) : https://www.lsti-certification.fr/images/Trusted-List-RGS-eIDAS_LSTI_V6.4.pdfCette liste exhaustive peut sembler complexe. Durant nos essais, nous avons pu trouver des informations sur les sites de "TBS-Internet" et "Certigna". Le prix d'un certificat est d'environ 300 € HT par an. Le certificat obtenu devra être fourni au portail Chorus, au format pkcs7, avec toute la chaîne de certification. À partir de ce moment, les appels d'API seront "authentifiés". Note : certaines documentations de "Chorus Pro" indiquent qu'il est possible d'obtenir un certificat de test pour le portail de qualification. Nous n'avons à ce jour pas vu de fournisseur le permettant sans un contact direct avec leurs services. Il est, par contre, possible d'utiliser le même certificat pour l'environnement de test et l'environnement de qualification. Programmation des API REST de Chorus Pro en WLangage Présentation Les API de "Chorus Pro" sont des API REST manipulant des paramètres JSON, il suffit donc d'utiliser les variables de type JSON, restRequête et restRéponse du WLangage. // Construction des paramètres
ParametreEntree est un JSON
cRequete.Contenu = ParametreEntree
...
// Exécution de l'appel REST
cReponse = RESTEnvoie(cRequete) Attention : Si vous utilisez un proxy, pensez à configurer l'accès au proxy dans votre code grâce à la fonction Proxy. Remarque : Vous trouverez dans la LST 115 un exemple d'utilisation des API pour envoyer des factures PDF sur le portail Chorus Pro. Construction de l'entête Toutes les requêtes REST de l'API "Chorus Pro" contiennent des données d'identification permettant de fournir : - Les identifiants (login et mot de passe) du compte technique.
// Utilisateur technique
cRequete.Utilisateur = GetNomUtilisateurTechnique()
cRequete.MotDePasse = GetMDPUtilisateurTechnique() - Le certificat (format .p12) et son mot de passe.
// Signature par certificat
cRequete.CertificatClient = GetCertificat()
cRequete.MotDePasseCertificatClient = GetMDPCertificat()
Note : A partir de la version 24, il est possible d'utiliser un certificat stocké dans la bibliothèque de l'application (donc d'éviter sa diffusion). Il suffit d'indiquer son nom sous la forme d'une chaîne. Le certificat de l'autorité de confiance certifiant "Chorus Pro" ne semble pas reconnu par tous les postes Windows, il a donc été explicitement autorisé par la fonction CertificatDeConfianceAjoute. Manipulation des paramètres ou des résultats Les API REST de "Chorus Pro" manipulent et renvoient des données au format JSON. Le format des données JSON est indiqué dans le bas de la page associée à l'API. Chaque fichier contient un exemple de contenu JSON, par exemple :
{
“idUtilisateurCourant” : 331,
“fichierFacture” : “JVB...G”,
“formatDepot” : “PDF_NON_SIGNE”,
“nomFichier” : “facture_capgemini.pdf”
} WINDEV 24 permet non seulement de manipuler les données JSON grâce au type de variable JSON mais également d'en importer la description à l'aide d'un JSON existant. Il suffit pour cela d'utiliser l'option "Importer un XML ou un JSON dans ce projet" du menu contextuel de l'élément "Descriptions externes" de l'explorateur de projet.
// Construction des paramètres
ParametreEntree est un JSON, description="DeposerPDFFacture_M8_V0_input"
ParametreEntree.nomFichier = fExtraitChemin(sFichierFacture, fFichier + fExtension) Exécution de la requête REST Lorsque les paramètres et l'entête sont renseignés, il suffit d'exécuter la requête REST construite et de gérer le code de retour (qui est alors un code HTTP classique). // Envoie la requête
cReponse est un restRéponse
cReponse = RESTEnvoie(cRequete) Callback pour la mise au point Il est possible de visualiser les trames envoyées lors de l'appel à la fonction RESTEnvoie grâce à la propriété ProcédureTrace de la variable de type httpRequête. cRequete..ProcédureTrace = CBDebug Parcours de résultats JSON Les données renvoyées par les API "Chorus Pro" contiennent souvent des tableaux de données dont le type "unitaire" n'est pas décrit. Il est cependant possible en WLangage d'utiliser une sous-partie d'une description JSON comme description :
EngagementJSON est un JSON
<description="RechercherEngagementJuridique_M8_V0_OutPut.listeEngagementJuridique"> Encodage PDF Pour fournir un fichier PDF à "Chorus Pro", il est nécessaire de l'encoder en base64 (à l'aide de la fonction Encode du WLangage). À ce jour, "Chorus Pro" ne semble pas correctement interpréter les données encodées contenant des RC. Il est nécessaire de les supprimer par exemple avec le code suivant : ParametreEntree.fichierFacture = Remplace(Encode(fChargeBuffer(sFichierFacture), ...
encodeBASE64),RC,"")
Liste des exemples associés :
|
Exemples didactiques (WINDEV) : WD Accès Chorus Pro
[ + ] Cet exemple montre comment accéder à l'API Chorus Pro.
|
Documentation également disponible pour…
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|