API de garantía
Primeros Pasos
El objetivo de la API de Reclamaciones de Garantía es mejorar la experiencia del usuario para enviar reclamaciones de garantía en BOSSWeb. El objetivo es reducir el tiempo requerido y la cantidad de entradas manuales necesarias para completar los formularios, rellenando previamente el borrador de la reclamación con información de una orden de reparación. Luego, el distribuidor va a BOSSWeb para completar la reclamación.
Solo se pueden crear borradores de reclamaciones de unidad a través de la API, las cuales están relacionadas con problemas del vehículo cubiertos por una garantía.
¿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 | 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á utilizando Autenticación de aplicaciones.
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/v4 |
|---|---|
Producción | https://cloud-api.brp.com/dcp/v4 |
Recurso: Reclamo
Este recurso se utiliza para trabajar con un reclamo de garantía.
Representación JSON
{
"dealer_no": "0000694307",
"vin": "2BPSMBMB2MV000203",
"odometer": "1050.5",
"rro_creation_date": "2022-01-10T08:20:50Z",
"date_of_repair": "2022-01-10T14:10:09Z",
"causal_part": "415129449",
"system_code": "1-Engine",
"work_order_no": "4334-01",
"symptom_description": "The part broke. Customer heard noise.",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "415129449",
"quantity": 1
}
]
}Propiedades
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
dealer_no * | cadena | Código que identifica de manera única a un concesionario. Debe tener 10 caracteres. Si tiene menos de 10 caracteres, agregue '0' al inicio. | Longitud: 10 |
vin * | cadena | El Número de Identificación del Vehículo (VIN). | Máx Longitud: 18 |
odometer * | número | Valor del odómetro de la unidad (Km o millas) de la orden de reparación. | Precisión: 0.1 Longitud Máx: 18 |
rro_creation_date * | cadena | La última fecha y hora en que este recurso cambió, en formato ISO 8601 | aaaa-mm-ddThh:mm:ssZ |
date_of_repair* | cadena | Fecha de reparación, en formato ISO 8601 | aaaa-mm-ddThh:mm:ssZ |
system_code* | cadena | Uno de: "1-Motor", "2-Sistema de Combustible", "3-Ignición", "4-Arranque", "5-Transmisión / Propulsión", "6-Frenos", "7-Dirección / Suspensión / Sistema de Tracción Delantera", "8-Suspensión / Sistema de Tracción Trasera", "9-Carrocería", "10-Eléctrico", "11-Accesorios, Herramientas Especiales, Otros", "12-Estructura del Casco", "13-Regulaciones CARB y EPA", "14-Regulaciones CARB", "15-Batería y Neumáticos" | |
casual_part* | cadena | El número de parte de la pieza defectuosa. | Longitud Máx: 18 |
symptom_description* | cadena | La descripción de los síntomas que llevaron al cliente a investigar. | Longitud Máx: 512 |
remedy_description* | cadena | La descripción de la solución del concesionario para resolver el problema. | Longitud Máx: 512 |
defect_description* | cadena | La descripción del problema proporcionada por el concesionario | Longitud Máx: 512 |
work_order_number* | cadena | Número de orden de trabajo (identificador del documento) + Número de tarea 👉 El valor en el campo work_order_number debe ser único. | Longitud Máx: 15 <orden_de_trabajo>-<código_de_tarea> |
installed_parts | array | La lista de piezas a instalar en el vehículo. |
|
installed_parts.item_id | cadena | El ID de cada pieza que se instalará. | Longitud Máx: 18 |
installed_parts.quantity | entero | La cantidad de la pieza que se instalará. |
|
* Estos campos son obligatorios.
Recurso: Trabajo
Este recurso se utiliza para recuperar el estado de creación de una reclamación borrador para un trabajo.
Representación JSON
{
"job_id": "DMS-20221219007781",
"claim_status": "failed",
"failure_reason": "Unit is out of Warranty",
"claim_number": null
}Propiedades
Propiedad | Tipo | Definición |
|---|---|---|
job_id | string | El ID del trabajo que procesa la creación del reclamo de garantía preliminar. |
claim_status | string | El estado de la creación del reclamo de garantía preliminar. |
failure_reason | string | La razón por la cual no se creó un reclamo de garantía preliminar. Por ejemplo: "La unidad está fuera de garantía". |
claim_number | string | El campo contiene el número de reclamo cuando se crea el reclamo de garantía preliminar. |
Recurso: Trabajos
Este recurso se utiliza para obtener el estado de creación de reclamaciones preliminares para una lista de trabajos.
Se devuelve al llamar al servicio Get con una lista de trabajos.
Representación JSON
{
"items": [
{
"job_id": "DMS-20230420009063",
"claim_status": "success",
"failure_reason": null,
"claim_number": "C010469"
},
{
"job_id": "DMS-20230420009064",
"claim_status": "success",
"failure_reason": null,
"claim_number": "C010470"
},
{
"job_id": "DMS-20221104000204",
"claim_status": "failed",
"failure_reason": "Part Price API is not responding",
"claim_number": null
},
{
"job_id": "DMS-20230710032398",
"claim_status": "failed",
"failure_reason": "Unit claims are disabled on this unit due to campaign inclusion. At least one outstanding campaign repair has to be completed before unit claims will be enabled. Campaign claims need to be fulfilled directly in Tavant.",
"claim_number": null
}
]
}Propiedades
Propiedad | Tipo | Definición |
|---|---|---|
elementos | Lista de objetos | |
job_id | cadena | El id del trabajo que procesa la creación del reclamo preliminar de garantía. |
claim_status | cadena | El estado de la creación del reclamo preliminar de garantía. |
failure_reason | cadena | La razón por la cual no se creó un reclamo preliminar de garantía. Por ejemplo: "La unidad está fuera de garantía". |
claim_number | cadena | El campo contiene el número de reclamo cuando se crea el reclamo preliminar de garantía. |
Limitaciones y restricciones
Tipos de reclamaciones
Esta API está limitada a la creación de borradores de reclamos de unidades. Los reclamos de piezas y los reclamos de campaña no son compatibles.
Comprender la garantía
Esta sección da seguimiento a la información proporcionada en la sección anterior Primeros pasos y analiza con más detalle los diferentes servicios de la API de Garantía.
Vista del proceso a alto nivel
La imagen a continuación muestra una vista de alto nivel del proceso preliminar de reclamación de garantía.
El concesionario selecciona una orden de reparación cerrada del DMS y lanza la función de borrador de reclamación de garantía.
El DMS muestra una ventana para permitir al concesionario ingresar la información requerida que no está disponible en la orden de reparación:
- El código del sistema.
- El número de parte causal.
- Las descripciones de síntoma, remedio y defecto.
Después de proporcionar la información requerida, el concesionario envía el borrador de la reclamación de garantía.
La información del borrador de la reclamación de garantía se envía a la API de Garantía, que la reenvía a la API de Tavant.
Tavant crea un trabajo con la información del borrador de la reclamación de garantía y lo añade a la cola de procesamiento.
El ID del trabajo se devuelve al DMS a través de la API de Garantía.
Tavant procesa el trabajo en la cola y el borrador de la reclamación de garantía se crea después de un momento.
El borrador de la reclamación de garantía está entonces disponible en BOSSWeb para su finalización.
El concesionario va a BOSSweb y completa y envía la reclamación de garantía.
Mientras Tavant procesa los trabajos, su DMS debe consultar la API de Garantía para obtener el estado del trabajo. Una vez que el trabajo se completa y se crea el borrador de la reclamación de garantía, el número de reclamación devuelto debe guardarse y mostrarse al concesionario.
De esta manera, el concesionario sabe cuándo puede ir a BOSSWeb para completar la reclamación.
Estado de creación en BOSSWeb
En BOSSWeb, el concesionario tiene acceso a Transferencias DMS en el módulo de gestión de garantía, que muestra las solicitudes de reclamación de garantía en borrador enviadas por el DMS.
Borrador
La vista muestra las reclamaciones de garantía en borrador de forma predeterminada. La Número de Acuse de Recibo columna muestra el ID del trabajo que la API de Garantía devuelve a su DMS en la carga útil de la respuesta de Creación.
El menú de estado permite al concesionario cambiar el filtro.
Exitoso
La vista Exitosa muestra las reclamaciones de garantía en borrador creadas por el proceso de Tavant. El botón Ir a la Reclamación permite al concesionario ir a la reclamación en borrador para completarla y enviarla.
Fallido
El Fallido vista muestra las solicitudes de reclamo de garantía en borrador que han fallado. El concesionario puede hacer clic en el botón Ver Errores para obtener los detalles del error.
Cuando llamas para obtener el estado del trabajo, normalmente recibirás el mismo error a través de la API de Garantía.
En Progreso
La vista En Progreso muestra las solicitudes de reclamo de garantía en borrador que aún están en la cola de Tavant y esperando ser procesadas.
La mayoría de las veces, esta vista está vacía.
Posibles Errores
La creación del reclamo de garantía en borrador se rechaza si:
- El número de concesionario no es válido.
- El VIN no es válido.
- El número de la pieza causal no es válido.
- Un campo obligatorio distinto de la descripción del síntoma está vacío.
- El código del sistema no es válido o está vacío.
- Un campo de fecha utiliza un formato no válido.
- Al número de orden de trabajo le falta el número de tarea.
- Ya se ha enviado un borrador de reclamo de garantía para la tarea de la orden de reparación.
Si un número de parte instalado no es una parte BRP, la parte se excluye de la creación de la reclamación.
Referencia de API
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/claim' \
--header 'Dealer-Number: 0000694307' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 20OZBLG4sVhTtmfEexlUQEw9OFiY' \
--data '{
"dealer_no": "0000691888",
"vin": "2BPSGDNA1NV000302",
"odometer": 1090.5,
"rro_creation_date": "2023-02-10T09:35:38-05:00",
"date_of_repair": "2023-02-11T09:35:38-05:00",
"causal_part": " 705203477 ",
"system_code": "11-Accessories, Special Tools, Others",
"work_order_no": "3001-02",
"symptom_description": "The part broke. Customer heard noise. By Maxime",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "219800518",
"quantity": 2
}
]
}'curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20230705032364' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs?jobs_id=DMS-20221104000204,DMS-20230710032398,DMS-20230420009063,DMS-20230420009064' \
--header 'Dealer-Number: 0000691695' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'Cómo hacerlo
Esta sección proporciona información sobre cómo obtener resultados específicos con la API.
Crear un Reclamo de Garantía Borrador
La respuesta es un ejemplo rápido de cómo crear un reclamo de garantía en borrador para un número VIN específico.
Cambie el número de concesionario o VIN para crear diferentes reclamos para distintas líneas de productos.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/claim' \
--header 'Dealer-Number: 0000694307' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"dealer_no": "0000691888",
"vin": "3JBUKAP46NK000775",
"odometer": 1090.5,
"rro_creation_date": "2023-02-10T09:35:38-05:00",
"date_of_repair": "2023-02-11T09:35:38-05:00",
"causal_part": " 705203477 ",
"system_code": "11-Accessories, Special Tools, Others",
"work_order_no": "200-10",
"symptom_description": "The part broke. Customer heard noise. By Maxime",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "219800518",
"quantity": 2
}
]
}'Obtener el Estado de un Trabajo de Reclamo de Garantía Borrador
Obtiene el estado de un reclamo de garantía en borrador enviado.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20221219007781' \
--header 'Authorization: Bearer 6dVfKN4VFqsl0DMDRfHPLUOunwBx'Manejo de errores
Esta sección presenta varios escenarios de llamadas incorrectas o inapropiadas, que dan como resultado mensajes de error y resultados incorrectos.
Error 400 (Solicitud incorrecta)
El código de estado 400 se observa generalmente 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; los más comunes se enumeran en la tabla siguiente.
Publicación
Respuesta | Resolución |
|---|---|
Devuelto si el número de distribuidor no se ingresa, es demasiado corto o demasiado largo {
"status": "400",
"id": "rrt-07545d3b30b8d2411-b-ea-6909-1591317-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "El parámetro 'Dealer-Number' es obligatorio pero falta."
},
{
"message": "[Path '/dealer_no'] La cadena \"12345678\" es demasiado corta (longitud: 8, mínimo requerido: 10): []"
}
]
}
}
}
| Para producir una respuesta correcta, debe ingresarse un número de distribuidor válido que contenga solo 10 números. No puede ser más largo ni más corto. |
Devuelto si la pieza causal no se ingresa o no es válida. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1695836-1.1",
"title": "bad_request",
"meta": {
"service": "15",
"detail": "Número de causal_part no válido ABC."
}
}
--------------------------------------
{
"status": "400",
"id": "rrt-0e20a46609994a8ad-c-ea-22696-1603343-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "El objeto tiene propiedades obligatorias faltantes ([\"causal_part\"]): []"
}
]
}
}
}
| Debe ingresarse una pieza causal válida para producir una respuesta correcta. |
Devuelto cuando no se ingresa un código de sistema o no es válido. {
"status": "400",
"id": "rrt-007c58ce55d14f4ff-d-ea-23462-1707968-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "[Path '/system_code'] Valor de instancia (\"16-ABCD\") no encontrado en enum (valores posibles: [\"1-Engine\",\"2-Fuel System\",\"3-Ignition\",\"4-Starting\",\"5-Transmission / Propulsion\",\"6-Braking\",\"7-Steering / Suspension / Front Drive System\",\"8-Suspension / Rear Drive System\",\"9-Body\",\"10-Electrical\",\"11-Accessories, Special Tools, Others\",\"12-Hull Structure\",\"13-CARB and EPA Regulations\",\"14-CARB Regulations\",\"15-Battery and Tyres\"]): []"
}
]
}
}
}
| Debe ingresarse un código de sistema válido para producir una respuesta correcta. Debe ingresarse uno de los códigos de sistema siguientes. "1-Motor" "2-Sistema de Combustible" "3-Ignición" "4-Arranque" "5-Transmisión / Propulsión" "6-Frenado" "7-Dirección / Suspensión / Sistema de Tracción Delantera" "8-Suspensión / Sistema de Tracción Trasera" "9-Carrocería" "10-Eléctrico" "11-Accesorios, Herramientas Especiales, Otros" "12-Estructura del Casco" "13-Regulaciones CARB y EPA" "14-Regulaciones CARB" "15-Batería y Neumáticos" |
Obtener
Respuesta | Resolución |
|---|---|
Se devuelve cuando el ID del trabajo no se ingresa en la URL. {
"status": "400",
"id": "rrt-07cdd77f98c381924-d-ea-22529-1664059-1",
"title": "solicitud_incorrecta",
"meta": {
"service": "01",
"detail": "falló la validación de la solicitud",
"payload": {
"details": [
{
"message": "El parámetro de consulta 'jobs_id' es obligatorio en la ruta '/warranties/jobs' pero no se encontró en la solicitud.: []"
}
]
}
}
} | Se debe ingresar un ID de trabajo válido en la URL para verificar el estado de una reclamación. Un ejemplo de un trabajo se ve así: DMS-20221219007781
|
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 No Encontrado es devuelto por el servicio Obtener Estado de la Tarea cuando el ID de tarea solicitado no se encuentra.
{
"status": "404",
"id": "rrt-07cdd77f98c381924-d-ea-22528-1664528-1.1",
"title": "not_found",
"meta": {
"service": "17",
"detail": "job_id 00000000 not found"
}
}Requisitos de DSP
Requisitos Funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | El borrador de la reclamación de garantía debe crearse a partir de una orden de reparación. |
2 | Obligatorio | Los mensajes de error deben mostrarse al concesionario. |
3 | Obligatorio | La lista de números de reclamación enviados debe 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 correctamente en el entorno de pruebas antes de que pueda comenzar la fase piloto del distribuidor.
ID | Prueba | Resultado Esperado |
|---|---|---|
1 |
|
|
2 |
|
|
3 |
|
|
Piloto del Concesionario
La siguiente tabla 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 del estado de creación de un reclamo de garantía en borrador para un VIN por cada línea de producto soportada por el concesionario. |
Validación 2 | Un concesionario debe poder encontrar VINs "En garantía" para producir una respuesta adecuada. |
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 Garantía. Este entorno de Postman contiene variables usadas por las consultas y está configurado para conectarse al entorno de pruebas.
Colecciones
La colección DMS - Garantía incluye ejemplos de llamadas API para crear un reclamo de garantía en borrador y recuperar el estado del trabajo.