API de Autenticación de Concesionarios
Cómo empezar
La API de Autenticación del Concesionario utiliza autenticación basada en tokens oAuth 2.0 para obtener un token para un concesionario.
¿Dónde empezar? ¡Léame primero!
Antes de empezar a trabajar con esta API, debe leer las siguientes secciones si aún no las ha revisado:
Información técnica
Características
Tipo de API | Tipo de DSP | Versión DCP | Complejidad |
|---|---|---|---|
Obtener datos de BRP | DMS | V3 - Internacional | Bajo |
Enviar datos a BRP | CRM | V4 - Norteamérica | Un poco más |
Transacción con BRP | | | Algo más |
Autenticación
Para llamar a la API de Autenticación de Aplicaciones, necesitas el client_id y el client_secret proporcionados por el equipo de DCP.
Asegúrate de usar el client_id que coincide con el entorno en el que se llama a la API!
El client_id y el client_secret utilizados para llamar a la API de Autenticación de Concesionarios NO son los mismos que los utilizados para llamar a la Autenticación de Aplicaciones!
URL base
Prueba | https://qa-cloud-api.brp.com/dcp |
|---|---|
Producción | https://cloud-api.brp.com/dcp |
Comprender la Autenticación de Concesionarios
Salesforce y BOSSWeb
La Autenticación de Concesionarios utiliza la cuenta BOSSWeb del concesionario para obtener un token de acceso. BOSSWeb está construido sobre Salesforce, por lo que tus credenciales de Autenticación de Concesionarios deben ser creadas y configuradas en Salesforce.
Para configurar tu acceso a la Autenticación de Concesionarios, debes proporcionar una URL de callback (URI de redirección).
Esta URL es llamada por Salesforce para enviar el código de acceso una vez que el concesionario haya iniciado sesión en BOSSWeb.
Para llamar a la Dealer Authentication API, necesitas el client_id y el client_secret creado por el equipo de DCP al configurar tu cuenta en Salesforce, así como el redirect_uri que proporcionaste cuando se crearon tus credenciales.
Consulta la sección Autenticación de Concesionarios para más información.
❗ ❗ La URL utilizada al llamar a la API de Autenticación de Concesionarios debe coincidir EXACTAMENTE con la que proporcionaste para la configuración ❗ ❗
Si la URL que proporcionaste para el entorno de producción es https://site debes usar la misma URL en el parámetro redirect en la llamada a la API de Autenticación de Concesionarios.
Si usas https://site/ o https://Site en el parámetro redirect recibirás un error:
👉 El URI de redirección debe coincidir exactamente, pero puedes incluir el parámetro de consulta state para proporcionar a tu callback información de estado, como el número del distribuidor.
❗ ❗ Al empezar a trabajar en una API de DCP, debemos solicitar acceso creando un ticket de certificación en Jira, como se describe en la sección Actividades de Certificación con Jira. ❗ ❗
Si ya comenzaste a trabajar en una API y perdiste el acceso, crea un ticket de soporte como se describe en la sección Abrir un Ticket de Soporte.
Las credenciales nunca expirarán ni serán revocadas (a menos que dejes DCP).
Sin embargo, las credenciales pueden cambiar, por lo que tu implementación debe permitir cambiar y usar nuevas credenciales fácilmente.
Tokens de Acceso y Actualización
La API de Autenticación de Concesionarios devuelve dos valores importantes:
- El access_token se utiliza para llamar a la API DCP usando Autenticación de Concesionarios.
- El refresh_token se utiliza para obtener un nuevo access_token cuando el actual ha expirado.
El access_token es válido por 2 horas.
El refresh_tokenes válido para siempre, y debe guardarse para su reutilización.
Consulta la sección Autenticación de Concesionarios para más información sobre la gestión de los tokens.
¡El token de acceso es específico del concesionario!
Un aspecto importante de la Autenticación de Concesionarios es que el token de acceso es específico del número de concesionario utilizado para obtener el código de autorización.
Si obtienes un código de autorización para el concesionario 0000694650 y llamas a una API DCP para realizar una operación para el concesionario 0000691730, recibirás un código de estado 403 Forbidden.
El Código de Autorización
El primer paso en el proceso de Autenticación del Distribuidor es obtener un código de acceso de BOSSWeb. El distribuidor debe iniciar sesión en BOSSWeb usando sus credenciales para obtener un código de acceso.
Para permitir que el distribuidor inicie sesión en BOSSWeb, debe obtener la URL con una llamada al endpoint Get Authorization Code de la API de Autenticación del Distribuidor.
La API devuelve una respuesta que contiene la URL para abrir en un navegador web. Cuando se lanza, el navegador muestra la página de inicio de sesión de BOSSWeb, como se muestra a continuación.
Después de un inicio de sesión exitoso, BOSSWeb redirige la página al URI especificado en el redirect_uri.
El URI de redirección recibe el access_code en los parámetros de consulta. Usted extrae el access_code para prepararse para la llamada para obtener el access_token.
En este ejemplo, se llama al URI de redirección https://localhost:8080/default.aspx y puede ver el código como el parámetro de consulta code.
https://localhost:8080/default.aspx?code=aPrxCTGnE3a3w03eYfuMJIiNS32dVwR0CGa81tdZ2H69H0fBscwRM_GQN8CkqB8wfqO6sX0TaA%3D%3D
Si hay un error en la URL utilizada para abrir la página de inicio de sesión de BOSSWeb, el error se devuelve al URI de redirección.
Por ejemplo, si el client_id es inválido, se devuelve lo siguiente al URI de redirección:
Modo de Simulación en el Entorno de Pruebas
Un desafío con la API de Autenticación de Concesionarios es que cuando se actualiza el entorno de prueba (es decir, los datos de producción se copian en el entorno de prueba), se pierde la configuración de Salesforce y la cuenta BOSSWeb del concesionario utilizada para las pruebas.
Para evitar reconfigurar la Autenticación de Concesionarios cada vez que haya una actualización y reiniciar sus pruebas, se ha añadido un modo de simulación a la API de Autenticación de Concesionarios en el entorno de prueba.
Qué Se Simula
Cuando el modo de simulación está habilitado, esto es lo que sucede:
- La validación del token de acceso en las APIs que usan Autenticación de Concesionarios está deshabilitada.
- La página de inicio de sesión de BOSSWeb no tiene que mostrarse: su URL de callback es llamada con un código de acceso simulado cuando llama al endpoint Obtener Código de Autorización.
- Cuando llama al endpoint Obtener Token para obtener o refrescar un token de acceso, se devuelven valores simulados.
‼️Cuando el modo de simulación está habilitado, no intentes abrir la página de inicio de sesión de BOSSWeb usando la URL devuelta por la llamada Obtener Código de Autorización ‼️
Cómo Saber Si la Simulación Está Habilitada
Cuando llamas al endpoint de la Obtener Código de Autorización se devuelve la siguiente respuesta.
{
"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"
}El campo url contiene la URL que se debe enviar a un navegador web para abrir la página de inicio de sesión de BOSSWeb.
El campo simulated indica si la simulación está habilitada.
‼️En el entorno de producción, simulated siempre es false.
Flujo de Autenticación de Concesionarios
A continuación se muestra el flujo de proceso para la API de Autenticación de Concesionarios.
‼️Para usar el modo de simulación, su DMS debe implementar un flujo similar al de abajo‼️
‼️Cuando el modo de simulación está habilitado, no intente abrir la página de inicio de sesión de BOSSWeb usando la URL devuelta por la llamada Obtener Código de Autorización ‼️
El flujo asume que su callback llama al endpoint Obtener Token.
Su flujo puede diferir, pero en resumen, si el modo de simulación está habilitado, no necesita abrir la página de inicio de sesión de BOSSWeb.
Referencia de 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'Cómo hacerlo
Esta sección mostrará ejemplos de cómo usar la API de Autenticación de Concesionarios. Para estos ejemplos, se utilizan los valores presentados en la tabla a continuación. Debe reemplazar los valores con los suyos propios antes de llamar a la API.
Variable | Valor |
|---|---|
client_id | %C*F-J@NcRfUjXn2 |
client_secret | kYp3s6v9y$B&E)H@ |
redirect URI | https://my.dps.com/dealer_auth/pro |
dealer number | 0000456789 |
user name | joe.smith |
Este ejemplo se realiza usando el entorno de producción.
En estos ejemplos, los tokens, client_id y client_secret son valores aleatorios. En realidad, los valores son más largos, de hasta 128 caracteres.
Obtener código de autorización
El primer paso es abrir un navegador web y navegar a la página de inicio de sesión de BOSSWeb.
Esto se hace llamando al API de Autenticación de ConcesionariosObtener Código de Autorizaciónendpoint.
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' El API devuelve una carga de respuesta con dos campos:
- urlcontiene la URL que se debe usar para abrir la página de inicio de sesión de BOSSWeb en un navegador web.
- simuladoindica si el modo de Autenticación de Concesionarios está activo. El campo siempre es false en producción.
Se muestra la ventana de inicio de sesión de BOSSWeb y el concesionario ingresa sus credenciales.
El URI de redirección recibe el access_code en los parámetros de la consulta y debe extraerlo.
https://my.dps.com/dealer_auth/pro?code=&E)H@McQfTjWnZq4
Ahora está listo para obtener el token de acceso bearer.
Obtener Token de Acceso
Para obtener el token de acceso bearer, llame a la API usando el access_code recibido en el paso anterior y el client_id, client_secret, y 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'Usted recibe access_token y refresh_token en el mensaje de respuesta.
El access_token se usa para llamar a las APIs de DCP.
El refresh_token debe guardarse ya que se reutiliza para refrescar el access_token .
Refrescar Token
El access_token es válido por 2 horas. Para evitar que los distribuidores tengan que iniciar sesión cada 2 horas, refresca el access_token antes de que expire.
Para refrescar el token, llamas a la API usando el tipo de concesión refresh_token .
La API devuelve un nuevo access_token que se usa para llamar a las APIs de DCP.
El refresh_token NO es devuelto por la API en la llamada de refresco. El refresh_token es válido hasta que sea revocado, por lo que debes conservarlo.
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'Uso del parámetro de consulta State
El primer paso es construir una URL que abra un navegador web y muestre la página de inicio de sesión de BOSSWeb. La URL contiene el parámetro de consulta state para proporcionar al callback información sobre el distribuidor que está llamando.
Usando los valores de nuestro ejemplo, tu URL es:
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=this is my dealer information
Se muestra la ventana de inicio de sesión de BOSSWeb y el concesionario introduce sus credenciales.
El URI de redirección recibe el access_code en los parámetros de la consulta y debe extraerlo. También recibe el valor proporcionado en el parámetro de consulta state.
https://my.dps.com/dealer_auth/pro?code=&E)H@McQfTjWnZq4&state=esta+es+mi+información+del+concesionario&state=esta+es+mi+información+del+concesionario
Ahora está listo para obtener el token de acceso bearer, como se describe en la sección Obtener Token de Acceso arriba.
La información que proporcionó en el parámetro de consulta state puede ser utilizada por su callback para vincular el token de acceso recibido con un concesionario específico.
Gestión de Errores
Esta sección presenta varios escenarios de llamadas incorrectas o inapropiadas, que resultan en mensajes de error y resultados inadecuados.
400 Solicitud Incorrecta
El código de estado de error 400 Solicitud Incorrecta es el único que devolvieron los servicios GET de la API de Autenticación del Concesionario.
Muchos problemas pueden causar un código de estado 400; los más comunes se enumeran en la tabla a continuación.
Respuesta | Resolución |
|---|---|
Se devuelve si el grant_type no es válido o el código de autorización ha expirado. {
"error": "invalid_grant",
"error_description": "código de autorización expirado"
} | Confirme que el grant_type esté configurado correctamente, solicite un nuevo código de autorización y vuelva a intentarlo. Si el reintento falla, póngase en contacto con el equipo de DCP. |
Se devuelve si el client_id no es válido. {
"error": "invalid_client_id",
"error_description": "identificador de cliente no válido"
} | Confirme que el client_id esté configurado correctamente y vuelva a intentarlo. Si el reintento falla, póngase en contacto con el equipo de DCP para asegurar que su DSP esté registrado en el Servidor de Autorización. |
Se devuelve si el client_secret no es válido. {
"error": "invalid_client",
"error_description": "credenciales de cliente no válidas"
} | Confirme que el client_secret esté configurado correctamente y vuelva a intentarlo. Si el reintento falla, póngase en contacto con el equipo de DCP para asegurar que su DSP esté registrado en el Servidor de Autorización. |
401 No autorizado
El userinfo endpoint de la API puede devolver el código de estado de error 401 No autorizado.
El error se devuelve cuando intentas llamar a la API de Autenticación de Distribuidores con un access_token expirado.
Tienes que obtener un nuevo access_token o renovar el que tienes llamando al endpoint de la API token.
Requisitos DSP
Requisitos Funcionales
ID | Tipo | |
|---|---|---|
1 | Obligatorio | El access_token debe actualizarse automáticamente cada 90 minutos |
2 | Obligatorio | El refresh_token debe guardarse en el perfil del concesionario y reutilizarse para solicitar un access_token. |
3 | Opcional | El concesionario puede acceder a una pantalla de configuración para iniciar sesión en BOSSWeb. El refresh_token recibido se guarda y se utiliza para obtener un access_token . |
Actividades de certificación
La API de Autenticación de Concesionarios no tiene actividades de certificación específicas; se valida a través de la API DCP utilizando la Autenticación de Concesionarios.
Postman
Esta sección describe lo que está disponible en Postman para explorar la API.
Entornos
Hay un entorno de Postman disponible para probar la API de Autenticación de Concesionarios. Este entorno de Postman contiene variables utilizadas por las consultas y está configurado para conectarse al entorno de prueba.
Colecciones
La colección DSP - Autenticación de Concesionarios contiene ejemplos de llamadas API para obtener y validar un token de acceso.