API de Autenticação do Revendedor
Introdução
A API de Autenticação de Concessionárias usa autenticação baseada em token oAuth 2.0 para obter um token para uma concessionária.
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 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 o BRP | | | Um pouco mais ainda |
Autenticação
Para chamar a API de Autenticação da Aplicação, você precisa do client_id e do client_secret fornecidos pela Equipe DCP.
Certifique-se de usar o client_id que corresponde ao ambiente no qual a API está sendo chamada!
O client_id e o client_secret usados para chamar a API de Autenticação do Dealer NÃO são os mesmos usados para chamar a Autenticação da Aplicação!
URL Base
Teste | https://qa-cloud-api.brp.com/dcp |
|---|---|
Produção | https://cloud-api.brp.com/dcp |
Compreendendo a Autenticação do Revendedor
Salesforce e BOSSWeb
A Autenticação do Revendedor usa a conta BOSSWeb do revendedor para obter um token de acesso. O BOSSWeb é construído sobre o Salesforce, portanto, suas credenciais de Autenticação do Revendedor devem ser criadas e configuradas no Salesforce.
Para configurar seu acesso de Autenticação do Revendedor, você deve fornecer uma URL de callback (URI de redirecionamento).
Essa URL é chamada pelo Salesforce para enviar o código de acesso depois que o revendedor faz login no BOSSWeb.
Para chamar a Dealer Authentication API, você precisa do client_id e do client_secret criado pela Equipe DCP ao configurar sua conta no Salesforce, assim como o redirect_uri que você forneceu quando suas credenciais foram criadas.
Consulte a seção Autenticação do Dealer para mais informações.
❗ ❗ A URL usada ao chamar a API de Autenticação do Dealer deve corresponder EXATAMENTE àquela que você forneceu para a configuração ❗ ❗
Se a URL que você forneceu para o ambiente de produção é https://site você deve usar a mesma URL no parâmetro redirect na chamada para a API de Autenticação do Dealer.
Se você usar https://site/ ou https://Site no parâmetro redirect você receberá um erro:
👉 O redirect URI deve corresponder exatamente, mas você pode incluir o parâmetro de query state para fornecer ao seu callback informações de estado, como o número do dealer.
❗ ❗ Ao iniciar o trabalho em uma API DCP, precisamos solicitar acesso criando um ticket de certificação no Jira, conforme descrito na seção Atividades de Certificação com Jira. ❗ ❗
Se você já iniciou o trabalho em uma API e perdeu o acesso, crie um ticket de suporte conforme descrito na seção Abrir um Ticket de Suporte.
As credenciais nunca expirarão ou serão revogadas (a menos que você saia do DCP).
No entanto, as credenciais podem mudar, então sua implementação deve permitir que você altere e use facilmente novas credenciais.
Tokens de Acesso e Atualização
A API de Autenticação de Concessionária retorna dois valores importantes:
- O access_token é usado para chamar a API DCP usando Autenticação de Concessionária.
- O refresh_token é usado para obter um novo access_token quando o atual expirar.
O access_token é válido por 2 horas.
O refresh_tokené válido para sempre, e deve ser guardado para reutilização.
Consulte a seção Autenticação de Concessionária para mais informações sobre como gerenciar os tokens.
O token de acesso é específico da concessionária!
Um aspecto importante da Autenticação de Concessionária é que o token de acesso é específico para o número da concessionária usado para obter o código de autorização.
Se você obtiver um código de autorização para a concessionária 0000694650 e chamar uma API DCP para realizar uma operação para a concessionária 0000691730, você receberá um código de status 403 Forbidden.
O Código de Autorização
A primeira etapa no processo de Autenticação do Revendedor é obter um código de acesso do BOSSWeb. O revendedor deve fazer login no BOSSWeb usando suas credenciais para obter um código de acesso.
Para permitir que o revendedor faça login no BOSSWeb, você deve obter a URL com uma chamada ao endpoint Get Authorization Code da API de Autenticação do Revendedor.
A API retorna uma resposta que contém a URL para abrir em um navegador web. Quando aberta, o navegador exibe a página de login do BOSSWeb, conforme mostrado abaixo.
Após um login bem-sucedido, o BOSSWeb redireciona a página para a URI especificada em redirect_uri.
A URI de redirecionamento recebe o access_code nos parâmetros de consulta. Você extrai o access_code para preparar a chamada para obter o access_token.
Neste exemplo, a URI de redirecionamento https://localhost:8080/default.aspx é chamada, e você pode ver o código como o parâmetro de consulta code.
https://localhost:8080/default.aspx?code=aPrxCTGnE3a3w03eYfuMJIiNS32dVwR0CGa81tdZ2H69H0fBscwRM_GQN8CkqB8wfqO6sX0TaA%3D%3D
Se houver um erro na URL usada para abrir a página de login do BOSSWeb, o erro será retornado para a URI de redirecionamento.
Por exemplo, se o client_id for inválido, o seguinte é retornado para o URI de redirecionamento:
Modo de Simulação no Ambiente de Teste
Um desafio com a API de Autenticação do Dealer é que, quando o ambiente de teste é atualizado (ou seja, os dados de produção são copiados para o ambiente de teste), a configuração do Salesforce e a conta BOSSWeb do dealer usada para testes são perdidas.
Para evitar reconfigurar a Autenticação do Dealer sempre que houver uma atualização e reiniciar seus testes, um modo de simulação foi adicionado à API de Autenticação do Dealer no ambiente de teste.
O Que É Simulado
Quando o modo de simulação está ativado, isto é o que acontece:
- A validação do token de acesso nas APIs que usam a Autenticação do Dealer é desativada.
- A página de login do BOSSWeb não precisa ser exibida: sua URL de callback é chamada com um código de acesso simulado quando você chama o Obter Código de Autorização endpoint.
- Quando você chama o Obter Token endpoint para obter ou atualizar um token de acesso, valores simulados são retornados.
‼️Quando o modo de simulação está ativado, não tente abrir a página de login do BOSSWeb usando a URL retornada pela chamada Obter Código de Autorização ‼️
Como Saber se a Simulação Está Ativada
Quando você chama o endpoint Obter Código de Autorização a seguinte resposta é retornada.
{
"url": "https://cloud-api.brp.com/dcp/authentication/dealer/authorize?response_type=code&client_id=my_client_id&redirect_uri=https%3A%2F%2Fmy.callback.com",
"simulated": "false"
}O campo url contém a URL para enviar a um navegador web para abrir a página de login do BOSSWeb.
O campo simulated indica se a simulação está ativada.
‼️No ambiente de produção, simulated é sempre false.
Fluxo de Autenticação do Concessionário
Abaixo está o fluxo do processo para a API de Autenticação do Concessionário.
‼️Para usar o modo de simulação, seu DMS deve implementar um fluxo semelhante ao abaixo‼️
‼️Quando o modo de simulação estiver ativado, não tente abrir a página de login do BOSSWeb usando a URL retornada pela chamada Obter Código de Autorização ‼️
O fluxo assume que seu callback chama o endpoint Obter Token.
Seu fluxo pode ser diferente, mas, em resumo, se o modo de simulação estiver ativado, você não precisa abrir a página de login do BOSSWeb.
Referência da API
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/authorize?client_id=my_client_id&redirect_uri=https%3A%2F%2Fmy.callback.com' curl --location --request POST 'https://qa-cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=authorization_code&client_id=REPLACE_ME&client_secret=REPLACE_ME&code=REPLACE_ME&redirect_uri=REPLACE_ME'curl --location --request POST 'https://qa-cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=refresh_token&client_id=REPLACE_ME&client_secret=REPLACE_ME&redirect_uri=REPLACE_ME&refresh_token=REPLACE_ME'curl --location 'https://qa-cloud-api.brp.com/dcp/authentication/dealer/userinfo' \
--header 'Authorization: Bearer REPLACE_ME'Como fazer
Esta seção mostrará exemplos de uso da API de Autenticação de Concessionárias. Para estes exemplos, os valores apresentados na tabela abaixo são usados. Você deve substituir os valores pelos seus próprios antes de chamar a API.
Variável | Valor |
|---|---|
client_id | %C*F-J@NcRfUjXn2 |
client_secret | kYp3s6v9y$B&E)H@ |
redirect URI | https://my.dps.com/dealer_auth/pro |
dealer number | 0000456789 |
user name | joe.smith |
Este exemplo foi feito usando o ambiente de produção.
Nestes exemplos, os tokens, client_id e client_secret são valores aleatórios. Na realidade, os valores são mais longos, com até 128 caracteres.
Obter Código de Autorização
O primeiro passo é abrir um navegador da web e navegar até a página de login do BOSSWeb.
Isso é feito chamando a API de Autenticação de Concessionário Obter Código de Autorização endpoint.
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/authorize?client_id=my_client_id&redirect_uri=https%3A%2F%2Fmy.callback.com' A API retorna um payload de resposta com dois campos:
- url contém a URL a ser usada para abrir a página de login do BOSSWeb em um navegador.
- simulated indica se o modo de Autenticação de Concessionário está ativo. O campo é sempre false em produção.
A janela de login do BOSSWeb é exibida, e o concessionário insere suas credenciais.
O URI de redirecionamento recebe o access_code nos parâmetros da query e deve extraí-lo.
https://my.dps.com/dealer_auth/pro?code=&E)H@McQfTjWnZq4
Agora você está pronto para obter o token de acesso bearer.
Obter Token de Acesso
Para obter o token de acesso bearer, chame a API usando o access_code recebido na etapa anterior e o client_id, client_secret, e o redirect_uri.
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=authorization_code&client_id=%C*F-J@NcRfUjXn2&client_secret=kYp3s6v9y$B&E)H@&code=&E)H@McQfTjWnZq4&redirect_uri=https://my.dps.com/dealer_auth/pro'Você recebe access_token e refresh_token na mensagem de resposta.
O access_token é usado para chamar as APIs do DCP.
O refresh_token deve ser salvo pois é reutilizado para renovar o access_token .
Renovar Token
O access_token é válido por 2 horas. Para evitar que os distribuidores precisem fazer login novamente a cada 2 horas, atualize o access_token antes que ele expire.
Para atualizar o token, você chama a API usando o tipo de concessão refresh_token grant type.
A API retorna um novo access_token que é usado para chamar as APIs do DCP.
O refresh_token não é RETORNADO pela API na chamada de atualização. O refresh_token é válido até ser revogado, então você deve mantê-lo.
curl --location --request POST 'https://cloud-api.brp.com/dcp/authentication/dealer/token?grant_type=refresh_token&client_id=%C*F-J@NcRfUjXn2&client_secret=kYp3s6v9y$B&E)H@&redirect_uri=https://my.dps.com/dealer_auth/pro'&refresh_token=%C*F-JaNdRfUjXn2'Usando o parâmetro de consulta State
A primeira etapa é construir uma URL que abra um navegador e mostre a página de login do BOSSWeb. A URL contém o parâmetro de consulta state para fornecer ao callback informações sobre o distribuidor que fez a chamada.
Usando os valores do nosso exemplo, sua URL é:
http://cloud-api.brp.com/dcp/authentication/dealer/authorize?response_type=code&client_id=%C*F-J@NcRfUjXn2&redirect_uri=https://my.dps.com/dealer_auth/pro&state=this is my dealer information
A janela de login do BOSSWeb é exibida, e o concessionário insere suas credenciais.
O URI de redirecionamento recebe o access_code nos parâmetros de consulta e deve extraí-lo. Ele também recebeu o valor fornecido no parâmetro de consulta state.
https://my.dps.com/dealer_auth/pro?code=&E)H@McQfTjWnZq4&state=this+is+my+dealer+information&state=this+is+my+dealer+information
Agora você está pronto para obter o token de acesso bearer, conforme descrito na seção Obter Token de Acesso acima.
As informações que você forneceu no parâmetro de consulta state podem ser usadas pelo seu callback para vincular o token de acesso recebido a um concessionário específico.
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 de erro 400 Solicitação Inválida é o único que os serviços GET da API de Autenticação do Dealer retornaram.
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 grant_type não for válido ou se o código de autorização tiver expirado. {
"error": "invalid_grant",
"error_description": "código de autorização expirado"
} | Confirme que o grant_type está configurado corretamente, solicite um novo código de autorização e tente novamente. Se a nova tentativa falhar, contate a equipe DCP. |
Retornado se o client_id não for válido. {
"error": "invalid_client_id",
"error_description": "identificador de cliente inválido"
} | Confirme que o client_id está configurado corretamente e tente novamente. Se a nova tentativa falhar, contate a equipe DCP para garantir que seu DSP esteja registrado no Servidor de Autorização. |
Retornado se o client_secret não for válido. {
"error": "invalid_client",
"error_description": "credenciais de cliente inválidas"
} | Confirme que o client_secret está configurado corretamente e tente novamente. Se a nova tentativa falhar, contate a equipe DCP para garantir que seu DSP esteja registrado no Servidor de Autorização. |
401 Não autorizado
O endpoint da API userinfo pode retornar o código de status de erro 401 Não autorizado.
O erro é retornado quando você tenta chamar a API de Autenticação do Dealer com um access_token expirado.
Você precisa obter um novo access_token ou renovar o que você tem chamando o endpoint da API token.
Requisitos do DSP
Requisitos Funcionais
ID | Tipo | |
|---|---|---|
1 | Obrigatório | O access_token deve ser automaticamente renovado a cada 90 minutos |
2 | Obrigatório | O refresh_token deve ser salvo no perfil do revendedor e reutilizado para solicitar um access_token. |
3 | Opcional | O revendedor pode acessar uma tela de configuração para fazer login no BOSSWeb. O refresh_token recebido é salvo e usado para obter um access_token . |
Atividades de Certificação
A API de Autenticação do Dealer não possui atividades específicas de certificação; ela é validada através da API DCP utilizando a Autenticação do Dealer.
Postman
Esta seção descreve o que está disponível no Postman para explorar a API.
Ambientes
Um ambiente Postman está disponível para testar a API de Autenticação do Revendedor. Este ambiente Postman contém variáveis usadas pelas consultas e está configurado para se conectar ao ambiente de teste.
Coleções
A coleção DSP - Autenticação do Revendedor contém exemplos de chamadas de API para obter e validar um token de acesso.