- Overview of Chorus Pro
- The portal
- Creating an account and downloading test data
- Activating APIs
- Need for a certificate
- Programming Chorus Pro REST APIs in WLanguage
- Build the header
- Managing parameters or results
- Running the REST request
- Callback for optimization
- Browsing JSON results
- PDF encoding
Chorus Pro: Automate the submission of invoices
In France, electronic invoicing has become mandatory for invoicing government services.
The French government has set up the Chorus Pro system to submit and monitor invoices. It is the tool for managing the expenditure and non-tax revenues of French government services.
From 01/01/2019, all companies with more than 10 employees must invoice government services by presenting an invoice (in PDF format) on Chorus Pro.
And in 2020, all companies must use Chorus Pro.
"Chorus Pro" is a platform that allows submitting invoices to the French government. It is possible to carry out these operations manually on the portal, but it is also possible to automate these tasks via a set of APIs.
"Chorus Pro" allows for two types of integration:
- an EDI mode (XML exchange),
- an API mode (API REST).
The EDI mode provides a limited subset of the API mode features.
This help page presents:
- An overview of Chorus Pro (with the necessary tools to use APIs).
- Programming Chorus Pro APIs in WLanguage.
In the LST #115, You will find an example on how to use APIs to submit PDF invoices on Chorus Pro.
"Chorus Pro" and its functionalities are aimed at two types of users:
- the services that receive invoices: the government,
- the services that submit invoices to the government.
: All the documentation about "Chorus Pro" and the APIs is available via the following link: https://communaute.chorus-pro.gouv.fr/?lang=en
Chorus Pro offers:
- A test environment
This environment is called "Qualification portal".
The qualification portal can be accessed via the following link: https://chorus-pro.gouv.fr/qualif. It can be easily recognized by its green color.
- A production environment
The production portal is available via the following address: https://chorus-pro.gouv.fr/. It can be easily recognized by its blue color.
Remark: test and production environments can be "linked" but they remain independent. An account must be created for every environment.
In the rest of this page, the operation are performed in the test environment.
Creating an account and downloading test data
Step 1: Creating a Chorus Pro account:
Before any operation, it is necessary to create a Chrorus Pro account (in the test and/or the production environment, according to your needs).
The creation of a Chorus account is not immediate (up to several days), so you should anticipate this step if necessary.
Indeed, to create a Chorus account, it is necessary to be an organization (called "structure" in the Chorus interface) and to specify, along with an email address, specific details about the organization (such as the SIRET, -French Company Registration Number-, for example). This information is verified before the account is created.
Remark: The address associated to the account must be a valid and regularly checked email address. This address will be used by Chorus to communicate on the changes and maintenance periods of the different environments.
Step 2: Test environment: Retrieving test data
When the Chorus account is created in the test environment, it is possible (perhaps indispensable) to ask for test data (called "Dataset" in the Chorus Pro vocabulary).
To do so:
- In the qualification portal, select "My account .. My dataset .. Create".
- The dataset generation starts. Keep in mind this operation may take more than 1 hour.
- At the end of the generation, click on "download attachments".
- The resulting file is a ".csv" file containing invoices, suppliers, etc.
- Log out from the qualification portal.
- Log in to the qualification portal using the identifiers provided in the downloaded file (Partner provider: login and password).
- You access the environment with the test data as "Primary manager of the structure". A set of invoices will have been automatically generated to carry out your tests. You can have pending, rejected and "production" invoices.
By default, APIs are not accessible for an account on "Chorus Pro" portals (test or production portals). In the "Chorus Pro" vocabulary, the term used is "connection".
It is necessary to explicitly authorize (connect) the access to the APIs before making any calls to APIs. In the test environment, the procedure is as follows:
- Select "Manager activities".
- Scroll down to "My structures".
- On the row of the structure, click on the pencil icon of the "Actions" column.
- Click on "Add areas" in the "Areas" section.
- Select the service(s) and activate the option "EDI and API connections".
- Log out from the portal.
- Log in to the portal using the identifiers provided in the downloaded file (Partner provider: login and password).
- A new option ("EDI and API connections") appears in the menu.
- Select this option and confirm.
- Now you must specify the certificate in order to use the APIs in the option "Create API connection". You can fin more details on the page: https://communaute.chorus-pro.gouv.fr/documentation/connection-to-chorus-pro/?lang=en
To use APIs, you must create a "technical" account on Chorus Pro. In the test portal, this technical account is created from the manager account.
The identity (email and password) of this technical account will be passed "in parameter" to the API RESTs.
Creating this account allows you to dissociate a use "by API" from a classic use of Chorus Pro via the manager account, for example.
Remark: it is possible to create several technical accounts and give them limited access to certain APIs.
Need for a certificate
Authentication by certificate
To authenticate calls by API, Chorus Pro requires authentication by client certificate. This type of identification is presented as a "digital identity card" in the Chorus Pro documentation.
This certificate will allow the portal to identify and authenticate each call. Each customer (I.e. each company that wants to connect to Chorus Pro by API) will have to buy a certificate from recognized bodies,
Buying a certificate
Chorus Pro requires only one type of certificate when using APIs (and not EDIs): a client authentication certificate that complies with the RGS* standard at least.
To do so, a list of providers is provided in the Chorus Pro documentation (make sure to choose a stamp that complies with the RGS* standard at least): https://www.lsti-certification.fr/images/Trusted-List-RGS-eIDAS_LSTI_V6.4.pdf
This exhaustive list may seem complex. During our tests, we were able to find information on the "TBS-Internet" and "Certigna" websites. The price of a certificate is around 300 €/ year.
The certificate obtained must be provided to the Chorus portal, in pkcs7 format, with the whole certificate string. From that point on, the API calls will be "authenticated".
Remark: according to certain Chorus documents, it is possible to obtain a test certificate for the qualification portal. To this day, we have not found a provider that allows this without contacting them directly. However, it is possible to use the same certificate for the test environment and for the qualification environment.
Programming Chorus Pro REST APIs in WLanguage
Chorus Pro APIs are REST APIs that manage JSON parameters, so you must simply use JSON, restRequest
// Build the parameters
ParameterEntry is JSON
cRequest.Content = ParameterEntry
// Make the REST call
cResponse = RESTSend(cRequest)
Caution: If you use a proxy, remember to configure the access to the proxy in your code with Proxy
Remark: In the LST #115, You will find an example on how to use APIs to submit PDF invoices on Chorus Pro.
Build the header
All REST requests of the Chorus Pro API contain authentication data that allows you to provide:
- The identifiers (login and password) of the technical account.
// Technical user
cRequest.User = GetTechnicalUserName()
cRequest.Password = GetTechnicalUserPassword()
- The password (.p12 format) and its password.
// Signature by certificate
cRequest.ClientCertificate = GetCertificate()
cRequest.ClientPassword = GetCertificatePassword()
Remark: From version 24, it is possible to use a certificate stored in the application library (to keep it from being shared). Simply specify its name in string format.
The trusted authority certificate for Chorus Pro does not seem to be recognized by all computers running on Windows, so it was explicitly authorized by TrustedCertificateAdd
Managing parameters or results
Chorus Pro REST APIs handle and sent data in JSON format. The format of the JSON data is specified in the footer of the page associated to the API.
Each file contains an example of JSON content, for example:
WINDEV 24 allows you not only to handle JSON data with the JSON variable but also to import its description by using an existing JSON.
All you need to do is use the option "Import an XML or a JSON into this project" in the popup menu of "External descriptions" of the project explorer.
// Build the parameters
ParameterEntry is JSON, description="DeposerPDFFacture_M8_V0_input"
ParameterEntry.FileName = fExtractPath(sInvoiceFile, fFile + fExtension)
Running the REST request
When the parameters and the header are specified, all you have to do is run the REST request built and manage the return code (which is a classic HTTP code).
// Send the request
cResponse is restResponse
cResponse = RESTSend(cRequest)
Callback for optimization
It is possible to display the frames sent when RESTSend
is called, thanks to the property ..ProcedureTrace
of the httpRequest
cRequest..ProcedureTrace = CBDebug
Browsing JSON results
The data sent by Chorus Pro APIs often contain data arrays whose "unitary" type is not specified. However, in WLanguage, it is possible to use a subset of a JSON description as description:
EngagementJSON is JSON
To submit a file to Chorus Pro, it is necessary to encode it in base64 (with Encode
To this date, Chorus Pro does not seem to correctly interpret encoded data containing CRs. They must be deleted in the following code, for example:
ParameterEntry.InvoiceFile = Replace(Encode(fChangeBuffer(sInvoiceFile), ...
This page is also available for…
Click [Add] to post a comment