Guide de démarrage
Bienvenue dans la documentation de l'API Chorus Pro. Ce guide complet vous aidera à configurer vos accès, comprendre l'authentification et effectuer votre première requête.
Sommaire
URLs de base
L'API Chorus Pro est disponible sur les environnements suivants :
Production
https://api.piste.gouv.fr/cprohttps://oauth.piste.gouv.frEnvironnement de production pour les requêtes réelles avec données réelles.
Sandbox
https://sandbox-api.piste.gouv.fr/cprohttps://sandbox-oauth.piste.gouv.frEnvironnement sandbox pour le développement et les tests.
1Créer un compte PISTE
PISTE est la plateforme d'accès aux API gouvernementales. C'est ici que vous obtiendrez vos identifiants OAuth.
- Rendez-vous sur le formulaire de création de compte PISTE
- Cliquez sur le lien de confirmation reçu par email
- Connectez-vous à votre espace PISTE
💡 Conseil: Créez un document pour noter tous vos identifiants (Client ID, Secret Key, compte technique, etc.). Vous en aurez besoin tout au long de la configuration.
2Consentements aux CGU des API
- Rendez-vous dans l'onglet "API", sous-onglet "Consentement CGU API"
- Affichez 100 lignes à la fois pour plus de lisibilité
- Cochez les cases pour les API suivantes :
⚠️ Attention: Chaque API y est 2 fois (Sandbox et Production). Cochez les deux !
3Activer les applications
Pour la Sandbox :
- Rendez-vous dans l'onglet "Mes Applications"
- Une application APP_SANDBOX_votre@email.com existe déjà, cliquez dessus
- Cliquez sur "Modifier l'application"
- Dans "Sélectionner les API", cochez les 4 API (Factures, Structures, Utilisateurs, Transverses)
- Cliquez sur "Appliquer les modifications"
Pour la Production :
- Cliquez sur "Créer une application"
- Remplissez les informations et sauvegardez
- Modifiez l'application et sélectionnez les mêmes 4 API
🔑 Récupérer vos identifiants OAuth
Dans l'onglet "Authentification" de votre application, vous trouverez :
Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxSecret Key: Cliquez sur "Consulter le client secret"
4Créer un compte technique Chorus Pro
Le compte technique est différent du compte PISTE. Il permet d'authentifier les requêtes API avec l'en-tête cpro-account.
Étapes de création :
- Connectez-vous au portail Chorus Pro (ou au portail de qualification pour la Sandbox)
- Allez dans "Mon compte" > "Gérer les comptes techniques"
- Cliquez sur "Créer un compte technique"
- Notez l'identifiant généré (format : TECH_1_xxxxxx@cpro.fr)
- Définissez un mot de passe sécurisé
Format de l'en-tête cpro-account :
# Encoder en base64 : identifiant:motdepasse
echo -n "TECH_1_xxxxxx@cpro.fr:votre_mot_de_passe" | base64
# Résultat (exemple)
VEVDSF8xX3h4eHh4eHhAY3Byby5mcjp2b3RyZV9tb3RfZGVfcGFzc2U=📖 Tutoriel détaillé: Créer un compte technique (documentation officielle)
5Authentification
⚠️ Double authentification obligatoire: Chaque requête API nécessite DEUX authentifications simultanées.
1. OAuth 2.0 (Bearer Token)
Token obtenu via la méthode client_credentials avec vos identifiants PISTE. Expire après 1 heure.
Authorization: Bearer YOUR_OAUTH_TOKEN2. En-tête cpro-account
Identifiants du compte technique Chorus Pro encodés en base64 sous la forme 'identifiant:motdepasse'.
cpro-account: base64(TECH_1_xxxxx@cpro.fr:password)Obtenir un token OAuth 2.0
curl -X POST "https://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"Réponse :
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
"token_type": "Bearer",
"expires_in": 3600
}6Votre première requête
Testez votre configuration avec le health-check ou en récupérant vos structures rattachées :
curl -X POST "https://api.piste.gouv.fr/cpro/utilisateurs/v1/monCompte/recuperer/rattachements" \
-H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
-H "cpro-account: YOUR_BASE64_CREDENTIALS" \
-H "Content-Type: application/json" \
-d '{
"parametresRecherche": {
"nbResultatsParPage": 100,
"pageResultatDemandee": 1
}
}'Réponse attendue :
{
"codeRetour": 0,
"libelle": "TRA_MSG_00.000",
"listeStructureRattachement": [
{
"idStructure": 12345678,
"identifiantStructure": "88200000000000",
"typeIdentifiantStructure": "SIRET",
"designationStructure": "Ma Structure",
"statutUtilisateur": "ACTIF"
}
]
}✅ Succès: Si vous obtenez "codeRetour": 0, votre configuration est correcte !
💡 Note: Si vous venez de créer le compte technique, il peut falloir attendre jusqu'à 1 heure avant que les requêtes fonctionnent.
7Flux de dépôt de facture
Voici les étapes typiques pour déposer une facture sur Chorus Pro via l'API :
Notes importantes
📋 Méthode POST pour tout
L'API Chorus Pro utilise la méthode POST pour presque toutes les opérations, même pour la récupération de données. Les badges verts indiquent les opérations de lecture, les bleus les créations.
🔐 Tokens qui expirent
Le token OAuth expire après 1 heure. Prévoyez un système de rafraîchissement automatique dans votre intégration.
⚡ Format des réponses
Les réponses incluent un champ 'codeRetour' (0 = succès) et 'libelle' avec le message. Vérifiez toujours ces champs même avec un HTTP 200.
Ressources et support
- 🌐Documentation officielle : portail.chorus-pro.gouv.fr/aife_documentation/
- 🔑Obtenir des accès API : data.gouv.fr/dataservices/api-chorus-pro/
- 📖Guide complet avec tutoriel vidéo : blog.choruspay.fr
- ✅Créer un compte technique : Tutoriel officiel
- 📄Documentation officielle PDF (AIFE) : Télécharger le PDF
⚠️ Constaté sur le terrain
- Comportement de la passerelle mesuré en production sur un mois (≈1,2 M d'appels, 08/2026) : la passerelle PISTE renvoie sporadiquement un faux HTTP 401 à corps vide en moins d'une seconde (≈0,1 % des appels, jusqu'à 3 % sur consulter/fournisseur aux heures ouvrées) alors que les identifiants sont valides. Un login ou mot de passe réellement faux renvoie AUSSI un 401 à corps vide (vérifié le 09/09/2026) : un 401 isolé ne permet pas de distinguer les deux cas. Réessayez une fois après 1 à 2 s, puis jugez sur la durée (plusieurs échecs étalés sur 30 min ou plus sans aucun succès entre), jamais sur quelques 401 consécutifs pendant une rafale.
- Tout appel dépassant ~30 s est coupé par la passerelle en HTTP 504 (corps vide) alors que le back-end peut aller au bout : un 504 est une issue INCONNUE, pas un échec (critique pour soumettre, voir « Soumettre une facture PDF »).
- Les pannes se manifestent par des pages HTML HTTP 503 sur tous les endpoints, y compris /api/oauth/token. Pendant une panne complète (constatée le 03/10/2026 à partir de 07:30 UTC, production et bac à sable, plusieurs heures) un même compte reçoit un mélange de timeouts à 60 s, de HTTP 503 et de HTTP 401 à corps vide : un 401 reçu pendant que d'autres appels partent en timeout ou en 5xx ne dit rien des identifiants techniques, ne pas le traiter comme un refus.
Guide de démarrage
Bienvenue dans la documentation de l'API Chorus Pro. Ce guide complet vous aidera à configurer vos accès, comprendre l'authentification et effectuer votre première requête.
Sommaire
URLs de base
L'API Chorus Pro est disponible sur les environnements suivants :
Production
https://api.piste.gouv.fr/cprohttps://oauth.piste.gouv.frEnvironnement de production pour les requêtes réelles avec données réelles.
Sandbox
https://sandbox-api.piste.gouv.fr/cprohttps://sandbox-oauth.piste.gouv.frEnvironnement sandbox pour le développement et les tests.
1Créer un compte PISTE
PISTE est la plateforme d'accès aux API gouvernementales. C'est ici que vous obtiendrez vos identifiants OAuth.
- Rendez-vous sur le formulaire de création de compte PISTE
- Cliquez sur le lien de confirmation reçu par email
- Connectez-vous à votre espace PISTE
💡 Conseil: Créez un document pour noter tous vos identifiants (Client ID, Secret Key, compte technique, etc.). Vous en aurez besoin tout au long de la configuration.
2Consentements aux CGU des API
- Rendez-vous dans l'onglet "API", sous-onglet "Consentement CGU API"
- Affichez 100 lignes à la fois pour plus de lisibilité
- Cochez les cases pour les API suivantes :
⚠️ Attention: Chaque API y est 2 fois (Sandbox et Production). Cochez les deux !
3Activer les applications
Pour la Sandbox :
- Rendez-vous dans l'onglet "Mes Applications"
- Une application APP_SANDBOX_votre@email.com existe déjà, cliquez dessus
- Cliquez sur "Modifier l'application"
- Dans "Sélectionner les API", cochez les 4 API (Factures, Structures, Utilisateurs, Transverses)
- Cliquez sur "Appliquer les modifications"
Pour la Production :
- Cliquez sur "Créer une application"
- Remplissez les informations et sauvegardez
- Modifiez l'application et sélectionnez les mêmes 4 API
🔑 Récupérer vos identifiants OAuth
Dans l'onglet "Authentification" de votre application, vous trouverez :
Client ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxSecret Key: Cliquez sur "Consulter le client secret"
4Créer un compte technique Chorus Pro
Le compte technique est différent du compte PISTE. Il permet d'authentifier les requêtes API avec l'en-tête cpro-account.
Étapes de création :
- Connectez-vous au portail Chorus Pro (ou au portail de qualification pour la Sandbox)
- Allez dans "Mon compte" > "Gérer les comptes techniques"
- Cliquez sur "Créer un compte technique"
- Notez l'identifiant généré (format : TECH_1_xxxxxx@cpro.fr)
- Définissez un mot de passe sécurisé
Format de l'en-tête cpro-account :
# Encoder en base64 : identifiant:motdepasse
echo -n "TECH_1_xxxxxx@cpro.fr:votre_mot_de_passe" | base64
# Résultat (exemple)
VEVDSF8xX3h4eHh4eHhAY3Byby5mcjp2b3RyZV9tb3RfZGVfcGFzc2U=📖 Tutoriel détaillé: Créer un compte technique (documentation officielle)
5Authentification
⚠️ Double authentification obligatoire: Chaque requête API nécessite DEUX authentifications simultanées.
1. OAuth 2.0 (Bearer Token)
Token obtenu via la méthode client_credentials avec vos identifiants PISTE. Expire après 1 heure.
Authorization: Bearer YOUR_OAUTH_TOKEN2. En-tête cpro-account
Identifiants du compte technique Chorus Pro encodés en base64 sous la forme 'identifiant:motdepasse'.
cpro-account: base64(TECH_1_xxxxx@cpro.fr:password)Obtenir un token OAuth 2.0
curl -X POST "https://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"Réponse :
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
"token_type": "Bearer",
"expires_in": 3600
}6Votre première requête
Testez votre configuration avec le health-check ou en récupérant vos structures rattachées :
curl -X POST "https://api.piste.gouv.fr/cpro/utilisateurs/v1/monCompte/recuperer/rattachements" \
-H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
-H "cpro-account: YOUR_BASE64_CREDENTIALS" \
-H "Content-Type: application/json" \
-d '{
"parametresRecherche": {
"nbResultatsParPage": 100,
"pageResultatDemandee": 1
}
}'Réponse attendue :
{
"codeRetour": 0,
"libelle": "TRA_MSG_00.000",
"listeStructureRattachement": [
{
"idStructure": 12345678,
"identifiantStructure": "88200000000000",
"typeIdentifiantStructure": "SIRET",
"designationStructure": "Ma Structure",
"statutUtilisateur": "ACTIF"
}
]
}✅ Succès: Si vous obtenez "codeRetour": 0, votre configuration est correcte !
💡 Note: Si vous venez de créer le compte technique, il peut falloir attendre jusqu'à 1 heure avant que les requêtes fonctionnent.
7Flux de dépôt de facture
Voici les étapes typiques pour déposer une facture sur Chorus Pro via l'API :
Notes importantes
📋 Méthode POST pour tout
L'API Chorus Pro utilise la méthode POST pour presque toutes les opérations, même pour la récupération de données. Les badges verts indiquent les opérations de lecture, les bleus les créations.
🔐 Tokens qui expirent
Le token OAuth expire après 1 heure. Prévoyez un système de rafraîchissement automatique dans votre intégration.
⚡ Format des réponses
Les réponses incluent un champ 'codeRetour' (0 = succès) et 'libelle' avec le message. Vérifiez toujours ces champs même avec un HTTP 200.
Ressources et support
- 🌐Documentation officielle : portail.chorus-pro.gouv.fr/aife_documentation/
- 🔑Obtenir des accès API : data.gouv.fr/dataservices/api-chorus-pro/
- 📖Guide complet avec tutoriel vidéo : blog.choruspay.fr
- ✅Créer un compte technique : Tutoriel officiel
- 📄Documentation officielle PDF (AIFE) : Télécharger le PDF
⚠️ Constaté sur le terrain
- Comportement de la passerelle mesuré en production sur un mois (≈1,2 M d'appels, 08/2026) : la passerelle PISTE renvoie sporadiquement un faux HTTP 401 à corps vide en moins d'une seconde (≈0,1 % des appels, jusqu'à 3 % sur consulter/fournisseur aux heures ouvrées) alors que les identifiants sont valides. Un login ou mot de passe réellement faux renvoie AUSSI un 401 à corps vide (vérifié le 09/09/2026) : un 401 isolé ne permet pas de distinguer les deux cas. Réessayez une fois après 1 à 2 s, puis jugez sur la durée (plusieurs échecs étalés sur 30 min ou plus sans aucun succès entre), jamais sur quelques 401 consécutifs pendant une rafale.
- Tout appel dépassant ~30 s est coupé par la passerelle en HTTP 504 (corps vide) alors que le back-end peut aller au bout : un 504 est une issue INCONNUE, pas un échec (critique pour soumettre, voir « Soumettre une facture PDF »).
- Les pannes se manifestent par des pages HTML HTTP 503 sur tous les endpoints, y compris /api/oauth/token. Pendant une panne complète (constatée le 03/10/2026 à partir de 07:30 UTC, production et bac à sable, plusieurs heures) un même compte reçoit un mélange de timeouts à 60 s, de HTTP 503 et de HTTP 401 à corps vide : un 401 reçu pendant que d'autres appels partent en timeout ou en 5xx ne dit rien des identifiants techniques, ne pas le traiter comme un refus.