API de Ordem de Unidades
Começando
A API de Pedidos de Unidades permite que o concessionário recupere os pedidos de unidades preparados no Sistema de Gerenciamento de Pedidos (OMS) no BOSSWeb.
O concessionário pode então acompanhar a entrega da unidade e, uma vez entregue, inseri-la no inventário usando o VIN encontrado nas informações de entrega.
Por onde começar? Leia isto primeiro!
Antes de começar a trabalhar nesta API, você precisa ler as seguintes seções, caso ainda não as tenha visto:
- Informações Técnicas para informações técnicas gerais sobre a API e ambientes.
- Autenticação e Credenciais para detalhes sobre autenticação e credenciais.
- Processo de Certificação para detalhes sobre o processo de certificação e Jira.
- Obtendo Suporte para detalhes sobre como obter ajuda e Jira.
Resumo de Negócios
Tópico | Descrição |
|---|---|
Escopo | Pedidos de unidades na América do Norte |
Cenários |
|
Funcionalidades principais |
|
Processos de negócios suportados |
|
Benefícios para concessionárias |
|
Benefícios para a BRP |
|
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 do Revendedor e Autenticação da Aplicação.
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)
Autenticação do Concessionário
Você precisa de um token de acesso válido antes de chamar esta API ou deve chamar a API de Autenticação do Revendedor para obter um.
O access_token é válido por 2 horas.
Você deve usar o refresh_token para obter um access_token antes que o atual expire.
❗❗ O access_token obtido através da API de Autenticação do Revendedor deve ser para o concessionário cujo número de concessionário é usado no campo dealer_no do payload ou do cabeçalho ❗❗
Veja a seção Login do Concessionário para mais informações.
Consulte o Autenticação do Concessionário e API de Autenticação do Revendedor seções para mais informações.
URL Base
Teste | https://qa-cloud-api.brp.com/dcp/v4 |
|---|---|
Produção | https://cloud-api.brp.com/dcp/v4 |
Recurso: Pedido de Unidade
A API retorna o recurso Pedidos de Unidade que contém pedidos de unidade.
Representação JSON
{
"sales_order_no": "1030001693",
"order_type": "regular",
"dealer_no": "0000690885",
"dealer_po_no": "IO690885-MY23-91DEC",
"creation_date": "2023-02-04T01:22:25Z",
"requested_delivery_date": "2022-11-21",
"items": [
{
"item_no": "000010",
"product_code": "0008MPF00",
"product_descr": "Defender MAX XT HD10",
"color": "Mossy Oak Break-Up Country Cam",
"model_year": "2023",
"segment_descr": "Defender MAX",
"package_descr": "XT",
"product_line": "SSV",
"customer_reference_period_descr": "Dec",
"customer_reference_year_code": "",
"order_qty": 1,
"requested_delivery_date": "2022-11-21",
"requested_delivery_period_descr": "Dec",
"is_cancellable": false,
"is_pre_order": false,
"is_cancellable_pre_order": false,
"estimated_delivery_period": "2023-02-27",
"estimated_delivery_period_type": "week",
"estimated_shipped_period": "2023-02-28",
"estimated_shipped_period_type": "week",
"ship_to_no": "0000690885",
"delivery_schedule": [
{
"schedule_line_no": "0002",
"confirmed_date": "2023-02-28",
"confirmed_qty": 1,
"processing_status": "",
"delivery_status": ""
}
],
"delivery_progress": [
{
"freight_no": "7000003739",
"estimated_shipped_date": "2023-02-28",
"estimated_delivery_date": "2023-02-27",
"goods_issue_date": "2023-02-27",
"shipped_date": "2023-02-28",
"delivery_date": "2023-02-28",
"confirmation_status_code": "10",
"serial_numbers": [
"3JBUCAX44PK001102"
],
"shipping_carrier": {
"carrier_no": "31000164",
"carrier_name": "MCK TRUCKING INC",
"carrier_mobile": "",
"carrier_email": "",
"carrier_contact": ""
}
}
]
}
]
}Propriedades
Propriedade | Tipo | Tipo | Notas |
|---|---|---|---|
sales_order_no | string | O número que identifica exclusivamente o documento de venda. | Comprimento máximo: 10 |
order_type | string | O tipo de pedido: regular ou urgente. | |
dealer_no | string | Código que identifica exclusivamente um revendedor. | Comprimento: 10 |
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 | Motos aquáticas | Sea-Doo |
SNO | Snowmobiles | Ski-Doo |
SSV | Veículos side-by-side | Can-Am Off-Road |
Recurso: Lista de Pedidos da Unidade
Quando chamado para solicitar uma lista de pedidos de unidade, a API de Unidades retorna uma matriz de Pedido de Unidade recursos.
👉 Mesmo que você chame a API de Pedidos de Unidade com um filtro para recuperar apenas um pedido, a API sempre retorna uma lista de pedidos de unidade.
As respostas retornadas contêm dois objetos que ajudam você a navegar pelas páginas de pedidos de unidade.
Representação JSON
{
"items": [
{
List of Unit Orders resources
}
],
"links": {
"previous": null,
"next": "https://qa-cloud-api.brp.com/dcp/v4/units/orders?page=2&limit=200"
},
"meta": {
"total_records": 233,
"total_pages": 2,
"current_page": 1,
"limit": 200
}
}Propriedades
Propriedade | Tipo | Definição |
|---|---|---|
items | Lista de objetos | Lista de recursos Unit que são retornados. |
links | objeto | Links de paginação. |
links.previous | string | URL a ser usada para recuperar a página anterior. NULL se não houver página anterior. |
links.next | string | URL a ser usada para recuperar a próxima página. NULL se não houver próxima página. |
meta | objeto | Estatísticas da requisição. |
meta.total_records | número | O número de registros retornados pela requisição. |
meta.total_pages | número | O número de páginas usando o limit para calcular. |
meta.current_page | número | O número da página atual ou número da página solicitada. |
meta.limit | número | Limite dos parâmetros da requisição. |
Links
O Links pode ser usado para navegar pelas páginas retornadas pela API de Units.
Quando um link não é NULL, ele pode ser usado para ir para a página anterior ou seguinte. Isso simplifica a navegação entre páginas porque você não precisa salvar sua consulta de parâmetros; a URL do link contém os parâmetros de consulta que você forneceu e os parâmetros padrão para aqueles que você não forneceu.
Metadados
O Meta fornece estatísticas sobre o número de recursos Unit retornados pela sua solicitação e o número de páginas esperadas.
Esta informação pode ser útil para diagnósticos e para verificar que todos os recursos da unidade foram recebidos.
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.
Parâmetro de Consulta de Filtro
O parâmetro de consulta $filter pode ser usado para filtrar os pedidos de unidade utilizando apenas as seguintes propriedades:
- sales_order_no
- dealer_po_no
- requested_delivery_date
👉 Usar outras propriedades na consulta $filter criará um erro ou será ignorado.
Referência da API
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME'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 | Embarcações pessoais | Sea-Doo |
SNO | Snowmobiles | Ski-Doo |
SSV | Veículos side-by-side | Can-Am Off-Road |
Como Fazer
Esta seção fornece informações sobre como obter resultados específicos com a API.
Obter Pedidos Usando um Intervalo de Datas
Este exemplo mostra como obter os pedidos de unidades usando um intervalo de datas.
A solicitação usa o parâmetro limit para limitar a resposta a 3 pedidos por página.
A propriedade links fornece as informações para navegar pelas páginas. Consulte a seção Paginação para mais informações.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obter Pedidos de Unidade para uma Linha de Produtos
Este exemplo mostra como obter os pedidos de unidade para uma linha de produtos específica. As linhas de produtos válidas estão listadas na tabela API de Ordem de Unidades .
A solicitação usa o parâmetro limit para limitar a resposta a 3 pedidos por página.
A propriedade links fornece as informações para navegar entre as páginas. Consulte a seção Paginação para mais informações.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&product_line=PWC&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obter um Pedido com o Número do Pedido de Venda
Este exemplo mostra como obter a ordem da unidade usando um número de pedido de vendas no $filter parâmetro de consulta.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=sales_order_no%20eq%20%271030417429%27' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obter um Pedido usando o Número de PO do Revendedor
Este exemplo mostra como obter o pedido da unidade usando um número de PO do revendedor no parâmetro de consulta $filter .
A solicitação usa o parâmetro limit para limitar a resposta a 2 pedidos por página.
A propriedade links fornece as informações para navegar entre as páginas. Consulte a seção Paginação para mais informações.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=dealer_po_no%20eq%20%20%27IO690885-MY23-91%27&limit=2' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obter Ordens da Unidade Usando a Data Solicitada
Este exemplo mostra como obter os pedidos de unidade usando um intervalo de datas solicitado no $filter parâmetro de consulta.
A solicitação usa o limit parâmetro para limitar a resposta a 3 pedidos por página.
O links fornece as informações para navegar pelas páginas. Consulte a Paginação seção para mais informações.
curl --location 'https://cloud-api.brp.com/dcp/v4/units/orders?dealer_no=0000690885&%24filter=((requested_delivery_date%20ge%202024-01-02)%20and%20((requested_delivery_date%20le%202024-07-02)))&limit=3' \
--header 'Authorization-Dealer: DEALER_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Manipulação 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 Requisição Inválida
O código de status 400 é geralmente observado 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 |
|---|---|
Retornado se o número do concessionário for inválido. {
"status": "400",
"id": "rrt-02ac3ea9453bba5fe-d-ea-2008293-6461009-1",
"title": "solicitacao_invalida",
"meta": {
"service": "01",
"detail": "falha na validação da requisição",
"payload": {
"details": [
{
"message": "A string \"12345\" é muito curta (tamanho: 5, mínimo requerido: 10): []"
}
]
}
}
} | Se o concessionário estiver usando seu DMS, pode ser que ele não seja mais um concessionário BRP. Verifique com ele e desabilite atualizações de inventário de peças. Certifique-se de que o número do concessionário tenha 10 caracteres. Se você salva o número sem zeros à esquerda, adicione o zero à esquerda antes de chamar a API. O erro também é retornado se o concessionário não for um concessionário BRP ativo. |
Retornado se o número do concessionário estiver ausente. {
"status": "400",
"id": "rrt-02ac3ea9453bba5fe-d-ea-2008293-6460630-1",
"title": "solicitacao_invalida",
"meta": {
"service": "01",
"detail": "falha na validação da requisição",
"payload": {
"details": [
{
"message": "O parâmetro de consulta 'dealer_no' é obrigatório no caminho '/units/orders' mas não foi encontrado na requisição.: []"
}
]
}
}
} | O número do concessionário é obrigatório na chamada. |
Retornado se uma data tiver um formato inválido. {
"status": "400",
"id": "rrt-0aa500db076dc9eed-d-ea-1328974-8272532-1",
"title": "solicitacao_invalida",
"meta": {
"service": "01",
"detail": "falha na validação da requisição",
"payload": {
"details": [
{
"message": "A string \"AAbbCC\" é inválida para o formato de data requerido yyyy-MM-dd: []"
}
]
}
}
} | Altere o formato da string de data para corresponder ao formato esperado pelo payload. |
Retornado se as datas estiverem invertidas.
{
"status": "400",
"id": "rrt-007c4ae418b4c128f-b-ea-3013144-8304219-1.1",
"title": "solicitacao_invalida",
"meta": {
"service": "21",
"detail": "O campo creation_date_from não pode ser posterior ao creation_date_to. Verifique suas datas e tente novamente."
}
}
| Verifique se o creation_date_from é anterior (mais antiga) que o creation_date_to. |
401 Não autorizado
O código de status de erro 401 Unauthorized é 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 status de erro 401 Unauthorized também é retornado se você não solicitou acesso à API criando um ticket no DCP Jira.
Quando estiver pronto para começar a trabalhar em uma API, você deve criar um ticket de certificação no Jira, conforme descrito na seção Atividades de Certificação com o 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.
403 Proibido
O código de status de erro 403 Forbidden é retornado se o número do concessionário não corresponder ao token do concessionário.
{
"status": "403",
"id": "rrt-08ca5848b0d5e485e-b-ea-1816747-7377470-1.1",
"title": "forbidden",
"meta": {
"service": "96",
"detail": "The dealer_no in the request doesn't correspond to the dealer_no associated with the dealer token provided."
}
}Certifique-se de que você está usando o token de autenticação do concessionário correto.
Requisitos DSP
Requisitos Funcionais
ID | Tipo | Requisito |
|---|---|---|
1 | Obrigatório | O access_token deve ser automaticamente renovado a cada 90 minutos |
2 | Obrigatório | O API de Autenticação do Revendedor access_token e refresh_token devem ser salvos e usados por todos os usuários com permissão para gerenciar pedidos de unidades. |
3 | Obrigatório | O API de Autenticação do Revendedor access_token deve ser renovado a cada 2 horas usando o refresh_token. |
Atividades de Certificação
Esta seção apresenta todas as atividades de certificação e validações que devem ser concluídas para certificar a API.
Validações
Os testes listados na tabela abaixo devem ser realizados com sucesso no ambiente de testes antes que você possa iniciar a fase piloto com o concessionário.
👉 Para executar os testes, você precisa de credenciais de concessionária BOSSWeb no ambiente de teste. Se você não as tiver, abra um ticket no Jira do DCP.
ID | Teste | Resultado Esperado |
|---|---|---|
1 | Recuperar os pedidos de unidades criados nos últimos 12 meses. | Os pedidos de unidades são exibidos no DMS, e as propriedades delivery_progress estão visíveis. |
2 | Obter os pedidos de unidades para uma linha de produtos suportada pelo concessionário. | Os pedidos de unidades são exibidos no DMS. |
3 | Obter um pedido de unidade usando o número do pedido de venda. | Obter um número de pedido de venda dos pedidos de unidades carregados na etapa 1. Recuperar o pedido de unidade correspondente. |
4 | Obter um pedido de unidade usando o número de PO do concessionário. | Obter um número de PO do concessionário a partir dos pedidos de unidades carregados na etapa 1. Recuperar o pedido de unidade correspondente. |
Piloto do Concessionário
A tabela abaixo descreve os parâmetros e validações do piloto do concessionário.
Parâmetro | Valor |
|---|---|
Ambiente | Produção |
Número de concessionários | 1 a 3 |
Duração | 1 semana |
Validação 1 | Recuperar os pedidos de unidade criados nos últimos 12 meses. |
Validação 2 | Os pedidos de unidade são atualizados diariamente e disponibilizados ao concessionário. |
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 Units Order API. Esse ambiente do Postman contém variáveis usadas pelas consultas e está configurado para conectar-se ao ambiente de teste.
Coleções
A coleção DMS - Units Order contém exemplos de chamadas de API para obter pedidos de unidades de um concessionário.