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.

Tired of dealing with PISTE, certificates and XML? Chorus Pay handles the whole flow for you - quote acceptance, purchase order, invoice deposited on Chorus Pro.Discover Chorus Pay →·Compare both approaches

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=

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

⚠️ Observed in the field

  • Gateway behaviour measured in production over one month (≈1.2 M calls, 08/2026): the PISTE gateway occasionally returns a spurious HTTP 401 with an empty body in under a second (≈0.1 % of calls overall, up to 3 % on consulter/fournisseur during business hours) although the credentials are valid. A genuinely wrong login or password ALSO comes back as a 401 with an empty body (verified 09/09/2026), so a single 401 cannot tell the two apart: retry once after 1 to 2 s, then judge on persistence over time (several failures spread over 30 min or more with no success in between), never on a handful of consecutive 401s during a burst.
  • Any call exceeding ~30 s is cut by the gateway with HTTP 504 (empty body) while the backend may still complete: a 504 is an UNKNOWN outcome, not a failure (critical for soumettre, see « Submit PDF invoice »).
  • Outages show up as HTTP 503 HTML pages on every endpoint including /api/oauth/token. During a full outage (observed 03/10/2026 from 07:30 UTC, production and sandbox, several hours) the same account gets a mix of 60 s timeouts, HTTP 503 and HTTP 401 with an empty body: a 401 received while other calls time out or return 5xx says nothing about the technical credentials, do not treat it as a refusal.