API d'authentification du concessionnaire
Pour commencer
L’API d’authentification des concessionnaires utilise l’authentification par jeton oAuth 2.0 pour obtenir un jeton pour un concessionnaire.
Par où commencer ? Lisez-moi d’abord !
Avant de commencer à travailler sur cette API, vous devez lire les sections suivantes si vous ne les avez pas déjà consultées :
- Informations techniques pour des informations techniques générales sur l’API et les environnements.
- Authentification et informations d’identification pour plus de détails sur l’authentification et les identifiants.
Informations techniques
Caractéristiques
Type d'API | Type DSP | Version DCP | Complexité |
|---|---|---|---|
Obtenir des données de BRP | DMS | V3 - International | Faible |
Envoyer des données à BRP | CRM | V4 - Amérique du Nord | Un peu plus |
Transaction avec BRP | | | Quelque peu plus |
Authentification
Pour appeler l’API d’authentification de l’application, vous devez utiliser le client_id et le client_secret qui vous sont fournis par l’équipe DCP.
Assurez-vous d’utiliser le client_id qui correspond à l’environnement dans lequel l’API est appelée !
Le client_id et le client_secret utilisés pour appeler l’API d’authentification des concessionnaires ne sont PAS les mêmes que ceux utilisés pour appeler l’authentification de l’application !
URL de base
Test | https://qa-cloud-api.brp.com/dcp |
|---|---|
Production | https://cloud-api.brp.com/dcp |
Comprendre l’authentification des concessionnaires
Salesforce et BOSSWeb
L’authentification des concessionnaires utilise le compte BOSSWeb du concessionnaire pour obtenir un jeton d’accès. BOSSWeb est construit sur Salesforce, donc vos identifiants d’authentification des concessionnaires doivent être créés et configurés dans Salesforce.
Pour configurer votre accès à l’authentification des concessionnaires, vous devez fournir une URL de rappel (URI de redirection).
Cette URL est appelée par Salesforce pour envoyer le code d’accès une fois que le concessionnaire s’est connecté à BOSSWeb.
Pour appeler l’API d’authentification des concessionnaires, vous avez besoin du client_id et du client_secret créés par l’équipe DCP lors de la configuration de votre compte dans Salesforce, ainsi que du redirect_uri que vous avez fourni lors de la création de vos identifiants.
Reportez-vous à la section Authentification des concessionnaires pour plus d’informations.
❗ ❗ L’URL utilisée pour appeler l’API d'authentification du concessionnaire doit correspondre EXACTEMENT à celle que vous avez fournie pour la configuration ❗ ❗
Si l’URL que vous avez fournie pour l’environnement de production est https://site vous devez utiliser la même URL dans le paramètre redirect lors de l’appel à l’ API d'authentification du concessionnaire.
Si vous utilisez https://site/ ou https://Site dans le paramètre redirect vous recevrez une erreur :
👉 L’URI de redirection doit correspondre exactement, mais vous pouvez inclure le paramètre de requête state pour fournir à votre callback des informations d’état, comme le numéro du concessionnaire.
❗ ❗ Lorsque nous commençons à travailler sur une API DCP, nous devons demander l’accès en créant un ticket de certification dans Jira, comme décrit dans la section Activités de Certification avec Jira. ❗ ❗
Si vous avez déjà commencé à travailler sur une API et que vous avez perdu l’accès, créez un ticket de support comme décrit dans la section Ouvrir un Ticket de Support.
Les identifiants n’expireront jamais et ne seront jamais révoqués (sauf si vous quittez DCP).
Cependant, les identifiants peuvent changer, donc votre implémentation doit vous permettre de les modifier et d’utiliser facilement de nouveaux identifiants.
Jetons d’accès et de rafraîchissement
L’API d’authentification du concessionnaire renvoie deux valeurs importantes :
- Le access_token est utilisé pour appeler l’API DCP en utilisant l’authentification du concessionnaire.
- Le refresh_token est utilisé pour obtenir un nouveau access_token lorsque l’actuel est expiré.
Le access_token est valable pendant 2 heures.
Le refresh_tokenest valable pour toujours, et il doit être conservé pour réutilisation.
Reportez-vous à la section Authentification du concessionnaire pour plus d’informations sur la gestion des jetons.
Le jeton d’accès est spécifique au concessionnaire !
Un aspect important de l’authentification du concessionnaire est que le jeton d’accès est spécifique au numéro de concessionnaire utilisé pour obtenir le code d’autorisation.
Si vous obtenez un code d’autorisation pour le concessionnaire 0000694650 et appelez une API DCP pour effectuer une opération pour le concessionnaire 0000691730, vous recevrez un code d’état 403 Interdit.
Le code d'autorisation
La première étape du processus d’authentification du concessionnaire consiste à obtenir un code d’accès depuis BOSSWeb. Le concessionnaire doit se connecter à BOSSWeb en utilisant ses identifiants pour obtenir un code d’accès.
Pour permettre au concessionnaire de se connecter à BOSSWeb, vous devez obtenir l’URL grâce à un appel à l’API d’authentification du concessionnaire, point de terminaison Obtenir le code d’autorisation.
L’API renvoie une réponse contenant l’URL à ouvrir dans un navigateur web. Lorsqu’il est lancé, le navigateur affiche la page de connexion BOSSWeb, comme illustré ci‑dessous.
Après une connexion réussie, BOSSWeb redirige la page vers l’URI spécifiée dans le redirect_uri.
L’URI de redirection reçoit le access_code dans les paramètres de requête. Vous extrayez le access_code pour préparer l’appel permettant d’obtenir le access_token.
Dans cet exemple, l’URI de redirection https://localhost:8080/default.aspx est appelée, et vous pouvez voir le code dans le paramètre de requête code.
https://localhost:8080/default.aspx?code=aPrxCTGnE3a3w03eYfuMJIiNS32dVwR0CGa81tdZ2H69H0fBscwRM_GQN8CkqB8wfqO6sX0TaA%3D%3D
S’il y a une erreur dans l’URL utilisée pour ouvrir la page de connexion BOSSWeb, l’erreur est renvoyée à l’URI de redirection.
Par exemple, si le client_id est invalide, ce qui suit est renvoyé à l’URI de redirection :
Mode de simulation dans l’environnement de test
Un défi avec l’API d’authentification des concessionnaires est que lorsque l’environnement de test est actualisé (c’est‑à‑dire que les données de production sont copiées dans l’environnement de test), la configuration Salesforce et le compte BOSSWeb du concessionnaire utilisé pour les tests sont perdus.
Pour éviter de reconfigurer l’authentification des concessionnaires à chaque actualisation et de devoir redémarrer vos tests, un mode de simulation a été ajouté à l’API d’authentification des concessionnaires dans l’environnement de test.
Ce qui est simulé
Lorsque le mode de simulation est activé, voici ce qui se passe :
- La validation du jeton d’accès dans les API utilisant l’authentification des concessionnaires est désactivée.
- La page de connexion BOSSWeb n’a pas besoin d’être affichée : votre URL de rappel est appelée avec un code d’accès simulé lorsque vous appelez le point de terminaison Obtenir le code d’autorisation.
- Lorsque vous appelez le point de terminaison Obtenir le jeton pour obtenir ou actualiser un jeton d’accès, des valeurs simulées sont renvoyées.
‼️Lorsque le mode simulation est activé, n’essayez pas d’ouvrir la page de connexion BOSSWeb en utilisant l’URL retournée par l’appel Obtenir un code d’autorisation ‼️
Comment savoir si la simulation est activée
Lorsque vous appelez le point de terminaison Obtenir un code d’autorisation la réponse suivante est retournée.
{
"url": "https://cloud-api.brp.com/dcp/authentication/dealer/authorize?response_type=code&client_id=my_client_id&redirect_uri=https%3A%2F%2Fmy.callback.com",
"simulated": "false"
}Le champ url contient l’URL à envoyer à un navigateur Web pour ouvrir la page de connexion BOSSWeb.
Le champ simulated indique si la simulation est activée.
‼️Dans l’environnement de production, simulated est toujours false.
Flux d’authentification du concessionnaire
Ci-dessous se trouve le flux de processus pour l’API d’authentification du concessionnaire.
‼️Pour utiliser le mode de simulation, votre DMS doit mettre en œuvre un flux similaire à celui ci‑dessous‼️
‼️Lorsque le mode de simulation est activé, n'essayez pas d'ouvrir la page de connexion BOSSWeb en utilisant l’URL renvoyée par l’appel Obtenir le code d’autorisation ‼️
Le flux suppose que votre callback appelle l’endpoint Obtenir le jeton
Votre flux peut différer, mais en résumé, si le mode simulation est activé, vous n'avez pas besoin d’ouvrir la page de connexion BOSSWeb.
Référence API
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/authorize?client_id=my_client_id&redirect_uri=https%3A%2F%2Fmy.callback.com' curl --location --request POST 'https://qa-cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=authorization_code&client_id=REPLACE_ME&client_secret=REPLACE_ME&code=REPLACE_ME&redirect_uri=REPLACE_ME'curl --location --request POST 'https://qa-cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=refresh_token&client_id=REPLACE_ME&client_secret=REPLACE_ME&redirect_uri=REPLACE_ME&refresh_token=REPLACE_ME'curl --location 'https://qa-cloud-api.brp.com/dcp/authentication/dealer/userinfo' \
--header 'Authorization: Bearer REPLACE_ME'Comment faire
Cette section montrera des exemples d’utilisation de l’API d’authentification des concessionnaires. Pour ces exemples, les valeurs présentées dans le tableau ci‑dessous sont utilisées. Vous devez remplacer les valeurs par les vôtres avant d’appeler l’API.
Variable | Valeur |
|---|---|
client_id | %C*F-J@NcRfUjXn2 |
client_secret | kYp3s6v9y$B&E)H@ |
redirect URI | https://my.dps.com/dealer_auth/pro |
numéro de concessionnaire | 0000456789 |
nom d’utilisateur | joe.smith |
Cet exemple est réalisé en utilisant l’environnement de production.
Dans ces exemples, les jetons, client_id et client_secret sont des valeurs aléatoires. En réalité, les valeurs sont plus longues, jusqu’à 128 caractères.
Obtenir un code d’autorisation
La première étape consiste à ouvrir un navigateur Web et à accéder à la page de connexion BOSSWeb.
Cela se fait en appelant l’API d’authentification du concessionnaire Obtenir le code d’autorisation .
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/authorize?client_id=my_client_id&redirect_uri=https%3A%2F%2Fmy.callback.com' L’API renvoie une charge utile de réponse contenant deux champs :
- url contient l’URL à utiliser pour ouvrir la page de connexion BOSSWeb dans un navigateur Web.
- simulated indique si le mode d’authentification du concessionnaire est actif. Le champ est toujours false en production.
La fenêtre de connexion BOSSWeb s’affiche et le concessionnaire saisit ses identifiants.
L’URI de redirection reçoit le access_code dans les paramètres de requête et doit l’extraire.
https://my.dps.com/dealer_auth/pro?code=&E)H@McQfTjWnZq4
Vous êtes maintenant prêt à obtenir le jeton d’accès bearer.
Obtenir un jeton d’accès
Pour obtenir le jeton d’accès bearer, appelez l’API en utilisant le access_code reçu à l’étape précédente ainsi que le client_id, client_secret, et redirect_uri.
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=authorization_code&client_id=%C*F-J@NcRfUjXn2&client_secret=kYp3s6v9y$B&E)H@&code=&E)H@McQfTjWnZq4&redirect_uri=https://my.dps.com/dealer_auth/pro'Vous recevez access_token et refresh_token dans le message de réponse.
Le access_token est utilisé pour appeler les API DCP.
Le refresh_token doit être sauvegardé puisqu’il est réutilisé pour renouveler le access_token .
Renouveler le jeton
Le access_token est valide pendant 2 heures. Pour éviter que les concessionnaires aient à se reconnecter toutes les 2 heures, rafraîchissez le access_token avant son expiration.
Pour rafraîchir le jeton, vous appelez l’API en utilisant le type de jeton refresh_token .
L’API renvoie un nouveau access_token qui est utilisé pour appeler les API DCP.
Le refresh_token n’est PAS renvoyé par l’API lors de l’appel de rafraîchissement. Le refresh_token reste valide jusqu’à sa révocation, vous devez donc le conserver.
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=refresh_token&client_id=%C*F-J@NcRfUjXn2&client_secret=kYp3s6v9y$B&E)H@&redirect_uri=https://my.dps.com/dealer_auth/pro'&refresh_token=%C*F-JaNdRfUjXn2'Utilisation du paramètre d’état (State)
La première étape consiste à construire une URL qui ouvre un navigateur web et affiche la page de connexion BOSSWeb. L’URL contient le paramètre de requête state afin de fournir au callback des informations sur le concessionnaire appelant.
En utilisant les valeurs de notre exemple, votre URL est :
http://cloud-api.brp.com/dcp/authentication/dealer/authorize?response_type=code&client_id=%C*F-J@NcRfUjXn2&redirect_uri=https://my.dps.com/dealer_auth/pro&state=ceci est l’information de mon concessionnaire
La fenêtre de connexion BOSSWeb s’affiche et le concessionnaire saisit ses identifiants.
L’URI de redirection reçoit le access_code dans les paramètres de requête et doit l’extraire. Elle reçoit également la valeur fournie dans le paramètre de requête state.
https://my.dps.com/dealer_auth/pro?code=&E)H@McQfTjWnZq4&state=this+is+my+dealer+information&state=this+is+my+dealer+information
Vous êtes maintenant prêt à obtenir le jeton d’accès bearer, comme décrit dans la section Obtenir un jeton d’accès ci-dessus.
Les informations que vous avez fournies dans le paramètre de requête state peuvent être utilisées par votre callback pour lier le jeton d’accès reçu à un concessionnaire spécifique.
Gestion des erreurs
Cette section présente divers scénarios d’appels incorrects ou erronés, qui entraînent des messages d’erreur et des résultats incorrects.
400 Requête Incorrecte
Le code d’erreur 400 Requête Incorrecte est le seul renvoyé par les services GET de l’API d’authentification des concessionnaires.
De nombreux problèmes peuvent provoquer un code d’état 400 ; les plus courants sont répertoriés dans le tableau ci-dessous.
Réponse | Résolution |
|---|---|
Renvoyé si le grant_type n’est pas valide ou si le code d’autorisation a expiré. {
"error": "invalid_grant",
"error_description": "code d’autorisation expiré"
} | Vérifiez que le grant_type est correctement configuré, demandez un nouveau code d’autorisation, puis réessayez. Si la tentative échoue, contactez l’équipe DCP. |
Renvoyé si le client_id n’est pas valide. {
"error": "invalid_client_id",
"error_description": "identifiant client invalide"
} | Vérifiez que le client_id est correctement configuré et réessayez. Si la tentative échoue, contactez l’équipe DCP pour confirmer que votre DSP est enregistré dans le serveur d’autorisation. |
Renvoyé si le client_secret n’est pas valide. {
"error": "invalid_client",
"error_description": "identifiants client invalides"
} | Vérifiez que le client_secret est correctement configuré et réessayez. Si la tentative échoue, contactez l’équipe DCP pour confirmer que votre DSP est enregistré dans le serveur d’autorisation. |
401 Non autorisé
L’userinfo point de terminaison de l’API peut renvoyer le code d’erreur 401 Non autorisé.
L’erreur est renvoyée lorsque vous essayez d’appeler l’API d’authentification du concessionnaire avec un access_token expiré.
Vous devez obtenir un nouveau access_token ou actualiser celui que vous avez en appelant le point de terminaison de l’API token.
Exigences DSP
Exigences fonctionnelles
ID | Type | |
|---|---|---|
1 | Obligatoire | Le access_token doit être automatiquement actualisé toutes les 90 minutes |
2 | Obligatoire | Le refresh_token doit être enregistré dans le profil du concessionnaire et réutilisé pour demander un access_token. |
3 | Optionnel | Le concessionnaire peut accéder à un écran de configuration pour se connecter à BOSSWeb. Le refresh_token reçu est enregistré et utilisé pour obtenir un access_token . |
Activités de certification
L'API d'authentification du concessionnaire n'a pas d'activités de certification spécifiques ; elle est validée via l'API DCP en utilisant l'authentification du concessionnaire.
Postman
Cette section décrit ce qui est disponible dans Postman pour explorer l'API.
Environnements
Un environnement Postman est disponible pour essayer l’API d’authentification des concessionnaires. Cet environnement Postman contient des variables utilisées par les requêtes et est configuré pour se connecter à l’environnement de test.
Collections
La collection DSP - Authentification des concessionnaires contient des exemples d’appels API pour obtenir et valider un jeton d’accès.