Información Técnica
Características
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 |
Autenticación
La API está utilizando Autenticación de Aplicación.
Necesitas un token de acceso válido antes de llamar a esta API, o tienes que llamar al 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> |
Qué Cambió de V2
- Un punto final para todas las transacciones.
- La carga útil puede contener muchas transacciones.
- La API de Transacciones Minoristas V2 utiliza Autenticación Básica, mientras que la API V5 utiliza Autenticación de Aplicación.
- La carga útil cambió de XML-STAR a JSON.
- Soporta muchas monedas.
Recurso: Transacciones
El recurso de Transacciones se utiliza para enviar todo tipo de transacciones a la API.
La carga útil de la API de Transacciones Minoristas contiene mucha información. A veces, su DMS puede no ser capaz de proporcionar la información solicitada.
Está bien, y cada caso se discutirá durante las actividades de certificación. Si su DMS tiene limitaciones técnicas que impiden enviar cierta información, las excepciones se documentarán y acordarán.
Representación JSON
{
"transactions": [
{
"header": {
"cancel_flag": false,
"customers": [
{
"city": "Denver",
"country": "USA",
"customer_hash": "77c6c73a430e5b4630321d52eecfba3574662dcfcee84d92cefde2b93df03161",
"customer_id": "21765GE0",
"recipient": "Customer",
"state_province": "COL"
},
{
"city": "Kuujjuaq",
"country": "CAN",
"customer_hash": "b25d0a94ad6707d04957ca22400aeae92ba7a4497e53f25f1991d7323d0864e7",
"customer_id": "008463",
"recipient": "Customer",
"state_province": "QC"
}
],
"transaction_close_date": "2023-04-24T00:00:00Z",
"transaction_number": "32302544",
"transaction_open_date": "2023-04-23T00:00:00Z",
"transaction_source": "In-Store",
"transaction_uuid": "7ca4be01-f750-4236-a3dc-a4128259a827"
},
"parts": [
{
"currency": "CAD",
"is_special_order": false,
"quantity_uom": "EA",
"part_description": "CLASSIC BALL CAP MEN O/S",
"part_number": "4544970090",
"quantity": 1.0,
"dealer_cost": 14.98,
"dealer_price": 18.43,
"msrp": 24.99,
"total_customer_price": 18.43,
"additional_costs": []
},
{
"currency": "CAD",
"is_special_order": false,
"quantity_uom": "EA",
"part_description": "CLASSIC CURVED CAP MEN O/S",
"part_number": "4486830089",
"quantity": 1.0,
"dealer_cost": 14.98,
"dealer_price": 18.43,
"msrp": 24.99,
"total_customer_price": 18.43,
"additional_costs": []
}
],
"units": [
{
"odometer_reading": 0,
"vin": "3JBUVAX48PK003400",
"class_code": "New",
"sales_lead_id": "LM",
"additional_costs": [],
"currency": "CAD",
"financed_amount": 0,
"trade_ins": [],
"financed_rate": 0,
"financed_term_duration": 0,
"dealer_cost": 27198.59,
"dealer_price": 30399.0,
"msrp": 30399.0,
"total_customer_price": 30399.0
}
],
"jobs": [
{
"vin": "3JBVNAV48PE000387",
"odometer_reading": 0,
"currency": "CAD",
"time_cards": [
{
"labour_rate": 129.0,
"labour_worked_hours": 2.23,
"labour_billed_hours": 2.23,
"technician_party_id": "TECH000"
}
],
"total_customer_job_price": 287.67,
"is_warranty_job": false,
"job_number": "20095262",
"job_code": "OTH",
"description": "NEW SXS - SET-UP & PDI",
"additional_costs": [],
"hours": 0
}
]
}
]
}Propiedades
Todos los campos numéricos utilizan un punto (.) como separador decimal. La coma (,) no es compatible como separador decimal.
❗ Las propiedades opcionales deben incluirse en su carga útil si la información está disponible en su DMS.
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
transacciones * | Lista de objetos | | |
transacciones.encabezado * | objeto | Encabezado de transacción. | |
transacciones.encabezado. número_de_transacción * | cadena | El sistema del concesionario genera un número de transacción, que debe ser único para el concesionario.. Vea la Limitaciones y Restricciones sección para más información. | Longitud máxima: 36 |
transacciones.encabezado. fecha_de_apertura_de_transacción * | fecha | La fecha en que se abrió la transacción, tal como está escrita en el sistema del concesionario | Formato: aaaa-mm-ddThh:mm:ssZ |
transacciones.encabezado. fecha_cierre_transacción * | fecha | La fecha en que se cerró la transacción, según lo escrito en el sistema del concesionario | Formato: aaaa-mm-ddThh:mm:ssZ |
encabezado.transacciones. fuente_de_transacción * | cadena | La fuente de la transacción Uno de:
| |
transacciones.encabezado. bandera_de_cancelación * | boolean | Bandera para indicar que esta transacción ha sido cancelada. | |
transacciones.encabezado. uuid_transacción * | cadena | Un ID único para indicar esta iteración de la transacción. ❗❗ La transaction_uuid CADA vez que se envía la carga útil! Si la carga útil se reenvía después de un error, el transaction_uuid debe ser diferente ❗❗ | Formato: (^([0-9A-Fa-f]{8}[-]?[0-9A-Fa-f]{4}[-]?[0-9A-Fa-f]{4}[-]?[0-9A-Fa-f]{4}[-]?[0-9A-Fa-f]{12})$) |
encabezado.transacciones. clientes * | Lista de objetos | | |
encabezado.transacciones. clientes.customer_id * | cadena | Identificador único a nivel de concesionario (o DMS) para este cliente. Si no se proporciona ninguno (por ejemplo, transacción en efectivo) establezca el valor en "INVITADO". | Longitud máxima: 36 |
transacciones.encabezado. clientes. hash_del_cliente * | cadena | Un hash SHA-256 del número de teléfono y el correo electrónico del cliente. El formato requerido es SHA-256(^\+[1-9]\d{1,14}\s\S+@\S+\.\S+$) es decir, SHA-256(dirección de correo electrónico del espacio de números de teléfono E.164). p.ej.:SHA-256(+18882729222 [email protected]) Si falta el correo electrónico o el número de teléfono, entonces establece la propiedad en nulo | Formato: ^[a-fA-F0-9]{64}$ |
encabezado.transacciones. clientes.destinatario * | cadena | ¿Quién fue el receptor de la transacción? Uno de:
Cliente: el cliente "estándar". Auto: el concesionario en sí (por ejemplo, vender piezas a diferentes departamentos, hacer una adición a los vehículos, etc.). Concesionario: un concesionario que no sea el mismo. | |
transacciones.encabezado. ciudad de los clientes | cadena | La ciudad donde vive el cliente. | Longitud máxima: 128 |
transacciones.encabezado. clientes. estado_provincia | cadena | Estado o provincia donde vive el cliente. Establecer en nulo si no es aplicable para el país. | Longitud máxima: 128 |
transacciones.encabezado. países de los clientes | cadena | País donde vive el cliente. | Longitud máxima: 128 |
transacciones.partes * | Lista de Objetos | | |
transacciones.partes. descripción_parte * | cadena | La descripción de la parte o “PARTES NO BRP”. | Longitud máxima: 128 |
transacciones.partes. número_de_parte * | cadena | Números de parte definidos por BRP o “PARTES NO BRP”. | Longitud máxima: 18 |
transacciones.partes. cantidad * | número | El número de tales partes. | Formato ±9999999.99 |
transacciones.partes. cantidad_uom * | cadena | Las Unidades de Medida utilizadas en el campo de cantidad, como se define en la tabla a continuación. | Longitud máxima: 10 |
transacciones.partes. es_pedido_especial * | boolean | Una bandera para indicar si esta parte fue un pedido especial, es decir, una parte que no se suele tener en stock. | |
transacciones.partes. precio_total_cliente * | número | El precio total del cliente, incluidos todos los impuestos, descuentos, tarifas de envío, etc. Incluye todos los costos adicionales. | Formato ±9999999.99 |
transacciones.partes. precio_del_concesionario | número | El precio unitario (para una cantidad de 1) establecido por el concesionario para la pieza | Formato ±9999999.99 |
transacciones.partes. costo_del_concesionario | número | El precio unitario (para una cantidad de 1) al que el comerciante compró el artículo de BRP. | Formato ±9999999.99 |
transacciones.partes.msrp | número | El precio de venta sugerido por el fabricante para la unidad (por una cantidad de 1) del artículo en el momento de la transacción. | Formato ±9999999.99 |
transacciones.partes. moneda * | cadena | La moneda utilizada para todos los precios en este objeto y objetos hijos. Vea la tabla de divisas a continuación. | |
transacciones.partes. número_de_trabajo_asociado | cadena | El número de trabajo del trabajo que consumió esta parte. | Longitud máxima: 36 |
transacciones.partes. costos_adicionales * | Lista de objetos | | |
transacciones.partes. costos_adicionales.tipo * | cadena | El tipo de costo adicional. Uno de:
| |
transacciones.partes. costos_adicionales. descripción * | cadena | Una breve descripción del costo. | Longitud máxima: 255 |
transacciones.partes. costos_adicionales. monto aplicable | número | El monto sobre el cual se aplica la tasa para calcular el costo adicional. | Formato ±9999999.99 |
transacciones.partes. costos_adicionales.tasa | número | La tasa (por ejemplo, la tasa impositiva) se aplica al monto aplicable para determinar el costo adicional. | Un valor entre -1.00000 y 1.00000 |
transacciones.partes. costos_adicionales.monto * | número | El monto del costo adicional. | Formato ±9999999.99 |
transacciones.unidades | Lista de Objetos |
|
|
transacciones.unidades.vin * | cadena | El Número de Identificación del Vehículo (VIN) de la unidad comprada. | Longitud máxima: 17 |
transacciones.unidades. lectura_del_odómetro | número | Lectura del odómetro en kilómetros. | Formato 9999999.99 |
transacciones.unidades.horas | número | Lectura del número de horas trabajadas. | Formato 9999999.99 |
ttransacciones.unidades. código_clase * | cadena | El código de clase para esta unidad. Uno de:
| |
transacciones.unidades. id_de_oportunidad_de_venta | cadena | El ID de BRP del cliente potencial de la venta que resultó en esta venta. | Longitud máxima: 36 |
transacciones.unidades. precio_total_cliente * | número | El precio total pagado por el cliente por esta unidad. Incluye todos los costos adicionales. | Formato ±9999999.99 |
transacciones.unidades. precio_del_concesionario * | número | El precio de venta al público establecido por el concesionario para esta unidad. | Formato ±9999999.99 |
transacciones.unidades. costo_del_concesionario * | número | El precio al que el concesionario compró esta unidad de BRP. | Formato ±9999999.99 |
transacciones.unidades.precioSugeridoDeVenta | número
| El precio de venta sugerido por el fabricante, en el momento de la transacción, para esta unidad. | Formato ±9999999.99 |
transacciones.unidades. moneda * | cadena | La moneda utilizada para todos los precios en este objeto y objetos hijos. Vea la tabla de divisas a continuación. | |
transacciones.unidades. monto_financiado | número | La cantidad que el cliente financió para la compra de esta unidad. | Formato ±9999999.99 |
transacciones.unidades. tasa_financiada | número | La tasa de financiamiento. | Valor entre 0.0000 y 1.0000 |
transacciones.unidades. duración del término financiado | número | El número de meses durante los cuales se financió la unidad. | Formato 9999999.99 |
transacciones.unidades. comercio_ins | Lista de objetos |
|
|
transacciones.unidades. comercio_ins.fabricante | cadena | El fabricante de la unidad entregada. | Longitud máxima: 36 |
transacciones.unidades. comercio_ins.vin | cadena | El VIN del vehículo que fue entregado. | Longitud máxima: 17 |
transacciones.unidades. comercio_ins. lectura del odómetro | número | Lectura del odómetro en kilómetros. | Formato 9999999.99 |
transacciones.unidades. horas_de_comercio | número | Lectura del número de horas trabajadas. | Formato 9999999.99 |
transacciones.unidades. comercio_ins.modelo | cadena | El modelo de la unidad entregada a cambio. | Longitud máxima: 255 |
transacciones.unidades. comercio_ins.precio | número | El precio que el concesionario pagó por la unidad entregada a cambio. ❗La cantidad debe ser negativa. | Formato ±9999999.99 |
transacciones.unidades. año_comercio | cadena | El año del modelo del vehículo que se está intercambiando. | Entero yyyy |
transacciones.unidades. costos_adicionales * | Lista de objetos |
|
|
transacciones.unidades. acostos_adicionales.tipo * | cadena | El tipo de costo adicional. Uno de:
| |
transacciones.unidades. costos_adicionales.descripcion * | cadena | Una breve descripción del costo. | Longitud máxima: 255 |
transacciones.unidades. costos_adicionales.monto_aplicable | número | El monto sobre el cual se aplica la tasa para calcular el costo adicional. | Formato ±9999999.99 |
transacciones.unidades. costos_adicionales.tasa | número | La tasa (por ejemplo, la tasa impositiva) se aplica al monto aplicable para determinar el costo adicional. | Un valor entre -1.00000 y 1.00000 |
transacciones.unidades.costos_adicionales.monto * | número | El monto del costo adicional. | Formato ±9999999.99 |
transacciones.trabajos * | Lista de objetos | | |
transacciones.trabajos. número_de_trabajo * | cadena | El número de trabajo a nivel del concesionario. | Longitud máxima: 36 |
transacciones.trabajos. código_de_trabajo * | cadena | El código de trabajo para este trabajo.Uno de
Vea la tabla de Códigos de Trabajo a continuación para más información. | Longitud máxima: 3 |
transacciones.trabajos. descripción * | cadena | La descripción del trabajo. | Longitud máxima: 255 |
transacciones.trabajos.es_trabajo_de_garantía * | boolean | Bandera para indicar si este trabajo estaba cubierto por garantía. | |
número_de_reclamación_de_garantía | cadena | El número de reclamación de garantía BRP. | Longitud máxima: 36 |
transacciones.trabajos.precio_total_del_trabajo_del_cliente * | número | El precio total pagado por el cliente solo por el trabajo (es decir, excluyendo las piezas). Incluye todos los costos adicionales. | Formato ±9999999.99 |
transacciones.trabajos.moneda * | cadena | La moneda utilizada para todos los precios en este objeto y objetos hijos. Vea la tabla de divisas a continuación. | |
transacciones.trabajos.vin | cadena | El Número de Identificación del Vehículo (VIN) de la unidad en reparación/mantenimiento. | Longitud máxima: 17 |
transacciones.trabajos. lectura del odómetro | número | Lectura del odómetro en kilómetros. | Formato 9999999.99 |
transacciones.trabajos.horas | número | Lectura del número de horas trabajadas. | Formato 9999999.99 |
transacciones.trabajos. fabricante | cadena | El fabricante de la unidad en la que se realizó el trabajo. | Longitud máxima: 36 |
transacciones.trabajos.modelo | cadena | El modelo de la unidad en la que se realizó el trabajo. | Longitud máxima: 255 |
transacciones.trabajos.año | cadena | El año del modelo de la unidad en la que se realizó el trabajo. | Entero yyyy |
transacciones.trabajos. tarjetas_de_tiempo * | Lista de objetos | | |
transacciones.trabajos. tarjetas_de_tiempo. horas_trabajadas* | número | El número de horas que esta fiesta trabajó en este trabajo. | Formato 9999999.99 |
transacciones.trabajos. tarjetas_de_tiempo. horas_facturadas_de_trabajo* | número | El número de horas que se facturó a esta fiesta por este trabajo. | Formato 9999999.99 |
transacciones.trabajos. tarifas_de_trabajo.tiempo_tarjetas | número | La tarifa por hora de esta parte. | Formato 9999999.99 |
transacciones.trabajos. tarjetas_de_tiempo. id_del_técnico* | cadena | El ID definido por el distribuidor para esta fiesta. | Longitud máxima: 36 |
transacciones.trabajos. costos_adicionales * | Lista de objetos | | |
transacciones.trabajos. costos_adicionales.tipo * | cadena | El tipo de costo adicional. Uno de:
| |
transacciones.trabajos. costos_adicionales. ddescripción * | cadena | Una breve descripción del costo. | Longitud máxima: 255 |
transacciones.trabajos. costos_adicionales. monto aplicable | número | El monto sobre el cual se aplica la tasa para calcular el costo adicional. | Formato ±9999999.99 |
transacciones.trabajos. costos_adicionales.tasa | número | La tasa (por ejemplo, la tasa impositiva) se aplica al monto aplicable para obtener el monto del costo adicional. | Un valor entre -1.00000 y 1.00000 |
transacciones.trabajos. costos_adicionales.monto * | número | El monto del costo adicional. | Formato ±9999999.99 |
- Las propiedades en azul y marcadas con un asterisco (*) son obligatorias en el recurso.
Tablas de referencia
Moneda
Organización de Ventas | Moneda | Versión 3 | Versión 4 |
|---|---|---|---|
1010 | CAD | | X |
3020 | USD | | X |
6030 | EUR | X | |
6030 | NOK | X | |
6050 | SEK | X | |
6050 | EUR | X | |
6050 | GBP | X | |
8070 | MXN | X | |
8075 | BRL | X | |
7080 | AUD | X | |
7080 | NZD | X | |
Unidad de Medidas
Código | Descripción | Dimensión |
|---|---|---|
" | Pulgada | Longitud |
CAJA | Caja | Cantidad |
BR | Barrel | Amount |
BT | Bottle | Amount |
BU | Cube | Amount |
I CAN | Capsule | Amount |
CC | Centímetro cúbico | Volume |
CDM | Cubic decimeter | Volume |
CG | Centígrados | Weight |
CL | Centilitros | Volumen |
CM | Centimeter | Longitud |
CS | Caja | Amount |
FT | Pies | Length |
G | Gramo | Weight |
GA | Gallones | Volume |
GU | US gallon | Volume |
H | Time | Time |
KG | Kilogram | Weight |
L | Liter | Volume |
LB | Libra | Weight |
LT | Batch | Amount |
M | Meter | Length |
M2 | Square meter | Area |
MG | Miligramo | Weight |
ML | Mililitro | Volume |
MM | Milímetro | Length |
OZ | Onzas | Weight |
P | Points | Amount |
PAC | Package | Amount |
PC | Piece | Amount |
PR | Par | Amount |
PT | Pintas | Volume |
QT | Quartz | Volume |
ROL | Rodar | Amount |
SET | Establish | Cantidad |
SF | Pies Cuadrados | Area |
SH | Hojas | Cantidad |
SÍ | Pulgada Cuadrada | Área |
SY | Yarda Cuadrada | Area |
TB | Tubo | Cantidad |
YD | Patio | Longitud |
HL | Hectolitro | Volumen |
M3 | Metro cúbico | Volumen |
P3 | Cubic feet | Volume |
LM | Línea de metro | length |
CM2 | Square centimeter | Superficie |
PO3 | Cubic inch | Volume |
DZ | Dozen | Amount |
Códigos de Trabajo
Nombre | Código | Descripción |
|---|---|---|
Detallando | DET | Limpieza, detallado, etc. |
Inspección Pre-Entrega | PDI | Inspección Pre-Entrega |
Mantenimiento Programado | SMC | Todas las actividades de mantenimiento estándar |
Instalación de piezas y accesorios | PADRE | Toda la instalación de piezas adicionales |
Reparar | RPR | Todas las reparaciones en un vehículo |
Otro | OTRO | Todos los demás trabajos |
Recurso: Respuesta de Transacciones
La API devuelve el Respuesta de Transacciones recurso cuando la llamada POST es exitosa.
El nombre de archivo contiene el nombre del archivo creado para almacenar los datos en el procesador de carga de datos del backend.
👉 ¡Mantén este nombre de archivo en tu registro DMS!
Es útil al investigar un problema de compartición de datos de transacciones minoristas. 🕵️♀️
Representación JSON
{
"status": "success",
"filename": "dealer_retail_transaction_api_delta_20230709_222142Z_4582fbf4-8670-4e06-a22d-a576c9dd6a9f.json.gz"
}Propiedades
Propiedad | Tipo | Definición | Notas |
|---|---|---|---|
estado | cadena | Siempre éxito. | |
nombre de archivo | cadena | El archivo donde se almacenan los datos en el backend para su procesamiento. | |
Limitaciones y Restricciones
Formato de Número
Todos los campos numéricos con decimales utilizan un punto (.) como separador decimal. La coma (,) no es compatible como separador decimal.
Número Máximo de Transacciones
Se pueden enviar un máximo de 500 transacciones en una carga útil.
Tamaño de Carga Útil de Transacciones
La API de Transacciones Minoristas funciona en APIGee, que tiene un tamaño máximo de carga útil de 10 MB.
Consulte la sección 413 Entidad de Solicitud Demasiado Grande para más información sobre cómo manejar el código de estado 413.
Número de Transacción
El número de transacción encontrado en el encabezado se utiliza como la clave única de la transacción.
❗ El número de transacción debe ser único para un concesionario ❗
Vemos dos casos:
- Su DMS tiene una secuencia de números de transacción utilizada para todos los tipos de transacciones (venta al mostrador, órdenes de reparación y ventas de unidades).
- Su DMS tiene una secuencia de números de transacción diferente para cada tipo de transacción (venta al mostrador, orden de reparación y venta de unidad)
En el primer caso, cada transacción, independientemente de su tipo, tiene un número de transacción único. No tiene nada que hacer.
En el segundo caso, dos transacciones pueden tener el mismo número de transacción. Por ejemplo, tanto una venta al mostrador como una orden de reparación pueden tener el número de transacción "12345".
En este caso, necesita agregar un prefijo al número de transacción para hacerlo único. Por ejemplo:
- "P-" para venta al mostrador.
- "R-" para órdenes de reparación.
- "U-" para ventas de unidades.
En nuestro ejemplo, el número de transacción de venta al mostrador será "P-12345" y el número de transacción de la orden de reparación será "R-12345".