API de orden de unidades
Comenzando
La API de Orden de Unidades permite al concesionario recuperar las órdenes de unidades preparadas en el Sistema de Gestión de Pedidos (OMS) en BOSSWeb.
El concesionario puede luego rastrear la entrega de la unidad y, una vez entregada, insertarla en el inventario usando el VIN encontrado en la información de entrega.
¿Dónde empezar? ¡Léeme 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 para información técnica general sobre la API y los entornos.
- Autenticación y Credenciales para obtener detalles sobre autenticación y credenciales.
- Proceso de Certificación para detalles sobre el proceso de certificación y Jira.
- Obteniendo Apoyo para obtener detalles sobre cómo obtener ayuda y Jira.
Resumen empresarial
Tema | Descripción |
|---|---|
Alcance | Órdenes de unidades en Norteamérica |
Escenarios |
|
Funcionalidades principales |
|
Procesos de negocio soportados |
|
Beneficios para los concesionarios |
|
Beneficios para BRP |
|
Información técnica
Características
Tipo de API | Tipo de DSP | Versión de 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 del Distribuidor y Autenticación de la Aplicación.
Autenticación de la Aplicación
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)
Autenticación del Concesionario
Necesitas un token de acceso válido antes de llamar a esta API o tienes que llamar a la API de Autenticación de Concesionarios para obtener uno.
El access_token es válido por 2 horas.
Tienes que usar el refresh_token para obtener un access_token antes de que el actual expire.
❗❗ El access_token obtenido a través de la API de Autenticación de Concesionarios debe ser para el concesionario cuyo número de concesionario se usa en el campo dealer_no del payload o del encabezado ❗❗
Consulta la sección Inicio de Sesión del Concesionario para más información.
Consulte la Autenticación del Distribuidor y las secciones de API de Autenticación de Concesionarios para obtener más información.
URL Base
Prueba | https://qa-cloud-api.brp.com/dcp/v4 |
|---|---|
Producción | https://cloud-api.brp.com/dcp/v4 |
Recurso: Pedido de Unidad
La API devuelve el Pedidos de Unidad recurso que contiene pedidos de unidades.
Representación JSON
{
"sales_order_no": "1030001693",
"order_type": "regular",
"dealer_no": "0000690885",
"dealer_po_no": "IO690885-MY23-91DEC",
"creation_date": "2023-02-04T01:22:25Z",
"requested_delivery_date": "2022-11-21",
"items": [
{
"item_no": "000010",
"product_code": "0008MPF00",
"product_descr": "Defender MAX XT HD10",
"color": "Mossy Oak Break-Up Country Cam",
"model_year": "2023",
"segment_descr": "Defender MAX",
"package_descr": "XT",
"product_line": "SSV",
"customer_reference_period_descr": "Dec",
"customer_reference_year_code": "",
"order_qty": 1,
"requested_delivery_date": "2022-11-21",
"requested_delivery_period_descr": "Dec",
"is_cancellable": false,
"is_pre_order": false,
"is_cancellable_pre_order": false,
"estimated_delivery_period": "2023-02-27",
"estimated_delivery_period_type": "week",
"estimated_shipped_period": "2023-02-28",
"estimated_shipped_period_type": "week",
"ship_to_no": "0000690885",
"delivery_schedule": [
{
"schedule_line_no": "0002",
"confirmed_date": "2023-02-28",
"confirmed_qty": 1,
"processing_status": "",
"delivery_status": ""
}
],
"delivery_progress": [
{
"freight_no": "7000003739",
"estimated_shipped_date": "2023-02-28",
"estimated_delivery_date": "2023-02-27",
"goods_issue_date": "2023-02-27",
"shipped_date": "2023-02-28",
"delivery_date": "2023-02-28",
"confirmation_status_code": "10",
"serial_numbers": [
"3JBUCAX44PK001102"
],
"shipping_carrier": {
"carrier_no": "31000164",
"carrier_name": "MCK TRUCKING INC",
"carrier_mobile": "",
"carrier_email": "",
"carrier_contact": ""
}
}
]
}
]
}Propiedades
Property | Type | Type | Notes |
|---|---|---|---|
sales_order_no | string | The number that uniquely identifies the sales document. | Max length: 10 |
order_type | string | The order type: regular or rush. | |
dealer_no | string | Code that uniquely identifies a dealer. | Length: 10 |
dealer_po_no | string | The number that the customer uses to uniquely identify a purchasing document. | Max length: 35 |
creation_date | string | Date and time when the unit order was created. | Format: YYYY-MM-DDTHH:MM:SSZ |
requested_delivery_date | string | The proposed date by which the customer requests the delivery of the unit. | Format: YYYY-MM-DD |
items | List of objects | Details on each unit order | |
items.item_no | string | The number that uniquely identifies the item in the sales order. | Max length: 6 |
items.product_code | string | Code that uniquely identifies a BRP product. | Max length: 18 |
items.product_descr | string | Description of the product. | Max length: 40 |
items.color | string | Color | Max Length: 70 |
items.model_year | string | Model year | |
items.segment_descr | string | The segment description | Max Length: 70 |
items.package_descr | string | The package description | Max Length: 70 |
items.product_line | string | The unit's product line. Refer to the Product Lines table below. | Max Length: 70 |
items.order_qty | number | The order quantity for this item. Always 1. | Precision: 1.000 |
items. requested_delivery_date | string | Requested delivery date. | Format: YYYY-MM-DD |
items. requested_delivery_period_descr | string | Description of the period related to the requested delivery date | Max length: 40 |
items.is_cancellable | boolean | Indicates if the order can be canceled. | True or false |
items.is_pre_order | boolean | Indicates if the order is a pre-order. | True or false |
items. is_cancellable_pre_order | boolean | Indicates if the pre-order can be canceled. | True or false |
items. estimated_delivery_period | string | Estimated delivery period start date. | Format: YYYY-MM-DD |
items. estimated_delivery_period_type | string | Period type of the estimated shipped period. One of:
| Max length: 6 |
items. estimated_shipped_period | string | Estimated shipped period start date. | Format: YYYY-MM-DD |
items. estimated_shipped_period_type | string | Period type of the estimated shipped period. One of:
| Max length: 6 |
items.ship_to_no | string | Ship to dealer number | Max length: 10 |
items.ship_to_address | object | | |
items.ship_to_address. street | string | Street address (1st line) | Max length: 60 |
items.ship_to_address. city | string | City | Max length: 40 |
items.ship_to_address. state | string | Code that uniquely identifies a province/state in a country, in ISO 3166-2 (2nd part) format. | Max length: 3 |
items.ship_to_address. country | string | Code that uniquely identifies a country in ISO 3166-1 format. | Max length: 2 |
items.ship_to_address. postal_code | string | Postal code | Max length: 10 |
items.delivery_schedule | list of objects | | |
items.delivery_schedule. schedule_line_no | string | Code that uniquely identifies the delivery schedule | Max length: 4 |
items.delivery_schedule. confirmed_date | string | Confirmed delivery date. | Format: YYYY-MM-DD |
items.delivery_schedule. confirmed_qty | string | Confirmed quantity | Precision: 1.000 |
items.delivery_schedule. processing_status | string | Identify the life cycle status of the order line item. One of:
| |
items.delivery_schedule. delivery_status | string | Delivery status. One of:
| |
items.delivery_progress | list of objects | | |
items.delivery_progress. freight_no | string | Code that uniquely identifies the freight number | Max length: 20 |
items.delivery_progress. estimated_shipped_date | string | Estimated shipped date. | Format: YYYY-MM-DD |
items.delivery_progress. estimated_delivery_date | string | Estimated delivery date. | Format: YYYY-MM-DD |
items.delivery_progress. good_issue_date | string | Date the unit was subtracted from BRP's inventory. | Format: YYYY-MM-DD |
items.delivery_progress. shipped_date | string | Actual shipped date. | Format: YYYY-MM-DD |
items.delivery_progress. delivery_date | string | Actual delivery date. | Format: YYYY-MM-DD |
items.delivery_progress. confirmation_status_code | string | Confirmation status cod. One of:
| Max length: 2 |
items.delivery_progress. serial_numbers | List of strings | Delivered unit serial numbers | Max length: 18 |
items.delivery_progress. shipping_carrier | Object | Information on the shipping carrier. | |
items.delivery_progress. shipping_carrier.carrier_no | string | Carrier number. | Max length: 10 |
items.delivery_progress. shipping_carrier. carrier_name | string | Carrier name. | Max length: 40 |
items.delivery_progress. shipping_carrier. carrier_mobile | number | Mobile phone number of the carrier. | Max length: 10 |
items.delivery_progress. shipping_carrier. carrier_email | string | Email of the carrier. | Max length: 241 |
items.delivery_progress. shipping_carrier. carrier_contact | string | Contact of the carrier. | |
Líneas de productos
Clave | Valor | Marca |
|---|---|---|
2WV | Vehículos de dos ruedas | Can-Am On-Road |
3WV | Vehículos de tres ruedas | Can-Am On-Road |
ATV | Vehículos todoterreno | Can-Am Off-Road |
OE | Motores fueraborda | Sea-Doo |
PTN | Lanchas pontón | Sea-Doo |
PWC | Motos acuáticas personales | Sea-Doo |
SNO | Motos de nieve | Ski-Doo |
SSV | Vehículos side-by-side | Can-Am Off-Road |
Recurso: Lista de órdenes de unidades
Cuando se llama para solicitar una lista de órdenes de unidad, la API de Unidades devuelve una matriz de Orden de Unidad recursos.
👉 Incluso si llamas a la API de Órdenes de Unidades con un filtro para recuperar solo una orden, la API siempre devuelve una lista de órdenes de unidad.
Las respuestas devueltas contienen dos objetos que te ayudan a navegar por las páginas de órdenes de unidad.
Representación JSON
{
"items": [
{
List of Unit Orders resources
}
],
"links": {
"previous": null,
"next": "https://qa-cloud-api.brp.com/dcp/v4/units/orders?page=2&limit=200"
},
"meta": {
"total_records": 233,
"total_pages": 2,
"current_page": 1,
"limit": 200
}
}Propiedades
Propiedad | Tipo | Definición |
|---|---|---|
items | Lista de objetos | Lista de recursos de Unidad que se devuelven. |
links | objeto | Enlaces de paginación. |
links.previous | cadena | URL que se utilizará para recuperar la página anterior. NULL si no hay página anterior. |
links.next | cadena | URL que se utilizará para recuperar la página siguiente. NULL si no hay página siguiente. |
meta | objeto | Estadísticas de la solicitud. |
meta.total_records | número | La cantidad de registros devueltos por la solicitud. |
meta.total_pages | número | El número de páginas usando el límite para calcular. |
meta.current_page | número | El número de página actual o el número de página solicitado. |
meta.limit | número | Límite de los parámetros de la solicitud. |
Enlaces
El objeto Links puede utilizarse para navegar por las páginas devueltas por la API de Units.
Cuando un enlace no es NULL, puede utilizarse para ir a la página anterior o siguiente. Esto simplifica la navegación de páginas porque no tienes que guardar los parámetros de tu consulta; la URL del enlace contiene los parámetros de consulta que proporcionaste y los parámetros de consulta predeterminados para aquellos que no proporcionaste.
Metadatos
El objeto Meta proporciona estadísticas sobre el número de recursos Unit devueltos por tu solicitud y el número de páginas que se pueden esperar.
Esta información puede ser útil para diagnósticos y para verificar que se recibieron todos los recursos de la unidad.
Limitaciones y Restricciones
Formato de Número
Todos los campos numéricos con decimales usan el punto(.) como separador decimal. La coma (,) NO es compatible como separador decimal.
Parámetro de Consulta Filter
El $filter parámetro de consulta puede usarse para filtrar las órdenes de unidad usando solo las siguientes propiedades:
- sales_order_no
- dealer_po_no
- fecha_de_entrega_solicitada
👉 Usar otras propiedades en la $filter generará un error o será ignorada.
Referencia de la API
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME'Líneas de productos
Clave | Valor | Marca |
|---|---|---|
2WV | Vehículos de dos ruedas | Can-Am On-Road |
3WV | Vehículos de tres ruedas | Can-Am On-Road |
ATV | Vehículos todoterreno | Can-Am Off-Road |
OE | Motores fueraborda | Sea-Doo |
PTN | Barcos pontón | Sea-Doo |
PWC | Motos acuáticas | Sea-Doo |
SNO | Motos de nieve | Ski-Doo |
SSV | Vehículos side-by-side | Can-Am Off-Road |
Cómo hacerlo
Esta sección proporciona información sobre cómo obtener resultados específicos con la API.
Obtener órdenes usando un rango de fechas
Este ejemplo muestra cómo obtener las órdenes de unidades usando un rango de fechas.
La solicitud usa el parámetro limit para limitar la respuesta a 3 órdenes por página.
El enlaces propiedad proporciona la información para navegar por las páginas. Consulte la Paginación sección para más información.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtener pedidos de unidades para una línea de productos
Este ejemplo muestra cómo obtener los pedidos de unidades para una línea de productos específica. Las líneas de productos válidas se enumeran en la tabla API de orden de unidades .
La solicitud utiliza el parámetro limit para limitar la respuesta a 3 órdenes por página.
La propiedad links proporciona la información para navegar entre las páginas. Consulta la sección Paginación para más información.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&product_line=PWC&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtener un pedido con el número de orden de venta
Este ejemplo muestra cómo obtener el orden de la unidad utilizando un número de pedido de ventas en el $filter parámetro de consulta.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=sales_order_no%20eq%20%271030417429%27' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtener una orden con el número de PO del distribuidor
Este ejemplo muestra cómo obtener la orden de la unidad usando un número de PO del distribuidor en el parámetro de consulta $filter .
La solicitud usa el límite parámetro para limitar la respuesta a 2 órdenes por página.
La propiedad enlaces proporciona la información para navegar las páginas. Consulta la sección Paginación para más información.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=dealer_po_no%20eq%20%20%27IO690885-MY23-91%27&limit=2' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtener órdenes de la unidad usando la fecha solicitada
Este ejemplo muestra cómo obtener las órdenes de la unidad utilizando un rango de fechas solicitado en el $filter parámetro de consulta.
La solicitud utiliza el parámetro limit para limitar la respuesta a 3 órdenes por página.
El enlaces proporciona la información para navegar por las páginas. Consulta la Paginación sección para más información.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=((requested_delivery_date%20ge%202024-01-02)%20and%20((requested_delivery_date%20le%202024-07-02)))&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Gestión de errores
Esta sección presenta varios escenarios de llamadas incorrectas o inapropiadas, 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 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 a continuación.
Respuesta | Resolución |
|---|---|
Devuelto si el número de distribuidor no es válido. {
"status": "400",
"id": "rrt-02ac3ea9453bba5fe-d-ea-2008293-6461009-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "La cadena \"12345\" es demasiado corta (longitud: 5, mínimo requerido: 10): []"
}
]
}
}
} | Si el distribuidor usa tu DMS, puede que ya no sea un distribuidor BRP activo. Verifícalo con ellos y desactiva las actualizaciones de inventario de repuestos. Asegúrate de que el número de distribuidor tenga 10 caracteres. Si guardas el número sin ceros a la izquierda, agrégalos antes de llamar a la API. El error también se devuelve si el distribuidor no es un distribuidor BRP activo. |
Devuelto si falta el número de distribuidor. {
"status": "400",
"id": "rrt-02ac3ea9453bba5fe-d-ea-2008293-6460630-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "El parámetro de consulta 'dealer_no' es obligatorio en la ruta '/units/orders' pero no se encontró en la solicitud.: []"
}
]
}
}
} | El número de distribuidor es obligatorio en la llamada. |
Devuelto si una fecha tiene un formato no válido. {
"status": "400",
"id": "rrt-0aa500db076dc9eed-d-ea-1328974-8272532-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "La cadena \"AAbbCC\" no es válida según el/los formato(s) de fecha solicitado(s) yyyy-MM-dd: []"
}
]
}
}
} | Cambia el formato de la cadena de fecha para que coincida con el formato requerido. |
Devuelto si las fechas están invertidas.
{
"status": "400",
"id": "rrt-007c4ae418b4c128f-b-ea-3013144-8304219-1.1",
"title": "bad_request",
"meta": {
"service": "21",
"detail": "El creation_date_from no puede ser posterior al creation_date_to. Por favor, verifica tus fechas e inténtalo de nuevo."
}
}
| Verifica que creation_date_from sea anterior (más antigua) que creation_date_to. |
401 No autorizado
El código de estado de error 401 Unauthorized se devuelve cuando intentas llamar a la API con un access_token expirado.
Debes 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 acceso, crea un ticket de soporte como se describe en la sección Abrir un Ticket de Soporte.
403 Prohibido
El código de estado de error 403 Forbidden se devuelve si el número de distribuidor no coincide con el token del distribuidor.
{
"status": "403",
"id": "rrt-08ca5848b0d5e485e-b-ea-1816747-7377470-1.1",
"title": "forbidden",
"meta": {
"service": "96",
"detail": "The dealer_no in the request doesn't correspond to the dealer_no associated with the dealer token provided."
}
}Asegúrate de que estás utilizando el token de autenticación del distribuidor correcto.
Requisitos de DSP
Requisitos funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | El access_token debe renovarse automáticamente cada 90 minutos |
2 | Obligatorio | El API de Autenticación de Concesionarios access_token y refresh_token deben guardarse y usarse por todos los usuarios con permiso para gestionar órdenes de unidades. |
3 | Obligatorio | El API de Autenticación de Concesionarios access_token debe renovarse cada 2 horas usando el refresh_token. |
4 | Opcional | El distribuidor debe poder encontrar una orden de unidad usando un número de PO del distribuidor. |
5 | Opcional | El distribuidor debe poder encontrar una orden de unidad usando un número de orden de venta. |
6 | Opcional | El distribuidor puede cargar manualmente órdenes de unidad proporcionando un rango de fechas. |
7 | Obligatorio | El DMS debe usar el servicio Get para realizar una carga inicial, recuperar todas las órdenes de unidad de los últimos 12 meses y guardarlas en la base de datos del DMS. |
8 | Obligatorio | El servicio Get debe usarse diariamente para recuperar las órdenes de unidad de los últimos 30 días y guardarlas en la base de datos del DMS. Se actualiza si una orden de unidad ya existe en la base de datos del DMS. |
9 | Obligatorio | Para cada orden de unidad, como mínimo, la siguiente información específica de BRP debe estar disponible para el distribuidor:
|
Actividades de Certificación
Esta sección presenta todas las actividades de certificación y validaciones que deben completarse para certificar la API.
Validaciones
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.
👉 Para ejecutar las pruebas, necesitas credenciales de distribuidor de BOSSWeb en el entorno de prueba. Si no las tienes, abre un ticket en el Jira de DCP.
ID | Prueba | Resultado esperado |
|---|---|---|
1 | Recuperar las órdenes de unidad creadas en los últimos 12 meses. | Las órdenes de unidad se muestran en el DMS, y las delivery_progress propiedades son visibles. |
2 | Obtener las órdenes de unidad para una línea de productos soportada por el distribuidor. | Las órdenes de unidad se muestran en el DMS. |
3 | Obtener una orden de unidad usando el número de orden de venta. | Obtener un número de orden de venta de las órdenes de unidad cargadas en el paso 1. Recuperar la orden de unidad correspondiente. |
4 | Obtener una orden de unidad usando el número de PO del distribuidor. | Obtener un número de PO del distribuidor de las órdenes de unidad cargadas en el paso 1. Recuperar la orden de unidad correspondiente. |
Piloto de Concesionarios
La siguiente tabla describe los parámetros y validaciones del piloto de concesionarios.
Parámetro | Valor |
|---|---|
Entorno | Producción |
Número de concesionarios | 1 a 3 |
Duración | 1 semana |
Validación 1 | Recuperar las órdenes de unidades creadas en los últimos 12 meses. |
Validación 2 | Las órdenes de unidades se actualizan diariamente y están disponibles para el concesionario. |
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 Units Order. Este entorno de Postman contiene variables utilizadas por las consultas y está configurado para conectarse al entorno de prueba.
Colecciones
La colección DMS - Orden de Unidades contiene ejemplos de llamadas API para obtener órdenes de unidades para un distribuidor.