API de Especificações de Unidades
Primeiros Passos
TA API de Especificações da Unidade fornece informações técnicas para uma unidade específica com base em seu Número de Identificação do Veículo (VIN).
No contexto da concessionária, a API de Especificações da Unidade permite que o concessionário acesse informações técnicas essenciais diretamente no seu DMS.
O concessionário pode solicitar informações sobre qualquer unidade BRP usando o VIN da unidade, mesmo que a unidade não esteja no inventário da concessionária.
Por Onde Começar? Leia Isto Primeiro!
Antes de começar a trabalhar nesta API, você precisa ler as seguintes seções se ainda não as tiver consultado:
Informações Técnicas
Características
Tipo de API | Tipo de DSP | Versão DCP | Complexidade |
|---|---|---|---|
Obter dados do BRP | DMS | V3 - Internacional | Baixa |
Enviar dados ao BRP | CRM | V4 - América do Norte | Um pouco mais |
Transação com BRP | | | Um pouco mais ainda |
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 deve chamar a 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> |
Recurso: Especificações da Unidade
O Especificações da Unidade recurso contém as informações técnicas de uma unidade específica.
Representação JSON
{
"serial_no": "2BPSAAKX2KV000006",
"model_year": 2019,
"model_number": "000AAKX00",
"model_name": "SM EXPEDITION LE 900 ACE-E SY/B/B 1",
"model_code": "",
"brands": [
"SKIDOO"
],
"product_line": "SNO",
"product_type": "10",
"manufacturer_name": "Bombardier Recreational Products Inc.",
"color_code_description": "",
"max_no_of_passengers": null,
"engine_code": "900_ACE",
"engine_code_description": "900 ACE",
"engine_displacement": 899,
"engine_power": null,
"no_of_cylinders": 3,
"gross_weight_vehicle_rating": null,
"net_weight": 253.107,
"weight_unit": "KG",
"inventory_type": "Stock",
"status": [
"At_customer_site"
],
"last_change_date": "2022-11-10T20:34:15Z"
}Propriedades
Todos os campos numéricos com decimais usam o ponto (.) como separador decimal. A vírgula (,) NÃO é suportada como separador decimal.
Propriedade | Tipo | Definição | Notas |
|---|---|---|---|
serial_no | string | Número de série da unidade | Comprimento Máx.:50 |
model_number | string | Número do modelo | Comprimento Máx.:50 |
model_name † | string | Nome/descrição do modelo | Comprimento Máx.:255 |
model_year | number | Ano do modelo da unidade | Inteiro aaaa |
model_code | string | Código do modelo | Comprimento Máx.:50 |
brands | Lista de strings | Código que identifica unicamente a marca do produto. Veja a tabela Marcas abaixo. |
|
product_line | string | Código que identifica unicamente a linha de produto. Veja a tabela Linhas de Produto abaixo. | Comprimento Máx.: 3 |
product_type | string | Código que identifica unicamente o tipo de produto. Veja a tabela Tipos de Produto abaixo. | Comprimento Máx.: 5 |
manufacturer_name | string | Nome do fabricante | Comprimento Máx.:255 |
color_code_description | string | Descrição da cor | Comprimento Máx.:50 |
max_no_of_passengers | number | Número máximo de passageiros definido pelo fabricante |
|
engine_code | string | Código do motor | Comprimento Máx.:50 |
engine_code_description | string | Descrição do código do motor | Comprimento Máx.:255 |
no_of_cylinders | number | Número de cilindros no motor |
|
engine_displacement | number | O volume deslocado por cada pistão, movendo-se do ponto morto inferior ao ponto morto superior. Este valor é para todos os pistões no total. Este valor é expresso em centímetros cúbicos. |
|
engine_power | number | Potência do motor em cavalos-vapor |
|
gross_weight_vehicle_rating | number | Representa o peso/massa operacional máximo de um veículo especificado pelo fabricante. (kg) |
|
net_weight | number | Peso líquido do produto. | Precisão: 0.001 |
weight_unit | string | Unidade de medida do peso. Uma de:
| Comprimento Máx.: 3 |
inventory_type | string | Uma de:
| |
status | lista de strings | Lista de status/eventos atribuídos à unidade. Os valores possíveis são:
Array vazio se a informação não estiver disponível. | |
last_change_date | date-time | Última data e hora em que o status foi alterado, no formato ISO 8601 UTC. | Formato: YYYY-MM-DDTHH:MM:SSZ
|
Propriedades marcadas com uma adaga (†) são retornadas no idioma solicitado.
Observe que a propriedade last_change_date pode ser nula pois existe a possibilidade de não haver alteração na propriedade status.
Marcas
Código | Valor |
|---|---|
SKIDOO | Ski-Doo |
SEADOO | Sea-Doo |
LYNX | Lynx |
CANAM | Can-Am |
Linhas de Produtos
Chave | Valor | Marca |
|---|---|---|
2WV | Veículos de duas rodas | Can-Am On-Road |
3WV | Veículos de três rodas | Can-Am On-Road |
ATV | Veículos todo-terreno | Can-Am Off-Road |
OE | Motores de popa | Sea-Doo |
PTN | Barcos pontoon | Sea-Doo |
PWC | Veículos aquáticos pessoais | Sea-Doo |
SNO | Snowmobiles | Ski-Doo |
SSV | Veículos Side-by-Side | Can-Am Off-Road |
Tipos de Produto
Chave | Valor |
|---|---|
10 | Veículo |
20 | Motor |
30 | Peças |
40 | Acessórios |
50 | Vestuário |
60 | Licenciamento e Brinquedos |
80 | Manuais |
90 | Reboque |
100 | Recondicionado |
110 | Óleos e Produtos Químicos |
NA | Quando não houver correspondência acima (Indefinido) |
Limitações e Restrições
Formato de Número
Todos os campos numéricos com decimais usam o ponto(.) como separador decimal. A vírgula (,) NÃO é suportada como separador decimal.
Referência da API
curl --location 'https://cloud-api.brp.com/dcp/v4/unit/3JBLGAR15GJ000100/specifications?language=en-US' \
--header 'Dealer-Number: 0000700304' \
--header 'Authorization: Bearer 'REPLACE_ME' Tabelas de Referência
Idiomas
Idioma no código de idioma ISO (ISO-639-1 + ISO 3166-1)
Formato: xx-XX
xx: código de idioma em minúsculas
XX: código de país em maiúsculas
Valores de código de idioma suportados
Código | Idioma |
|---|---|
de | Alemão |
en | Inglês |
es | Espanhol |
fi | Finlandês |
fr | Francês |
it | Italiano |
nl | Holandês |
no | Norueguês |
pt | Português (Brasil) |
sv | Sueco |
Como Fazer
Esta seção fornece informações sobre como obter resultados específicos com a API.
Obter Especificações da Unidade
Obtenha as informações técnicas de uma unidade no ambiente de produção.
curl --location 'https://cloud-api.brp.com/dcp/v4/unit/3JBLWPP10EJ000558/specifications?language=de-DE' \
--header 'Dealer-Number: 0000701404' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' Tratamento de Erros
Esta seção apresenta vários cenários de chamadas inadequadas ou incorretas que resultam em mensagens de erro e resultados impróprios.
400 Solicitação Inválida
O código de status 400 é geralmente visto durante o desenvolvimento e a integração e não deve ser recebido durante operações normais. A resposta retornada contém as informações necessárias para corrigir o problema.
Muitos problemas podem causar um código de status 400; os mais comuns estão listados na tabela abaixo.
Resposta | Resolução |
|---|---|
Falta o número VIN no caminho. {
"status": "400",
"id": "rrt-074faba1d0796ac77-c-ea-24394-1768654-1",
"title": "bad_request",
"meta": {
"service": "00",
"detail": "Caminho não encontrado."
}
} | Certifique-se de que o VIN seja adicionado ao caminho. |
Falta o número do concessionário no cabeçalho. {
"status": "400",
"id": "rrt-07cdd77f98c381924-d-ea-22528-1563912-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "falha na validação da solicitação",
"payload": {
"details": [
{
"message": "O parâmetro de cabeçalho 'Dealer-Number' é obrigatório no caminho '/unit/{VIN}/specifications', mas não foi encontrado na requisição.: []"
}
]
}
}
} | Adicione o parâmetro de cabeçalho Dealer-Number com um número de concessionário válido. |
Retornado se o formato de idioma não for válido. {
"status": "400",
"id": "rrt-07cdd77f98c381924-d-ea-22528-1564213-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "falha na validação da solicitação",
"payload": {
"details": [
{
"message": "A regex ECMA 262 \"^[a-z]{2}-[A-Z]{2}$\" não corresponde à string de entrada \"XX-AA\": []"
}
]
}
}
} | O formato de idioma válido é o seguinte Formato: xx-XX xx: código do idioma em minúsculas XX: código do país em maiúsculas Um formato de idioma válido deve ser inserido para produzir uma resposta adequada. |
Retornado se o parâmetro for inválido {
"status": "400",
"id": "rrt-07783bca845d5...",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "falha na validação da solicitação",
"errors": {
"details": [
{
"message": "parâmetro de consulta inesperado: lang: []"
}
]
}
}
} | Lang é um parâmetro inválido. O parâmetro Language deve ser informado para obter uma resposta válida. |
401 Não Autorizado
O código de erro 401 Não Autorizado é retornado quando você tenta chamar a API com um access_token expirado.
Você precisa obter um novo access_token com uma chamada para a API de Autenticação de Aplicativos.
O código de erro 401 Não Autorizado também é retornado se você não solicitou acesso à API criando um ticket no Jira do DCP.
Quando você estiver pronto para começar a trabalhar em uma API, deve criar um ticket de certificação no Jira, conforme descrito na seção Atividades de Certificação com Jira.
Se você já começou a trabalhar em uma API e perdeu o acesso, crie um ticket de suporte conforme descrito na seção Abrir um Ticket de Suporte.
404 Não Encontrado
O código de status 404 Não Encontrado é retornado quando o VIN não é encontrado.
{
"status": "404",
"id": "rrt-07cdd77f98c381924-d-ea-22528-1563968-1.1",
"title": "not_found",
"meta": {
"service": "02",
"detail": "No record was found for the serial number A1B2C3"
}
}O revendedor pode ter cometido um erro ao inserir o VIN, ou a unidade não é um produto BRP ou é muito antiga.
Você deve relatar o erro ao usuário para que ele tente novamente.
Requisitos DSP
Requisitos Funcionais
ID | Tipo | Requisito |
|---|---|---|
1 | Obrigatório | Quando a API retornar o código de status 404 Not Found, o erro deve ser exibido na interface do usuário. |
2 | Obrigatório | O concessionário deve conseguir visualizar as especificações de uma unidade com base no número de série (VIN). |
Atividades de Certificação
Esta seção apresenta todas as atividades e validações de certificação que devem ser concluídas para certificar a API.
Garantia de Qualidade
Os testes listados na tabela abaixo devem ser realizados com sucesso no ambiente de teste antes que você possa iniciar a fase piloto do concessionário.
ID | Teste | Resultado Esperado |
|---|---|---|
1 | Obter as especificações técnicas para o VIN 3JBLGAP60MJ000001 (ATV) usando o idioma do seu concessionário | As informações técnicas são exibidas na interface do usuário. |
2 | Obter as especificações técnicas para o VIN YDV00054F021 (PWC) usando o idioma do seu concessionário | As informações técnicas são exibidas na interface do usuário. |
3 | Obter as especificações técnicas para o VIN 2BXNBDD10MV000013 (3WV) usando o idioma do seu concessionário | As informações técnicas são exibidas na interface do usuário. |
4 | Obter as especificações técnicas para o VIN 3JBVXAV27MK000001 (SSV) usando o idioma do seu concessionário | As informações técnicas são exibidas na interface do usuário. |
5 | Obter as especificações técnicas para o VIN YH2LLGNC9NR000595 (SNO) usando o idioma do seu concessionário | As informações técnicas são exibidas na interface do usuário. |
6 | Obter as especificações técnicas para o VIN YH2STML51LR0001 (SNO) usando o idioma do seu concessionário | O código de status 404 Not Found é retornado e você exibe o erro na interface do usuário. |
Piloto de Concessionárias
A tabela abaixo descreve os parâmetros e validações do piloto de concessionárias.
Parâmetro | Valor |
|---|---|
Ambiente | Produção |
Número de concessionárias | 1 a 3 |
Duração | 1 semana |
Validação 1 | Pedir às concessionárias que solicitem as informações técnicas de uma unidade para cada linha de produto. Capturar a tela com as informações exibidas e enviá-la para a equipe DCP. |
Postman
Esta seção descreve o que está disponível no Postman para explorar a API.
Ambientes
Um ambiente do Postman está disponível para testar a API de Especificações de Unidade. Este ambiente do Postman contém variáveis usadas pelas consultas e configuradas para se conectar ao ambiente de teste.
Coleções
A coleção DMS - Especificações de Unidade inclui exemplos de chamadas de API para recuperar informações de veículos.