Comprensión de las transacciones minoristas
Esta sección proporciona información esencial sobre transacciones y varios aspectos de la API de Transacciones Minoristas.
❗ ❗ ❗ ¡Tómate un momento para leerlo! ❗ ❗ ❗
Conceptos Básicos
Esta sección presenta los conceptos básicos para el transacciones propiedades del objeto.
Separador Decimal
Todos los campos numéricos utilizan un punto (.) como separador decimal. La coma (,) no es compatible como separador decimal.
Propiedades Obligatorias y Opcionales
Las propiedades del objeto de transacción se enumeran en la Propiedades sección. Algunas propiedades son obligatorias (las identificadas en azul y con un asterisco). Las otras propiedades son opcionales y pueden ser excluidas si no tienes la información.
La API devuelve un código de estado 400 Bad Request si la carga útil carece de una propiedad obligatoria.
Si la propiedad obligatoria es un array y no hay información para enviar, la carga útil debe contener un array vacío.
Por ejemplo, la carga útil debe contener un array de partes vacío si no hay transacción OTC.
"parts": [],
Por ejemplo, el concesionario puede no haber incluido la lectura del odómetro en una orden de reparación. La odometer_reading propiedad puede ser excluida de la carga útil o enviada con un null valor.
❗ Las propiedades opcionales deben incluirse en su carga útil si la información está disponible en su DMS.
Valor faltante para una propiedad
Si su DMS no tiene la información para una propiedad de transacción y la propiedad es opcional, puede eliminarla de la carga útil.
Si la propiedad es obligatoria, puede establecer la propiedad según el tipo de propiedad:
- Cadena: una cadena vacía ("") o nulo.
- Número: un valor nulo.
- Fecha: un valor nulo.
Precios
Hay muchas propiedades de precio encontradas en las partes y transacciones de unidad. La mayoría son bastante directas.
- Precio del concesionario: El precio unitario (para una cantidad de 1) que el concesionario establece para la parte o vehículo.
- Costo del concesionario: El precio unitario (para una cantidad de 1) al que el concesionario compró el artículo de BRP.
- Precio de venta sugerido por el fabricante (MSRP): El precio unitario (para una cantidad de 1) precio de venta sugerido por el fabricante para el artículo en el momento de la transacción.
- Precio total al cliente: El total precio que pagó el cliente, incluidos todos los impuestos, reembolsos, tarifas de envío, etc. Consulte a continuación para obtener más información sobre el precio total al cliente.
El precio total al cliente para piezas comienza con la cantidad valor de propiedad multiplicado por el precio de venta sugerido por el fabricante (MSRP).
Todos los costos adicionales están incluidos en el cálculo del precio total al cliente para un artículo.
Un precio puede ser negativo si representa un retorno, un intercambio o un descuento.
Costos Adicionales
Los documentos de costos adicionales documentan lo que se añade al costo del concesionario para obtener el precio total al cliente.
👉 Si el total_customer_price es diferente del msrp, la transacción debe incluir additional_costs elementos para explicar la diferencia.
Hay cuatro tipos de costos adicionales:
- Impuesto: El monto del impuesto aplicado al artículo.
- Logística: Las tarifas asociadas con el envío, la entrega, el embalaje, etc.
- Descuento: El monto del descuento se resta del precio total.
- Otro: Cualquier otro costo incluido en el precio total del cliente que no se encuentre en las categorías anteriores.
Los costos adicionales pueden ser un monto positivo , como impuestos, o un monto negativo, como un descuento.
❗❗ Puede que tenga información en sus DMS sobre costos adicionales no incluidos en el valor_total_cliente . Estos costos adicionales no deben ser enviados en la carga útil ❗❗
❗❗ Si el costo adicional es una tarifa fija, no incluya el monto_aplicable y tarifa campos para la transacción. Incluya solo el monto campo en el costo adicional.
No envíe una tarifa con un valor de 0. ❗❗
Aquí hay un ejemplo de un cliente comprando un vehículo nuevo y entregando uno viejo.
"units": [
{
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.2,
"hours": 1.5,
"class_code": "NEW",
"sales_lead_id": "xxxx-xxxx",
"total_customer_price": 10194.35, /* 8 */
"dealer_price": 16249.00, /* 1 */
"dealer_cost": 15000.00,
"msrp": 16249.00,
"currency": "CAD",
"additional_costs": [
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": 16249.00,
"rate": 0.15,
"amount": 2437.35 /* 2 */
},
{
"type": "Tax",
"description": "Environmental Tax",
"amount": 8.00 /* 3 */
},
{
"type": "Logistic",
"description": "Delivery Fee",
"amount": 50.00 /* 4 */
},
{
"type": "Discount",
"description": "Spring Sale Discount",
"rate" : -0.15,
"amount": -500.00 /* 5 */
},
{
"type": "Discount",
"description": "Delivery Fee Discount",
"amount": -50.00 /* 6 */
}
],
"trade_ins": [
{
"manufacturer": "BRP",
"vin": "2BPSTCEA0AA000001",
"odometer_reading": 16180,
"hours": 1024.7,
"price": -8000.00 /* 7 */
}
],
"financed_amount": 10994.21,
"financed_rate": 0.0499,
"financed_term_duration": 60
}
]El precio total al cliente se calcula así:
- + 16249 (precio del concesionario)
- + 2437.35 (Impuesto sobre ventas)
- + 8.00 (Impuesto Ambiental)
- + 50 (Cargo de Entrega)
- - 500 (Descuento por Venta de Primavera)
- - 50 (Descuento por Cargo de Entrega)
- - 8000 (intercambio)
- = 10194.35
También se utiliza un costo adicional para documentar los costos de trabajo fuera del concesionario, que se cobran al cliente.
Por ejemplo, una parte del carro puede necesitar ser pintada durante una reparación del vehículo. La parte del carro se envía a un taller de pintura, y el costo relacionado se documenta como un costo adicional. Por ejemplo:
"additional_costs": [
{
"type": "Other",
"description": "Side panel paint job",
"amount": 413.58
},
{
...Impuestos
Los impuestos deben incluirse en los costos adicionales de cada artículo en una transacción. Por ejemplo, si hay dos partes en una transacción de partes, debería haber un costo adicional de impuestos para cada una de las dos partes.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/dealer/MY_DEALER/retail-transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"transactions": [
{
"header": {
"cancel_flag": false,
"customers": [
{
"city": "Denver",
"country": "USA",
"customer_hash": "77c6c73a430e5b4630321d52eecfba3574662dcfcee84d92cefde2b93df03161",
"customer_id": "21765GE0",
"recipient": "Customer",
"state_province": "COL"
}
],
"transaction_close_date": "2023-06-14T00:00:00Z",
"transaction_number": "33446088",
"transaction_open_date": "2023-06-13T00:00:00Z",
"transaction_source": "In-Store",
"transaction_uuid": "f6c1d22c-0325-43d6-8d62-51623b8edb61"
},
"parts": [
{
"currency": "CAD",
"is_special_order": false,
"quantity_uom": "PC",
"part_description": "FLANGED TORX SCREW M6 X 30",
"part_number": "420441575",
"quantity": 10.0,
"dealer_cost": 1.74,
"dealer_price": 2.89,
"msrp": 2.89,
"total_customer_price": 28.90,
"additional_costs": [
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": 28.90,
"rate": 0.15,
"amount": 4.34
}
]
},
{
"currency": "CAD",
"is_special_order": false,
"quantity_uom": "PC",
"part_description": "XPS - SYN CHAIN CASE OIL 355ML",
"part_number": "9779156",
"quantity": 1.0,
"dealer_cost": 9.44,
"dealer_price": 15.99,
"msrp": 15.99,
"total_customer_price": 15.99,
"additional_costs": [
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": 15.99,
"rate": 0.15,
"amount": 2.40
}
]
}
],
"units": [],
"jobs": []
}
]
}'👉 Si su DMS solo muestra el monto total del impuesto para la transacción, este monto debe dividirse entre cada artículo.
Con nuestro ejemplo anterior, digamos que su DMS tiene un impuesto total de $6.74. El precio total al cliente para la transacción es de $44.89. El monto del impuesto se dividirá así:
- Primera parte: $28.90 / $44.89 * $6.74 = $4.34
- Segunda parte: $15.99 / $44.89 * $6.74 = $2.40
Intercambio en una venta de unidad
Cuando un cliente compra una unidad, puede entregar una unidad que posee como intercambio para reducir el costo de la nueva unidad. Hay al menos 3 escenarios diferentes respecto a un intercambio:
- Un intercambio que reduce el precio total del cliente.
- Un intercambio con un pago que reduce el precio total del cliente.
- Un intercambio con un pago que no reduce el precio total del cliente.
❗El monto de la entrega debe ser negativo ❗
Escenario Simple
El caso simple es cuando el valor de la entrega se resta del precio total del cliente.
"units": [
{
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.2,
"hours": 1.5,
"class_code": "NEW",
"sales_lead_id": "xxxx-xxxx",
"total_customer_price": 10194.35, /* 8 */
"dealer_price": 16249.00, /* 1 */
"dealer_cost": 15000.00,
"msrp": 16249.00,
"currency": "CAD",
"additional_costs": [
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": 16249.00,
"rate": 0.15,
"amount": 2437.35 /* 2 */
},
{
"type": "Tax",
"description": "Environmental Tax",
"amount": 8.00 /* 3 */
},
{
"type": "Logistic",
"description": "Delivery Fee",
"amount": 50.00 /* 4 */
},
{
"type": "Discount",
"description": "Spring Sale Discount",
"rate" : -0.15,
"amount": -500.00 /* 5 */
},
{
"type": "Discount",
"description": "Delivery Fee Discount",
"amount": -50.00 /* 6 */
}
],
"trade_ins": [
{
"manufacturer": "BRP",
"vin": "2BPSTCEA0AA000001",
"odometer_reading": 16180,
"hours": 1024.7,
"price": -8000.00 /* 7 */
}
],
"financed_amount": 10994.21,
"financed_rate": 0.0499,
"financed_term_duration": 60
}
]El precio total del cliente se calcula así:
- + 16249 (precio del concesionario)
- + 2437.35 (Impuesto sobre Ventas)
- + 8.00 (Impuesto Ambiental)
- + 50 (Cargo de Entrega)
- - 500 (Descuento por Venta de Primavera)
- - 50 (Descuento por Cargo de Entrega)
- - 8000 (intercambio)
- = 10194.35
Intercambio con un Pago
El segundo escenario es cuando un pago está asociado con el intercambio. Se realiza un pago cuando hay un saldo de préstamo restante en la unidad de intercambio, y el concesionario paga este saldo. El resultado es que el monto del intercambio es menor y no reduce el costo total para el cliente.
"units": [
{
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.2,
"hours": 1.5,
"class_code": "NEW",
"sales_lead_id": "xxxx-xxxx",
"total_customer_price": 12194.35, /* 9 */
"dealer_price": 16249.00, /* 1 */
"dealer_cost": 15000.00,
"msrp": 16249.00,
"currency": "CAD",
"additional_costs": [
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": 16249.00,
"rate": 0.15,
"amount": 2437.35 /* 2 */
},
{
"type": "Tax",
"description": "Environmental Tax",
"amount": 8.00 /* 3 */
},
{
"type": "Logistic",
"description": "Delivery Fee",
"amount": 50.00 /* 4 */
},
{
"type": "Discount",
"description": "Spring Sale Discount",
"rate" : -0.15,
"amount": -500.00 /* 5 */
},
{
"type": "Discount",
"description": "Delivery Fee Discount",
"amount": -50.00 /* 6 */
},
{
"type": "Other",
"description": "Payout",
"amount": 2000.00 /* 7 */
}
],
"trade_ins": [
{
"manufacturer": "BRP",
"vin": "2BPSTCEA0AA000001",
"odometer_reading": 16180,
"hours": 1024.7,
"price": -8000.00 /* 8 */
}
],
"financed_amount": 12194.35,
"financed_rate": 0.0499,
"financed_term_duration": 60
}
]El precio total para el cliente se calcula así:
- + 16249 (precio del concesionario)
- + 2437.35 (Impuesto sobre Ventas)
- + 8.00 (Impuesto Ambiental)
- + 50 (Tarifa de Entrega)
- - 500 (Descuento de Venta de Primavera)
- - 50 (Descuento de Tarifa de Entrega)
- + 2000 (Pago)
- - 8000 (intercambio)
- = 12194.35
👉 El pago debe ser agregado a los costos adicionales; de lo contrario, el precio total para el cliente será incorrecto.
Pago Mayor Que el Valor de Intercambio
El tercer escenario es cuando el pago asociado con el intercambio es mayor que el valor del intercambio. En este escenario, el intercambio no reduce el precio total del cliente.
"units": [
{
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.2,
"hours": 1.5,
"class_code": "NEW",
"sales_lead_id": "xxxx-xxxx",
"total_customer_price": 19194.35, /* 9 */
"dealer_price": 16249.00, /* 1 */
"dealer_cost": 15000.00,
"msrp": 16249.00,
"currency": "CAD",
"additional_costs": [
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": 16249.00,
"rate": 0.15,
"amount": 2437.35 /* 2 */
},
{
"type": "Tax",
"description": "Environmental Tax",
"amount": 8.00 /* 3 */
},
{
"type": "Logistic",
"description": "Delivery Fee",
"amount": 50.00 /* 4 */
},
{
"type": "Discount",
"description": "Spring Sale Discount",
"rate" : -0.15,
"amount": -500.00 /* 5 */
},
{
"type": "Discount",
"description": "Delivery Fee Discount",
"amount": -50.00 /* 6 */
},
{
"type": "Other",
"description": "Payout",
"amount": 6000.00 /* 7 */
}
],
"trade_ins": [
{
"manufacturer": "BRP",
"vin": "2BPSTCEA0AA000001",
"odometer_reading": 16180,
"hours": 1024.7,
"price": -5000.00 /* 8 */
}
],
"financed_amount": 12194.35,
"financed_rate": 0.0499,
"financed_term_duration": 60
}
]El precio total del cliente se calcula así:
- + 16249 (precio del concesionario)
- + 2437.35 (Impuesto sobre Ventas)
- + 8.00 (Impuesto Ambiental)
- + 50 (Tarifa de Entrega)
- - 500 (Descuento de Venta de Primavera)
- - 50 (Descuento de Tarifa de Entrega)
- + 6000 (Pago)
- - 5000 (intercambio)
- = 19194.35
👉 El pago debe ser agregado a los costos adicionales; de lo contrario, el precio total para el cliente será incorrecto.
Agregación de Cantidades
Si la cantidad de piezas excede uno, el costo_del_concesionario, precio_del_concesionario, y msrp las propiedades permanecen unitarias (para una cantidad de 1).
El precio_total_del_cliente y los costos_adicionales para estas piezas son para el número de piezas indicado por el valor_de_cantidad de la propiedad.
Tarjeta de Tiempo de Trabajo Tasa de Mano de Obra
La información relacionada con un trabajo de servicio está contenida en la trabajos propiedad.
La información se ve así:
"jobs": [
{
"job_number": "14727",
"job_code": "OTH",
"description": "Special Ultra High Altitude Tuning",
"is_warranty_job": false,
"total_customer_job_price": 135.15,
"currency": "CAD",
"time_cards": [
{
"labour_worked_hours": 1.5,
"labour_billed_hours": 1.5,
"labour_rate": 85,
"technician_party_id": "TECH00123"
}
],
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.5,
"hours": 1.7,
"additional_costs": [
{
"amount": 7.65,
"description": "Sales",
"rate": 0.06,
"type": "Tax",
"applicable_amount": 127.50
}
]
}
]El valor_total_del_cliente_del_trabajo es la suma de todos los time_cards para todos los técnicos que trabajaron en el trabajo más los costos adicionales del trabajo. Para cada tarjeta de tiempo, el monto es horas_facturadas_de_mano_de_obra * tasa_de_mano_de_obra.
¿Pero qué pasa si el trabajo se realiza a un precio fijo para el cliente?
En este caso, el tasa_de_trabajo se calcula a partir de las horas_facturadas_de_trabajo valor.
Por ejemplo, los datos deberían verse así si el trabajo se realiza a un precio fijo de $75 por 1.5 horas.
La tasa_de_trabajo es $75.00 / 1.5 horas = $50.00
"jobs": [
{
"job_number": "14727",
"job_code": "OTH",
"description": "Special Ultra High Altitude Tuning",
"is_warranty_job": false,
"total_customer_job_price": 79.50,
"currency": "CAD",
"time_cards": [
{
"labour_worked_hours": 1.5,
"labour_billed_hours": 1.5,
"technician_party_id": "TECH00123",
"labour_rate" : 50.00
}
],
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.5,
"hours": 1.7,
"additional_costs": [
{
"amount": 4.50,
"description": "Sales",
"rate": 0.06,
"type": "Tax",
"applicable_amount": 75.00
}
]
}
]Entendiendo las Transacciones
Esta sección presenta información detallada sobre el contenido de cada tipo de transacción.
Todos los campos numéricos utilizan un punto (.) como separador decimal. La coma (,) no es ACEPTADA como separador decimal.
Encabezado
La transacción encabezado contiene información sobre el cliente y la transacción según lo definido en su DMS.
Propiedad | ¿Qué es? |
|---|---|
número_de_transacción * | El identificador de la transacción se define en su DMS. ¡Debe ser único para el concesionario! |
fecha_de_apertura * | La fecha en que se creó la transacción. Incluso si la transacción se modifica después de que se abre, esta fecha no cambia. |
fecha_de_cierre * | La fecha en que se cerró la transacción en su DMS. La definición de un transacción cerrada puede diferir de un sistema a otro. Generalmente, una transacción se considera cerrada si el cliente paga y los fondos se envían a contabilidad. |
fuente_de_transacción * | La fuente de la transacción, ya sea "en tienda" o "en línea". El objetivo es recibir las transacciones en línea si están disponibles en su DMS. |
bandera_de_cancelación * | Indica si la transacción fue cancelada. Una transacción cancelada no es un retorno. Un retorno es una transacción con montos negativos, como se describe en el Devoluciones sección. Si envías una transacción que luego se cancela por cualquier motivo, envía la misma transacción con el cancel_flag establecido en TRUE y un transaction_uuid valor. Entonces sabremos que la transacción fue cancelada. |
uuid_transacción * | Un ID único para indicar esto iteración de la transacción. Si se crea una transacción y luego se modifica, por ejemplo, al agregar partes, el número_de_transacción y fecha_de_apertura las propiedades mantienen el mismo valor cuando envías la carga útil. Sin embargo, el transaction_uuid propiedad debe ser diferente. El número_de_transacción nos permite encontrar la transacción original, y los diferentes uuid_de_transacción indica que la transacción fue actualizada. |
clientes * | La lista de clientes para las transacciones. Vea a continuación las propiedades del cliente. Si no hay información del cliente disponible, el arreglo está vacío. |
- Las propiedades en azul y marcadas con un asterisco (*) son obligatorias en el recurso.
Aunque generalmente solo hay un cliente para una transacción, el encabezado contiene una lista de clientes en caso de que la necesites.
❗ ❗ No se debe enviar información personal del cliente en la carga útil ❗ ❗
No nombre, apellido, dirección de correo electrónico, número de teléfono, etc.
La única información proporcionada es la ciudad, estado o provincia y país del cliente.
Si el customer_id contiene información personal del cliente, como su apellido, establezca la propiedad en null o una cadena vacía.
BRP utiliza la información del cliente en el encabezado para vincular transacciones realizadas por el mismo cliente en el mismo concesionario.
El objetivo es extraer estadísticas sobre la lealtad del cliente, concesionario y marca.
El ID del cliente y/o los valores hash del cliente se utilizan para esto. Si no están disponibles, no hay problema 😁.
Propiedad | ¿Qué es? |
|---|---|
id_cliente * | Un identificador único a nivel del concesionario (o DMS) para este cliente. Si no está disponible, por ejemplo, si el cliente va al mostrador sin una cuenta en el concesionario, use "INVITADO". IMPORTANTE Si el customer_id el valor de la propiedad contiene la información personal del cliente, como su apellido, establezca la propiedad en null o una cadena vacía.
|
hash_del_cliente * | Un hash SHA-256 del número de teléfono y el correo electrónico del cliente. El hash debe ser calculado sobre la cadena: Número de teléfono E.164 + espacio + dirección de correo electrónico Por ejemplo: +18882729222 [email protected] IMPORTANTE Establezca el valor de la propiedad en nulo si falta el correo electrónico o el número de teléfono. |
destinatario * | ¿Quién fue el receptor de la transacción? Uno de: . Cliente . Uno mismo . Concesionario Cliente: el cliente "estándar". Uno mismo: el propio concesionario, por ejemplo, vendiendo piezas a diferentes departamentos, añadiendo accesorios a un vehículo, etc. Concesionario: un concesionario diferente al propio. |
ciudad | La ciudad donde vive el cliente. Si no está disponible, la ciudad donde se encuentra el concesionario. |
estado_provincia | Estado o provincia donde vive el cliente. Establezca en nulo si no se aplica al país. |
país | El país donde vive el cliente. Si no está disponible, el país donde se encuentra el concesionario. |
- Las propiedades en azul, marcadas con un asterisco (*), son obligatorias en el recurso.
Partes
La Partes transacción se utiliza para ventas de partes, accesorios y ropa (PA&A) de mostrador.
❗ ❗ Solo se deben incluir partes, accesorios y ropa de BRP en las transacciones de partes ❗ ❗
Si una transacción que contiene una unidad de BRP también contiene algunas partes que no son de BRP, estas partes se incluyen en un objeto de parte agregado con el número_de_parte y descripción_de_parte propiedades establecidas en "PARTES-NON-BRP".
Propiedad | ¿Qué es? |
|---|---|
descripción_parte * | La descripción de la parte BRP se obtiene del catálogo de piezas (ver el API de piezas). Establecer en “NON-BRP-PARTS” para una pieza no BRP utilizada en un trabajo de orden de reparación. Si la descripción de la parte no está disponible, la propiedad se establece en nulo o en una cadena vacía. |
número_de_parte * | El número de parte del BRP se obtiene del catálogo de piezas (ver el API de piezas). Establecer en “NON-BRP-PARTS” para una pieza no BRP utilizada ien un trabajo de orden de reparación. |
cantidad * | La cantidad de esta parte. Puede ser un número decimal para partes con una unidad de medida, como longitud (metros, pies) o volumen (litros, onzas, galones). |
cantidad_uom * | Las Unidades de Medida (UOM) se utilizan para calificar la cantidad. El valor se obtiene del catálogo de piezas (ver el API de piezas). Las unidades de medida válidas se enumeran en la tabla de Unidades de Medida (UoM) a continuación. |
es_pedido_especial * | Una bandera para indicar que esta parte es un pedido especial para un cliente. Es una parte que no suele estar en stock y fue ordenada para un cliente. |
precio_total_cliente * precio_del_concesionario costo_del_concesionario precio de venta sugerido por el fabricante | Los precios son como se describe en la sección Precios arriba. |
moneda * | La moneda se utiliza para todos los precios en este objeto y en los objetos hijos. Las unidades de medida válidas se enumeran en la sección de moneda a continuación. |
número_de_trabajo_asociado | El número de trabajo de la orden de reparación que consumió esta pieza. Así es como se identifican las partes utilizadas en un trabajo de orden de reparación. El valor debe coincidir con uno de los número_de_trabajopropiedad en el Trabajos array. Ver el Trabajos sección a continuación. |
costos_adicionales * | Una serie de costos adicionales. Si no hay costos adicionales, el arreglo está vacío. Vea la sección Costos Adicionales arriba. |
- Las propiedades en azul y marcadas con un asterisco (*) son obligatorias en el recurso.
El número_de_trabajo_asociado es esencial para vincular las partes al trabajo utilizando las partes.
El valor debe coincidir con uno de los números_de_trabajo en la Lista de Trabajos
Trabajos
Los Trabajos representan el trabajo realizado en un vehículo para una orden de reparación del concesionario.
Si el trabajo se realiza en un vehículo no-BRP utilizando piezas BRP, la transacción contiene solo estas piezas y ningún trabajo.
Propiedad | ¿Qué es? |
|---|---|
número_de_trabajo * | El número de trabajo es del DMS del concesionario y debe ser único en el concesionario. |
código_de_trabajo * | El código para este trabajo. |
descripción * | La descripción del trabajo, tal como fue ingresada en el DMS por el técnico. |
es_trabajo_de_garantía * | Bandera para indicar si este trabajo está cubierto por una garantía |
número_de_reclamación_de_garantía | El número de reclamación que se recibió de BRP. |
precio_total_del_trabajo_del_cliente * | Los precios totales para el cliente, como se describe en la sección Precios arriba. IMPORTANTE El precio total del trabajo del cliente es la suma de todos los costos laborales, excluyendo los costos de las piezas. |
moneda * | La moneda utilizada para todos los precios en este objeto y en los objetos hijos. Las unidades de medida válidas se enumeran en la sección de moneda a continuación. |
vino | El Número de Identificación del Vehículo (VIN) de la unidad en reparación/mantenimiento. |
lectura del odómetro | Lectura del odómetro en kilómetros. Si el odómetro del vehículo está en millas, debe convertirse a kilómetros. |
horas | Lectura del número de horas de trabajo para un vehículo sin odómetro, como un Sea-Doo. |
fabricante | El fabricante de la unidad en la que se realizó el trabajo. |
modelo | El modelo de la unidad en la que se llevó a cabo el trabajo. |
año | El año del modelo de la unidad en la que se realizó el trabajo. |
tarjetas_de_tiempo * | Un arreglo de tarjetas de tiempo. El arreglo está vacío si no hay información de tarjetas de tiempo disponible. Vea a continuación los detalles. |
costos_adicionales * | Una serie de costos adicionales. Si no hay costos adicionales, el arreglo está vacío. Vea la sección Costos Adicionales arriba. Si el trabajo se realiza fuera del concesionario, por ejemplo, enviando una pieza a un taller de pintura, el costo se documenta con un costo adicional de tipo "Otro". |
- Las propiedades en azul, marcadas con un asterisco (*), son obligatorias en el recurso.
El Tarjeta de Tiempo documenta el trabajo de un técnico en un trabajo. Hay un objeto de tarjeta por técnico que trabaja en el trabajo.
Propiedad | ¿Qué es? |
|---|---|
horas_trabajadas * | El número de horas que este técnico trabajó en este trabajo. |
horas_facturadas * | El número de horas que este técnico facturó al cliente por este trabajo. |
tarifa_hora * | La tarifa por hora de este técnico. |
id_técnico * | El ID del técnico en el concesionario. |
- Las propiedades en azul, marcadas con un asterisco (*), son obligatorias en el recurso.
Las horas trabajadas y facturadas pueden diferir si el concesionario decide no cobrar al cliente por todas las horas.
Por cada tarjeta de tiempo, el valor de labour_billed_hours x labour_rate se suma al total_customer_job_price por el trabajo.
Por ejemplo, 2 técnicos trabajaron en un vehículo, uno para reparar un defecto y otro para instalar un accesorio.
{
"job_number": "5678",
"job_code": "FIX",
"description": "Repair and install",
"is_warranty_job": false,
"total_customer_job_price": 197.50,
"currency": "CAD",
"time_cards": [
{
"labour_worked_hours": 1.5,
"labour_billed_hours": 1.5,
"labour_rate": 65,
"technician_party_id": "TECH00101"
},
{
"labour_worked_hours": 2,
"labour_billed_hours": 2,
"labour_rate": 50,
"technician_party_id": "TECH00113"
}
],
"vin": "2BPSCDRB0AA000001",
"odometer_reading": 1.2,
"hours": 1.5
}El precio total por la mano de obra incluida en el total_customer_job_price es:
Unidades
La Unidades documenta la transacción de la venta de un vehículo a un cliente.
❗ ❗ Su DMS solo envía ventas unitarias de vehículos BRP ❗ ❗
Propiedad | ¿Qué es? |
|---|---|
vino * | El Número de Identificación del Vehículo (VIN) del vehículo comprado. |
lectura_del_odómetro | Lectura del odómetro en kilómetros. Si el odómetro del vehículo está en millas, debe convertirse a kilómetros. |
horas | Lectura del número de horas de trabajo de un vehículo sin odómetro, como un Sea-Doo. |
código_clase * | El código de clase para este vehículo: "Nuevo", "Usado" o "Demostrador". |
id_de_oportunidad_de_venta | El ID de BRP de los leads de ventas que resultaron en esta venta. |
precio_total_cliente * precio_del_concesionario costo_del_concesionario precio de venta sugerido por el fabricante | |
moneda * | La moneda se utiliza para todos los precios de este objeto y sus objetos hijos. Las unidades de medida válidas se enumeran en la sección de moneda a continuación. |
monto_financiado | La cantidad que se financió para la compra de este vehículo. |
tasa_financiada | La tasa de financiamiento. |
duración del término financiado | El número de meses durante los cuales se financia la unidad. |
comercio_ins | Una lista de vehículos de intercambio. La propiedad no se envía o está vacía si no hay un intercambio. |
- Las propiedades en azul y marcadas con un asterisco (*) son obligatorias en el recurso.
El Intercambio documenta el vehículo que el cliente dio como intercambio para reducir el precio_total_del_cliente valor.
Propiedad | ¿Qué es? |
|---|---|
fabricante | El fabricante del vehículo entregado a cambio. |
vino | El VIN del vehículo entregado a cambio. |
lectura_del_odómetro | Lectura del odómetro en kilómetros. Si el odómetro del vehículo está en millas, debe convertirse a kilómetros. |
horas | Lectura del número de horas de trabajo para un vehículo sin odómetro, como un Sea-Doo. |
modelo | El modelo del vehículo entregado a cambio. |
precio * | El precio que el concesionario pagó por la unidad entregada a cambio. El precio debe ser un número negativo para restarlo de la total_customer_price valor. |
año | El año del modelo del vehículo entregado a cambio. |
- Las propiedades en azul y marcadas con un asterisco (*) son obligatorias en el recurso.
Preferiblemente, debe incluir el VIN de un vehículo de intercambio. Si el VIN no está disponible, se utilizarán el fabricante y el año del modelo.
Un vehículo de intercambio precio debe ser un número negativo para eliminar el valor del total_precio_cliente valor.
Formato de Datos
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 |
Estado de la Transacción
Esta sección describe cómo manejar los cambios en una transacción.
Transacciones Actualizadas
El requisito básico es que solo cerradas las transacciones se envíen a BRP.
Sin embargo, dependiendo del comportamiento de su DMS y de lo que se considere una transacción cerrada, una transacción enviada a la API de Transacciones Minoristas puede ser modificada en su DMS.
Puede enviar la transacción actualizada siempre que el número_de_transacción sea el mismo para ambas instancias, pero el uuid_de_transacción es diferente.
Una transacción puede ser actualizada siempre que el número_de_transacción sea el mismo para ambas instancias, pero el uuid_de_transacción es diferente.
El número_de_transacción,uuid_de_transacción, y la fecha de recepción de la transacción añadida por la API de Transacciones Minoristas se utilizan durante el análisis de datos para encontrar la última transacción.
Transacciones Canceladas
Su DMS puede permitir que el concesionario cancele una transacción. Para cancelar una transacción, actualícela con el cancelar_bandera configurada en VERDADERO.
Dado que una cancelación es una actualización, se aplican las mismas reglas: el número_de_transacción es el mismo para ambas instancias, pero el uuid_de_transacción es diferente.
Una transacción puede ser cancelada enviándola con la cancelar_bandera configurada en VERDADERO, el mismo número_de_transacción y un nuevo uuid_de_transacción.
Devoluciones
Las devoluciones se gestionan como cualquier otra transacción, pero con un negativo total_customer_price y todos los costos adicionales.
Por ejemplo, cuando un cliente devuelve una parte, la transacción aparece de la siguiente manera.
{
"part_description": "Deep Snow Soft Knee Pads",
"part_number": "860202702",
"quantity": 1,
"quantity_uom": "PC",
"is_special_order": false,
"total_customer_price": -120.74,
"dealer_price": 104.99,
"dealer_cost": 79.99,
"msrp": 99.99,
"currency": "CAD",
"additional_costs":[
{
"type": "Tax",
"description": "Sales Tax",
"applicable_amount": -104.99,
"rate": 0.15,
"amount": -15.75
}
],
"associated_job_number": ""
}Puedes mezclar transacciones "normales" y transacciones de devolución en el mismo conjunto de transacciones.
Por ejemplo, el Array de transacciones de partes podría contener 2 compras de un cliente y una devolución.
Privacidad de Datos
Consentimiento para Compartir Datos
Como se explica en la Consentimiento para Compartir Datos del Concesionario sección, el concesionario debe consentir la compartición de datos antes de que se envíen los datos de cualquier transacción minorista.
El intercambio de datos de transacciones minoristas es un tema más sensible que el intercambio de datos de inventario de piezas con los concesionarios.
Entender qué y por qué se comparte a través de la API de Transacciones Minoristas es importante para explicárselo a los concesionarios.
Información No-BRP
¡Solo las transacciones que contienen información de BRP PA&A y de unidades se envían a la API de Transacciones Minoristas!
¡Si una transacción solo concierne a PA&A y unidades no-BRP, no debe enviarse a la API de Transacciones Minoristas!
Información del Cliente
Las reglas y leyes de privacidad de datos han estado vigentes en algunos países durante años y ahora se están implementando en muchos estados y países.
Por eso, la carga útil de las transacciones minoristas no contiene la información personal del cliente.
El customer_hashen la customer objeto ha sido diseñado para ser no reversible: el correo electrónico y el número de teléfono del cliente no se pueden recuperar del hash.
Es esencial incluir el valor hash SOLO si tanto el correo electrónico como el número de teléfono del cliente están disponibles.
Si falta uno, el valor hash debe establecerse en null.
Transmisión de Datos
Cuándo Enviar
Su DMS puede enviar transacciones a medida que se cierran en tiempo real o como una presentación por lotes al final del día laboral.
Las transacciones cerradas consisten en facturas que se registran como completas en su DMS. Si un concesionario reabre una factura para hacer cambios, esa factura no se envía a BRP hasta que se haya cerrado nuevamente.
Cuando la factura se cierre nuevamente, envíe la factura actualizada como se describe en la Transacciones Actualizadas sección.
La "regla general" sobre qué incluir en su carga útil de transacción a BRP es cualquier transacción publicada en el libro mayor general (GL).
Datos Históricos
Para muchos programas de BRP, los datos históricos de transacciones minoristas son esenciales y, en algunos casos, requeridos. Por ejemplo, el programa de Gestión de Inventario Minorista (RIM) requiere que se disponga de 18 a 24 meses de datos de transacciones minoristas antes de que el concesionario pueda unirse a RIM.
Cuando un concesionario consiente el intercambio de datos, todos los datos disponibles dentro de los últimos 4 años deben ser enviados.
Si el concesionario opta por no participar en el intercambio de datos, la transmisión de datos históricos debe detenerse.
Retransmisión de Datos
Su DMS debe ser capaz de reenviar transacciones para un rango de fechas específico. Esta función es manual; la solicitud no se enviará a través de una API.
Esta función se utilizará si, por alguna razón, faltan o están corruptos los datos.
Lógica de Reintento Automático
En caso de una falla del sistema BRP o una interrupción debido a mantenimiento u otros problemas imprevistos, su DMS recibe un mensaje de error de la API que contiene una descripción del error.
Su DMS debe tener un proceso de automatización para reenviar una solicitud hasta que reciba una respuesta de reconocimiento.
Durante las primeras 24 horas, se recomienda una estrategia de reintento deslizante. En esta estrategia, su DMS continúa intentando llamar a la API, añadiendo retrasos de tiempo incrementales en cada intento subsiguiente.
Por ejemplo, el primer reintento puede esperar 5 minutos, el segundo esperará 10 minutos, el tercero esperará 20 minutos, y así sucesivamente. Cada reintento duplica el tiempo de espera hasta que se exceda el conteo de reintentos.
Después de 24 horas de reintentos, su DMS debe continuar intentando una vez al día. Si el problema persiste, su DMS debe retener todos los datos de transacciones minoristas de BRP hasta que se resuelva el problema.
Transición entre la API V2 y la API V4
Muchos programas comerciales de BRP utilizan datos de transacciones minoristas. La API V2 (STAR XML) y la API V4 (JSON) difieren significativamente en sus formatos de carga útil y procesamiento en el backend.
La API V2 envía los datos de transacciones minoristas a una base de datos SQL Server, que los programas comerciales de BRP utilizan actualmente para recuperar los datos.
La API V4 envía los datos de transacciones minoristas a una base de datos en la nube, y los programas comerciales de BRP deben ser modificados para recuperar los datos de esta base de datos en la nube.
Para ayudar a los programas comerciales de BRP durante la transición, la API V2 debe permanecer activa temporalmente incluso si la API V4 está certificada y desplegada en producción.
👉 Los datos de transacciones minoristas deben enviarse utilizando tanto la API V2 como la API V4 durante la transición.
Tan pronto como suficientes DMS hayan certificado la API V4 para incluir el 70-75% de los concesionarios, la API V2 será desactivada.