Comment Utiliser l'API Chorus Pro : Guide Complet 2026 (Authentification + Dépôt de Facture)

Utiliser l’API afin d’automatiser Chorus Pro est un vrai jeu de PISTE sans parler du fait que cette dernière a une conception un peu particulière et surtout une documentation tantôt illisible, tantôt introuvable et même absente dans certains cas.

Vous allez découvrir aujourd’hui une véritable cinématique de tout ce qu’il vous faut pour déposer une facture sur Chorus Pro automatiquement par API, avec en fin d’article les pièges que nous avons rencontrés en production.

Vous pouvez prendre ce tutoriel comme une documentation de l’API de Chorus Pro car j’y ai mis beaucoup d’efforts et fais de mon mieux afin qu’il soit (beaucoup) plus clair que ce que vous trouverez sur le site de l’AIFE (Agence pour l'Informatique Financière de l'État).

Document ou note

Avant toute chose, je vous recommande fortement de créer un document ou une note pour y conserver toutes les informations (identifiants, mots de passes etc.) que vous obtiendrez durant le tutoriel, surtout quand je dis qu’il faut les conserver précieusement.

Voici un exemple de ce que vous pourriez obtenir (j’imagine que vous comprenez pourquoi c’est essentiel de tout noter correctement) :

# Configuration Chorus Pro
## Compte PISTE

Email : xxxxxxx@example.com
Mote de passe : xxxxxxxxxxxxxx

## PROD

#### OAUTH (PISTE)
CLIENT ID : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SECRET KEY : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

#### Compte Technique
identifiant : TECH_1_xxxxxxxxxxxxxx@cpro.fr 
mot de passe : xxxxxxxxxxxx
technical_id : xxxxxxxx

#### Infos
Structure (SIRET) : 882xxxxxxxxxxx
Bank Code : xxxxxx
Resultat : TECH_1_xxxxxxxxxxxxx@cpro.fr:xxxxxxxxxxxx
Base 64 : VEVDSF8xX3h4eHh4eHh4eHh4eHhAY3Byby5mcjp4eHh4eHh4eHh4eHg=

## SANDBOX

#### OAUTH (PISTE)
CLIENT ID : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SECRET KEY : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

#### Compte principal (créé manuellement avec votre email) -> pour créer le matelas de données

Email : xxxxxxx@gmail.com
Mot de passe : xxxxxxxxxxxxxx

#### Compte `GEST_PRIVE_SIRET`…

Adresse de connexion_1 : GEST_PRIVE_SIRET_1_xxxxxxxxxxxxxx@cpro.fr
Mot de passe_1 : xxxxxxxxxxxx

#### Compte Technique
Identifiant : TECH_1_xxxxxxxxxxxxxx@cpro.fr 
Mot de passe : xxxxxxxxxxxx
Technical_id : xxxxxxxx

#### Infos
Structure (SIRET) : 882xxxxxxxxxxx
Bank Code : xxxxxx
Resultat : TECH_1_xxxxxxxxxxxxx@cpro.fr:xxxxxxxxxxxx
Base 64 : VEVDSF8xX3h4eHh4eHh4eHh4eHhAY3Byby5mcjp4eHh4eHh4eHh4eHg=

Vous pouvez d’ailleurs copier le fichier ci-dessus dans un éditeur Markdown pour l’utiliser comme modèle afin de mieux suivre le tutoriel.

Prérequis

Pour suivre ce tutoriel, vous aurez besoin de bien comprendre le concept d’API et de connaître ou maîtriser un peu POSTMAN ainsi que le codage informatique ou un logiciel d’automatisation.

Si vous partez de zéro, j’ai réalisé une vidéo qui devrais vous aider que vous pouvez consulter en cliquant ici.

Accéder à l’API de Chorus Pro

Dans un premier temps, nous allons voir comment mettre en place une connexion à Chorus Pro et pour cela, il nous faut un accès API qui nécessite la création d’un compte sur PISTE, le consentement au conditions générales d’utilisation des différentes API, l’activation pour chaque application de chaque environnement et la récupération des moyens d’authentification.

Créer votre compte sur Piste

  1. Rendez vous sur ce formulaire de création de compte
  2. Cliquez sur le lien de confirmation reçu par email

Connectez-vous à votre espace PISTE

Consentements aux CGU des applications PISTE

  1. Rendez vous dans l’onglet « API », sous onglet «  Consentement CGU API »
  2. Je vous recommande d’afficher 100 lignes à la fois, en séléctionnant « 100 » dans « Afficher les lignes » en bas à droite du tableau
    • Factures
    • Structures
    • Utilisateurs
    • Transverses
  3. Cliquez ensuite sur le bouton orange en haut « Valider mes choix CGU ».

Maintenant je vous recommande de cocher les cases dans le tableau pour les API suivantes :

⚠️
Attention ! Chaque API y est 2 fois (une fois pour le mode Sandbox et une fois pour la Production), cochez donc les deux.

Activer la Sandbox (PISTE)

  1. Rendez-vous dans l’onglet « Mes Applications »
  2. Une application APP_SANDBOX_votre@email.com doit déjà exister, vous pouvez cliquer dessus.
  3. Cliquez en haut à droite sur « Modifier l’application »
  4. Dans «  Sélectionner les API » tout en bas cochez à nouveau les API suivantes :
    • Factures
    • Structures
    • Utilisateurs
    • Transverses
  5. Cliquez ensuite sur « Appliquer les modifications »
  6. Dans l’onglet « Authentification » en haut vous allez pouvoir récupérer vos « Identifiants Oauth » !
  7. Copier le « Client ID » qui doit ressembler à quelque-chose comme ça : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  8. Gardez-le bien précieusement en sécurité, vous en aurez besoin ensuite.
  9. Faites de même pour le « Secret Key » et cliquant sur « Consulter le client secret », copiez le en cliquant sur « Copy » et gardez-le également précieusement en sécurité. Il doit ressembler également à quelque-chose comme ça : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Félicitations, vous avez vos accès !

Activer la Production (PISTE)

Pour la production, les étapes sont sensiblement les mêmes que pour la recette (SandBox) sauf qu’il faut créer une nouvelle application au préalable.

  1. Rendez-vous dans l’onglet « Mes Applications »
  2. Cliquez sur « Créer une application » ou rendez-vous directement ici.
  3. Vous pouvez à présent remplir les Champs avec vos informations puis cliquer sur « Sauvegarder l’application ».
  4. Une fois sur la fiche de la nouvelle application créée vous devriez pouvoir de la même manière « Modifier l’application ».
  5. C’est à nouveau en bas dans «  Sélectionner les API » que vous pourrez cocher les suivantes :
    • Factures
    • Structures
    • Utilisateurs
    • Transverses
  6. Cliquez pour « Appliquer les modifications », puis rendez-vous à nouveau dans l’onglet « Authentification » pour récupérer les client id et secrets.
  7. À nouveau, conservez ces informations bien précieusement.

Créer votre compte Chorus Pro sur le portail de qualification

Nous allons maintenant créer un premier compte sur le portail de qualification Chorus Pro, celui-ci nous permettra d’accéder à la génération d’un « Matelas de données », une base de donnée fictive nous permettant de tester les choses sans envoyer de vraies factures.

  1. Connectez vous sur le « Portail de Qualification » et cliquez en haut à droite pour créer un compte.
  2. Remplissez les formulaire, puis cliquez sur « Créer mon compte »
  3. Vous devriez recevoir un lien de confirmation pour créer votre mot de passe, toutefois, si ce n’était pas le cas (et j’ai eu le problème), il suffit d’aller sur le formulaire de connexion, de faire « Mot de passe oublié ? » et mettre son email puis « Valider » pour finalement recevoir le lien de confirmation.
  4. Vous avez à présent accès à votre compte de qualification.

Générer un matelas de données (qualification)

  1. Connectez-vous à votre espace sur le « Portail de Qualification » .
  2. Cliquez pour « Accéder au domaine » du « Matelas de données ».
  3. Accédez à l’espace, puis cliquez sur « Soumettre ».
  4. La génération peux prendre quelques minutes…

Récupérez un compte utilisateur de test

Patientez et actualisez régulièrement la page jusqu’à ce que la génération du matelas soit terminée.

  1. Un bouton marron devrait alors apparaître : «  Générer et télécharger le fichier CSV du matelas structures et utilisateurs » , cliquez dessus.
  2. Un fichier CSV est alors téléchargé, vous pouvez l’ouvrir dans une feuille de calcul (Excel, Libre Office, Open Office…)
  3. Cherchez dans le document un compte dont l’adresse de connexion commence par GEST_PRIVE_SIRET et récupérez donc l’adresse de connexion et le mot de passe indiqué juste après (colonnes G et H pour moi sur Excel).
  4. Je vous conseille de vous connecter sur le portail de qualification avec ces accès et d’enregistrer les codes dans votre navigateur.

Vous disposez maintenant d’un compte fournisseur ressemblant trait pour trait à celui que vous avez en production.

Créer un compte technique

ℹ️
Cette étape est la première que vous pouvez à la fois réaliser sur votre compte de recette et sur votre vraie compte Chorus Pro en tant que fournisseur.

Pour utiliser l’API Chorus Pro, vous avez besoin d’un identifiant et d’un mot de passe, pour les obtenir, il est nécessaire de créer un compte technique.

Voici les étapes à suivre :

  1. Connectez-vous sur le compte fournisseur dont vous venez de récupérer l’accès (qui commence par GEST_PRIVE_SIRET)
  2. Accédez au domaine « Raccordements » (EDI et API)
  3. Accèdez à « Compte technique » (la dernière tuile)
  4. Sélectionnez le type de demande « Création d’un compte technique », puis choississez la seule structure disponible.
  5. Conservez bien le login, l’email et le mot de passe que vous obtenez, puis cliquez sur « Soumettre ».

Déclarer les raccordements

Si vous ne déclarez pas le raccordement, les API ne fonctionneront pas, cette étape est donc essentielle !

SandBox

  1. Retournez la page d’accueil du portail de qualification.
  2. Accédez au domaine « Raccordements » puis à nouveau « Raccordements ».
  3. Cliquez dans le nouvel onglet qui s’est ouvert sur « Créer un raccordement ».
  4. Sélectionnez un raccordement API.
  5. Sélectionnez votre structure puis indiquez le nom de l’application de production (première colonne du tableau dans PISTE). -> Ex: APP_SANDBOX_votre@email.com
  6. Le type d’utilisation en fonction de si vous êtes éditeur ou si c’est une application interne.
  7. Entrez les informations du contact technique (probablement les votres si vous lisez cet article).
  8. Cliquez sur « Finaliser » si tout est bon.

Production

Pareil que pour la SandBox, il faudra le faire en prod.

  1. Connectez-vous à votre espace sur le portail Chorus Pro(officiel maintenant, plus la SandBox).
  2. Accédez au domaine « Raccordements » puis à nouveau « Raccordements ».
  3. Cliquez dans le nouvel onglet qui s’est ouvert sur « Créer un raccordement ».
  4. Sélectionnez un raccordement API.
  5. Sélectionnez votre structure puis indiquez le nom de l’application de production (première colonne du tableau dans PISTE).
  6. Le type d’utilisation en fonction de si vous êtes éditeur ou si c’est une application interne.
  7. Entrez les informations du contact technique (probablement les votres si vous lisez cet article).
  8. Cliquez sur « Finaliser » si tout est bon.

Votre première requête API !!

Nous allons faire une première requête sur l’API en SandBox pour que vous compreniez bien le fonctionnement, on va récupérer la liste des structures rattachées à l’utilisateur technique que l’on a créé.

Pour cela, je vous recommande d’installer le logiciel POSTMAN que nous allons utiliser pour réalise nos premières requêtes. Voici le lien : https://www.postman.com/downloads/ .

Je vous recommandé également d’ouvrir ces pages de documentations (qui vont probablement vous aider) :

OAuth

J’ai menti, nous n’allons non pas faire une mais 2 requêtes à l’API puisqu’une requête est nécessaire au préalable pour s’authentifier sur l’API et une seconde pour obtenir le résultat que l’on recherche.

  1. Ouvrez POSTMAN
  2. Créez une nouvelle collection, par exemple : « Chorus Pro Tests »
  3. Créez une requête HTTP dans la collection que vous pouvez appeler « Oauth » par exemple
  4. Dans l’onglet « Body », il faut remplacer YOUR_CLIENT_ID et YOUR_CLIENT_SECRET par ceux que vous avez obtenu sur PISTE pour la SandBox.
  5. Cliquez ensuite sur le bouton bleu « Send » pour envoyer la requête.

Copiez et collez le code suivant dans l’URL de la requête.

curl -X POST "https://sandbox-oauth.piste.gouv.fr/api/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=openid resource.READ"

Dans le cadre « Body » du résultat de la requête en bas de l’écran, vous devriez obtenir un résultat qui ressemble à cela:

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "openid resource.READ"
}

Comme on peut le voir, on obtient un « Access Token » de type « Bearer » qui est valide pour 1h.

Nous devrons donc chaque heure effectuer à nouveau cette opération pour à nouveau accéder à l’API.

Mes structures (Requête API Chorus Pro)

Ça y est, nous allons faire la vraie requête, notre première sur l’API de Chorus Pro. Plutôt que de vous donner simplement un « copier / coller » , pour celle-ci, j’aimerais vous expliquer plus en détail ce que l’on va faire puisque ça n’est pas si simple.

La première étape est d’encoder l’identifiant et le mot de passe du compte technique dans un format « Base 64 ».

Le plus simple pour cela est d’utiliser un outil comme celui-ci : Encodeur / Décodeur Base64 – Outil en ligne

Il faudra entrer quelque-chose qui ressemble à ça :

  • [login_utilisateur_technique]:[mot_de_passe]
  • ou
  • TECH_1_xxxxxxxxxxxxx@cpro.fr:xxxxxxxxxxxx dans le convertisseur.Et vous obtiendrez quelques chose qui ressemble à cela : VEVDSF8xX3h4eHh4eHh4eHh4eHhAY3Byby5mcjp4eHh4eHh4eHh4eHg= .

On va maintenant construire notre première requête dans POSTMAN.

  1. Pour cela, créez une nouvelle requête dans la collection que vous pourrez appeler « Mes structures » par exemple.
  2. Sélectionnez la méthode POST (et oui, même pour récupérer une liste tout se fait avec un POST dans l’API Chorus Pro… sauf le healthcheck, allez savoir pouquoi… peut-être parce qu’il n’a pas de pagination et donc pas de body…)
  3. Dans le champ de l’URL, vous pouvez indiquer la suivante : https://sandbox-api.piste.gouv.fr/cpro/utilisateurs/v1/monCompte/recuperer/rattachements
  4. C’est dans l’onglet « Headers » que ça se corse :
    1. Il faut mettre un header avec la clé Authorization et la valeur Bearer VOTRE_ACCESS_TOKEN (celui que vous avez récupérer lors de la première requête s’il n’a pas expiré, sinon vous devrez relancer la requête pour en obtenir un nouveau).
    2. Ensuite, un header avec la clé cpro-account qui contient ce que vous avez encodé précédemment en Base 64.

C’est bon, vous pouvez envoyer le requête !

Vous devriez obtenir quelque-chose qui ressemble à cela :

{
    "codeRetour": 0,
    "libelle": "TRA_MSG_00.000",
    "parametresRetour": {
        "pageCourante": 1,
        "pages": 1,
        "nbResultatsParPage": 100,
        "total": 1
    },
    "listeStructureRattachement": [
        {
            "idStructure": 00000000,
            "identifiantStructure": "xxxxxxxxxxxxxx",
            "typeIdentifiantStructure": "SIRET",
            "designationStructure": "SIRET_xxxxxxxxxxxxxx",
            "statutUtilisateur": "ACTIF",
            "roleUtilisateur": "GESTIONNAIRE_PRINCIPAL",
            "statutRattachementStructure": "VALIDEE",
            "idRattachementStructure": 10101010
        }
    ]
}
💡
Si cela fait peu de temps que vous avez créé le compte technique, il se peut qu’il soit nécessaire d’attendre un peu avant que cette requête fonctionne ainsi (1 heure maximum).

Flux automatisé de dépôt d’une facture

Afin de déposer une facture sur Chorus Pro via l’API, plusieurs étapes sont nécessaires.

Les pièges que la documentation ne dit pas

Quelques comportements de l'API appris en production, à nos dépens :

  • Les codes service peuvent finir par un espace dans le référentiel Chorus Pro. Envoyez le code exact, sans le nettoyer : un code « trimé » est refusé avec GFT_MSG_01.033, un message qui laisse croire que le service n'appartient pas à la structure.
  • La liste des services d'une structure est paginée. Un grand établissement peut en avoir des milliers (2 458 pour le CNRS, sur trois pages) : si vous ne lisez que la première page, le bon service n'apparaît jamais. Voir la requête.
  • L'obligation de numéro d'engagement se lit service par service (consulter, champ numeroEngagement) : quand un service est renseigné, sa règle prime sur celle de la structure.
  • La recherche de structures ne renvoie jamais typeStructure : c'est un critère d'entrée (PUBLIQUE ou PRIVEE), pas une donnée de sortie. Voir la requête.
  • Arrondissez tous les montants au centime avant l'envoi : Chorus Pro affiche jusqu'à quatre décimales, et un résidu de calcul (99,9997) se voit sur la facture.
  • Le jeton OAuth expire au bout d'une heure : renouvelez-le avant chaque série d'appels plutôt qu'à l'erreur.

Qui écrit ce guide

Ce guide est écrit par Chorus Pay. On utilise cette API tous les jours pour déposer les factures de nos clients, c'est pour ça qu'on le tient à jour, et il doit vous suffire pour faire votre premier dépôt sans nous.

Si vous vendez vous-même au secteur public, le dépôt n'est qu'une étape. Avant, il y a le devis, le bon de commande à réclamer, le numéro d'engagement qui manque ; après, le suivi jusqu'au paiement. Chorus Pay s'occupe de ce parcours depuis votre boutique en ligne (PrestaShop, Shopify, WooCommerce) ou votre outil de gestion (Pennylane, Dolibarr), et votre boutique est mise en avant sur mandat-administratif.fr.

Si vous développez pour d'autres, l'API Chorus Pay crée une commande en un appel et vous prévient par webhook à chaque étape : vous n'avez plus d'intégration Chorus Pro à maintenir. Vous êtes intégrateur ? On rémunère les recommandations, conditions à voir ensemble.

Dans tous les cas, l'argent ne passe pas par nous et les factures restent sur Chorus Pro : si vous arrêtez Chorus Pay, vous repartez de ce tutoriel.

1 crédit = 1 facture déposée, sans abonnement (tarifs). Réserver un appel ou écrire à support@choruspay.fr.