API de campañas
Comenzando
La API de Campañas permite que sus distribuidores soliciten y vean los detalles de campañas/boletines de garantía a través de su DMS para un número de identificación de vehículo (VIN) específico.
Cuando un cliente trae una unidad para mantenimiento o reparación, una parte importante de las actividades del distribuidor es verificar si los boletines de garantía y seguridad son aplicables a la unidad. Los boletines de garantía y seguridad pueden encontrarse usando el VIN de la unidad. Al crear la orden de reparación, el técnico busca boletines aplicables a la unidad. Si se encuentran boletines, los trabajos y las piezas correspondientes pueden añadirse a la orden de reparación.
¿Por dónde empezar? ¡Léeme primero!
Antes de comenzar a trabajar en esta API, debes leer las siguientes secciones si aún no las has 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
La API está utilizando Autenticación de Aplicaciones.
Necesitas un token de acceso válido antes de llamar a esta API o debes llamar a la API de Autenticación de Aplicaciones para obtener uno.
¡El token de acceso es válido por 30 minutos! (1799 segundos)
URL base
Prueba | https://qa-cloud-api.brp.com/dcp/<v3 o v4> |
|---|---|
Producción | https://cloud-api.brp.com/dcp/<v3 o v4> |
Recurso: Campañas
El recurso de Campañas proporciona información sobre un número de serie específico (VIN) y cierta información sobre las campañas relacionadas
Representación JSON
{
"vin": "2BPSCEKCXKV000009",
"usage_descr": "Personal/Recreational",
"target_market_descr": "Canada, US",
"product_code": "000CEKC00",
"platform_descr": "REV-G4",
"package_descr": "SP",
"model_year": "2019",
"model_descr": "Summit",
"length": "154\" (3923 mm)",
"is_cross_border": false,
"engine_type": "850 E-TEC",
"comments": "",
"color_descr": "Black",
"campaigns": [
{
"type_descr": "Regular",
"period_valid_to": "2022-01-31",
"period_valid_from": "2019-01-22",
"is_claimed": true,
"campaign_no": "0010",
"campaign_descr": "ENGINE COOLANT OUTLET HOSE LEAK",
"bulletin_no": "2019-9",
"articles": [
{
"last_publish_date": "2019-03-11T17:10:42.000Z",
"content_type": "PDF",
"article_url": "https://brp--qauat.my.salesforce.com/kAA0c000000fxSR?lang=en_US",
"article_no": "000136062",
"article_id": "kaA0c000000L42WEAS",
"article_descr": "SKI-DOO 2019-9 Engine Coolant Outlet Hose Leak_136062_WCN11Y019S01_en"
}
]
},
{
"type_descr": "Safety",
"period_valid_to": "9999-12-31",
"period_valid_from": "2019-07-02",
"is_claimed": false,
"campaign_no": "0012",
"campaign_descr": "FUEL INJECTOR POTENTIAL LEAK",
"bulletin_no": "2019-11",
"articles": [
{
"last_publish_date": "2019-07-03T16:52:52.000Z",
"content_type": "PDF",
"article_url": "https://brp--qauat.my.salesforce.com/kAA0c000000KzTR?lang=en_US",
"article_no": "000136589",
"article_id": "kaA0c000000L48jEAC",
"article_descr": "SKI-DOO 2019-11 Fuel Injector - Potential Leak_136589_WSC11Y019S02_en"
},
{
"last_publish_date": "2019-07-03T15:07:14.000Z",
"content_type": "URL",
"article_url": "https://brp--qauat.my.salesforce.com/kA90c000000004S?lang=en_US",
"article_no": "000136553",
"article_descr": "Ski-Doo Fuel Injector Bolts Replacement"
}
]
}
],
"brand_descr": "Ski-Doo Snowmobile"
}
Propiedades
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
serial_no | string | Número de serie de la unidad | Longitud máxima:18 |
usage_descr† | string | Describir el uso de la unidad | Longitud máxima:30 |
product_code | String | Código que identifica de manera única un producto. | Longitud máxima:18 |
model_descr | String | Descripción del producto. | Longitud máxima:40 |
- Las propiedades marcadas con una daga (†) se devuelven en el idioma solicitado.
Limitaciones y restricciones
Línea de producto
El concesionario puede solicitar las campañas de la unidad solo para la línea de producto que el concesionario soporta.
Dado que un concesionario no puede realizar trabajo en una línea de producto para la cual no está calificado, las campañas no son útiles.
URL del artículo
Cada campaña contiene una lista de artículos. En la información del artículo, la propiedad article_url contiene la URL del artículo.
Esta URL enlaza al artículo en BOSSWeb. Para acceder al artículo utilizando esta URL, tendrá que abrir una ventana del navegador web hacia la URL del artículo y el distribuidor deberá proporcionar sus credenciales de BOSSWeb para acceder al artículo.
Consulte la sección Uso de campañas para obtener artículos sobre cómo utilizar la información de la campaña.
Disponibilidad de idiomas
No todas las campañas están traducidas a todos los idiomas.
Si el idioma solicitado no está disponible, las campañas se devuelven en inglés.
Referencia de la API
curl --location 'https://cloud-api.brp.com/dcp/v3/unit/2BPSMXKF5KV000020/campaigns?language=en-US' \
--header 'Dealer-Number: 0000701207' \
--header 'Authorization: Bearer REPLACE_ME'
Tablas de referencia
Idiomas
Idioma en código de idioma ISO (ISO-639-1 + ISO 3166-1)
Formato: xx-XX
xx: código de idioma en minúsculas
XX: código de país en mayúsculas
Valores de códigos de idioma compatibles
Código | Idioma |
|---|---|
de | Alemán |
en | Inglés |
es | Español |
fi | Finés |
fr | Francés |
it | Italiano |
nl | Neerlandés |
no | Noruego |
pt | Portugués (Brasil) |
sv | Sueco |
Cómo hacer
Esta sección proporciona información sobre cómo obtener resultados específicos con la API.
Obtener campañas en francés
La siguiente consulta es un ejemplo rápido de cómo obtener las campañas en francés.
curl --location 'https://cloud-api.brp.com/dcp/v3/unit/2BPSMXKF5KV000020/campaigns?language=fr-CA' \
--header 'Dealer-Number: 0000691888' \
--header 'Authorization: Bearer YOUR ACCESS TOKEN'Usar campañas para obtener artículos
Llamar a la API de artículos
Al llamar a la API de campañas, deberías notar la propiedad article_no en el cuerpo de la respuesta JSON. Usa el número de artículo de las campañas para llamar a la API de artículos y obtener el PDF del artículo.
Consulta el API de artículos para más información.
Usando la URL del Artículo
Ten en cuenta que esta no es la forma preferida de recuperar un artículo de una campaña.
En el cuerpo de la respuesta JSON devuelta por la API, deberías notar la propiedad article_url. Copiar y pegar la URL en tu navegador te dirigirá a BOSSweb, como se muestra en la imagen a continuación.
Puedes iniciar sesión usando tus credenciales de QA BOSSweb y ser dirigido al PDF del artículo.
El artículo depende del idioma solicitado al llamar a la API.
El artículo se muestra en BOSSWeb, como se muestra en la imagen a continuación.
Manejo de Errores
Esta sección presenta varios escenarios de llamadas incorrectas o erróneas, que resultan en mensajes de error y resultados incorrectos.
400 Solicitud Incorrecta
El código de estado 400 generalmente se ve durante el desarrollo y la integración y no debería recibirse durante operaciones normales. La respuesta devuelta contiene la información necesaria para corregir el problema.
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 formato de idioma no es válido. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22692-1283834-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "ECMA 262 regex \"^[a-z]{2}-[A-Z]{2}$\" does not match input string \"\": []"
}
]
}
}
} | El formato de idioma válido es el siguiente Formato: xx-XX xx: código de idioma en minúsculas XX: código de país en mayúsculas Se debe ingresar un formato de idioma válido para producir una respuesta adecuada. |
Se devuelve si el VIN no es válido. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1483377-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "VIN YDV40501Afff was not found",
"payload": {
"errors": [
{
"title": "VIN YDV40501Afff was not found",
"code": "not_found"
}
]
}
}
} | Se debe ingresar un VIN válido para producir una respuesta adecuada. |
Se devuelve cuando el concesionario no tiene la línea de productos correspondiente al VIN. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11755-1483106-1.1",
"title": "not_found",
"meta": {
"service": "97",
"detail": "Sorry, the VIN entered does not match a product that you support.",
"payload": {
"errors": [
{
"title": "Sorry, the VIN entered does not match a product that you support.",
"code": "unauthorized"
}
]
}
}
}
| El concesionario debe admitir la línea de productos del VIN. |
Se devuelve cuando falta el número de concesionario. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22691-1284376-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "Header parameter 'Dealer-Number' is required on path '/unit/{vin}/campaigns' but not found in request.: []"
}
]
}
}
}
| Se debe proporcionar un número de concesionario en el encabezado de la solicitud. |
Se devuelve cuando el número de concesionario no es válido. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1482909-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "No dealer principal was found for Dealer-Number",
"payload": {
"errors": [
{
"title": "No dealer principal was found for Dealer-Number: 000011hhhh",
"code": "not_found"
}
]
}
}
} | El número de concesionario proporcionado en el encabezado de la solicitud debe ser un número de concesionario BRP válido. |
401 No autorizado
El código de estado de error 401 No autorizado se devuelve cuando intentas llamar a la API con un access_token expirado.
Tienes que obtener un nuevo access_token con una llamada a la API de Autenticación de Aplicaciones.
El código de estado de error 401 Unauthorized también se devuelve si no solicitaste acceso a la API creando un ticket en el Jira de DCP.
Cuando estés listo para comenzar a trabajar en una API, debes crear un ticket de certificación en Jira, como se describe en la sección Actividades de Certificación con Jira.
Si ya empezaste a trabajar en una API y perdiste acceso, crea un ticket de soporte como se describe en la sección Abrir un Ticket de Soporte.
404 No Encontrado
El código de estado 404 Not Found se devuelve cuando el VIN solicitado no se encuentra o no tiene ninguna campaña.
Respuesta | Resolución |
|---|---|
Devuelto cuando el VIN introducido no se encuentra {
"status": "404",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1483377-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "El VIN YDV40501Afff no fue encontrado",
"payload": {
"errors": [
{
"title": "El VIN YDV40501Afff no fue encontrado",
"code": "not_found"
}
]
}
}
} | Debe introducirse un VIN correcto para que la API responda adecuadamente. |
Devuelto cuando el VIN es válido, pero no tiene ninguna campaña activa. {
"status": "404",
"id": "rrt-065e1c5bbf0ebc061-b-ea-31810-5677524-5.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "El VIN 3JB2GEG2XLJ006676 no tiene ninguna campaña.",
"payload": {
"errors": [
{
"title": "El VIN 3JB2GEG2XLJ006676 no tiene ninguna campaña.",
"code": "not_found"
}
]
}
}
} | No hay nada que hacer excepto mostrar un mensaje al concesionario informándole que no hay ninguna campaña activa para este VIN. |
Requisitos de DSP
Requisitos funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | La lista de campañas aplicables a la unidad debe mostrarse al concesionario. |
2 | Obligatorio | El indicador y el texto de advertencia de mercado transfronterizo/mercado gris deben mostrarse al concesionario. |
3 | Obligatorio | Los mensajes de error deben mostrarse al concesionario. |
4 | Obligatorio | Se debe mostrar un mensaje al usuario cuando la unidad no tenga una campaña activa. |
Actividades de certificación
Esta sección presenta todas las actividades de certificación y validaciones que deben completarse para certificar la API.
Aseguramiento de la calidad
Las pruebas enumeradas en la tabla a continuación deben realizarse correctamente en el entorno de prueba antes de que pueda comenzar la fase piloto del concesionario.
Lista de VIN
Línea de producto | VIN |
|---|---|
Motos de nieve (SNO) | 2BPSMXKF5KV000020 |
ATV | RLVDGF119FVN00027 |
Sea-Doo (PWC) | YDV00005G819 |
Side-by-Side (SSV) | 3JB7VAX42MK000288 |
3-Ruedas (3WV) | 3JB2FEG45PJ002724 |
ID | Prueba | Resultado esperado |
|---|---|---|
1 | Llame a la API de campañas para cada idioma y la línea de productos del VIN que admite su concesionario. | Muestre toda la información relevante de la campaña relacionada con el VIN ingresado. |
2 | Llame a la API de campañas con la línea de productos de un VIN que no sea compatible con su concesionario. | Se muestra un registro de error con estado 400: "Lo sentimos, el VIN ingresado no coincide con un producto que usted admite. |
Piloto del concesionario
La tabla a continuación describe los parámetros y validaciones del piloto del concesionario.
Parámetro | Valor |
|---|---|
Entorno | Producción |
Número de concesionarios | 1 a 3 |
Duración | 1 semana |
Validación 1 | Enviar una captura de pantalla de las campañas para uno o dos VIN para cada línea de producto soportada por el concesionario. |
Postman
Esta sección describe lo que está disponible en Postman para explorar la API.
Entornos
Un entorno de Postman está disponible para probar la API de Campañas. Este entorno de Postman contiene variables utilizadas por las consultas y configuradas para conectarse al entorno de prueba.
Colecciones
La colección DMS - Campañas contiene ejemplos de llamadas API para recuperar campañas de vehículos.