API de Oportunidade de Vendas

65 min

Introdução

A API de Oportunidade de Vendas está relacionada ao gerenciamento de leads de vendas. A arquitetura da API de Oportunidade de Vendas é incomum porque ela chama seu CRM para enviar oportunidades de vendas.

O objetivo da API de Oportunidade de Vendas é enviar rapidamente oportunidades de vendas aos concessionários, permitindo um acompanhamento rápido com os clientes e atualizações de status fáceis de retornar à BRP.

A seção Compreendendo a Oportunidade de Vendas fornece informações sobre o gerenciamento de leads de vendas e o uso da API de Oportunidade de Vendas.

Terminologia da BRP

Antes de começarmos, vamos definir alguns termos.

Um lead de vendas: um cliente em potencial interessado em um produto BRP. Algumas informações sobre esse cliente em potencial estão disponíveis, incluindo seu nome, número de telefone ou endereço de e-mail, bem como o produto de interesse.

Oportunidade de vendas: Um lead de vendas validado e qualificado foi atribuído a um concessionário.

Disposição: É o resultado da oportunidade de venda processada pelo concessionário. A oportunidade de venda pode resultar em contatar o cliente, uma venda de unidade ou abandono.

Por Onde Começar? Leia Isso Primeiro!

Antes de começar a trabalhar nesta API, você precisa ler as seguintes seções caso ainda não as tenha visto:

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.

Resumo de Negócios

Tópico	Descrição
Escopo	Lead de vendas em todas as regiões
Cenários	Um cliente potencial solicita informações sobre um produto. O concessionário entra em contato com o cliente potencial e atualiza o status da oportunidade de venda.
Principais funcionalidades	Enviar oportunidades de venda para o CRM do concessionário. Receber atualizações de status das oportunidades de venda do CRM.
Processos de negócio suportados	Gestão de leads
Benefícios para concessionários	Receber rapidamente oportunidades de venda e fornecer respostas rápidas aos clientes potenciais. Não é necessário acessar o BOSSWeb para gerenciar oportunidades de venda.
Benefícios para a BRP	Potencialmente, os concessionários farão mais vendas.

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 BRP	CRM	V4 - América do Norte	Um pouco mais
Transação com BRP			Um pouco mais ainda

Autenticação

A API usa Autenticação de Aplicações.

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/v4
Produção	https://cloud-api.brp.com/dcp/v4

Recurso: Oportunidade de Venda

O recurso Oportunidade de Venda fornece informações básicas sobre oportunidades de venda da BRP. Ele inclui informações sobre o consumidor, a unidade de interesse e o status do consumidor.

Representação JSON

{
  "sales_opportunity_id": "00Q6s000001TQcaEAG",
  "dealer_no": "0000695896",
  "language": "en",
  "consumer": {
    "first_name": "Mike3",
    "last_name": "Debrush",
    "culture_code": "en-US",
    "phone_no": "819 532-1234",
    "mobile_no": "819 532-1278",
    "email": "[email protected]",
    "address": {
      "street": "458 Main Street",
      "city": "Orlando",
      "state": "FL",
      "country": "US",
      "postal_code": "12562-12345"
    }
  },
  "product_interest": {
    "category": "Contest/Events/Demo",  
    "model": "SSV all track",
    "brand": "canam_side_by_side"
  },
  "status": [
    {
      "code": "new",
      "set_on": "2025-05-20T19:19:00Z"
    }
  ],
  "model_number": "0008HSB00",
  "comments": "I want a tough SSV",
  "assignment_date": "2025-05-20T15:19:00Z",
  "start_date": "2025-05-20T19:19:00Z",
  "byo_uri": "https://can-am.brp.com/off-road/ca/fr/configuration-et-prix/app.html?platform=SSV_SSP_2_MAX&package=4X4_X&unitid=0008HSB00",
  "campaign_name": "",
  "event_description": "SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN",
  "intent_to_buy": "4-6 months",
  "lead_score": "Medium",
  "questions_answers" : [
    { "question": "What are you looking for in a SSV?",
      "answer": "Sun and fun" 
    },
    { "question": "Who will use the SSV?",
      "answer": "Me and my dog" 
    }
  ],
  "ownership": {
    "brand": "Polaris RZR Trail",
    "trade_in": 1000.00
    }
}

Propriedades

Property	Type	Definition	Notes
sales_opportunity_id	string	Sales opportunity identifier	Length:18
dealer_no	string	The BRP dealer number is assigned to the sales opportunity.	Length:10
language	string	The language of the customer in ISO language code (ISO-639-1)	Format xx
consumer	object	consumer information
consumer .first_name	string	Consumer's first name	Length:40
consumer .last_name	string	Consumer's last name	Length:40
consumer .culture_code	string	The communication language of the consumer in the ISO language code (ISO-639-1 + ISO 3166-1)	Length:80
consumer .phone_no	string	Consumer phone number	Length:40
consumer .mobile_no	string	Consumer mobile phone	Length:40
consumer .email	string	Consumer email	Length:80
consumer .address	object	consumer address
consumer.address .street	string	Address of the consumer	Length:255
consumer.address .city	string	City of the consumer	Length:40
consumer.address .state	string	Code that uniquely identifies a province/state in a country. 👉 The property contains the second part of the subdivision code of the ISO 3166-2 format. For example, the complete subdivision code for Oregon is "US-OR". The property contains "OR".	Length:2
consumer.address .country	string	Code that uniquely identifies a country, in ISO 3166-1 format.	Length:2
consumer.address .postal_code	string	Postal code of the consumer.	Length:20
product_interest	object	product interest selected by the consumer
product_interest .category	string	The category of the product in which the consumer is interested. Free text field.	Max Length:100
product_interest .model	string	Model of the product in which the consumer is interested.	Max Length:100
product_interest .brand	string	The product brand the consumer is interested in. canam_atv canam_offroad canam_roadster canam_side_by_side lynx seadoo_pontoon seadoo_watercraft skidoo	Max Length:100
status*	list of objects	List of statuses attached to the sales opportunity
status.code*	string	Status code of the consumer new contacted unit_sold abandoned
status.set_on*	datetime	Date and time at which the status has been set, in ISO 8601 format.	Format: YYYY-MM-DDTHH:MM:SSZ
model_no	string	The model in which the customer is interested.	9 characters, format 000xxxx00
comment	string	Any comments left by the user.	Max Length:4000
assignment_date	string	Date and time the lead was assigned to the dealer, in UTC. In ISO 8601 format.	Format: YYYY-MM-DDTHH:MM:SSZ
start_date	string	Date and time when the 2-hour timer started, in UTC. In ISO 8601 format.	Format: YYYY-MM-DDTHH:MM:SSZ
byo_uri	string	URI (Uniform Resource Identifier) to the Build-Your-Own prepared by the customer	Max Length:255
campaign_name	string	Name of the promotion campaign linked to the customer request.	Max Length:50
event_description	string	The event description is created to track the campaign results. Each event description respects a nomenclature and has the following information: - Unique ID - Source (e.g. Web, Facebook...) - Category (e.g. Contest, Promo, Demo, Request a quote...) - Free-text (optional) for having more info Example of an event description: SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN	Max Length:100
intent_to_buy	string	Indicates the customer’s intention to buy a unit soon. Possible values: 0-3 months 4-6 months 7-12 months More than one year I don't know yet I don't plan to buy one I have already pre-purchased one	Max Length:50
lead_score	string	Indicates the lead score based on information available to BRP. Low Medium High 👉 Can be empty	Max Length:50
questions_answers	list of objects	List of questions and answers.
questions_answers. question	string	Free text used by BRP’s marketing team to ask a question to the potential customer.	Max Length:255
questions_answers. answer	string	Customer response, free text.	Max Length:255
ownership	object	Information on the unit currently owned by the customer.
ownership.brand	string	Brand of the unit.	Max Length:50
ownership.trade_in	number	The trade-in value of the unit.	Precision: 0.01

Recurso: Atualização de Oportunidade de Vendas

Um CRM usa o recurso de Atualização de Oportunidade de Vendas para enviar atualizações de status para oportunidades de vendas.

Representação JSON

{
  "sales_opportunity_id": "00Q6s000001WNwGEAW",
  "status": [
    {
      "code": "contacted",
      "set_on": "2020-06-13T14:48:12Z"
    }
  ]
}

Propriedades

Propriedade	Tipo	Definição	Notas
sales_opportunity_id	string	Identificador da oportunidade de venda	Comprimento:18
status*	lista de objetos	A lista de status associados à oportunidade de venda
status.code*	string	Código de status do consumidor novo contatado unidade_vendida abandonado
status.set_on*	datetime	Data e hora em que o status foi definido, no formato ISO 8601.	Formato: AAAA-MM-DDTHH:MM:SSZ

Limitações e Restrições

Métodos de Autenticação do CRM

A API de Oportunidades de Vendas suporta dois métodos de autenticação:

Autenticação OAuth 2.0 usando credenciais de cliente, como usado pela API de Autenticação de Aplicativos.

Assinatura de webhook usando SHA256.

❗ A API de Oportunidades de Vendas não suporta e não suportará outros métodos de autenticação ❗

Consulte a seção Informações Técnicas sobre Métodos de Autenticação para mais informações.

Requisitos de Segurança

Toda a comunicação deve ocorrer por HTTPS.

Os endpoints de token OAuth e os endpoints de callback devem usar HTTPS.

TLS 1.2 ou superior deve ser suportado.

Os certificados SSL devem ser válidos e emitidos por uma Autoridade Certificadora (CA) confiável.

Certificados autoassinados não são permitidos em ambientes de produção.

Compreendendo a Oportunidade de Vendas

Visão do Processo em Alto Nível

O processo de leads de vendas e oportunidades de vendas em nível macro é mostrado abaixo.

O processamento de leads de vendas é realizado pelo Sistema de Gestão de Leads (LMS) da BRP.

Um potencial cliente solicita informações sobre um produto por meio de uma das plataformas de comunicação:

Site da BRP brp.com.

Um site de mídia social, como o Facebook.

Um aplicativo, como o BRP Go.

Um aplicativo específico para eventos, por exemplo, durante o Clube da BRP.

O lead de vendas é enviado para o Sistema de Gestão de Leads (LMS) da BRP.

O LMS valida o lead de vendas. Se o lead de vendas for válido, o LMS tenta encontrar o revendedor mais próximo que ofereça a linha de produtos solicitada pelo potencial cliente.

Se nenhum for encontrado, o lead de vendas é descartado.

Se um revendedor for encontrado, o lead de vendas se torna uma oportunidade de venda.

Se um revendedor for encontrado, a oportunidade de venda é enviada ao BOSSWeb.

Se o revendedor tiver um CRM certificado pelo DCP e tiver ativado a integração com o LMS (consulte a seção Configuração do CRM no BOSSWeb abaixo), a oportunidade de venda é enviada para o CRM do revendedor.

Se o revendedor não tiver um CRM certificado pelo DCP ou se a integração com o LMS não estiver ativa, nenhuma ação é tomada.

Se a oportunidade de venda for enviada corretamente ao CRM do revendedor, o LMS envia um SMS e um e-mail ao revendedor com as informações da oportunidade de venda.

O revendedor entra em contato com o potencial cliente para discutir a solicitação.

O revendedor atualiza o status da oportunidade de venda em seu CRM.

Se a integração do LMS estiver ativa, o CRM envia o status da oportunidade de venda ao LMS. O status da oportunidade de venda é enviado ao BOSSWeb.

Caso contrário, o revendedor atualiza o status da oportunidade de venda no BOSSWeb.

Configuração de CRM no BOSSWeb

Para que o LMS envie oportunidades de vendas para o CRM do concessionário, o concessionário deve primeiro ativar a integração com o LMS.

👉Você pode compartilhar este documento com seus concessionários.

Configurando seu CRM certificado pela BRP para receber leads de vendas BRP.pdf

A integração do LMS é gerenciada no BOSSWeb em Administração -> Concessionária, conforme mostrado abaixo.

O concessionário clica no link Termos e Condições indicado pela seta verde na imagem, e a página mostrada abaixo é exibida.

O concessionário marca a caixa de seleção e escolhe uma das Ferramentas de CRM listadas.

❗❗ O concessionário deve selecionar o CRM que está em operação em sua concessionária ❗❗

Se o concessionário selecionar um CRM aleatório porque não possui um CRM certificado pelo DCP (como frequentemente vemos), a integração do LMS não funcionará❗

O concessionário clica em Salvar para habilitar a integração com o LMS, e o CRM do concessionário começa a receber oportunidades de vendas.

👉 A qualquer momento, o concessionário pode retornar à página de Termos e Condições e desmarcar a caixa de seleção para desabilitar a integração com o LMS.

Nesse caso, o CRM deixa de receber oportunidades de vendas.

Configuração de Endpoint do CRM

O processo para enviar uma oportunidade de vendas para um CRM é mostrado abaixo.

Seu CRM deve fornecer um endpoint para que a API de Oportunidade de Vendas envie oportunidades de vendas.

O LMS encontra um revendedor para enviar a oportunidade de vendas e recupera o CRM configurado pelo revendedor para a integração com o LMS.

A oportunidade de vendas é enviada para a API de Oportunidade de Vendas, incluindo o nome do CRM na consulta.

A API de Oportunidade de Vendas verifica em sua configuração o CRM para o qual a oportunidade de vendas deve ser enviada.

Se o CRM não for encontrado, um erro é retornado ao LMS.

Se o CRM for encontrado, a configuração do CRM é recuperada.

A API de Oportunidade de Vendas determina se o CRM usa Autenticação de Aplicação ou uma assinatura de webhook.

Se o CRM usar Autenticação de Aplicação, a API de Oportunidade de Vendas chama o endpoint de autenticação do CRM para obter um token Bearer.

Se o CRM usar uma assinatura de webhook, a API de Oportunidade de Vendas calcula a assinatura e a adiciona ao payload.

A API de Oportunidade de Vendas chama o endpoint do CRM usando as credenciais configuradas para enviar a oportunidade de vendas.

O CRM confirma o recebimento da oportunidade de vendas. Se ocorrer um erro, ele é retornado ao LMS.

O revendedor atualiza o status da oportunidade de vendas em seu CRM. O CRM envia o status para a API de Oportunidade de Vendas.

A API de Oportunidade de Vendas envia o status ao LMS.

Para cada CRM certificado pelo DCP, a API de Oportunidade de Vendas requer os seguintes parâmetros:

O endpoint a ser chamado para enviar a oportunidade de vendas.

Um nome de usuário (ID do cliente).

Uma senha (segredo do cliente).

O endpoint a ser chamado para obter um token de acesso OAuth 2.0 Bearer, caso o CRM utilize autenticação OAuth 2.0.

❗❗ A API de Oportunidade de Vendas requer que uma autenticação baseada em token OAuth 2.0 ou uma assinatura de webhook seja utilizada pelo CRM para o endpoint fornecido ❗❗

Tratamento de Erros

Se o seu CRM detectar um erro ao processar a oportunidade de vendas, ele deve retornar uma faixa de códigos de status padrão RFC 9110 e um payload JSON descrevendo o erro.

Você pode consultar a seção Código de status da resposta para obter diretrizes.

O payload JSON de erro deve ser baseado no payload descrito na seção Payload de Resposta . Seu payload deve conter, no mínimo, um campo de texto descrevendo o erro.

Resumo do Que Você Deve Fornecer

Quando você começar a trabalhar com a API de Oportunidade de Vendas, deverá fornecer as informações listadas abaixo.

Para fornecer as informações:

Baixe o arquivo Excel.

Preencha a planilha correspondente ao método de autenticação usado pelo seu CRM.

Envie o arquivo por e-mail para [email protected] ou anexe-o ao seu ticket de certificação da Jira da API de Oportunidade de Vendas.

Modelo de Configuração de Oportunidade de Vendas.xlsx

Ambiente	Método de Autenticação	Informação
Teste	Todos	A URL usada para enviar as oportunidades de venda ao seu CRM no ambiente de teste.
Teste	OAuth	Client ID
Teste	OAuth	Client Secret
Teste	OAuth	URL usada para obter um token Bearer.
Teste	Assinatura	App Secret para assinar o payload.
Teste	Todos	Um ou mais números de concessionárias BRP válidos para enviar oportunidades de venda.
Produção	Todos	A URL usada para enviar as oportunidades de venda ao seu CRM no ambiente de teste.
Produção	OAuth	Client ID
Produção	OAuth	Client Secret
Produção	OAuth	URL usada para obter um token Bearer.
Produção	Assinatura	App Secret para assinar o payload.

Informações Técnicas sobre Métodos de Autenticação

A API de Oportunidade de Vendas suporta dois métodos de autenticação:

Autenticação OAuth 2.0 usando credenciais de cliente, como usado pelo DCP API de Autenticação de Aplicativos.

Assinatura de webhook usando SHA256.

❗ A API de Oportunidades de Vendas não suporta e não suportará outros métodos de autenticação ❗

Autenticação de Aplicação (OAuth 2.0)

Suponha que o seu CRM use um método de Autenticação de Aplicação (OAuth 2.0) para autorizar requisições da API de Oportunidades de Vendas ao seu CRM. Nesse caso, sua plataforma de CRM deve expor um endpoint de token OAuth 2.0 compatível, suportando o tipo Client Credentials Grant.

A API de Oportunidades de Vendas usará esse endpoint para obter um token Bearer, que será usado no cabeçalho Authorization das chamadas subsequentes da API para o seu sistema CRM.

Requisitos

Você deve fornecer:

URL de Token OAuth2 (HTTPS) Um endpoint HTTPS publicamente acessível que suporte o client credentials grant, um para os ambientes de teste e produção.

Credenciais de Cliente para ambos os ambientes de teste e produção.

Um ID de cliente

Um segredo do cliente

Formato de Resposta do Token A resposta deve retornar um access_token válido e um campo expires_in em formato JSON.

Obter um Token

Obtenha o token Bearer de acesso necessário para chamar o endpoint do CRM.

POST

{Your OAuth2 Token Endpoint}

curl --request POST 'https:{Your OAuth2 Token Endpoint}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=REPLACE_ME_CLIENT_ID' \
--data-urlencode 'client_secret=REPLACE_ME_CLIENT_SECRET'

Melhores Práticas de Segurança

O endpoint de token deve usar HTTPS

Os tokens devem ser limitados por tempo (expires_in) e não de longa duração

Evite expor credenciais sensíveis em logs ou mensagens de erro

Especificação do Endpoint de Payload

Seu sistema deve expor um endpoint HTTP(S) que aceite payloads JSON enviados pela API de Oportunidade de Vendas. Todas as solicitações para esse endpoint serão autenticadas usando um token Bearer previamente obtido por meio do seu serviço de token OAuth2.

Autenticação

Todas as solicitações incluirão o token Bearer no Autorização cabeçalho:

Authorization: Bearer {access_token}

Seu sistema deve validar o token antes de processar o payload.

Requisitos do Endpoint

URL: [seu_endpoint_url] (por exemplo, https://api.external-system.com/data/receive)

Método: POST

Content-Type: application/json

Autenticação: Bearer Token (Fluxo de Credenciais do Cliente OAuth2)

Payload de Resposta

Seu endpoint de CRM deve usar a faixa padrão de códigos de status da RFC 9110:

2xx (Sucesso): A solicitação foi recebida, compreendida e aceita com sucesso

4xx (Erro do Cliente): A solicitação contém sintaxe inválida ou não pode ser atendida

5xx (Erro do Servidor): O servidor falhou em atender a uma solicitação aparentemente válida

Seu endpoint deve retornar pelo menos os seguintes códigos de status de resposta.

Código de Status	Descrição
200 OK	Indica que a requisição foi bem-sucedida e a oportunidade de vendas está sendo processada. Nenhum payload é retornado.
400 Bad Request	Indica que o servidor não pode ou não irá processar a requisição devido a algo que é percebido como um erro do cliente (por exemplo, sintaxe de requisição malformada, estrutura inválida da mensagem da requisição ou roteamento enganoso). IMPORTANTE: O payload da resposta deve indicar os campos do payload da requisição ou parâmetros de consulta que estão incorretos.
401 Unauthorized	Indica que a requisição não foi aplicada porque não possui credenciais de autenticação válidas.
404 Not Found	Indica que o servidor não conseguiu encontrar os objetos solicitados, por exemplo, o concessionário não foi encontrado.
500 Internal Server Error	Indica que o servidor está ciente de que cometeu um erro ou é incapaz de executar o método solicitado.
504 Gateway Timeout	Indica que a API não recebeu uma resposta em tempo hábil de um servidor upstream que precisava acessar para completar a requisição.

Para códigos de status de erro 4xx e 5xx, um payload de resposta deve ser retornado para fornecer informações sobre o erro. O payload de resposta utiliza a estrutura mostrada na tabela abaixo.

Propriedade	Tipo	Definição
title	string	Código que identifica o erro ou frase descritiva Um de unauthorized internal_error not_found bad_request
message	string	Uma descrição do erro.

Por exemplo, se a oportunidade de venda for para um revendedor não encontrado no seu CRM, será retornado o seguinte payload de resposta e o código de status 404.

{
    "title": "not_found",
    "message": "Dealer 0000690006 not found"
}

Segurança

O endpoint deve usar HTTPS

O token Bearer deve ser validado com segurança

Todos os payloads devem ser registrados com segurança e tratados de acordo com sua política de governança de dados.

Assinatura do Webhook

A abordagem de assinatura do webhook é simples.

Para garantir a autenticidade e integridade dos payloads enviados da API de Oportunidade de Vendas para sua aplicação CRM, nós os assinamos com um HMAC usando sua chave de aplicação exclusiva.

A chave de aplicação que você fornece é usada para calcular uma assinatura sobre todo o payload usando o algoritmo SHA-256.

A assinatura é então adicionada ao cabeçalho no campo X-Hub-Signature-256 antes de o payload ser enviado ao seu CRM.

Quando você receber o payload, use a mesma chave de aplicação e o algoritmo SHA-256 para calcular a assinatura e compará-la com a que está no X-Hub-Signature-256 campo de cabeçalho.

Se a assinatura corresponder, você pode prosseguir com o processamento da oportunidade de venda. Se não corresponder, rejeite o payload e retorne um erro 401 Unauthorized.

Definição da Chave de Aplicação

A chave de aplicação (também chamada de “segredo de assinatura”) é uma cadeia aleatória gerada com segurança e associada ao seu CRM.

Formato	String hexadecimal de 64 caracteres. Pelo menos 32 bytes (256 bits), mais longo é melhor. Exemplo: f7d9a47e143a4b298b819f48b3b77e4b24ae746f55c7c35b2c09c1ec3adbe7c2
Segurança	Trate sua chave de aplicação como uma senha. Armazene-a com segurança no seu servidor. Nunca a exponha em código do lado do cliente ou a terceiros. Aleatoriedade criptograficamente segura. Ela NÃO deve ser uma senha ou frase legível por humanos. Ela NÃO deve ser uma chave curta ou string fácil de adivinhar.

A chave da aplicação pode ser gerada usando as bibliotecas disponíveis.

import secrets

key = secrets.token_hex(32)  # 64-char hex string (32 bytes) )

Assinatura de Payload

Calculamos o HMAC do corpo bruto da requisição usando SHA-256 e a chave do seu aplicativo como segredo.

A assinatura resultante é enviada no X-Hub-Signature-256 cabeçalho.

X-Hub-Signature-256: sha256=<signature>

<signature> é a representação hexadecimal em minúsculas do digest HMAC.

Abaixo está um exemplo do cálculo da assinatura com um payload de oportunidade de vendas de exemplo e uma chave de aplicação aleatória.

const crypto = require('crypto');

// Application key (hexadecimal string, must match the receiver's expectation)
const appKeyHex = 'f7d9a47e143a4b298b819f48b3b77e4b24ae746f55c7c35b2c09c1ec3adbe7c2';

// Sales Opportunity payload
const payloadObj = { "sales_opportunity_id": "yVg0i5ULZnCJ5IKi8k", "language": "en", "consumer": { "first_name": "John", "last_name": "Doe", "culture_code": "en-US", "phone_no": "555 555-1234", "mobile_no": "555 555-1278", "email": "[email protected]", "address": { "street": "123 Random Street", "city": "Orlando", "state": "FL", "country": "US", "postal_code": "12562-12345" } }, "product_interest": { "category": "Contest/Events/Demo", "model": "SSV all track", "brand": "canam_side_by_side" }, "status": [{ "code": "new", "set_on": "2025-05-20T19:19:00Z" }], "model_number": "0008HSB00", "comments": "I want a tough SSV", "assignment_date": "2025-05-20T15:19:00Z", "start_date": "2025-05-20T19:19:00Z", "byo_uri": "https://can-am.brp.com/off-road/ca/fr/configuration-et-prix/app.html?platform=SSV_SSP_2_MAX&package=4X4_X&unitid=0008HSB00", "campaign_name": "", "event_description": "SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN", "intent_to_buy": "4-6 months", "lead_score": "Medium", "questions_answers": [{ "question": "What are you looking for in a SSV?", "answer": "Sun and fun" }, { "question": "Who will use the SSV?", "answer": "Me and my dog" }], "ownership": { "brand": "Polaris RZR Trail", "trade_in": 1000 }, "customer_no": "0000691232" };

const rawBody = Buffer.from(JSON.stringify(payloadObj), 'utf8');

// Compute the HMAC SHA256 signature (hex digest)
const signature = crypto
    .createHmac('sha256', appKeyHex)
    .update(rawBody)
    .digest('hex');

// Prepare the signature header
const headers = {
    'Content-Type': 'application/json',
    'X-Hub-Signature-256': `sha256=${signature}`
};

// signature = "1f91bc0b914dd833968daff615988dae63ea177b9a52fb7f5268df20f9e6a824"

console.log(signature);

Validação do Payload

Para validar a assinatura do payload recebido, seu CRM deve executar estas etapas:

Recupere sua chave de aplicação (como um array de bytes).

Leia o corpo bruto enviado pelo nosso CRM.

Calcule o digest HMAC-SHA256 do corpo usando sua chave de aplicação.

Compare o digest calculado com o valor no cabeçalho X-Hub-Signature-256 (após remover o prefixo sha256=).

Abaixo está um exemplo de verificação de assinatura, acompanhado por um payload de oportunidade de vendas de exemplo e uma chave de aplicação gerada aleatoriamente.

const crypto = require('crypto');

// --- Payload and key (same as signature creation) ---
const payloadObj = { "sales_opportunity_id": "yVg0i5ULZnCJ5IKi8k", "language": "en", "consumer": { "first_name": "John", "last_name": "Doe", "culture_code": "en-US", "phone_no": "555 555-1234", "mobile_no": "555 555-1278", "email": "[email protected]", "address": { "street": "123 Random Street", "city": "Orlando", "state": "FL", "country": "US", "postal_code": "12562-12345" } }, "product_interest": { "category": "Contest/Events/Demo", "model": "SSV all track", "brand": "canam_side_by_side" }, "status": [{ "code": "new", "set_on": "2025-05-20T19:19:00Z" }], "model_number": "0008HSB00", "comments": "I want a tough SSV", "assignment_date": "2025-05-20T15:19:00Z", "start_date": "2025-05-20T19:19:00Z", "byo_uri": "https://can-am.brp.com/off-road/ca/fr/configuration-et-prix/app.html?platform=SSV_SSP_2_MAX&package=4X4_X&unitid=0008HSB00", "campaign_name": "", "event_description": "SD054_FB_CONTEST___ECOMM-WIN-A-PFD-US-EN", "intent_to_buy": "4-6 months", "lead_score": "Medium", "questions_answers": [{ "question": "What are you looking for in a SSV?", "answer": "Sun and fun" }, { "question": "Who will use the SSV?", "answer": "Me and my dog" }], "ownership": { "brand": "Polaris RZR Trail", "trade_in": 1000 }, "customer_no": "0000691232" };

// Convert to compact JSON as sent (matches JSON.stringify in Node.js and compact Python)
const rawBody = Buffer.from(JSON.stringify(payloadObj), 'utf8');

// Secret key
const appKeyHex = 'f7d9a47e143a4b298b819f48b3b77e4b24ae746f55c7c35b2c09c1ec3adbe7c2';

// Calculate expected signature
const expectedSig = crypto.createHmac('sha256', appKeyHex).update(rawBody).digest('hex');

// What would be in the X-Hub-Signature-256 header (from the siganture example)
const headerSignature = 'sha256=1f91bc0b914dd833968daff615988dae63ea177b9a52fb7f5268df20f9e6a824';

// --- Simulate receiver: extract signature from header and verify ---
const receivedHeader = headerSignature; // From header in real request
const providedSig = receivedHeader.split('=')[1];

const expectedBuf = Buffer.from(expectedSig, 'hex');
const providedBuf = Buffer.from(providedSig, 'hex');

const isValid = expectedBuf.length === providedBuf.length &&
    crypto.timingSafeEqual(expectedBuf, providedBuf);

if (isValid) {
    console.log('Signature is valid!');
} else {
    console.log('Signature is INVALID!');
}

❗ Se a assinatura calculada não corresponder à assinatura recebida, retorne um status 401 Unauthorized e registre o erro para auxiliar no diagnóstico ❗

Referência da API

Send Opportunity Status

Send a sales opportunity processing status.

POST

/dealer/{dealer_no}/opportunity/update

curl --request POST 'https://cloud-api.brp.com/dcp/v4/dealer/0000690885/opportunity/update' \
--header 'Authorization: Bearer REPLACE_ME'
--data '
{
  "sales_opportunity_id": "00Q4R00001dBg21",
  "status": [
    {
      "code": "contacted",
      "set_on": "2024-07-25T14:48:12Z"
    }
  ]
}'

Tratamento de Erros

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

400 Solicitação Inválida

O código de status 400 é normalmente encontrado durante o desenvolvimento e a 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, e os mais comuns estão listados na tabela abaixo.

Resposta	Resolução
Retornado se uma propriedade estiver faltando. { "status": 400, "errors": [ { "code": "schema_error", "title": "Provided payload does not conform to the expected JSON Schema", "meta": [ { "keyword": "enum", "dataPath": ".status[0].code", "schemaPath": "#/properties/status/items/properties/code/enum", "params": { "allowedValues": [ "contacted", "unit_sold", "abandoned" ] }, "message": "should be equal to one of the allowed values" } ] } ] }	Adicione a propriedade faltante ao payload.
Retornado se uma data tiver um formato inválido. { "status": "400", "id": "rrt-0eb1275f0947eeef3-d-ea-3040725-18600050-2", "title": "bad_request", "meta": { "service": "01", "detail": "request validation failed", "payload": { "details": [ { "message": "[Path '.status[0].set_on'] String \"25-11-2023T15:18:58Z\" is invalid against requested date format(s) [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,12}Z]: []" } ] } } }	Altere o formato da string de data para corresponder ao formato esperado no payload.

401 Não autorizado

O código de status de erro 401 Unauthorized é retornado quando você tenta chamar a API com um access_token.

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

Retornado quando o ID da oportunidade de vendas recebido no payload Disposição da Oportunidade de Vendas é desconhecido.

Testes de Certificação

Fases

Os testes são realizados em três fases.

Fase 1: O objetivo da primeira fase é validar seu CRM fazendo chamadas diretas, ou seja, sem passar pela API de Oportunidades de Vendas. Nesta fase, a disposição não é verificada. Chamadas são feitas para verificar o tratamento de erros do seu CRM.

Fase 2: Durante esta fase, oportunidades de venda são enviadas ao seu CRM pela API de Oportunidades de Vendas, e seu CRM envia disposições chamando o Enviar Status da Oportunidade.

Fase 3: A última fase é enviar oportunidades de venda ao seu CRM usando o fluxo completo, desde um lead de vendas no Salesforce até o seu CRM. Seu CRM envia disposições que são verificadas no Salesforce.

👉 As etapas específicas do teste estão listadas na seção ValidaçõesValidações abaixo.

Arquitetura de Testes

Esta seção apresenta a arquitetura de testes para cada fase.

👉 Para realizar testes, você deve identificar, para cada fase, um revendedor BRP válido em seu ambiente de teste que será usado para enviar a oportunidade de venda.

Fase 1

Durante a fase 1, consultas do Postman são usadas para chamar seu CRM para enviar oportunidades de venda, mas também para enviar payloads inválidos para validar o tratamento de erros do seu CRM.

Consultas do Postman são usadas para validar o método de autenticação do seu CRM.

Se o seu CRM usa a Autenticação de Aplicação (OAuth 2.0)aplicação, chamadas serão feitas para recuperar um token Bearer e outras chamadas serão feitas para criar erros.

Se o seu CRM usar o método Assinatura do Webhookaaa, as chamadas serão feitas com uma assinatura inválida.

Consultas são usadas para enviar uma oportunidade de vendas, e outras chamadas são usadas para enviar payloads inválidos.

Fase 2

Na fase 2, oportunidades de vendas são enviadas por consultas do Postman para o seu CRM através da API de Oportunidade de Vendas.

Seu CRM também pode enviar uma atualização de status da oportunidade de vendas (disposition) para a API de Oportunidade de Vendas, que é então encaminhada para um servidor simulado no Postman.

Fase 3

Na fase 3, leads de vendas são enviados para o Salesforce via consultas do Postman. O Salesforce então envia a oportunidade de vendas para o seu CRM e recebe uma atualização de status.

Requisitos de DSP

Requisitos Funcionais

ID	Tipo	Requisito
1	Obrigatório	Seu CRM deve fornecer um dos métodos de autenticação descritos naInformações Técnicas de Métodos de Autenticação seção.
2	Obrigatório	Seu CRM deve exibir todas as propriedades da oportunidade de vendas na interface do usuário. 👉 Se o seu CRM não tiver algumas das propriedades, elas podem ser agrupadas e exibidas em um campo de texto.
3	Obrigatório	Ao enviar a atualização de status da oportunidade de vendas, mapeie o estado do seu CRM para um dos estados listados naRecurso: Atualização de Oportunidade de Vendas 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.

Testes da Fase 1

Os testes listados na tabela abaixo devem ser concluídos no ambiente de testes antes que você possa iniciar os testes da fase 2.

Autenticação de Aplicações (OAuth 2.0)

ID	Teste	Resultado Esperado
1	Solicitar um token Bearer.	O CRM retorna um token Bearer válido.
2	Solicitar um token Bearer sem client_id.	O CRM retorna o status de resposta 401.
3	Solicitar um token Bearer com um client_id inválido.	O CRM retorna o status de resposta 401.
4	Enviar uma oportunidade de venda com um token Bearer válido.	O CRM retorna o status 200.
5	Enviar uma oportunidade de venda com um token Bearer inválido.	O CRM retorna o status de resposta 401.
6	Enviar uma oportunidade de venda com um número de concessionária inválido.	O CRM retorna o status de resposta 404.
7	Enviar uma oportunidade de venda com um payload inválido.	O CRM retorna o status de resposta 400.

Assinatura de Webhook

ID	Teste	Resultado Esperado
1	Enviar uma oportunidade de venda com uma assinatura válida.	O CRM retorna o status 200.
2	Enviar uma oportunidade de venda com uma assinatura inválida.	O CRM retorna um status de resposta 401.
3	Enviar uma oportunidade de venda com um número de revendedor inválido.	O CRM retorna um status de resposta 404.
4	Enviar uma oportunidade de venda com um payload inválido.	O CRM retorna um status de resposta 400.

Testes da Fase 2

Os testes listados na tabela abaixo devem ser concluídos no ambiente de teste antes que você possa iniciar os testes da fase 3.

ID	Teste	Resultado Esperado
1	Recebeu uma oportunidade de vendas.	Exiba a oportunidade de vendas recebida no seu CRM. Forneça uma captura da interface do usuário que mostre todas as informações disponíveis da oportunidade de vendas.
2	Enviar atualização de status da oportunidade.	Atualize o estado da oportunidade de vendas no CRM e verifique se a alteração é enviada para a API.

Testes da Fase 3

Os testes listados na tabela abaixo devem ser concluídos no ambiente de teste antes que você possa iniciar a fase piloto com o concessionário.

ID	Teste	Resultado Esperado
1	Recebeu uma oportunidade de venda.	Exibir a oportunidade de venda recebida no seu CRM. Forneça uma captura de tela da interface do usuário que mostre todas as informações disponíveis da oportunidade de venda.
2	Enviar atualização do status da oportunidade.	Atualize o estado da oportunidade de venda no CRM e verifique que a alteração é enviada para a API.

Piloto do Concessionário

A tabela abaixo descreve os parâmetros do piloto do concessionário e suas respectivas validações.

Parâmetro	Valor
Ambiente	Produção
Número de concessionários	1 a 3
Duração	2 semanas
Validação 1	Verifique se as oportunidades de venda enviadas pela BRP estão disponíveis no CRM.
Validação 2	Verifique se a BRP recebeu atualizações de status sobre a oportunidade de venda.

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 Oportunidade de Vendas. Este ambiente Postman contém variáveis usadas pelas consultas e configuradas para conectar ao ambiente de teste.

Teste - Ambiente DSP

Coleções

A coleção CRM - Oportunidade de Vendas contém exemplos de chamadas de API para enviar uma disposição de oportunidade de vendas.

Há também exemplos de chamadas diretas para seus endpoints CRM para ajudar a testar a integração.

Há um exemplo para um CRM usando autenticação oAuth e outro para o método de assinatura.

👉 Para usar as consultas, você deve definir as variáveis da coleção com as informações do endpoint do seu CRM.

CRM - Oportunidade de Vendas

Registro de Alterações

Revisão 1.0

Added

Primeira versão