Información Técnica
Esta sección presenta información técnica básica sobre las API de DCP para ayudarte a comenzar tu desarrollo.
Entornos
Hay dos entornos disponibles para llamar a las API de DCP: prueba y producción.
La URL base selecciona el entorno para llamar a una API de DCP.
Prueba | https://qa-cloud-api.brp.com/dcp |
|---|---|
Producción | https://cloud-api.brp.com/dcp |
Información importante:
- Los dos entornos utilizan diferentes conjuntos de credenciales
- El entorno de prueba a veces tiene datos limitados o antiguos, pero no afecta el comportamiento de la API.
- El entorno de producción debe ser utilizado solo para la fase piloto del concesionario de certificación y una vez que la API esté certificada.
Una vez que tenga sus credenciales, el entorno de prueba se puede utilizar durante sus actividades de desarrollo para validar la integración de la API DCP en su DSP.
El entorno de prueba también se utiliza durante las actividades de certificación descritas en el Proceso de Certificación sección.
Información General
Esta sección presenta información general sobre las API de DCP.
Formato de Carga Útil de Consulta
Todas las API de DCP utilizan una carga útil JSON para las solicitudes y las respuestas.
Al llamar a una API de DCP para enviar datos a BRP, la carga útil recibida por la API de DCP se valida contra una Especificación OpenAPI (OAS).
Si la carga útil recibida por la API de DCP no coincide con la OAS, la API de DCP devuelve un error 400 Solicitud Incorrecta.
Al llamar a una API de DCP para enviar datos a BRP, la carga útil recibida por la API de DCP se valida contra una Especificación OpenAPI (OAS).
Si la carga útil recibida por la API de DCP no coincide con la OAS, la API de DCP devuelve un error 400 Solicitud Incorrecta.
La propiedad del objeto JSON en error se proporciona en la carga útil de respuesta de error.
Por ejemplo, si la carga útil contiene una propiedad de fecha y el formato de fecha es inválido, se recibe la siguiente respuesta de error.
{
"status": 400,
"id": "rrt-07783bca845d5f9ca-d-ea-4205-62358060-1",
"title": "bad_request",
"meta": {
"service": "01",
"code": "request validation failed",
"errors": {
"details": [
{
"message": "[Path '/date_of_repair'] String \"20223-01-10T14:10:09Z\" is invalid against requested date format(s) [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,12}Z]: []"
}
]
}
}
}Este error se observa generalmente durante la integración de la API de DCP en el DSP y se ve durante las fases de pruebas y certificación.
Formato de Carga Útil de Respuesta
La carga útil de respuesta devuelta por las API de DCP generalmente se prepara utilizando datos recibidos de los sistemas de backend. En algunos casos, se realiza un mapeo entre el valor devuelto por el backend y el valor devuelto en la carga útil de respuesta.
Puede suceder que los valores para un campo en la carga útil de respuesta no estén disponibles, por ejemplo, si un valor devuelto por el backend falta en el mapeo de campos.
Esta situación se gestiona utilizando las siguientes reglas.
- Todos los campos son siempre presentes en la carga útil.
- Si el campo es un string y no hay valor para devolver, el campo se establece en una cadena vacía (“”).
- Si no se devuelve ningún valor para todos los demás tipos de campo, el campo se establece en el null valor. Por ejemplo, si un campo es un número o una fecha y falta el valor, se devuelve el null valor
- Si el campo es un array sin valor para devolver, la carga útil contiene un array vacío. Por ejemplo: "pricings": [ ]
Ruta: Singular versus Plural
Las rutas de la API de DCP utilizan la convención singular/plural.
- Cuando el endpoint trabaja en un solo objeto, la ruta utiliza el singular.
- Por ejemplo, la ruta es así cuando se llama a la Partes API para buscar una pieza
- El plural se utiliza cuando el endpoint trabaja en una colección de objetos.
- Por ejemplo, al llamar a la Partes API para obtener todos los cambios desde una fecha específica, la ruta es así:
Asegúrate de verificar la ruta del endpoint de la API en el Catálogo de API.
Separador Decimal
Todos los campos numéricos con decimales utilizan el punto(.) como separador decimal. La coma (,) no es compatible como separador decimal.
Paginación
Algunas API de DCP devuelven una lista de objetos. Por ejemplo, la API de piezas devuelve un catálogo de partes, y la API de Orden de Piezas Obtener servicio puede devolver una lista de órdenes de partes.
En este caso, los datos son demasiado grandes para ser devueltos en una sola carga de respuesta, así que la paginación se utiliza para dividir la respuesta en muchas cargas.
Se proporciona un mecanismo para que el llamador navegue por las páginas. La respuesta contiene la enlaces propiedad, que contiene las anterior y siguiente propiedades para navegar por las páginas.
,
"links": {
"previous": null,
"next": "https://qa-cloud-api.brp.com/dcp/v4/parts?language=en-US&last_changed_date=1900-01-01&sales_org=3020¤cy=USD&limit=200&page=2"
}Si anterior es nulo, estás en la primera página.
Si siguiente es nulo, estás en la última página.
Algunas API también devuelven una meta propiedad que proporciona información sobre la cantidad de datos devueltos, el número de páginas, etc.
"meta": {
"total_records": 72062,
"total_pages": 361,
"current_page": 1,
"limit": 200
}Catálogo de API
Las referencias técnicas de la API DCP están disponibles en la Catálogo de API sección.
Para cada API DCP, las siguientes secciones proporcionan toda la información necesaria sobre la API.
- Introducción: una introducción a la API, incluyendo el contexto técnico y comercial.
- Información técnica: autenticación, resumen de recursos, límites y restricciones, etc.
- La referencia de la API: los servicios disponibles con sus parámetros, carga útil, etc.
- Cómo hacerlo: ejemplos de cómo usar la API DCP para realizar una función.
- Manejo de errores: información sobre cómo manejar los errores más comunes.
- Requisitos de DSP: requisitos obligatorios y opcionales sobre cómo implementar una función utilizando la API DCP. También contiene las actividades de certificación.
- Postman: una descripción de los recursos disponibles para validar la integración de la API DCP utilizando Postman.
Características de la API
La sección de características de cada API Comenzando sección presenta las características generales de la API, como se muestra a continuación.
Las dos características más importantes son:
- Tipo de DSP: indica si un DMS, un CRM, o ambos utilizan la API DCP.
- Versión de DCP: indica qué versiones de DCP de la API son compatibles.
Tipo de API | Tipo de DSP | Versión DCP | Complejidad |
|---|---|---|---|
Obtener datos del BRP | DMS | V3 - Internacional | Bajo |
Enviar datos a BRP | CRM | V4 - América del Norte | Un poco más |
Transacción con BRP | | | Algo más |
Versión DCP
Para la mayoría de las API de DCP, no verás diferencias en la carga útil y las llamadas entre las versiones 3 y 4. Para estas API de DCP, las diferencias están en los sistemas de backend, que es por eso que las versiones de la API están documentadas en la misma sección. La Características sección de la Introducción sección indica qué versiones de DCP de la API son compatibles.
Si hay diferencias en la carga útil y/o llamadas entre las versiones de DCP para una API de DCP, las diferentes versiones están documentadas en secciones específicas del Catálogo de API.
Por ejemplo, la API de Orden de Piezas podría tener una carga útil ligeramente diferente entre la V3 - Internacional y V4 - Norteamericano versiones.
En este caso, habría dos secciones en el Catálogo de API:
- API de Orden de Piezas V3
- API de Orden de Piezas V4
Requisitos de DSP
El equipo de DCP puede definir requisitos funcionales para su DSP para asegurarse de que la integración de la API de DCP cumpla con los objetivos comerciales.
Hay dos tipos de requisitos funcionales que se pueden definir: obligatorios y opcionales.
Requisitos Obligatorios
Un requisito obligatorio es un requisito funcional que debe ser implementado por su DSP.
La implementación del requisito se valida y verifica durante el proceso de certificación.
Si un requisito obligatorio no se implementa correctamente, la API de DCP no puede ser certificada.
Un ejemplo de un requisito obligatorio es que una API de DCP debe ser llamada automáticamente todos los días para recuperar la última actualización del catálogo de partes.
Requisito Opcional
Un requisito opcional es un requisito funcional que el equipo de DCP sugiere encarecidamente que implemente en su DSP.
Estos requisitos añaden valor comercial a la integración de la API de DCP en el DSP. Sin embargo, el equipo de DCP es consciente de que el DSP puede tener limitaciones que impidan implementar estos requisitos, por lo que son opcionales.
Postman
La información técnica de la mayoría de las API de DCP incluye un conjunto de objetos de Postman: entorno y colecciones.
Para usar estos objetos, debes exportarlos del espacio de trabajo compartido de Postman e importarlos en tu entorno de equipo de Postman.
Antes de usar las colecciones y la consulta, debes cambiar las variables de entorno para usar tu información.
Debes cambiar todos los valores que comienzan con "YOUR_"
Resumen del Manejo de Errores
El manejo de errores es un aspecto importante de las API de DCP. Los DSP que utilizan las API de DCP deben implementar un manejo de errores sólido para proporcionar al concesionario información significativa.
El Catálogo de API proporciona la lista de códigos de estado específicos que pueden ser devueltos por una API y los pasos a seguir cuando se recibe el código de estado.
Códigos de estado de respuesta
Las API de DCP utilizan el rango de códigos de estado estándar RFC 9110:
- 2xx (Exitoso): La solicitud fue recibida, entendida y aceptada con éxito
- 4xx (Error del Cliente): La solicitud contiene una sintaxis incorrecta o no puede ser cumplida
- 5xx (Error del Servidor): El servidor no pudo cumplir con una solicitud aparentemente válida
Las API de DCP devuelven los siguientes códigos de estado.
Código de Estado | Descripción |
|---|---|
200 OK | Indica que la solicitud ha tenido éxito. El contenido enviado en una respuesta 200 depende del método de solicitud. |
400 Solicitud Incorrecta | Indica que el servidor no puede o no procesará la solicitud debido a algo que se percibe como un error del cliente (por ejemplo, sintaxis de solicitud mal formada, enmarcado de mensaje de solicitud no válido o enrutamiento de solicitud engañoso). IMPORTANTE: el Carga Útil de Respuesta indica los campos de carga útil de la solicitud o los parámetros de consulta en error. Si hay muchos campos o parámetros inválidos, todos deben ser listados. |
401 No autorizado | Indica que la solicitud no se ha aplicado porque carece de credenciales de autenticación válidas. |
403 Prohibido | Indica que el servidor entendió la solicitud pero se negó a cumplirla. Por ejemplo, se puede usar el método PUT para actualizar un objeto que no se puede actualizar. |
404 No Encontrado | Indica que el servidor no encontró los objetos solicitados. |
413 Contenido Demasiado Grande | Indica que el servidor se niega a procesar una solicitud porque el contenido solicitado es más grande de lo que el servidor está dispuesto o es capaz de procesar. |
Error interno del servidor 500 | Indica que el servidor es consciente de que ha cometido un error o es incapaz de realizar el método solicitado. |
502 Puerta de enlace incorrecta | Indica que la API recibió una respuesta no válida de un servidor ascendente al que accedió mientras intentaba cumplir con la solicitud. |
504 Tiempo de espera de la puerta de enlace | Indica que la API no recibió una respuesta oportuna de un servidor ascendente al que necesitaba acceder para completar la solicitud. |
La sección Cómo Manejar Errores proporciona un manejo de errores genérico para cada código de estado utilizado 4xx y 5xx. Las especificaciones detalladas de la API DCP en el Catálogo de API proporciona un manejo de errores específico para cada código de estado.
Carga Útil de Respuesta
Para el rango de códigos de estado de error 4xx y 5xx, se devuelve una carga útil de respuesta para proporcionar información sobre el error. La carga útil de respuesta utiliza una estructura basada en la especificación de JSON API para errores especificaciones, como se muestra en la tabla a continuación.
❗❗ El código de estado 504 Gateway Timeout devuelve una carga útil de respuesta básica ya que la API DCP no puede interceptar el error ❗❗
{ "fault": { "faultstring": "Tiempo de Espera de la Puerta de Enlace", "detail": { "errorcode": "messaging.adaptors.http.flow.GatewayTimeout" } } }
Propiedad | Tipo | Definición |
|---|---|---|
estado | cadena | El código de estado HTTP aplicable a este problema se expresa como un valor de cadena. |
id | cadena | Una cadena única que identifica la solicitud, generada por Apigee |
título | cadena | Código que identifica el error o la frase de razón Uno de
|
meta | objeto | |
meta.servicio | cadena | El código de servicio donde se originó el error. Es una referencia interna de la API de DCP que identifica la API de DCP. |
meta.detalle | cadena | Detalles sobre la causa del error |
meta.carga útil | objeto | La respuesta en bruto del servicio que causa el error (opcional) |
Por ejemplo, una llamada a un método GET para obtener un número de distribuidor inexistente devolvería la siguiente respuesta.
{
"status": "400",
"id": "rrt-05cc5cef09974c73d-d-ea-11235-10626775-11.1",
"title": "not_found",
"meta": {
"service": "07",
"detail": "Backend error",
"payload": {
"status": 400,
"errors": [
{
"code": "Vintage",
"title": "PAA Order Validate (API/Method)",
"detail": "Please contact Vintage Parts. See bulletin 123981 or www.vpartsinc.com",
"meta": {
"product_code": "080037100",
"item_id": "2833e5ad-ff54-44c1-9058-af64c955faa9",
"message": "015 - Warning -Please contact Vintage Parts. See bulletin 123981 for item_id = 2833e5ad-ff54-44c1-9058-af64c955faa9 product_code = 080037100 (/BRP/PART_ORDER/062)"
}
}
]
}
}
}Cómo manejar errores
400 Solicitud incorrecta
El código de estado 400 Solicitud incorrecta se ve principalmente durante la integración y pruebas de una API DCP.
El código de estado se devuelve cuando algo en la solicitud está ausente o tiene un valor inválido. Por ejemplo:
- Falta un parámetro de consulta requerido
- Un parámetro de consulta tiene un valor inválido
- Falta una propiedad obligatoria en el payload
- Una propiedad del payload tiene un valor inválido
Por ejemplo, si la API DCP requiere el número de distribuidor en el payload y la propiedad falta, se envía lo siguiente:
{
"status": 400,
"id": "rrt-06edc2039f6ce7033-b-ea-23590-61122983-1",
"title": "bad_request",
"meta": {
"service": "01",
"code": "request validation failed",
"errors": {
"details": [
{
"message": "Object has missing required properties ([\"dealer_no\"]): []"
}
]
}
}
}Si la propiedad del número de concesionario contiene un valor no válido, se envía lo siguiente:
{
"status": 400,
"id": "rrt-0570f8640a6f6ee97-d-ea-31505-59966586-1.1",
"title": "not_found",
"meta": {
"service": "07",
"payload": {
"errors": "Dealer number 12345678 is invalid."
}
}
}Estos errores deben corregirse durante las fases de integración y prueba.
❗❗ No intente reenviar la carga útil después de un estado 400 a menos que pueda solucionar automáticamente el problema ❗❗
Si se envía la misma carga útil sin modificación, se devolverá el mismo estado 400.
Sin embargo, si el usuario de DSP proporciona un valor de propiedad o un valor de consulta, el error debe convertirse en algo significativo para el usuario.
Tenga en cuenta que para muchas API de DCP, se devuelve el código de estado 404 No encontrado cuando no se encuentra un objeto.
401 No autorizado
Este es simple: llamaste a una API de DCP con el token de acceso incorrecto o caducado.
{
"status": 401,
"id": "rrt-0debaee1f7de5da53-c-ea-8481-2988956-1",
"title": "unauthorized",
"meta": {
"service": "05",
"detail": "Please verify your credentials or the Bearer token you provided. Contact the DCP team if you need further assistance."
}
}Para resolver este error:
- Asegúrate de usar las credenciales correctas establecidas para el entorno (prueba o producción)
- Asegúrate de que tu token de acceso se actualice regularmente.
Consulta la sección Autenticación y Credenciales para información sobre las credenciales.
403 Prohibido
Este error generalmente se encuentra solo durante la integración y pruebas de una API DCP.
El 403 Prohibido se devuelve cuando intentas llamar a una API interna de BRP directamente sin pasar por la URL adecuada de la API DCP.
{
"error": {
"id": "rrt-0b8f470f8a6f5fd93-d-ea-17530-62132303-1",
"status": 403,
"code": "Not Allowed",
"title": "Not Allowed to call the API from this origin"
}
}La solución a este error es actualizar la URL que estás utilizando para llamar a la API DCP.
404 No Encontrado
Una API DCP que utiliza un parámetro de consulta para encontrar un objeto, como un número de concesionario, número de parte o VIN, devuelve el estado 404 No Encontrado.
{
"status": 404,
"id": "rrt-06edc2039f6ce7033-b-ea-23589-61142930-1.1",
"title": "not_found",
"meta": {
"service": "07",
"detail": "Product code 0126488 not found."
}
}En general, el error debe ser reportado al usuario del DSP.
413 Contenido Demasiado Grande
Las API de DCP están desplegadas en APIGee, que tiene un límite de carga útil de 10 MB. Si la carga útil que envías es mayor de 10 MB, recibirás el código de estado 413.
La única forma de resolver este error es asegurarse de que el tamaño de la carga útil enviada al integrar una API de DCP sea menor de 10 MB dividiéndola en muchos mensajes.
Ten en cuenta que las API de DCP que probablemente encuentren este error son las API de Inventario de Piezas de Distribuidor y de Datos de Transacciones Minoristas.
500 Error Interno del Servidor
Un sistema backend devuelve el estado de error interno del servidor 500 por muchas razones, por lo que no es posible un manejo específico.
Si es posible, la mejor manera de manejar el error es esperar un tiempo (30 a 60 segundos) y llamar a la API de DCP nuevamente.
Generalmente funcionará. Pero si no lo hace, puedes intentar un par de veces (3 a 5 veces).
Si aún no funciona después de muchos intentos, debes devolver un mensaje de error al usuario y contactar al equipo de DCP para reportar el error con la mayor cantidad de información posible. Consulta la sección Obteniendo Apoyo para obtener información sobre cómo reportar problemas.
502 Puerta de enlace incorrecta
El 502 Puerta de enlace incorrecta puede ocurrir cuando la API DCP llama a una API interna de BRP, que ellos llaman un sistema backend.
Si es posible, la mejor manera de manejar el error es esperar un momento (30 a 60 segundos) y llamar a la API DCP nuevamente.
Generalmente funcionará. Pero si no lo hace, puedes intentar un par de veces (3 a 5 veces).
Si aún no funciona después de muchos intentos, debes devolver un mensaje de error al usuario y contactar al equipo DCP para informar el error con la mayor cantidad de información posible. Consulta la sección Obteniendo Soporte para información sobre cómo informar problemas.
504 Tiempo de espera de la puerta de enlace
APIGee tiene un tiempo de espera estricto de 55 segundos. Si el sistema backend tarda más de ±50 segundos en devolver una respuesta, APIGee devuelve un código de estado 504 Tiempo de espera de la puerta de enlace al DSP que llama.
Hay dos maneras generales de manejar este error
Esperar y Reintentar
La carga del sistema backend puede causar el tiempo de espera. Así que espera un momento (30 a 60 segundos) y llama a la API DCP nuevamente.
Generalmente funcionará. Pero si no lo hace, puedes intentar un par de veces (3 a 5 veces).
Si aún no funciona después de muchos intentos, debes devolver un mensaje de error al usuario.
Esperar a la finalización
Para el transacción DCP APIs, como el pedido de piezas, ¡no reintentes la transacción!
El tiempo de espera ocurrió porque el sistema backend tarda más de ±50 segundos en finalizar la transacción, pero la transacción aún se está procesando.
Las APIs de transacción DCP proporcionan un servicio para obtener el estado de la transacción.
Espera un momento (60 a 90 segundos) y llama al servicio API DCP para obtener el estado de la transacción.
Si aún se está procesando, espera de nuevo y llama al servicio API DCP hasta que la transacción esté terminada.
Para estar seguro, puedes limitar el número de reintentos a 5 a 10 reintentos.