Les aides proposées par l'AIFE vous permettront de faire les premiers tests et appels API vers la qualification puis vers la production. Ces aides sont à partager avec la communauté de développeurs API. Vous pouvez contribuer à l'enrichissement de ces aides en nous contactant par e-mail.
Table des matières
1 Rappel des prérequis
Voici les pré requis pour pouvoir faire des appels API en qualification :
Ces trois étapes vous permettent de faire des appels API en qualification.
2 1er test API avec SOAP UI
2.1 Principe
La plateforme Chorus Pro permet de gérer par webservice les factures envoyées aux clients institutionnels. Pour réaliser la connexion, il faut : - une structure identifiée (SIRET de la société maîtresse) qui supervise éventuellement d’autres structures (autres SIRET) - un utilisateur gestionnaire (principal ou secondaire) - un compte utilisateur technique attaché à la structure - activer les droits d’accès à l’API pour cette structure.
2.2 Prérequis
- Installer SOAPUI
- Disposer d'un access token via piste
2.3 Procédure
Au préalable de l’exécution de l’appel API Chorus Pro, l’utilisateur doit récupérer un « Access Token ». La récupération de ce jeton est décrite dans le guide utilisateur de PISTE.
Afin de procéder à l’appel, suivre les étapes suivantes pour paramétrer le SOAPui :
Depuis la fenêtre de l’appel SOAPui, cliquer sur « Auth » (encadré rouge ci-dessous).
Suite au clic, le bloc d’authentification s’affiche comme illustré ci-dessous :
Sélectionner « Add new authorization », une nouvelle pop-in s’affiche :
Préciser dans le champ « type », la valeur OAuth2.0 et choisir un profil.
Suite à la validation, la nouvelle authorization est créée :
Cliquer sur « Get Token ».
- Dans “Oauth 2 Flow” sélectionner « Client Credentials Grant »
- Copier le Client ID et le Client Secret – qui sont récupérables dans PISTE comme décrit dans le guide utilisateur PISTE dans la rubrique « 6.5 Génération d’une Api Key » du guide utilisateur PISTE UserGuide_navigation_FR
- Remplir l’Access Token URL en fonction d’où doit être effectué l’appel (zone Internet ou ADER). Pour cela se référer à la rubrique « 10.2 Liste des points d’accès PISTE par partenaire » du guide utilisateur PISTE UserGuide_navigation_FR
- Scope = « openid »
- Valider en cliquant sur Get Access Token
Une fois l’access Token généré, procéder à l’appel API Chorus Pro comme décrit ci-dessous :
- La valeur obtenue lors du get access Token est automatiquement renseigné dans le champ Access Token (bloc « Authorization » Profile 1) :
Procéder à la création d’un Header en cliquant sur le bouton [Headers] et sur le « + » :
Saisir « cpro-account » comme nom de header et valider :
- Lorsque le header est créé, renseigner dans le champ « Value » la combinaison « logintechnique:password » encodée en base 64
- Exécuter l’appel API en cliquant sur la flèche verte et vous obtiendrez alors une réponse dans la zone de droite (onglet JSON).
Le format d'encodage attendu : l’encodage du contenu doit être obligatoirement en UTF-8 (Content-Type: charset=UTF-8).
3 Récupération de l'access Token pour procéder à un appel API Chorus Pro en mode OAuth2 avec la commande Curl
De même que pour l’exécution de l’appel API Chorus Pro (depuis soapUi), l’utilisateur doit premièrement récupérer un « Access Token » via la commande Curl.
Le jeton est obtenu en curl en utilisant la commande suivante depuis Internet :
curl –k –H "content-type :application/x-www-form-urlencoded" –d "grant_type=client_credentials&client_id=XXXXX&client_secret=XXXXXXX&scope=openid" –X POST https://sandbox-oauth.piste.gouv.fr/api/oauth/token
Ou la commande ci-dessous depuis le Réseau Interministériel de l'État (RIE):
curl –k –H "content-type :application/x-www-form-urlencoded" –d "grant_type=client_credentials&client_id=XXXXX&client_secret=XXXXXXX&scope=openid" –X POST https://sandbox-oauth.aife.finances.rie.gouv.fr/api/oauth/token
4 Consommation de l'API en Curl
Pour consommer l’API, il faut effectuer la requête suivante (en ajoutant l’entête Authorization: Bearer à chaque requête) depuis internet :
curl -k -H "content-type: application/json; charset=UTF-8" -H "Authorization:Bearer <access_token>" -H "cpro-account:<logintechnique:password encodée en base 64>" --data '{votre_body_json}' –X POST https://sandbox-api.piste.gouv.fr/{votre_API}
Ou la commande suivante depuis le réseau interministériel de l'État (RIE):
curl -k -H "content-type: application/json; charset=UTF-8" -H "Authorization:Bearer <access_token>" -H "cpro-account:<logintechnique:password encodée en base 64>" --data '{votre_body_json}' –X POST https://sandbox-api.aife.finances.rie.gouv.fr/{votre_API}
La réponse retournée est similaire à la capture écran ci-dessous :
5 Liste des URL PISTE pour accéder aux API Chorus Pro
- Nom d’accès INTERNET :
https://sandbox-api.piste.gouv.fr (type d’accès : consommation SANDBOX) ;
https://api.piste.gouv.fr (type d’accès : consommation PRODUCTION) ;
https://piste.gouv.fr/ (type d’accès : portail PISTE) ;
https://sandbox-oauth.piste.gouv.fr/api/oauth/token (type d’accès : obtention d’un jeton SANDBOX) ;
https://oauth.piste.gouv.fr/api/oauth/token (type d’accès : obtention d’un jeton PRODUCTION).
- Nom d’accès ADER :
https://api.aife.finances.rie.gouv.fr (type d’accès : consommation PRODUCTION) ;
https://oauth.aife.finances.rie.gouv.fr/api/oauth/token (type d’accès : obtention d’un jeton PRODUCTION) ;
https://sandbox-api.aife.finances.rie.gouv.fr (type d’accès : consommation SANDBOX) ;
https://sandbox-oauth.aife.finances.rie.gouv.fr/api/oauth/token (type d’accès : obtention d’un jeton SANDBOX).