Informações Técnicas
Características
Tipo de API | Tipo de DSP | Versão DCP | Complexidade |
|---|---|---|---|
Obter dados do BRP | DMS | V3 - Internacional | Baixo |
Enviar dados para o BRP | CRM | V4 - América do Norte | Um pouco mais |
Transação com BRP | | | Um pouco mais |
Autenticação
A API está usando Autenticação da Aplicação.
Você precisa de um token de acesso válido antes de chamar esta API, ou você deve chamar o API de Autenticação de Aplicativos para obter um.
O token de acesso é válido por 30 minutos! (1799 segundos)
URL Base
Teste | https://qa-cloud-api.brp.com/dcp/<v3 ou v4> |
|---|---|
Produção | https://cloud-api.brp.com/dcp/<v3 ou v4> |
O que mudou do V2
- Um endpoint para todas as transações.
- A carga útil pode conter muitas transações.
- A API de Transações de Varejo V2 usa Autenticação Básica, enquanto a API V5 usa Autenticação de Aplicação.
- A carga útil mudou de XML-STAR para JSON.
- Suporta muitas moedas.
Recurso: Transações
O recurso Transações é usado para enviar todos os tipos de transações para a API.
A carga útil da API de Transações de Varejo contém muitas informações. Às vezes, seu DMS pode não conseguir fornecer as informações solicitadas.
Está tudo bem, e cada caso será discutido durante as atividades de certificação. Se o seu DMS tiver limitações técnicas que impeçam o envio de algumas informações, as exceções serão documentadas e acordadas.
Representação 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
}
]
}
]
}Propriedades
Todos os campos numéricos usam um ponto (.) como separador decimal. A vírgula (,) é NÃO suportada como separador decimal.
❗ As propriedades opcionais devem ser incluídas em sua carga útil se as informações estiverem disponíveis em seu DMS.
Propriedade | Tipo | Definição | Notas |
|---|---|---|---|
transações * | Lista de objetos | | |
transações.cabeçalho * | objeto | Cabeçalho da transação. | |
transações.cabeçalho. número_da_transação * | string | O sistema do revendedor gera um número de transação, que deve ser único para o revendedor. Veja a Limitações e Restrições seção para mais informações. | Comprimento Máximo:36 |
transações.cabeçalho. data_abertura_transação * | data | A data em que a transação foi aberta, conforme escrito no sistema do revendedor | Formato: aaaa-mm-ddThh:mm:ssZ |
transações.cabeçalho. data_de_fechamento_da_transação * | data | A data em que a transação foi encerrada, conforme escrito no sistema do revendedor | Formato: aaaa-mm-ddThh:mm:ssZ |
transações.cabeçalho. origem_da_transação * | string | A fonte da transação Um dos:
| |
transações.cabeçalho. bandeira_cancelar * | boolean | Sinal para indicar que esta transação foi cancelada. | |
transações.cabeçalho. uuid_transação * | string | Um ID único para indicar esta iteração da transação. ❗❗ A transaction_uuid CADA vez que a carga útil é enviada! Se a carga útil for reenviada após um erro, o transaction_uuid deve 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})$) |
transações.cabeçalho. clientes * | Lista de objetos | | |
transações.cabeçalho. clientes.customer_id * | string | Identificador único no nível do revendedor (ou DMS) para este cliente. Se nenhum for fornecido (por exemplo, transação em dinheiro) defina o valor como "CONVIDADO". | Comprimento Máximo:36 |
transações.cabeçalho. clientes. hash_do_cliente * | string | Um hash SHA-256 no número de telefone e e-mail do cliente. O formato requerido é SHA-256(^\+[1-9]\d{1,14}\s\S+@\S+\.\S+$) ou seja, SHA-256(endereço de e-mail do espaço do número de telefone E.164). por exemplo: SHA-256(+18882729222 [email protected]) Se o e-mail ou o número de telefone estiverem ausentes, então defina a propriedade como nula | Formato: ^[a-fA-F0-9]{64}$ |
transações.cabeçalho. destinatários dos clientes * | string | Quem estava do lado receptor da transação? Um dos:
Cliente: o cliente "padrão". Auto: a concessionária em si (por exemplo, vendendo peças para diferentes departamentos, fazendo uma adição a veículos, etc.). Concessionária: uma concessionária diferente dela mesma. | |
transações.cabeçalho. cidade dos clientes | string | A cidade onde o cliente mora. | Comprimento Máximo:128 |
transações.cabeçalho. clientes. estado_província | string | Estado ou Província onde o cliente mora. Defina como nulo se não aplicável para o país. | Comprimento Máximo:128 |
transações.cabeçalho. países.dos.clientes | string | País onde o cliente mora. | Comprimento Máximo:128 |
transações.partes * | Lista de Objetos | | |
transações.partes. descrição_da_parte * | string | A descrição da parte ou “PEÇAS-NÃO-BRP”. | Comprimento Máximo:128 |
transações.partes. número_da_peca * | string | Números de peça definidos pela BRP ou “PEÇAS NÃO BRP”. | Comprimento Máximo:18 |
transações.partes. quantidade * | número | O número de tais partes. | Formato ±9999999,99 |
transações.partes. quantidade_uom * | string | As Unidades de Medida usadas no campo de quantidade, conforme definido na tabela abaixo. | Comprimento Máximo:10 |
transações.partes. é_pedido_especial * | boolean | Uma bandeira para indicar se esta parte foi um pedido especial, ou seja, uma parte que normalmente não é mantida em estoque. | |
transações.partes. preço_total_do_cliente * | número | O preço total do cliente, incluindo todos os impostos, descontos, taxas de envio, etc. Inclui todos os custos adicionais. | Formato ±9999999,99 |
transações.partes. preço_do_revendedor | número | O preço unitário (para uma quantidade de 1) definido pelo revendedor para a peça | Formato ±9999999,99 |
transações.partes. custo_do_revendedor | número | O preço unitário (para uma quantidade de 1) pelo qual o revendedor comprou o item da BRP. | Formato ±9999999,99 |
transações.partes.msrp | número | O preço de varejo sugerido pelo fabricante para a unidade (para uma quantidade de 1) do item no momento da transação. | Formato ±9999999,99 |
transações.partes. moeda * | string | A moeda utilizada para todos os preços neste objeto e objetos filhos. Veja a tabela de Moedas abaixo. | |
transações.partes. número_do_trabalho_associado | string | O número do trabalho da tarefa que consumiu esta peça. | Comprimento Máximo:36 |
transações.partes. custos_adicionais * | Lista de objetos | | |
transações.partes. custos_adicionais.tipo * | string | O tipo de custo adicional. Um dos:
| |
transações.partes. custos_adicionais. descrição * | string | Uma breve descrição do custo. | Comprimento Máximo:255 |
transações.partes. custos_adicionais. valor_aplicável | número | O valor sobre o qual a taxa é aplicada para calcular o custo adicional. | Formato ±9999999,99 |
transações.partes. taxas_de_custo_adicionais | número | A taxa (por exemplo, a taxa de imposto) é aplicada ao valor aplicável para determinar o custo adicional. | Um valor entre -1.00000 e 1.00000 |
transações.partes. custos_adicionais.quantia * | número | O valor do custo adicional. | Formato ±9999999,99 |
transações.unidades | Lista de Objetos |
|
|
transações.unidades.vin * | string | O Número de Identificação do Veículo (VIN) da unidade comprada. | Comprimento Máximo:17 |
transações.unidades. leitura_do_odômetro | número | Leitura do odômetro em quilômetros. | Formato 9999999,99 |
transações.unidades.horas | número | Leitura do número de horas trabalhadas. | Formato 9999999,99 |
ttransações.unidades. código_classe * | string | O código da classe para esta unidade. Um dos:
| |
transações.unidades. id_do_lead_de_vendas | string | O ID do BRP do lead de venda que resultou nesta venda. | Comprimento Máximo:36 |
transações.unidades. preço_total_do_cliente * | número | O preço total pago pelo cliente por esta unidade. Inclui todos os custos adicionais. | Formato ±9999999,99 |
transações.unidades. preço_do_revendedor * | número | O preço de varejo base definido pelo revendedor para esta unidade. | Formato ±9999999,99 |
transações.unidades. custo_do_revendedor * | número | O preço pelo qual o revendedor comprou esta unidade da BRP. | Formato ±9999999,99 |
transações.unidades.preço sugerido ao consumidor | número
| O preço de varejo sugerido pelo fabricante, no momento da transação, para esta unidade. | Formato ±9999999,99 |
transações.unidades. moeda * | string | A moeda utilizada para todos os preços neste objeto e objetos filhos. Veja a tabela de Moedas abaixo. | |
transações.unidades. valor_financiado | número | O valor que o cliente financiou para a compra desta unidade. | Formato ±9999999,99 |
transações.unidades. taxa_financiada | número | A taxa de financiamento. | Valor entre 0,0000 e 1,0000 |
transações.unidades. duração_do_termo_financiado | número | O número de meses durante os quais a unidade foi financiada. | Formato 9999999,99 |
transações.unidades. comércio_ins | Lista de objetos |
|
|
transações.unidades. comércio_ins.fabricante | string | O fabricante da unidade trocada. | Comprimento Máximo:36 |
transações.unidades. comércio_ins.vin | cadeia | O VIN do veículo que foi trocado. | Comprimento Máximo:17 |
transações.unidades. comércio_ins. leitura_do_odômetro | número | Leitura do odômetro em quilômetros. | Formato 9999999,99 |
transações.unidades. horas_de_comércio | número | Leitura do número de horas trabalhadas. | Formato 9999999,99 |
transações.unidades. comércio_ins.modelo | string | O modelo da unidade trocada. | Comprimento Máximo:255 |
transações.unidades. comércio_ins.preço | número | O preço que o revendedor pagou pela unidade trocada. ❗O valor deve ser negativo. | Formato ±9999999,99 |
transações.unidades. comércio_ins.ano | cadeia | O ano do modelo do veículo que está sendo trocado. | Inteiro yyyy |
transações.unidades. custos_adicionais * | Lista de objetos |
|
|
transações.unidades. acustos_adicionais.tipo * | string | O tipo de custo adicional. Um dos:
| |
transações.unidades. descrição_dos_custos_adicionais * | string | Uma breve descrição do custo. | Comprimento Máximo:255 |
transações.unidades. custos_adicionais.valor_aplicável | número | O valor sobre o qual a taxa é aplicada para calcular o custo adicional. | Formato ±9999999,99 |
transações.unidades. taxas_adicionais.rate | número | A taxa (por exemplo, a taxa de imposto) é aplicada ao valor aplicável para determinar o custo adicional. | Um valor entre -1.00000 e 1.00000 |
transações.unidades.custos_adicionais.quantia * | número | O valor do custo adicional. | Formato ±9999999,99 |
transações.trabalhos * | Lista de objetos | | |
transações.trabalhos. número_do_trabalho * | string | O número do trabalho no nível do concessionário. | Comprimento Máximo:36 |
transações.trabalhos. código_do_trabalho * | string | O código do trabalho para este trabalho.Um dos
Veja a tabela de Códigos de Trabalho abaixo para mais informações. | Comprimento Máximo:3 |
transações.empregos. descrição * | string | A descrição do trabalho. | Comprimento Máximo:255 |
transações.trabalhos.eh_trabalho_garantia * | boolean | Sinal para indicar se este trabalho foi coberto pela garantia. | |
número_de_reclamação_de_garantia | string | O número da reclamação de garantia BRP. | Comprimento Máximo:36 |
transações.trabalhos.preço_total_do_trabalho_do_cliente * | número | O preço total pago pelo cliente apenas pelo trabalho (ou seja, excluindo peças). Inclui todos os custos adicionais. | Formato ±9999999,99 |
transações.trabalhos.moeda * | string | A moeda utilizada para todos os preços neste objeto e objetos filhos. Veja a tabela de Moedas abaixo. | |
transações.trabalhos.vin | string | O Número de Identificação do Veículo (VIN) da unidade em reparo/manutenção. | Comprimento Máximo:17 |
transações.trabalhos. leitura_do_odômetro | número | Leitura do odômetro em quilômetros. | Formato 9999999,99 |
transações.trabalhos.horas | número | Leitura do número de horas trabalhadas. | Formato 9999999,99 |
transações.trabalhos. fabricante | string | O fabricante da unidade na qual o trabalho foi realizado. | Comprimento Máximo:36 |
transações.empregos.modelo | string | O modelo da unidade em que o trabalho foi realizado. | Comprimento Máximo:255 |
transações.trabalhos.ano | string | O ano do modelo da unidade em que o trabalho foi realizado. | Inteiro yyyy |
transações.trabalhos. cartões_de_horas * | Lista de objetos | | |
transações.trabalhos. cartões_de_ponto. horas_trabalhadas* | número | O número de horas que esta parte trabalhou neste trabalho. | Formato 9999999,99 |
transações.trabalhos. cartões_de_horas. horas_trabalhadas_faturadas* | número | O número de horas que esta festa foi cobrada por este trabalho. | Formato 9999999,99 |
transações.trabalhos. taxas_de_trabalho.time_cards | número | A tarifa horária desta parte. | Formato 9999999,99 |
transações.trabalhos. cartões_de_horas. id_do_partido_técnico* | string | O ID definido pelo dealer para esta festa. | Comprimento Máximo:36 |
transações.trabalhos. custos_adicionais * | Lista de objetos | | |
transações.trabalhos. custos_adicionais.tipo * | string | O tipo de custo adicional. Um dos:
| |
transações.trabalhos. custos_adicionais. ddescrição * | string | Uma breve descrição do custo. | Comprimento Máximo:255 |
transações.empregos. custos_adicionais. valor_aplicável | número | O valor sobre o qual a taxa é aplicada para calcular o custo adicional. | Formato ±9999999,99 |
transações.trabalhos. custo_adicional.taxa | número | A taxa (por exemplo, a taxa de imposto) é aplicada ao montante aplicável para obter o valor do custo adicional. | Um valor entre -1.00000 e 1.00000 |
transações.trabalhos. custos_adicionais.quantia * | número | O valor do custo adicional. | Formato ±9999999,99 |
- Propriedades em azul e marcadas com um asterisco (*) são obrigatórias no recurso.
Tabelas de Referência
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 |
Códigos de Trabalho
Nome | Código | Descrição |
|---|---|---|
Detalhamento | SOY | Limpeza, detalhamento, etc. |
Inspeção Pré-Entrega | PDI | Inspeção Pré-Entrega |
Manutenção Programada | SMC | Todas as atividades de manutenção padrão |
Instalação de Peças e Acessórios | PAI | Toda a instalação de peças adicionais |
Reparar | RPR | Todos os reparos em um veículo |
Outro | OUTRO | Todos os outros trabalhos |
Recurso: Resposta de Transações
A API retorna o Resposta de Transações recurso quando a chamada POST é bem-sucedida.
O nome do arquivo contém o nome do arquivo criado para armazenar os dados no processador de carga de dados do backend.
👉 Mantenha este nome de arquivo no seu log DMS!
É útil ao investigar um problema de compartilhamento de dados de transações de varejo. 🕵️♀️
Representação JSON
{
"status": "success",
"filename": "dealer_retail_transaction_api_delta_20230709_222142Z_4582fbf4-8670-4e06-a22d-a576c9dd6a9f.json.gz"
}Propriedades
Propriedade | Tipo | Definição | Notas |
|---|---|---|---|
status | string | Sempre sucesso. | |
nome do arquivo | string | O arquivo onde os dados são armazenados no backend para processamento. | |
Limitações & Restrições
Formato de Número
Todos os campos numéricos com decimais usam um ponto (.) como separador decimal. A vírgula (,) é NÃO suportada como separador decimal.
Número Máximo de Transações
Um máximo de 500 transações pode ser enviado em um payload.
Tamanho do Payload de Transações
A API de Transações de Varejo funciona no APIGee, que tem um tamanho máximo de payload de 10 MB.
Veja a seção 413 Entidade de Solicitação Muito Grande para mais informações sobre como lidar com o código de status 413.
Número da Transação
O número da transação encontrado no cabeçalho é usado como a chave única da transação.
❗ O número da transação deve ser único para um revendedor ❗
Vemos dois casos:
- Seu DMS tem uma sequência de números de transação usada para todos os tipos de transação (venda no balcão, ordens de reparo e vendas de unidades).
- Seu DMS tem uma sequência de números de transação diferente para cada tipo de transação (venda no balcão, ordem de reparo e venda de unidade)
No primeiro caso, cada transação, independentemente de seu tipo, tem um número de transação único. Você não tem nada a fazer.
No segundo caso, duas transações podem ter o mesmo número de transação. Por exemplo, tanto uma venda no balcão quanto uma ordem de reparo podem ter o número de transação "12345".
Neste caso, você precisa adicionar um prefixo ao número da transação para torná-lo único. Por exemplo:
- "P-" para venda no balcão.
- "R-" para ordens de reparo.
- "U-" para vendas de unidades.
No nosso exemplo, o número da transação de venda no balcão será "P-12345" e o número da transação da ordem de reparo será "R-12345".