DOCS

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

  1. 1. Créer un compte PISTE
  2. 2. Consentements CGU
  3. 3. Activer les applications
  4. 4. Créer un compte technique
  5. 5. Authentification
  6. 6. Première requête
  7. 7. Flux de dépôt de facture

URLs de base

L'API Chorus Pro est disponible sur les environnements suivants :

Production

API:https://api.piste.gouv.fr/cpro
OAuth:https://oauth.piste.gouv.fr

Environnement de production pour les requêtes réelles avec données réelles.

Sandbox

API:https://sandbox-api.piste.gouv.fr/cpro
OAuth:https://sandbox-oauth.piste.gouv.fr

Environnement 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.

  1. Rendez-vous sur le formulaire de création de compte PISTE
  2. Cliquez sur le lien de confirmation reçu par email
  3. 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

  1. Rendez-vous dans l'onglet "API", sous-onglet "Consentement CGU API"
  2. Affichez 100 lignes à la fois pour plus de lisibilité
  3. Cochez les cases pour les API suivantes :
✓ Factures✓ Structures✓ Utilisateurs✓ Transverses

⚠️ Attention: Chaque API y est 2 fois (Sandbox et Production). Cochez les deux !

3Activer les applications

Pour la Sandbox :

  1. Rendez-vous dans l'onglet "Mes Applications"
  2. Une application APP_SANDBOX_votre@email.com existe déjà, cliquez dessus
  3. Cliquez sur "Modifier l'application"
  4. Dans "Sélectionner les API", cochez les 4 API (Factures, Structures, Utilisateurs, Transverses)
  5. Cliquez sur "Appliquer les modifications"

Pour la Production :

  1. Cliquez sur "Créer une application"
  2. Remplissez les informations et sauvegardez
  3. 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-xxxxxxxxxxxx
  • Secret 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 :

  1. Connectez-vous au portail Chorus Pro (ou au portail de qualification pour la Sandbox)
  2. Allez dans "Mon compte" > "Gérer les comptes techniques"
  3. Cliquez sur "Créer un compte technique"
  4. Notez l'identifiant généré (format : TECH_1_xxxxxx@cpro.fr)
  5. 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_TOKEN

2. 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 :

1Récupérer l'ID de la structure destinataire à partir de son SIRET
2Consulter la structure pour vérifier ses paramètres et qu'elle est active
3Récupérer les différents services (Code Service) si nécessaire
4Option A : Importer le PDF puis effectuer le dépôt
5Option B : Créer la facture directement via l'API (mode SAISIE_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