API de Informações DSP

37 min

Começando

A API de Informações do DSP fornece à BRP uma lista diária e atualizada dos clientes BRP que utilizam o seu sistema.

Esta lista atualizada permite à BRP gerir informações de concessionárias e garantir a precisão dos dados para programas de negócios importantes, incluindo os programas do Sistema de Gestão de Leads (LMS), que atendem às concessionárias.

❗ ❗ Apenas os concessionários BRP Powersports devem ser enviados ❗ ❗

Os outros tipos de concessionários BRP NÃO fazem parte do DCP e não devem ser incluídos na lista de concessionárias.

❗ ❗ Todos os concessionários BRP ativos devem ser enviados na lista de Informações DSP, mesmo que o compartilhamento de dados para Inventário de Peças da Concessionária e Transações de Varejo não esteja habilitadod ❗ ❗

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 consultou:

Comece Aqui Com Leitura Obrigatória!
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.

Gerenciando a Lista de Concessionários

Para apoiar as diversas iniciativas de negócios da BRP, o DCP deve associar corretamente os concessionários aos seus DMS. A API DSP Information ajuda, mas existem casos em que ela não é suficiente. Um concessionário pode mudar seu sistema DMS e manter o antigo por um tempo. Nessa situação, o consentimento de compartilhamento de dados no DMS antigo frequentemente permanece ativado, e o DCP recebe dados de inventário e transações de varejo de ambos os DMS.

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 para o 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 de Aplicação.

Você precisa de um token de acesso válido antes de chamar esta API, ou você 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: Revendedores

O Revendedores recurso permite que DSPs atualizem sua lista de revendedores.

Representação JSON

{
   "items":[
      {
         "dealer_no":"0000699623",
         "Data_sharing_consent": true
      },
      {
         "dealer_no":"0000694307",
         "Data_sharing_consent": false
      }
   ]
}

Propriedades

Propriedade	Tipo	Definição	Notas
items	Lista de Objetos	Lista de concessionárias. Deve conter pelo menos uma concessionária.
dealer_no	String	Código que identifica exclusivamente uma concessionária. Deve conter 10 caracteres. Se tiver menos de 10 caracteres, adicionar '0' no início.	Comprimento:10
data_sharing_consent	Booleano	Indicando se o cliente consentiu em compartilhar seus dados com a BRP através desse DMS. O valor é um dos seguintes: true false

Todas as propriedades são obrigatórias.

Limitações e Restrições

Tamanho da Lista de Concessionárias

Para evitar timeouts, a lista de concessionárias não deve conter

mais de 800 concessionárias.

Entendendo as Informações do DSP

A Lista de Concessionárias

Sistema Centralizado vs. Descentralizado

Seu sistema pode ser centralizado, por exemplo, baseado na web, ou descentralizado, com um servidor instalado na concessionária.

A forma como a API de Informações DSP é chamada depende do tipo de sistema:

Centralizado: você envia a lista completa das concessionárias ativas todos os dias.

Descentralizado: cada concessionária ativa chama a API todos os dias.

Observe que a chamada deve ser feita aleatoriamente entre 00:00 e 06:00 no fuso horário da concessionária.

👉 Observe que mesmo com um sistema descentralizado, você pode ter uma lista centralizada de concessionárias.

Adicionando e Removendo uma Concessionária

É essencial atualizar sua lista de concessionárias sempre que uma nova concessionária BRP entrar no seu DMS ou CRM, ou quando uma concessionária BRP deixar de usar seu sistema.

Quando uma concessionária parar de usar seu DSP, pare de enviá-la nos dados de Informações do DSP, e ela será marcada como inativa do nosso lado.

Em alguns casos, você pode ter uma concessionária usando seu DSP que deixa de ser uma concessionária BRP. Nesse caso, pare de enviá-la nos dados de Informações do DSP, e ela será marcada como inativa do nosso lado.

Começamos a criar tickets no Jira do tipo 'Atualização de Lista de Concessionárias' para informar você quando a BRP adiciona uma nova concessionária BRP e quando uma concessionária deixa de ser BRP.

👉 Por favor, processe esses tickets e nos informe no ticket quando a alteração tiver sido realizada.

Referência da API

Update Dealer List

Update your dealer list. For DMSs, also update the data sharing consent flag.

POST

/dsp/dealers

curl --location 'https://cloud-api.brp.com/dcp/v4/dsp/dealers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
   "items":[
      {
         "dealer_no":"0000692157",
         "data_sharing_consent":true
      },
      {
         "dealer_no":"0000690373",
         "data_sharing_consent":true
      }
   ]
}'

Como Fazer

Esta seção fornece informações sobre como obter resultados específicos com a API.

Enviar Lista de Concessionárias

Envie sua lista de concessionárias a partir de um servidor central no ambiente de produção.

❗ ❗ Apenas as concessionárias BRP Powersports devem ser enviadas ❗ ❗

Os outros tipos de concessionárias BRP NÃO fazem parte do DCP e não devem ser incluídos na lista de concessionárias.

Enviar Lista de Concessionárias

curl --location 'https://cloud-api.brp.com/dcp/v4/dsp/dealers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' 
--data '{
  "items": [
    {
      "dealer_no": "0000690005",
      "data_sharing_consent": true
    },
    {
      "dealer_no": "0000690020",
      "data_sharing_consent": true
    },
    {
      "dealer_no": "0000690012",
      "data_sharing_consent": false
    },
    {
      "dealer_no": "0000690009",
      "data_sharing_consent": true
    },
    {
      "dealer_no": "0000690025",
      "data_sharing_consent": true
    },
    {
      "dealer_no": "0000690026",
      "data_sharing_consent": false
    },
    {
      "dealer_no": "0000690032",
      "data_sharing_consent": true
    }
    ]
}'

Tratamento de Erros

Esta seção apresenta vários cenários de chamadas incorretas que resultam em mensagens de erro e resultados imprecisos.

207 Multi-Status

O código 207 Multi-Status é retornado quando um dos números de concessionária enviados na lista é inválido.

Você deve validar sua lista de concessionárias e remover qualquer número inválido.

Isso pode ocorrer quando seu cliente não é mais uma concessionária BRP.

400 Bad Request

O código de status 400 é normalmente encontrado durante o desenvolvimento e integração e não deve ocorrer 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 na tabela abaixo.

Resposta	Resolução
Retornado se a lista de concessionárias estiver vazia. { "status": "400", "id": "rrt-0bde02a11a182b18f-b-ea-22691-1539844-1", "title": "bad_request", "meta": { "service": "01", "detail": "a validação da requisição falhou", "payload": { "details": [ { "message": "[Path '/items'] Array é muito curto: deve ter pelo menos 1 elemento, mas a instância possui 0 elementos: []" } ] } } }	A lista de concessionárias não pode estar vazia. Revise sua integração e garanta que você envia a lista de concessionárias.
Retornado se você chamar a API sem a lista de concessionárias. { "status": "400", "id": "rrt-0bde02a11a182b18f-b-ea-22692-1540163-1", "title": "bad_request", "meta": { "service": "01", "detail": "a validação da requisição falhou", "payload": { "details": [ { "message": "O objeto possui propriedades obrigatórias ausentes ([\"items\"]): []" } ] } } }	O payload da requisição deve conter a lista de concessionárias.
Retornado se um item da concessionária estiver sem o sinalizador de compartilhamento de dados. { "status": "400", "id": "rrt-0bde02a11a182b18f-b-ea-22692-1540393-1", "title": "bad_request", "meta": { "service": "01", "detail": "a validação da requisição falhou", "payload": { "details": [ { "message": "[Path '/items/0'] O objeto possui propriedades obrigatórias ausentes ([\"data_sharing_consent\"]): []" } ] } } }	Quando chamado do seu DMS, a lista de concessionárias deve conter o sinalizador de compartilhamento de dados. O sinalizador é opcional quando chamado do seu CRM.
Retornado se houver uma propriedade inválida na lista de concessionárias. { "status": "400", "id": "rrt-0bde02a11a182b18f-b-ea-22691-1540493-1", "title": "bad_request", "meta": { "service": "01", "detail": "a validação da requisição falhou", "payload": { "details": [ { "message": "[Path '/items/0'] A instância do objeto possui propriedades que não são permitidas pelo schema: [\"invalid_property\"]: []" } ] } } }	Verifique o formato do payload JSON acima para as propriedades válidas.

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 Jira do DCP.

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.

404 Não Encontrado

A API de Informações do DSP retorna um status 404 Not Found quando seu DSP ainda não foi registrado no sistema backend do BRP.

Na resposta da API, você verá o nome do seu DSP e o tipo de DSP (DMS ou CRM) no objeto errors, na propriedade detail.

{
    "status": "404",
    "id": "rrt-095670f08a456e78c-d-ea-22270-46269273-1.1",
    "title": "not_found",
    "meta": {
        "service": "03",
        "detail": "Backend error",
        "payload": {
            "errors": [
                {
                    "code": "Not Found",
                    "title": "DSP name entered is invalid or inactive.",
                    "detail": "DSP name entered is invalid or inactive: <DSP NAME> for type DMS"
                }
            ]
        }
    }
}

❗ Quando você receber um status '404 Not Found', abra um ticket no Jira do DCP.

Requisitos de DSP

Requisitos Funcionais

Lista de Concessionárias

ID	Tipo	Requisito
1	Obrigatório	Sua lista de concessionárias deve ser atualizada automaticamente todos os dias Se seu sistema for centralizado, a lista de concessionárias contém todas as concessionárias ativas. Se seu sistema for descentralizado (ou seja, instalado na concessionária), uma lista separada é fornecida para cada localização.
2	Obrigatório	Se uma concessionária parar de usar seu DMS/CRM, você deve removê-la da sua lista.
3	Obrigatório	Somente as concessionárias BRP Powersports estão incluídas na lista.
4	Obrigatório	Quando uma concessionária BRP Powersports começa a usar seu DMS, você deve adicioná-la à lista e notificar o DCP. Consulte a seção

Atividades de Certificação

Esta seção descreve todas as atividades de certificação e validações necessárias para certificar a API.

Garantia de Qualidade

Os testes listados na tabela abaixo devem ser concluídos com sucesso no ambiente de teste antes que você possa iniciar a fase piloto do revendedor.

Lista de Revendedores

ID	Teste	Resultado Esperado
1	Envie sua lista de concessionárias e forneça sua lista de concessionárias em um arquivo	A equipe DCP verifica que sua lista de concessionárias está salva no sistema de backend e corresponde à lista que você forneceu. A lista de concessionárias fornecida deve incluir o valor do indicador de compartilhamento de dados para cada concessionária.
2	Atualize automaticamente sua lista de concessionárias todos os dias por 3 dias	A equipe DCP verifica que sua lista de concessionárias está salva no sistema de backend diariamente.

Piloto de Concessionárias

A tabela abaixo descreve os parâmetros do piloto de concessionárias e suas validações correspondentes.

Lista de Concessionárias

Parâmetro	Valor
Ambiente	Produção
Número de concessionárias	Todas as suas concessionárias
Duração	2 semanas
Validação 1	A equipe DCP verifica diariamente se sua lista de concessionárias está salva no sistema backend.
Validação 2	Você deve fornecer sua lista de concessionárias em um arquivo duas vezes durante o período piloto. A equipe DCP verifica se a lista salva no sistema backend corresponde à lista que você forneceu.
Validação 3	Verifique se apenas concessionárias de Powersports são enviadas para a lista.

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 Informações DSP. Este ambiente do Postman contém variáveis usadas pelas consultas e está configurado para se conectar ao ambiente de teste.

Teste - Ambiente DSP

Coleções

A coleção DSP - DSP Information inclui exemplos de chamadas de API para atualizar sua lista de concessionárias.

DSP - Informações DSP

Registro de Alterações da API

Revisão 1.2

Added

Adicionado o registro de atividades do CRM.

Revisão 1.1

Fixed

Alinhada a estrutura da mensagem de erro ao padrão descrito na seção de Informações Técnicas.

Revisão 1.0

Added

Primeiro lançamento