API de artículos
Comenzando
La API de Artículos permite que sus distribuidores vean un PDF de artículo en su DMS para un número de artículo específico.
Cuando un cliente trae una unidad para mantenimiento o reparación, una parte importante de las actividades del distribuidor es usar los artículos aplicables a la campaña de garantía de la unidad. Al usar los artículos, su distribuidor puede ver la campaña de garantía.
Un artículo proporciona información sobre:
- Problema
- Solución
- Piezas requeridas
- Acciones correctivas
El artículo detalla todo e incluye imágenes, asegurando que sus distribuidores no tengan problema en solucionar el inconveniente.
¿Dónde empezar? ¡Léame primero!
Antes de comenzar a trabajar en 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 | Baja |
Enviar datos a BRP | CRM | V4 - Norteamérica | Un poco más |
Transacción con BRP | | | Algo más |
Autenticación
La API está usando Autenticación de la Aplicación.
Necesitas un token de acceso válido antes de llamar a esta API o tienes que 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: Artículos
El recurso de artículos proporciona información sobre un artículo específico.
Representación JSON
{
"article_no": "000136021",
"article_descr": "SKI-DOO 2019-11 Fuel Injector - Potential Leak_136589_WSC11Y019S02_en",
"article_url": "https://brp--qauat--c.visualforce.com/apex/Article_Detail_Warranty_Bulletin?lang=en_US&id=kAA0c000000KzTR#googtrans(en|en)",
"last_publish_date": "2019-07-03T12:52:50Z",
"content_type": "PDF",
"content":"pdf…!@#$%^&DFRUIJHKODFGHUJK^&U*I(OGHJKHJKKJbase64dsadasadsdasa"
}
Propiedades
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
article_no* | string | La cadena que se utiliza para identificar el artículo. | Longitud máxima:18 |
article_descr | string | Descripción del artículo. | Cadena |
article_url | string | La URL se utiliza para mostrar el artículo en BOSSweb. | Cadena |
last_publish_date | Fecha-hora | Fecha y hora en que el artículo ha sido publicado. En formato ISO 8601. | Formato: yyyy-mm-ddThh:mm:ssZ |
content_type | string | Descripción del tipo de artículo. Uno de los siguientes:
| Longitud máxima:3 |
content | string | Detalles del artículo.
| Cadena máxima |
Limitaciones y restricciones
URL del artículo
Para usar la URL del artículo para mostrar el contenido del artículo, el distribuidor debe iniciar sesión en BOSSWeb.
El contenido del artículo se almacena en SalesForce. El distribuidor solo puede acceder a él a través de BOSSWeb, por lo que la URL es una URL del Centro de Conocimiento de BOSSWeb.
La forma preferida de mostrar el contenido del artículo es usar el PDF.
El PDF está codificado en base64 y debe convertirse en un PDF binario antes de mostrarse.
Disponibilidad de idiomas
No todos los artículos están traducidos a todos los idiomas.
Si el idioma solicitado no está disponible, el artículo se devuelve en inglés.
Referencia de la API
curl --request POST 'https://qa-cloud-api.brp.com/dcp/v3/article/000020951?language=fr-CA' \
--header 'Dealer-Number: 0000690006' \
--header 'Authorization: Bearer REPLACE_ME'Cómo hacerlo
Esta sección proporciona información sobre cómo obtener resultados específicos con la API.
Obtener artículos en francés
La consulta siguiente es un ejemplo rápido de cómo obtener el artículo en francés.
curl --location 'https://qa-cloud-api.brp.com/dcp/v3/article/000020951?language=fr-CA' \
--header 'Dealer-Number: 0000690006' \
--header 'Authorization: Bearer YOUR ACCESS TOKEN'Una vez convertido de la codificación base64 a un PDF, el documento puede mostrarse y se ve como 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 inadecuados.
400 Solicitud Incorrecta
El código de estado 400 generalmente se observa durante el desarrollo y la integración y no debería recibirse durante las operaciones normales. La respuesta devuelta contiene la información necesaria para corregir el problema.
Muchos problemas pueden causar un código de estado 400, y los más comunes se enumeran en la tabla a continuación.
Respuesta | Resolución |
|---|---|
Se devuelve si el formato del idioma es inválido. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22691-415152-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "La expresión regular ECMA 262 \"^[a-z]{2}-[A-Z]{2}$\" no coincide con la cadena de entrada \"AA-BBB\": []"
}
]
}
}
} | El formato válido del idioma es el siguiente Formato: xx-XX xx: código de idioma en minúsculas XX: código de país en mayúsculas Debe introducirse un formato de idioma válido para producir una respuesta adecuada. |
Se devuelve cuando falta el número de distribuidor. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22692-415715-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{\r
"message": "El parámetro de cabecera 'Dealer-Number' es obligatorio en la ruta '/article/{article_no}' pero no se encontró en la solicitud.: []"
}
]
}
}
} | Debe proporcionarse un número de distribuidor en la cabecera de la solicitud. |
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 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.
404 No Encontrado
El código de estado 404 Not Found se devuelve cuando no se encuentra el artículo.
Respuesta | Resolución |
|---|---|
Devuelto cuando el número de artículo introducido no se encuentra {
"status": "404",
"id": "rrt-00a574511a562afb5-b-ea-22206-2601758-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Error del backend",
"payload": {
"status": "404",
"errors": [
{
"title": "El artículo 123456789 no fue encontrado",
"code": "not_found"
}
]
}
}
} | Se debe introducir un número de artículo correcto para que la API pueda devolver una respuesta adecuada. Para que un número de artículo sea correcto, debe encontrarse en la lista de números de artículo. |
Requisitos de DSP
Requisitos Funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | Los mensajes de error deben mostrarse al concesionario. |
2 | Obligatorio | Los artículos aplicables a la campaña deben mostrarse a los concesionarios. |
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 con éxito en el entorno de prueba antes de que pueda comenzar la fase piloto para concesionarios.
ID | Prueba | Resultado Esperado |
|---|---|---|
1 | Llame a la API de Artículos para cada idioma que su DMS soporte. Artículo #: 000136062 | Mostrar toda la información relevante del artículo correspondiente al número de artículo ingresado. |
2 | Llame a la API con un número de artículo no válido. Artículo #: 123456789 | Se muestra un registro de error con estado 400 "Artículo no encontrado" |
Piloto de Concesionarios
La tabla a continuación describe los parámetros y validaciones del piloto de concesionarios.
Parámetro | Valor |
|---|---|
Entorno | Producción |
Número de distribuidores | 1 a 3 |
Duración | 1 semana |
Validación 1 | Enviar una captura de pantalla de un artículo para uno o dos números de artículo, para cada distribuidor en el piloto. |
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 Artículos. Este entorno de Postman contiene variables utilizadas por las consultas y está configurado para conectarse al entorno de prueba.
Colecciones
La colección DMS - Artículos contiene ejemplos de llamadas API para recuperar un artículo.