DOCS

Getting Started

Welcome to the Chorus Pro API documentation. This complete guide will help you configure your access, understand authentication, and make your first request.

Table of Contents

  1. 1. Create a PISTE account
  2. 2. CGU Consent
  3. 3. Activate applications
  4. 4. Create a technical account
  5. 5. Authentication
  6. 6. First request
  7. 7. Invoice submission flow

Base URLs

The Chorus Pro API is available on the following environments:

Production

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

Production environment for live requests with real data.

Sandbox

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

Sandbox environment for development and testing.

1Create a PISTE Account

PISTE is the platform for accessing government APIs. This is where you'll get your OAuth credentials.

  1. Go to the PISTE account creation form
  2. Click the confirmation link received by email
  3. Log in to your PISTE dashboard

💡 Tip: Create a document to note all your credentials (Client ID, Secret Key, technical account, etc.). You'll need them throughout the setup.

2API Terms of Service Consent

  1. Go to the "API" tab, sub-tab "CGU API Consent"
  2. Display 100 rows at a time for better readability
  3. Check the boxes for the following APIs:
✓ Factures✓ Structures✓ Utilisateurs✓ Transverses

⚠️ Warning: Each API appears twice (Sandbox and Production). Check both!

3Activate Applications

For Sandbox:

  1. Go to the "My Applications" tab
  2. An APP_SANDBOX_your@email.com application already exists, click on it
  3. Click "Edit application"
  4. In "Select APIs", check the 4 APIs (Factures, Structures, Utilisateurs, Transverses)
  5. Click "Apply changes"

For Production:

  1. Click "Create an application"
  2. Fill in the information and save
  3. Edit the application and select the same 4 APIs

🔑 Get your OAuth credentials

In the "Authentication" tab of your application, you'll find:

  • Client ID : xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • Secret Key : Click "View client secret"

4Create a Chorus Pro Technical Account

The technical account is different from the PISTE account. It's used to authenticate API requests with the cpro-account header.

Creation steps:

  1. Log in to the Chorus Pro portal (or the qualification portal for Sandbox)
  2. Go to "My account" > "Manage technical accounts"
  3. Click "Create a technical account"
  4. Note the generated identifier (format: TECH_1_xxxxxx@cpro.fr)
  5. Set a secure password

cpro-account header format:

# Encoder en base64 : identifiant:motdepasse
echo -n "TECH_1_xxxxxx@cpro.fr:votre_mot_de_passe" | base64

# Résultat (exemple)
VEVDSF8xX3h4eHh4eHhAY3Byby5mcjp2b3RyZV9tb3RfZGVfcGFzc2U=

📖 Detailed tutorial: Create a technical account (official documentation)

5Authentication

⚠️ Dual authentication required: Every API request requires TWO simultaneous authentications.

1. OAuth 2.0 (Bearer Token)

Token obtained via the client_credentials grant with your PISTE credentials. Expires after 1 hour.

Authorization: Bearer YOUR_OAUTH_TOKEN

2. cpro-account Header

Chorus Pro technical account credentials encoded in base64 as 'identifier:password'.

cpro-account: base64(TECH_1_xxxxx@cpro.fr:password)

Get an OAuth 2.0 Token

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"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "token_type": "Bearer",
  "expires_in": 3600
}

6Your First Request

Test your configuration with the health-check or by retrieving your linked structures:

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
    }
  }'

Expected response:

{
  "codeRetour": 0,
  "libelle": "TRA_MSG_00.000",
  "listeStructureRattachement": [
    {
      "idStructure": 12345678,
      "identifiantStructure": "88200000000000",
      "typeIdentifiantStructure": "SIRET",
      "designationStructure": "Ma Structure",
      "statutUtilisateur": "ACTIF"
    }
  ]
}

✅ Success: If you get "codeRetour": 0, your configuration is correct!

💡 Note: If you just created the technical account, you may need to wait up to 1 hour before requests work.

7Invoice Submission Flow

Here are the typical steps to submit an invoice on Chorus Pro via the API:

1Get the recipient structure ID from its SIRET
2Consult the structure to verify its parameters and that it's active
3Retrieve the services (Service Code) if needed
4Option A: Upload the PDF then submit the invoice
5Option B: Create the invoice directly via the API (SAISIE_API mode)

Important Notes

📋 POST Method for Everything

The Chorus Pro API uses POST for almost all operations, even data retrieval. Green badges indicate read operations, blue ones indicate creations.

🔐 Expiring Tokens

The OAuth token expires after 1 hour. Plan for an automatic refresh system in your integration.

⚡ Response Format

Responses include a 'codeRetour' field (0 = success) and 'libelle' with the message. Always check these fields even with HTTP 200.

Resources & Support