API de entregas
Primeros Pasos
La API de Entregas es parte de la tríada de APIs relacionadas con la gestión de pedidos de Piezas, Accesorios y Ropa (PA&A), las otras dos siendo la API de Orden de Piezas y la API de facturas.
👉 Tómate el tiempo para leer la sección Orden, Factura y Entrega: La Historia Completa para obtener detalles sobre pedidos de piezas, entregas, facturación y cómo usar las tres APIs para conectarlas todas.
La API de Entregas permite al concesionario recuperar un documento de entrega con la información de envío usando un número de entrega encontrado en el albarán y la información del pedido de piezas cuando el pedido ha sido enviado.
La API de Entregas también proporciona un servicio para recuperar una lista de documentos de entrega para un concesionario usando un filtro.
❗ La API de Entregas NO PUEDE usarse para recuperar un documento de entrega de una unidad ❗
¿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:
- Orden, Factura y Entrega: La Historia Completa para obtener una visión general del proceso de pedido y entrega de piezas.
Resumen empresarial
Tema | Descripción |
|---|---|
Alcance | PA&A en Norteamérica |
Escenarios |
|
Funcionalidades principales |
|
Procesos empresariales soportados |
|
Beneficios para concesionarios |
|
Beneficios para BRP |
|
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: Entrega
Cuando se solicita una lista de documentos de entrega, la API de Entregas devuelve un arreglo de Entrega recursos. Cada recurso de Entrega mostrado a continuación contiene toda la información en un documento de entrega.
Cuando se solicita obtener un documento de entrega específico, la API de Entregas devuelve un único recurso de Entrega .
Representación JSON
{
"delivery_no": "8502015519",
"dealer_no": "0000690885",
"customer_address": {
"street": "109 THOMAS DRIVE",
"city": "AMERICUS",
"state": "GA",
"country": "US",
"postal_code": "31709-5533"
},
"shipping_condition": "S1",
"ship_to_no": "0020000953",
"ship_to_address": {
"street": "1601 S SLAPPEY BLVD",
"city": "ALBANY",
"state": "GA",
"country": "US",
"postal_code": "31701-2645"
},
"last_change_date": "2024-05-07T00:00:00Z",
"items": [
{
"delivery_item_no": "000010",
"product_code": "420686602",
"product_description": "GASKET SET",
"order_qty": 1,
"delivery_qty": 1,
"package_qty": 1,
"sales_order_no": "1030969589",
"sales_order_item_no": "007001",
"dealer_po_no": "ODN041123",
"tracking_details": [
{
"tracking_no": "1Z7F7W950301444225",
"tracking_url": "https://wwwapps.ups.com/WebTracking/track?loc=en_US&AgreeToTermsAndConditions=yes&track.x=26&track.y=5&trackNums=1Z7F7W950301444225"
}
]
}
]
}Propiedades
Todos los campos numéricos con decimales usan el punto (.) como separador decimal. La coma (,) NO es compatible como separador decimal.
Property | Type | Definition | Notes |
|---|---|---|---|
delivery_no | String | Delivery number | Length: 10 |
dealer_no | String | Code representing the dealer number or other entity number who placed the order. | Length:10 |
customer_address | object | Delivery address |
|
customer_address .street | string | Street address (1st line) | Max Length:60 |
customer_address .city | string | City | Max Length:40 |
customer_address .state | string | Code that uniquely identifies a province/state in a country, in ISO 3166-2 (2nd part) format. | Max Length:3 |
customer_address .country | string | Code that uniquely identifies a country, in ISO 3166-1 format. | Max Length:2 |
customer_address .postal_code | string | Postal code. | Max Length:10 |
ship_to_no | string | Code representing the customer or other entity number to which the goods are delivered. | Length:10 |
ship_to_address | object | Delivery address |
|
ship_to_address .street | string | street address (1st line) | Max Length:60 |
ship_to_address .city | string | City | Max Length:40 |
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 |
ship_to_address .country | string | Code that uniquely identifies a country, in ISO 3166-1 format. | Max Length:2 |
ship_to_address .postal_code | string | Postal code. | Max Length:10 |
shipping_condition | string | BRP custom code that uniquely identifies the shipping method for which the order is delivered. One value from the Shipping Method table. | Max Length: 2 |
last_change_date | string | Last date and time at which this resource has changed, in ISO 8601 UTC format. | Format: YYYY-MM-DDTHH:MM:SSZ |
items | List of objects |
|
|
items. delivery_item_no | string | Delivery item number. | Max Length: 6 |
items. product_code | string | Code that uniquely identifies a product. | Max Length: 18 |
items. product_description | string | The product description. | Max Length: 40 |
items. order_qty | number | Ordered quantity in sales unit of measure. 👉 If the value is 0, the delivery has not yet shipped. | Precision:1.00 |
items. delivery_qty | number | Delivered quantity in sales unit of measure. 👉 If the value is 0, the delivery has not yet shipped. | Precision:1.00 |
items. package_qty | number | Quantity in a package. | Precision:1.00 |
items. sales_order_no | string | Sales order document the item refers to. | Length:10 |
items. sales_order_item_no | string | Sales order document item number the item refers to. | Max Length:6 |
items. dealer_po_no | string | The number that the customer uses to uniquely identify a purchasing document. | Max Length: 35 |
items. tracking_details | List of objects |
|
|
items. tracking_details. tracking_no | String | Tracking number from the carrier. | Max Length: 30 |
items. tracking_details. tracking_url | String | URL tracking number from the carrier. | Max Length: 300 for each URL tracking number |
Métodos de envío - Norteamérica
Código V3 | Código V4 | Descripción | Uso |
|---|---|---|---|
01 | S1 | Envío Terrestre Acelerado | Actualización de primer nivel desde el servicio estándar nacional:
|
02 | S2 | Vehículo Fuera de Servicio | El envío más rápido disponible. Comúnmente usado cuando los retrasos son críticos (escenarios de vehículo fuera de servicio):
|
03 | S3 | Vehículo Fuera de Servicio Sábado | Igual que Vehículo Fuera de Servicio con la capacidad de recibirse un sábado. |
Métodos de envío - Internacional
Organización de Ventas | Código V3 | Descripción |
|---|---|---|
6030 - Escandinavia | 50 | itella |
6030 - Escandinavia | 51 | posten_logistik |
6030 - Escandinavia | 52 | terrestre |
6030 - Escandinavia | 53 | aéreo |
6030 - Escandinavia | 54 | terrestre |
6030 - Escandinavia | 55 | aéreo |
6030 - Escandinavia | 59 | terrestre |
6030 - Escandinavia | 60 | aéreo |
6050 - Europa (EMEA) | 30 | regular |
6050 - Europa (EMEA) | 33 | urgente |
7080 - Asia-Pacífico (APAC) | 38 | regular |
7080 - Asia-Pacífico (APAC) | 39 | urgente |
7080 - Asia-Pacífico (APAC) | 40 | regular |
7080 - Asia-Pacífico (APAC) | 82 | stock |
7080 - Asia-Pacífico (APAC) | 90 | stock |
8070 - México | 92 | regular |
8070 - México | 93 | aéreo |
8070 - México | 94 | urgente |
8075 - Brasil | 63 | aéreo_azul_cargo |
8075 - Brasil | 77 | sedex_correios |
8075 - Brasil | 78 | padrao_rodoviario |
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.
Documento de Entrega para un Distribuidor
Un distribuidor solo puede recuperar uno de sus documentos de entrega. El parámetro de cabecera Dealer-Number debe identificar al distribuidor que solicita el documento, y la API devuelve solo el documento de entrega para este distribuidor solicitante.
Tiempo de espera en la llamada para obtener
La API de Entregas ofrece el servicio LISTA para recuperar entregas basadas en algunos criterios, como un rango de fechas.
❗ En algunos casos, los criterios utilizados para la llamada al servicio LIST pueden seleccionar demasiados documentos de entrega y la API devuelve un tiempo de espera ❗
👉 Su DMS debe manejar el tiempo de espera y mostrar un mensaje de error que pida al concesionario cambiar el rango de fechas por uno más pequeño.
Cuando la cantidad de pedido y la cantidad de entrega son 0
En algunos casos, las propiedades order_qty y delivery_qty son 0. Esto ocurre cuando se crea una entrega pero no está lista para ser enviada.
Por ejemplo, esta entrega tiene las propiedades order_qty y delivery_qty en 0.
{
"delivery_no": "8502072259",
"dealer_no": "0000690885",
"customer_address": {
"street": "109 THOMAS DRIVE",
"city": "AMERICUS",
"state": "GA",
"country": "US",
"postal_code": "31709-5533"
},
"shipping_condition": "S1",
"ship_to_no": "0020000953",
"ship_to_address": {
"street": "1601 S SLAPPEY BLVD",
"city": "ALBANY",
"state": "GA",
"country": "US",
"postal_code": "31701-2645"
},
"last_change_date": "2024-05-24T00:00:00Z",
"items": [
{
"delivery_item_no": "000010",
"product_code": "9779426",
"product_description": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
"order_qty": 0,
"delivery_qty": 0,
"package_qty": 3,
"sales_order_no": "1030997804",
"sales_order_item_no": "012208",
"dealer_po_no": "ODN041256",
"tracking_details": []
}
]
}La propiedad deliveries de la orden de piezas correspondiente muestra que el estado de la pieza es allocated, lo que significa que no ha sido enviada.
Estas entregas pueden ignorarse porque el concesionario no las ha recibido.
{
"ordered_line": {
"item_id": "5DCAC1B678131EEF84D74B96E2BBC46A",
"item_no": "012200",
"product_code": "9779426",
"product_descr": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
"order_qty": 3,
"dealer_po_item_no": "",
"dealer_product_code": "",
"sales_uom": "PC",
"min_order_qty": 1,
"is_sales_bom": false,
"product_line": "SNO",
"product_type": "110",
"texts": []
},
"shipping_lines": [
{
"item_no": "012216",
"product_code": "9779426",
"product_descr": "OIL 4T 10W40 SYNTH. BLEND GAL/3,785L",
"ship_qty": 3,
"sales_uom": "PC",
"price_uom": "PC",
"package_uom": "CS",
"in_package": {
"qty": 3,
"uom": "PC"
},
"package_count": 3,
"msrp_unit_price": 56.99,
"wholesale_unit_price": 36.98,
"net_unit_price": 37.02,
"currency": "USD",
"is_substitute_product": false,
"substituted_product_code": null,
"product_line": "SNO",
"product_type": "110",
"plant": {
"name": "BRP - LAS VEGAS",
"city": "LAS VEGAS",
"state": "NV",
"country": "US"
},
"pricings": [
{
"condition_type": "gross_amt",
"total_amount": 110.94,
"currency": "USD"
},
{
"condition_type": "subtotal_amt",
"total_amount": 111.05,
"currency": "USD"
},
{
"condition_type": "tax_amt",
"total_amount": 8.88,
"currency": "USD"
},
{
"condition_type": "handling_fee",
"total_amount": 0.11,
"currency": "USD"
}
],
"deliveries": [
{
"status_code": "allocated",
"status_date": "2024-07-06T20:20:34Z",
"status_descr": "",
"qty": 3,
"availability_date": "2024-07-15",
"no": "",
"item_no": "",
"delivery_qty": 0,
"creation_date": "",
"carrier_name": "",
"split_delivery_no": "",
"split_delivery_item_no": "",
"trackings": [],
"billings": []
}
],
"statuses": [
{
"type": "success",
"code": "in_process",
"descr": "Your part is in process"
}
]
}
]
}
Referencia de API
curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502022612' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' curl --location 'https://cloud-api.brp.com/dcp/v4/deliveries?limit=5&last_change_date_from=2024-05-01&last_change_date_to=2024-05-25' \
--header 'Dealer-Number: 0000690885' \
--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 un Documento de Entrega para Encontrar una Orden de Piezas
Usando el número de entrega, puede obtener un documento de entrega específico. Por ejemplo, al recibir un paquete, el distribuidor ingresa el número de entrega que se encuentra en la etiqueta de envío para encontrar el documento de entrega.
Una vez que se encuentra el documento de entrega, el distribuidor puede usar el número de orden de venta (sales_order_no) para encontrar la orden de piezas relacionada.
Obtener el Documento de Entrega
curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502022612' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtener el pedido de repuestos
curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1030971827&dealer_no=0000690005' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtener los documentos de entrega para un período
Obtener los documentos de entrega para un rango de fechas.
curl --location 'https://cloud-api.brp.com/dcp/v4/deliveries?limit=5&last_change_date_from=2024-05-01&last_change_date_to=2024-05-25' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'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; los más comunes se encuentran en la tabla a continuación.
Respuesta | Resolución |
|---|---|
Devuelto si falta el parámetro de encabezado Dealer-Number . {
"status": "400",
"id": "rrt-00a574511a562afb5-b-ea-22208-1683284-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "la validación de la solicitud falló",
"payload": {
"details": [
{
"message": "El parámetro de encabezado 'Dealer-Number' es obligatorio en la ruta '/deliveries' pero no se encontró en la solicitud.: []"
}
]
}
}
} | Actualice su llamada API para agregar el parámetro Dealer-Number en el encabezado. |
Devuelto si falta el número de entrega en la consulta. {
"status": "400",
"id": "rrt-00a574511a562afb5-b-ea-22209-1683475-1",
"title": "bad_request",
"meta": {
"service": "00",
"detail": "Ruta no encontrada."
}
} | Asegúrese de incluir un número de entrega en la ruta de la consulta. |
Devuelto si el número de distribuidor es inválido {
"status": "400",
"id": "rrt-023ba21d3844ea361-c-ea-4985-19207929-2.1",
"title": "bad_request",
"meta": {
"service": "19",
"detail": "Número de distribuidor inválido"
}
} | Si el distribuidor está usando su DMS, puede ser que ya no sea un distribuidor BRP. Verifique con ellos y desactive las actualizaciones de inventario de repuestos. Asegúrese de que el número de distribuidor tenga 10 caracteres. Si guarda el número sin los ceros a la izquierda, añada el cero inicial antes de llamar a la API. |
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.
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 número de entrega.
{
"status": "404",
"id": "rrt-00a574511a562afb5-b-ea-22209-1683823-1.1",
"title": "not_found",
"meta": {
"service": "97",
"detail": "Delivery 8500045713 not found."
}
}El concesionario puede haber cometido un error al ingresar el número de entrega. Debes informar el error al usuario para que pueda intentarlo nuevamente.
Requisitos de DSP
Requisitos funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | El concesionario debe poder buscar un documento de entrega usando un número de entrega. |
2 | Obligatorio | El documento de entrega debe mostrarse al concesionario. |
3 | Obligatorio | El concesionario debe poder abrir una orden de repuestos usando el número de orden de venta (sales_order_no) encontrado en un documento de entrega. |
4 | Obligatorio | El parámetro de encabezado Dealer-Number debe configurarse con el número BRP del concesionario, y este no puede modificarlo. |
5 | Opcional | El DMS recupera los documentos de entrega de los últimos 3 meses y los guarda en la base de datos del DMS. El concesionario puede ver los documentos de entrega cargados. |
6 | Opcional | El concesionario puede encontrar un documento de entrega usando el número de rastreo del transportista. |
7 | Opcional | El servicio Get se usa diariamente para recuperar las entregas de los últimos 30 días y guardarlas en la base de datos del DMS. |
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 completarse en el entorno de prueba antes de que pueda comenzar la fase piloto del concesionario.
Para estas pruebas, debemos usar el número de concesionario 0000690005
ID | Prueba | Resultado esperado |
|---|---|---|
1 | Obtener el documento de entrega 8502067956 | El documento de entrega se carga y se muestra. |
2 | Obtener la lista de documentos de entrega con el rango de fechas 2023-06-20 a 2023-09-25 | Se carga una lista de 15 documentos de entrega. |
3 | Encontrar la orden de repuestos con el número de orden de venta encontrado en el documento de entrega 8502067956 | La orden de repuestos se encuentra y se muestra. |
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 | Proporcionar una lista de 10 a 20 números de entrega de las entregas recibidas por el concesionario. Proporcionar la captura de pantalla o realizar una demostración en vivo para mostrar al menos 10 documentos de entrega tal como los ve el concesionario. |
Validación 2 | Proporcionar los números de orden de venta (orden de repuestos) recuperados de los documentos de entrega en el Paso 1. Proporcionar la captura de pantalla o realizar una demostración en vivo para mostrar la orden de repuestos vinculada a al menos 10 documentos de entrega, tal como los ve 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 Entregas. Este entorno de Postman contiene variables utilizadas por las consultas y está configurado para conectarse al entorno de prueba.
Colecciones
La colección DMS - Deliveries contiene ejemplos de llamadas API para recuperar documentos de entrega.