Compreendendo Transações de Varejo
Esta seção fornece informações essenciais sobre transações e vários aspectos da API de Transações de Varejo.
❗ ❗ ❗ Reserve um momento para lê-lo! ❗ ❗ ❗
Conceitos Básicos
Esta seção apresenta os conceitos básicos para o transações propriedades do objeto.
Separador Decimal
Todos os campos numéricos usam um ponto (.) como o separador decimal. A vírgula (,) é NÃO suportada como um separador decimal.
Propriedades Obrigatórias e Opcionais
As propriedades do objeto de transação estão listadas na Propriedades seção. Algumas propriedades são obrigatórias (as identificadas em azul e com um asterisco). As outras propriedades são opcionais e podem ser excluídas se você não tiver as informações.
A API retorna um código de status 400 Bad Request se a carga útil estiver faltando uma propriedade obrigatória.
Se a propriedade obrigatória for um array, e não houver informações para enviar, a carga útil deve conter um array vazio.
Por exemplo, a carga útil deve conter um array de partes vazio se não houver transação OTC.
"parts": [],
Por exemplo, o revendedor pode não ter incluído a leitura do odômetro em uma ordem de reparo. A odometer_reading pode ser excluída da carga útil ou enviada com um null valor.
❗ As propriedades opcionais devem ser incluídas na sua carga útil se as informações estiverem disponíveis no seu DMS.
Valor Ausente para uma Propriedade
Se o seu DMS não tiver as informações para uma propriedade de transação e a propriedade for opcional, você pode removê-la da carga útil.
Se a propriedade for obrigatória, você pode definir a propriedade com base no tipo da propriedade:
- String: uma string vazia ("") ou nulo.
- Número: um valor nulo.
- Data: um valor nulo.
Preços
Existem muitas propriedades de preço encontradas nas partes e transações de unidade. A maioria é bastante direta.
- Preço do revendedor: O preço unitário (para uma quantidade de 1) que o revendedor define para a peça ou veículo.
- Custo do revendedor: O preço unitário (para uma quantidade de 1) pelo qual o revendedor comprou o item da BRP.
- Preço de Venda Sugerido pelo Fabricante (MSRP): O preço unitário (para uma quantidade de 1) preço de venda sugerido pelo fabricante para o item no momento da transação.
- Preço total do cliente: O total preço que o cliente pagou, incluindo todos os impostos, reembolsos, taxas de envio, etc. Veja abaixo para mais informações sobre o preço total do cliente.
O preço total do cliente para peças começa com a quantidade valor da propriedade multiplicado pelo preço de venda sugerido pelo fabricante (MSRP).
Todos os custos adicionais estão incluídos no cálculo do preço total do cliente para um item.
Um preço pode ser negativo se representar uma devolução, uma troca ou um desconto.
Custos Adicionais
Os custos adicionais documentam o que é adicionado ao custo do revendedor para obter o preço total do cliente.
👉 Se o preço_total_do_cliente for diferente do msrp, a transação deve incluir custos_adicionais itens para explicar a diferença.
Existem quatro tipos de custos adicionais:
- Imposto: O valor do imposto aplicado ao item.
- Logística: As taxas associadas ao envio, entrega, embalagem, etc.
- Desconto: O valor do desconto é subtraído do preço total.
- Outro: Qualquer outro custo incluído no preço total do cliente que não se enquadre nas categorias acima.
Custos adicionais podem ser um valor positivo ou um valor negativo, como um desconto.
❗❗ Você pode ter informações em seus DMS sobre custos adicionais não incluídos no valor_total_do_cliente. Esses custos adicionais não devem ser enviados na carga útil ❗❗
❗❗ Se o custo adicional for uma taxa fixa, não inclua o valor_aplicável e taxa nos campos da transação. Inclua apenas o valor no custo adicional.
Não envie uma taxa com um valor de 0. ❗❗
Aqui está um exemplo de um cliente comprando um novo veículo e trocando um antigo.
"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
}
]O preço total do cliente é calculado assim:
- + 16249 (preço do revendedor)
- + 2437.35 (Imposto sobre Vendas)
- + 8,00 (Imposto Ambiental)
- + 50 (Taxa de Entrega)
- - 500 (Desconto de Venda de Primavera)
- - 50 (Desconto na Taxa de Entrega)
- - 8000 (troca)
- = 10194,35
Um custo adicional também é utilizado para documentar custos de trabalho fora da concessionária, que são cobrados do cliente.
Por exemplo, uma peça do carro pode precisar ser pintada durante um reparo no veículo. A peça é enviada para uma oficina de pintura, e o custo relacionado é documentado como um custo adicional. Por exemplo:
"additional_costs": [
{
"type": "Other",
"description": "Side panel paint job",
"amount": 413.58
},
{
...Impostos
Os impostos devem ser incluídos nos custos adicionais de cada item em uma transação. Por exemplo, se houver duas peças em uma transação de peças, deve haver um custo adicional de imposto para cada uma das duas peças.
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": []
}
]
}'👉 Se o seu DMS mostrar apenas o valor total do imposto para a transação, esse valor deve ser dividido entre cada item.
Com nosso exemplo acima, digamos que seu DMS tenha um imposto total de $6.74. O preço total do cliente para a transação é $44.89. O valor do imposto será dividido assim:
- Primeira parte: $28.90 / $44.89 * $6.74 = $4.34
- Segunda parte: $15.99 / $44.89 * $6.74 = $2.40
Troca em uma Venda de Unidade
Quando um cliente compra uma unidade, ele pode entregar uma unidade que possui como troca para reduzir o custo da nova unidade. Existem pelo menos 3 cenários diferentes em relação a uma troca:
- Uma troca que reduz o preço total do cliente.
- Uma troca com um pagamento que reduz o preço total do cliente.
- Uma troca com um pagamento que não reduz o preço total do cliente.
❗O valor de troca deve ser negativo ❗
Cenário Simples
O caso simples é quando o valor de troca é subtraído do preço total do 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
}
]O preço total do cliente é calculado assim:
- + 16249 (preço do revendedor)
- + 2437.35 (Imposto sobre Vendas)
- + 8.00 (Imposto Ambiental)
- + 50 (Taxa de Entrega)
- - 500 (Desconto de Venda de Primavera)
- - 50 (Desconto da Taxa de Entrega)
- - 8000 (troca)
- = 10194.35
Troca com Pagamento
O segundo cenário é quando um pagamento é associado à troca. Um pagamento é feito quando há um saldo de empréstimo restante na unidade de troca, e o revendedor paga esse saldo. O resultado é que o valor da troca é menor, e isso não reduz o custo total para o 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
}
]O preço total para o cliente é calculado assim:
- + 16249 (preço do revendedor)
- + 2437.35 (Imposto sobre Vendas)
- + 8.00 (Imposto Ambiental)
- + 50 (Taxa de Entrega)
- - 500 (Desconto de Venda de Primavera)
- - 50 (Desconto de Taxa de Entrega)
- + 2000 (Pagamento)
- - 8000 (troca)
- = 12194.35
👉 O pagamento deve ser adicionado aos custos adicionais; caso contrário, o preço total para o cliente estará incorreto.
Pagamento Maior Que o Valor da Troca
O terceiro cenário é quando o pagamento associado à troca é maior do que o valor da troca. Neste cenário, a troca não reduz o preço total para o 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
}
]O preço total para o cliente é calculado assim:
- + 16249 (preço do revendedor)
- + 2437.35 (Imposto sobre Vendas)
- + 8.00 (Imposto Ambiental)
- + 50 (Taxa de Entrega)
- - 500 (Desconto de Venda de Primavera)
- - 50 (Desconto de Taxa de Entrega)
- + 6000 (Pagamento)
- - 5000 (troca)
- = 19194.35
👉 O pagamento deve ser adicionado aos custos adicionais; caso contrário, o preço total ao cliente estará incorreto.
Agregação de Quantidades
Se a quantidade de peças exceder uma, o custo_do_revendedor, preço_do_revendedor, e msrp as propriedades permanecem unitárias (para uma quantidade de 1).
O preço_total_do_cliente e os custos_adicionais para essas peças são para o número de peças indicado pelo valor_da_quantidade.
Tarifa de Mão de Obra do Cartão de Trabalho
As informações relacionadas a um trabalho de serviço estão contidas na trabalhos propriedade.
As informações parecem assim:
"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
}
]
}
]O valor_do_preço_total_do_cliente_do_trabalho é a soma de todos os cartões_de_trabalho para todos os técnicos que trabalharam no trabalho mais os custos adicionais do trabalho. Para cada cartão de trabalho, a quantia é horas_faturadas * tarifa_de_mão_de_obra.
Mas e se o trabalho for feito a um preço fixo para o cliente?
Neste caso, o taxa_de_trabalho é calculada a partir das horas_faturadas_de_trabalho valor.
Por exemplo, os dados devem parecer assim se o trabalho for feito a um preço fixo de $75 por 1,5 horas.
A taxa_de_trabalho é $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
}
]
}
]Compreendendo as Transações
Esta seção apresenta informações detalhadas sobre o conteúdo de cada tipo de transação.
Todos os campos numéricos usam um ponto (.) como o separador decimal. A vírgula (,) é NÃO suportada como separador decimal.
Cabeçalho
A transação cabeçalho contém informações sobre o cliente e a transação conforme definido no seu DMS.
Propriedade | O que é isso? |
|---|---|
número_da_transação * | O identificador da transação é definido no seu DMS. Deve ser único para o revendedor! |
data_abertura * | A data em que a transação foi criada. Mesmo que a transação seja modificada após ser aberta, esta data não muda. |
data_de_fechamento * | A data em que a transação foi encerrada no seu DMS. A definição de um transação fechada pode diferir de um sistema para outro. Geralmente, uma transação é considerada fechada se o cliente paga e os fundos são enviados para a contabilidade. |
origem_da_transação * | A fonte da transação, seja "na loja" ou "online". O objetivo é receber as transações online se elas estiverem disponíveis no seu DMS. |
bandeira_de_cancelamento * | Indica se a transação foi cancelada. Uma transação cancelada não é uma devolução. Um retorno é uma transação com valores negativos, conforme descrito na Retornos seção. Se você enviar uma transação que for posteriormente cancelada por qualquer motivo, envie a mesma transação com o cancel_flag definido como TRUE e um diferente transaction_uuid valor. Então saberemos que a transação foi cancelada. |
uuid_da_transação * | Um ID único para indicar este iteração da transação. Se uma transação é criada e depois modificada, por exemplo, adicionando partes, o número_da_transação e data_de_abertura as propriedades mantêm o mesmo valor quando você envia a carga útil. No entanto, o transaction_uuid propriedade deve ser diferente. O número_da_transação nos permite encontrar a transação original, e os diferentes uuid_da_transação indica que a transação foi atualizada. |
clientes * | A lista de clientes para as transações. Veja abaixo as propriedades do cliente. Se nenhuma informação do cliente estiver disponível, o array estará vazio. |
- Propriedades em azul e marcadas com um asterisco (*) são obrigatórias no recurso.
Embora geralmente haja apenas um cliente para uma transação, o cabeçalho contém uma lista de clientes caso você precise.
❗ ❗ Nenhuma informação pessoal do cliente deve ser enviada na carga útil ❗ ❗
Sem primeiro nome, sobrenome, endereço de e-mail, número de telefone, etc.
A única informação fornecida é a cidade, estado ou província e país do cliente.
Se o customer_id contiver informações pessoais do cliente, como seu sobrenome, defina a propriedade como null ou uma string vazia.
O BRP usa as informações do cliente no cabeçalho para vincular transações feitas pelo mesmo cliente na mesma concessionária.
O objetivo é extrair estatísticas sobre lealdade de clientes, concessionárias e marcas.
O ID do cliente e/ou valores de hash do cliente são usados para isso. Se não estiverem disponíveis, não há problema 😁.
Propriedade | O que é isso? |
|---|---|
id_do_cliente * | Um identificador único no nível do revendedor (ou DMS) para este cliente. Se não estiver disponível, por exemplo, se o cliente for ao balcão sem uma conta na concessionária, use "CONVIDADO". IMPORTANTE Se o customer_id o valor da propriedade contiver as informações pessoais do cliente, como seu sobrenome, defina a propriedade como null ou uma string vazia.
|
hash_do_cliente * | Um hash SHA-256 no número de telefone e e-mail do cliente. O hash deve ser calculado na string: Número de telefone E.164 + espaço + endereço de e-mail Por exemplo: +18882729222 email_Endereç[email protected] IMPORTANTE Defina o valor da propriedade como nulo se o e-mail ou número de telefone estiver faltando. |
destinatário * | Quem estava do lado receptor da transação? Um dos: . Cliente . Próprio . Concessionária Cliente: o cliente "padrão". Próprio: a própria concessionária, por exemplo, vendendo peças para diferentes departamentos, adicionando acessórios a um veículo, etc. Concessionária: uma concessionária diferente da própria. |
cidade | A cidade onde o cliente mora. Se não estiver disponível, a cidade onde o revendedor está localizado. |
estado_província | Estado ou Província onde o cliente reside. Defina como nulo se não se aplicar ao país. |
país | O país onde o cliente reside. Se não estiver disponível, o país onde o revendedor está localizado. |
- Propriedades em azul, marcadas com um asterisco (*), são obrigatórias no recurso.
Peças
O Parts transação é usada para vendas de peças, acessórios e vestuário (PA&A) no mercado de balcão (OTC).
❗ ❗ Apenas peças, acessórios e vestuário da BRP devem ser incluídos nas transações de peças ❗ ❗
Se uma transação contendo uma unidade BRP também contiver algumas peças não-BRP, essas peças são incluídas em um objeto de peça agregado com o número_da_peça e descrição_da_peça propriedades definidas como "PEÇAS-NÃO-BRP".
Propriedade | O que é isso? |
|---|---|
descrição_da_parte * | A descrição da peça BRP é obtida do catálogo de peças (veja o API de Peças). Defina como “NON-BRP-PARTS” para uma peça não BRP utilizada em um trabalho de ordem de reparo. Se a descrição da parte não estiver disponível, a propriedade é definida como nula ou uma string vazia. |
número_da_peça * | O número da peça BRP é obtido do catálogo de peças (veja o API de Peças). Defina como “NON-BRP-PARTS” para uma peça não BRP usada iem um trabalho de ordem de reparo. |
quantidade * | A quantidade desta peça. Pode ser um número decimal para partes com uma unidade de medida, como comprimento (metros, pés) ou volume (litros, onças, galões). |
quantidade_uom * | As Unidades de Medida (UOM) são usadas para qualificar a quantidade. O valor é obtido do catálogo de peças (veja o API de Peças). As unidades de medida válidas estão listadas na tabela de Unidades de Medida (UoM) abaixo. |
é_pedido_especial * | Uma bandeira para indicar que esta parte é um pedido especial para um cliente. É uma parte que normalmente não está em estoque e foi encomendada para um cliente. |
preço_total_do_cliente * preço_do_revendedor custo_do_revendedor preço sugerido pelo fabricante | Os preços são conforme descrito na seção Preços acima. |
moeda * | A moeda é usada para todos os preços neste objeto e nos objetos filhos. As unidades de medida válidas estão listadas na seção de moeda abaixo. |
número_do_trabalho_associado | O número do trabalho da ordem de reparo que consumiu esta peça. É assim que as peças usadas em um trabalho de ordem de reparo são identificadas. O valor deve corresponder a um dos número_do_trabalhopropriedade no Trabalhos array. Veja o Trabalhos seção abaixo. |
custos_adicionais * | Um conjunto de custos adicionais. Se não houver custos adicionais, o array está vazio. Veja a seção Custos Adicionais acima. |
- Propriedades em azul e marcadas com um asterisco (*) são obrigatórias no recurso.
O associated_job_number propriedade é essencial para vincular as partes ao trabalho usando as partes.
O valor deve corresponder a um dos job_number propriedade no Trabalhos array.
Empregos
Os Empregos transação representa o trabalho realizado em um veículo para uma ordem de reparo do concessionário.
Se o trabalho for realizado em um veículo não-BRP usando peças BRP, a transação contém apenas essas peças e nenhum trabalho.
Propriedade | O que é isso? |
|---|---|
número_do_trabalho * | O número do trabalho é do DMS do concessionário e deve ser único na concessionária. |
código_do_trabalho * | O código para este trabalho. |
descrição * | A descrição do trabalho, conforme inserida no DMS pelo técnico. |
é_trabalho_garantia * | Sinal para indicar se este trabalho está coberto por uma garantia |
número_do_reclamação_de_garantia | O número da reclamação que foi recebido da BRP. |
preço_total_do_trabalho_do_cliente * | Os preços totais dos clientes conforme descrito na seção Preços acima. IMPORTANTE O preço total do trabalho do cliente é a soma de todos os custos de mão de obra, excluindo custos de peças. |
moeda * | A moeda utilizada para todos os preços neste objeto e nos objetos filhos. As unidades de medida válidas estão listadas na seção de moeda abaixo. |
vinho | O Número de Identificação do Veículo (VIN) da unidade em reparo/manutenção. |
leitura_do_odômetro | Leitura do odômetro em quilômetros. Se o odômetro do veículo estiver em milhas, deve ser convertido para quilômetros. |
horas | Leitura do número de horas de trabalho de um veículo sem odômetro, como um Sea-Doo. |
fabricante | O fabricante da unidade na qual o trabalho foi realizado. |
modelo | O modelo da unidade em que o trabalho foi realizado. |
ano | O ano do modelo da unidade em que o trabalho foi realizado. |
cartões_de_horas * | Um array de cartões de ponto. O array está vazio se não houver informações de cartões de ponto disponíveis. Veja abaixo os detalhes. |
custos_adicionais * | Uma lista de custos adicionais. Se não houver custos adicionais, o array está vazio. Veja a seção Custos Adicionais acima. Se o trabalho for feito fora da concessionária, por exemplo, enviando uma peça para uma oficina de pintura, o custo é documentado com um custo adicional do tipo "Outro". |
- As propriedades em azul, marcadas com um asterisco (*), são obrigatórias no recurso.
O Cartão de Ponto documenta o trabalho de um técnico em um serviço. Há um objeto de cartão por técnico trabalhando no serviço.
Propriedade | O que é? |
|---|---|
horas_trabalhadas * | O número de horas que este técnico trabalhou neste trabalho. |
horas_faturadas * | O número de horas que este técnico faturou ao cliente por este trabalho. |
taxa_trabalhista * | A taxa horária deste técnico. |
id_participante_técnico * | O ID do técnico na concessionária. |
- Propriedades em azul, marcadas com um asterisco (*), são obrigatórias no recurso.
As horas trabalhadas e faturadas podem diferir se o revendedor decidir não cobrar do cliente por todas as horas.
Para cada cartão de ponto, o valor de horas_trabalhadas_faturadas x taxa_de_trabalho é adicionado ao preço_total_do_trabalho_do_cliente para o trabalho.
Por exemplo, 2 técnicos trabalharam em um veículo, um para reparar um defeito e um para instalar um acessório.
{
"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
}O preço total pela mão de obra incluída no preço_total_do_trabalho_do_cliente é:
Unidades
A Unidades documenta a venda de um veículo a um cliente.
❗ ❗ Seu DMS envia apenas vendas unitárias de veículos BRP ❗ ❗
Propriedade | O que é isso? |
|---|---|
vin * | O Número de Identificação do Veículo (VIN) do veículo adquirido. |
leitura_do_odômetro | Leitura do odômetro em quilômetros. Se o odômetro do veículo estiver em milhas, deve ser convertido para quilômetros. |
horas | Leitura do número de horas de trabalho para um veículo sem odômetro, como um Sea-Doo. |
código_classe * | O código da classe para este veículo: "Novo", "Usado" ou "Demonstrador". |
id_do_lead_de_vendas | O ID BRP dos leads de vendas que resultaram nesta venda. |
preço_total_do_cliente * preço_do_revendedor custo_do_revendedor preço sugerido pelo fabricante | |
moeda * | A moeda é usada para todos os preços deste objeto e seus objetos filhos. As unidades de medida válidas estão listadas na seção de moeda abaixo. |
valor_financiado | O valor que foi financiado para a compra deste veículo. |
taxa_financiada | A taxa de financiamento. |
duração_do_termo_financiado | O número de meses durante os quais a unidade é financiada. |
comércio_ins | Uma lista de veículos para troca. A propriedade não é enviada ou está vazia se não houver troca. |
- Propriedades em azul e marcadas com um asterisco (*) são obrigatórias no recurso.
O Trade-In documento do objeto documenta o veículo que o cliente deu como troca para reduzir o total_customer_price valor.
Propriedade | O que é isso? |
|---|---|
fabricante | O fabricante do veículo trocado. |
vinho | O VIN do veículo trocado. |
leitura_do_odômetro | Leitura do odômetro em quilômetros. Se o odômetro do veículo estiver em milhas, ele deve ser convertido para quilômetros. |
horas | Leitura do número de horas de trabalho de um veículo sem odômetro, como um Sea-Doo. |
modelo | O modelo do veículo trocado. |
preço * | O preço que o revendedor pagou pela unidade trocada. O preço deve ser um número negativo para subtrair do total_cliente_preço valor. |
ano | O ano do modelo do veículo trocado. |
- Propriedades em azul e marcadas com um asterisco (*) são obrigatórias no recurso.
Preferencialmente, você deve incluir o VIN de um veículo de troca. Se o VIN não estiver disponível, o fabricante e o ano do modelo serão utilizados.
Um veículo de troca preço deve ser um número negativo para remover o valor do total_customer_price valor.
Formato de Dados
Moeda
Organização de Vendas | Coin | Versão 3 | Version 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 | |
Unidade de Medidas
Código | Description | Dimensão |
|---|---|---|
" | Inch | Length |
CAIXA | Box | Quantity |
BR | Barril | Quantidade |
BT | Bottles | Quantity |
BU | Bucket | Quantity |
PODER | Cilindro | Quantity |
CC | Centímetro cúbico | Volume |
CDM | Decímetro cúbico | Volume |
CG | Centigramas | Weight |
CL | Centilitros | Volume |
CM | Centímetro | Length |
CS | Box | Quantity |
FT | Feet | Length |
G | Grass | Weight |
GA | Gallons | Volume |
GU | American Gallon | Volume |
H | Hora | Tempo |
KG | Quilograma | Peso |
L | Litro | Volume |
LB | Libra | Peso |
LT | Batch | Quantity |
M | Metrô | Length |
M2 | Metro quadrado | Area |
MG | Miligrama | Weight |
ML | Mililitro | Volume |
MM | Milímetro | Length |
OZ | Jaguars | Peso |
P | Pontos | Quantidade |
PAC | Pacote | Quantidade |
PC | Peça | Quantity |
PR | Par | Quantity |
PT | Paintings | Volume |
QT | Quartzos | Volume |
ROL | Scroll | Quantity |
CONFIGURAR | Set | Quantity |
SF | Pés Quadrados | Area |
SH | Leaves | Quantity |
SIM | Square Inch | Área |
SY | Jarda Quadrada | Área |
TB | Tubo | Quantidade |
YD | Quintal | Length |
HL | Hectolitro | Volume |
M3 | Metro cúbico | Volume |
P3 | Cubic feet | Volume |
LM | Metrô linear | length |
CM2 | Square centimeter | Superfície |
PO3 | Polegada cúbica | Volume |
DZ | Duzena | Quantidade |
Estado da Transação
Esta seção descreve como lidar com mudanças em uma transação.
Transações Atualizadas
O requisito básico é que apenas fechadas transações sejam enviadas para o BRP.
No entanto, dependendo do comportamento do seu DMS e do que é considerado uma transação fechada, uma transação enviada para a API de Transações de Varejo pode ser modificada no seu DMS.
Você pode enviar a transação atualizada desde que o número_da_transação seja o mesmo para ambas as instâncias, mas o uuid_da_transação é diferente.
Uma transação pode ser atualizada desde que o número_da_transação seja o mesmo para ambas as instâncias, mas o uuid_da_transação é diferente.
O número_da_transação,uuid_da_transação, e a data de recepção da transação adicionada pela API de Transação de Varejo são usadas durante a análise de dados para encontrar a transação mais recente.
Transações Canceladas
Seu DMS pode permitir que o revendedor cancele uma transação. Para cancelar uma transação, atualize-a com o cancelar_bandeira definido como VERDADEIRO.
Uma vez que um cancelamento é uma atualização, as mesmas regras se aplicam: o número_da_transação é o mesmo para ambas as instâncias, mas o uuid_da_transação é diferente.
Uma transação pode ser cancelada enviando-a com a cancelar_bandeira definida como VERDADEIRO, o mesmo número_da_transação e um novo uuid_da_transação.
Devoluções
As devoluções são gerenciadas como qualquer outra transação, mas com um negativo total_customer_price e todos os custos adicionais.
Por exemplo, quando um cliente devolve uma peça, a transação aparece da seguinte forma.
{
"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": ""
}Você pode misturar transações "normais" e transações de devolução no mesmo conjunto de transações.
Por exemplo, o array de transações de Peças poderia conter 2 compras de um cliente e uma devolução.
Privacidade de Dados
Consentimento para Compartilhamento de Dados
Conforme explicado na Consentimento para Compartilhamento de Dados do Revendedor seção, o revendedor deve consentir com o compartilhamento de dados antes que qualquer dado de transação de varejo seja enviado.
O compartilhamento de dados de transações de varejo é um assunto mais sensível do que o compartilhamento de dados de inventário de peças com os concessionários.
Entender o que e por que é compartilhado através da API de Transações de Varejo é importante para explicá-lo aos concessionários.
Informações Não-BRP
Apenas as transações que contêm informações de PA&A e unidade da BRP são enviadas para a API de Transações de Varejo!
Se uma transação diz respeito apenas a PA&A e unidades não-BRP, não deve ser enviada para a API de Transações de Varejo!
Informações do Cliente
Regras e leis de privacidade de dados estão em vigor em alguns países há anos e agora estão sendo implementadas em muitos estados e países.
É por isso que a carga útil das transações de varejo não contém as informações pessoais do cliente.
O customer_hashpropriedade no cliente objeto foi projetado para ser não reversível: o e-mail e o número de telefone do cliente não podem ser recuperados do hash.
É essencial incluir o valor hash APENAS se tanto o e-mail quanto o número de telefone do cliente estiverem disponíveis.
Se um estiver faltando, o valor hash deve ser definido como null.
Transmissão de Dados
Quando Enviar
Seu DMS pode enviar transações à medida que são fechadas em tempo real ou como uma submissão em lote no final do dia de trabalho.
Transações fechadas consistem em faturas que são registradas como completas em seu DMS. Se um revendedor reabrir uma fatura para fazer alterações, essa fatura não é enviada para a BRP até que tenha sido fechada novamente.
Quando a fatura for fechada novamente, envie a fatura atualizada conforme descrito na Transações Atualizadas seção.
A "regra geral" sobre o que incluir na sua carga de transação para a BRP é qualquer transação postada no livro razão geral (GL).
Dados Históricos
Para muitos programas da BRP, dados históricos de transações de varejo são essenciais e, em alguns casos, obrigatórios. Por exemplo, o programa de Gestão de Inventário de Varejo (RIM) exige que 18 a 24 meses de dados de transações de varejo estejam disponíveis antes que o revendedor possa se juntar ao RIM.
Quando um revendedor consente com o compartilhamento de dados, todos os dados disponíveis nos últimos 4 anos devem ser enviados.
Se o revendedor optar por não compartilhar dados, a transmissão de dados históricos deve parar.
Retransmissão de Dados
Seu DMS deve ser capaz de reenviar transações para um intervalo de datas específico. Essa função é manual; o pedido não será enviado através de uma API.
Essa função será utilizada se, por qualquer motivo, dados estiverem faltando ou corrompidos.
Lógica de Retentativa Automática
Em caso de falha ou interrupção do sistema BRP devido a manutenção ou outros problemas imprevistos, seu DMS recebe uma mensagem de erro da API contendo uma descrição do erro.
Seu DMS deve ter um processo de automação para reenviar uma solicitação até que você receba uma resposta de confirmação.
Para as primeiras 24 horas, uma estratégia de retentativa deslizante é recomendada. Nessa estratégia, seu DMS continua a tentar a chamada para a API, adicionando atrasos incrementais de tempo em cada tentativa subsequente.
Por exemplo, a primeira retentativa pode esperar 5 minutos, a segunda esperará 10 minutos, a terceira esperará 20 minutos, e assim por diante. Cada retentativa dobra o tempo de espera até que o número de retentativas seja excedido.
Após 24 horas de retentativas, seu DMS deve continuar a tentar uma vez por dia. Se o problema persistir, seu DMS deve reter todos os dados de transações de varejo do BRP até que o problema seja resolvido.
Transição Entre a API V2 e a API V4
Muitos programas de negócios do BRP usam dados de transações de varejo. A API V2 (STAR XML) e a API V4 (JSON) diferem significativamente em seus formatos de carga e processamento de backend.
A API V2 envia os dados de transações de varejo para um banco de dados SQL Server, que os programas de negócios do BRP atualmente usam para recuperar os dados.
A API V4 envia os dados de transações de varejo para um banco de dados em nuvem, e os programas de negócios do BRP devem ser modificados para recuperar os dados desse banco de dados em nuvem.
Para ajudar os programas de negócios do BRP durante a transição, a API V2 deve permanecer ativa temporariamente, mesmo que a API V4 esteja certificada e implantada em produção.
👉 Os dados de transações de varejo devem ser enviados usando tanto a API V2 quanto a API V4 durante a transição.
Assim que um número suficiente de DMSs tiver certificado a API V4 para incluir 70-75% dos revendedores, a API V2 será desativada.