API de campanhas

35 min

Introdução

A API de Campanhas permite que seus concessionários solicitem e visualizem detalhes de campanhas/boletins de garantia por meio de seu DMS para um número específico de identificação do veículo (VIN).

Quando um cliente leva uma unidade para manutenção ou reparo, uma parte importante das atividades do concessionário é verificar se boletins de garantia e segurança são aplicáveis à unidade. Os boletins de garantia e segurança podem ser encontrados usando o VIN da unidade. Ao criar a ordem de serviço, o técnico procura por boletins aplicáveis à unidade. Se boletins forem encontrados, os trabalhos e peças correspondentes podem ser adicionados à ordem de serviço.

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:

Comece Aqui Com Leitura Obrigatória!
Informações Técnicas para informações técnicas gerais sobre a API e os 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.

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

Recurso: Campanhas

O recurso Campanhas fornece informações sobre um número de série específico (VIN) e algumas informações sobre as campanhas relacionadas

Representação JSON

{
  "vin": "2BPSCEKCXKV000009",
  "usage_descr": "Personal/Recreational",
  "target_market_descr": "Canada, US",
  "product_code": "000CEKC00",
  "platform_descr": "REV-G4",
  "package_descr": "SP",
  "model_year": "2019",
  "model_descr": "Summit",
  "length": "154\" (3923 mm)",
  "is_cross_border": false,
  "engine_type": "850 E-TEC",
  "comments": "",
  "color_descr": "Black",
  "campaigns": [
    {
      "type_descr": "Regular",
      "period_valid_to": "2022-01-31",
      "period_valid_from": "2019-01-22",
      "is_claimed": true,
      "campaign_no": "0010",
      "campaign_descr": "ENGINE COOLANT OUTLET HOSE LEAK",
      "bulletin_no": "2019-9",
      "articles": [
        {
          "last_publish_date": "2019-03-11T17:10:42.000Z",
          "content_type": "PDF",
          "article_url": "https://brp--qauat.my.salesforce.com/kAA0c000000fxSR?lang=en_US",
          "article_no": "000136062",
          "article_id": "kaA0c000000L42WEAS",
          "article_descr": "SKI-DOO 2019-9 Engine Coolant Outlet Hose Leak_136062_WCN11Y019S01_en"
        }
      ]
    },
    {
      "type_descr": "Safety",
      "period_valid_to": "9999-12-31",
      "period_valid_from": "2019-07-02",
      "is_claimed": false,
      "campaign_no": "0012",
      "campaign_descr": "FUEL INJECTOR POTENTIAL LEAK",
      "bulletin_no": "2019-11",
      "articles": [
        {
          "last_publish_date": "2019-07-03T16:52:52.000Z",
          "content_type": "PDF",
          "article_url": "https://brp--qauat.my.salesforce.com/kAA0c000000KzTR?lang=en_US",
          "article_no": "000136589",
          "article_id": "kaA0c000000L48jEAC",
          "article_descr": "SKI-DOO 2019-11 Fuel Injector - Potential Leak_136589_WSC11Y019S02_en"
        },
        {
          "last_publish_date": "2019-07-03T15:07:14.000Z",
          "content_type": "URL",
          "article_url": "https://brp--qauat.my.salesforce.com/kA90c000000004S?lang=en_US",
          "article_no": "000136553",
          "article_descr": "Ski-Doo Fuel Injector Bolts Replacement"
        }
      ]
    }
  ],
  "brand_descr": "Ski-Doo Snowmobile"
}

Propriedades

Propriedade	Tipo	Definição	Notas
serial_no	string	Número de série da unidade	Comprimento máximo:18
usage_descr†	string	Descreve o uso da unidade	Comprimento máximo:30
product_code	String	Código que identifica exclusivamente um produto.	Comprimento máximo:18
model_descr	String	Descrição do produto.	Comprimento máximo:40
model_year	number	Ano do modelo do veículo.	Comprimento máximo:4
brand_descr†	string	Descrição da marca do produto.	Comprimento máximo:40
package_descr†	string	Descreve o pacote de um produto.	Comprimento máximo:40
color_descr†	string	Identifica a cor do veículo.	Comprimento máximo:40
length	string	Especifica o comprimento do produto.	Comprimento máximo:25
engine_type	string	Identifica o tipo de motor relacionado a um produto.	Comprimento máximo:40
platform_descr	string	Identifica a plataforma do produto.	Comprimento máximo:512
target_market_descr	string	Identifica qual mercado está relacionado a um veículo.	Comprimento máximo:40
is_cross_border	Booleano	Será definido como 'true' quando o país do concessionário for diferente do país do consumidor.
comments†	string	Comentários serão fornecidos apenas quando um veículo for 'cross_border' para fornecer informações adicionais ao concessionário	Comprimento máximo: 255
campaigns	lista de objetos	O objeto de campanha é usado para mostrar os detalhes de cada campanha.
campaigns .campaing_no	string	O número utilizado para identificar a campanha.	Comprimento máximo:10
campaigns .campaign_descr†	string	Descrição da campanha.	Comprimento máximo:40
campaigns .type_descr†	String	A classificação dos tipos de campanhas.	Comprimento máximo:40
campaigns .period_valid_from	data	Identifica a data de início da campanha. Em formato ISO 8601.	Formato: YYYY-MM-DD
campaigns .period_valid_to	data	Identifica a data em que a campanha terminará. Em formato ISO 8601.	Formato: YYYY-MM-DD
campaigns .is_claimed	booleano	O estado que permite saber o status do boletim: true false
campaigns .bulletin_no	string	O número utilizado para identificar o boletim.	String
campaigns.articles	Lista de Objetos	O objeto de artigo de campanha é usado para mostrar os detalhes de cada artigo relacionado a uma campanha.
campaigns.articles .article_no	string	O número utilizado para identificar o artigo.
campaigns.articles .article_descr	string	Descrição do artigo.	String
campaigns.articles .content_type	string	Descrição do tipo de artigo. Um dos: pdf url	Comprimento máximo:3
campaigns.articles .article_url	string	A URL é usada para exibir o artigo no DMS.	String
campaigns.articles .last_publish_date	Date-time	Data e hora em que o artigo foi publicado. Em formato ISO 8601.	Formato: yyyy-mm-ddThh:mm:ssZ

Propriedades marcadas com uma adaga (†) são retornadas no idioma solicitado.

Limitações e Restrições

Linha de Produto

O revendedor pode solicitar as campanhas da unidade apenas para a linha de produto que ele suporta.

Como um revendedor não pode realizar trabalho em uma linha de produto para a qual não é qualificado, as campanhas são inúteis.

URL do Artigo

Cada campanha contém uma lista de artigos. Nas informações do artigo, a propriedade article_url contém o URL do artigo.

Este URL leva ao artigo no BOSSWeb. Para acessar o artigo usando este URL, você precisará abrir uma janela do navegador com o URL do artigo, e o concessionário precisa fornecer suas credenciais do BOSSWeb para acessar o artigo.

Consulte a seção Usando Campanhas para Obter Artigos sobre como usar as informações da campanha.

Disponibilidade de Idiomas

Nem todas as campanhas são traduzidas para todos os idiomas.

Se o idioma solicitado não estiver disponível, as campanhas serão retornadas em inglês.

Referência da API

Get Campaigns

Get the campaigns for a vehicle based on the VIN.

GET

/unit/{serial_number}/campaigns

curl --location 'https://cloud-api.brp.com/dcp/v3/unit/2BPSMXKF5KV000020/campaigns?language=en-US' \
--header 'Dealer-Number: 0000701207' \
--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ódigos 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 Campanhas em Francês

A consulta abaixo é um exemplo rápido de como obter as campanhas em francês.

Obter Campanhas em Francês

curl --location 'https://cloud-api.brp.com/dcp/v3/unit/2BPSMXKF5KV000020/campaigns?language=fr-CA' \
--header 'Dealer-Number: 0000691888' \
--header 'Authorization: Bearer YOUR ACCESS TOKEN'

Usando Campanhas para Obter Artigos

Chamando a API de Artigos

Ao chamar a API de Campanhas, você deve observar a propriedade article_no no corpo da resposta JSON. Use o número do artigo das campanhas para chamar a API de Artigos e recuperar o PDF do artigo.

Consulte o API de Artigos para mais informações.

Usando a URL do Artigo

Observe que este não é o método preferido para recuperar um artigo de uma campanha.

No corpo da resposta JSON retornada pela API, você deve notar a propriedade article_url. Copiar/colar a URL no seu navegador irá direcioná-lo ao BOSSweb, como mostrado na imagem abaixo.

Você pode fazer login usando suas credenciais QA BOSSweb e ser direcionado ao PDF do artigo.

O artigo depende do idioma solicitado ao chamar a API.

O artigo é exibido no BOSSWeb, como mostrado na imagem abaixo.

Tratamento de Erros

Esta seção apresenta vários cenários de chamadas incorretas ou inválidas, que resultam em mensagens de erro e resultados inadequados.

400 Solicitação Inválida

O código de status 400 é geralmente visto durante o desenvolvimento e 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 formato do idioma for inválido. { "status": "400", "id": "rrt-0bde02a11a182b18f-b-ea-22692-1283834-1", "title": "bad_request", "meta": { "service": "01", "detail": "falha na validação da requisição", "payload": { "details": [ { "message": "ECMA 262 regex \"^[a-z]{2}-[A-Z]{2}$\" não corresponde à string de entrada \"\": []" } ] } } }	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 VIN for inválido. { "status": "400", "id": "rrt-0ef8248cf88949471-c-ea-11756-1483377-1.1", "title": "not_found", "meta": { "service": "03", "detail": "O VIN YDV40501Afff não foi encontrado", "payload": { "errors": [ { "title": "O VIN YDV40501Afff não foi encontrado", "code": "not_found" } ] } } }	Um VIN válido deve ser inserido para produzir uma resposta adequada.
Retornado se o concessionário não possuir a linha de produto correspondente ao VIN. { "status": "400", "id": "rrt-0ef8248cf88949471-c-ea-11755-1483106-1.1", "title": "not_found", "meta": { "service": "97", "detail": "Desculpe, o VIN inserido não corresponde a um produto que você oferece suporte.", "payload": { "errors": [ {\r "title": "Desculpe, o VIN inserido não corresponde a um produto que você oferece suporte.", "code": "unauthorized" } ] } } }	O concessionário deve oferecer suporte à linha de produto do VIN.
Retornado quando o número do concessionário está faltando. { "status": "400", "id": "rrt-0bde02a11a182b18f-b-ea-22691-1284376-1", "title": "bad_request", "meta": { "service": "01", "detail": "falha na validação da requisição", "payload": { "details": [ { "message": "O parâmetro de cabeçalho 'Dealer-Number' é obrigatório no caminho '/unit/{vin}/campaigns', mas não foi encontrado na requisição.: []" } ] } } }	Um número de concessionário deve ser fornecido no cabeçalho da requisição.
Retornado quando o número do concessionário é inválido. { "status": "400", "id": "rrt-0ef8248cf88949471-c-ea-11756-1482909-1.1", "title": "not_found", "meta": { "service": "03", "detail": "Nenhum concessionário principal foi encontrado para Dealer-Number", "payload": { "errors": [ { "title": "Nenhum concessionário principal foi encontrado para Dealer-Number: 000011hhhh", "code": "not_found" } ] } } }	O número de concessionário fornecido no cabeçalho da requisição deve ser um número BRP válido.

401 Não Autorizado

O código de status 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 status de erro 401 Unauthorized 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, deverá 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 Not Found é retornado quando o VIN solicitado não é encontrado ou não possui campanha.

Resposta	Resolução
Retornado quando o VIN informado não é encontrado { "status": "404", "id": "rrt-0ef8248cf88949471-c-ea-11756-1483377-1.1", "title": "not_found", "meta": { "service": "03", "detail": "VIN YDV40501Afff was not found", "payload": { "errors": [ { "title": "VIN YDV40501Afff was not found", "code": "not_found" } ] } } }	Um VIN correto deve ser informado para que a API responda adequadamente.
Retornado quando o VIN é válido, mas não possui nenhuma campanha ativa. { "status": "404", "id": "rrt-065e1c5bbf0ebc061-b-ea-31810-5677524-5.1", "title": "not_found", "meta": { "service": "03", "detail": "VIN 3JB2GEG2XLJ006676 does not have any campaigns.", "payload": { "errors": [ { "title": "VIN 3JB2GEG2XLJ006676 does not have any campaigns.", "code": "not_found" } ] } } }	Não há nada a ser feito além de exibir uma mensagem ao concessionário informando que não há campanha ativa para este VIN.

Requisitos de DSP

Requisitos Funcionais

ID	Tipo	Requisito
1	Obrigatório	A lista de campanhas aplicáveis à unidade deve ser mostrada ao concessionário.
2	Obrigatório	O indicador de mercado transfronteiriço/cinzento e o texto de aviso devem ser mostrados ao concessionário.
3	Obrigatório	Mensagens de erro devem ser mostradas ao concessionário.
4	Obrigatório	Uma mensagem deve ser mostrada ao usuário quando a unidade não tiver campanha ativa.

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.

Garantia de Qualidade

Os testes listados na tabela abaixo devem ser realizados com sucesso no ambiente de testes antes que você possa iniciar a fase piloto do concessionário.

Lista de VINs

Linha de Produto	VIN
Snowmobile (SNO)	2BPSMXKF5KV000020
ATV	RLVDGF119FVN00027
Sea-Doo (PWC)	YDV00005G819
Side-by-Side (SSV)	3JB7VAX42MK000288
3-Wheels (3WV)	3JB2FEG45PJ002724

ID	Teste	Resultado Esperado
1	Chamar a API de campanha para cada idioma e linha de produto do VIN que o seu concessionário suporta.	Exibir todas as informações relevantes da campanha referentes ao VIN inserido.
2	Chamar a API de campanha com uma linha de produto do VIN que não é suportada pelo seu concessionário.	Um log de erro é exibido com status 400: "Desculpe, o VIN inserido não corresponde a um produto que você suporta.

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árias	1 a 3
Duração	1 semana
Validação 1	Enviar uma captura de tela das campanhas para um ou dois VINs para cada linha de produto suportada pela concessionária.

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

Ambiente - DSP de Teste

Coleções

A coleção DMS - Campanhas contém exemplos de chamadas de API para recuperar campanhas de veículos.

DMS - Campanhas

Registro de Alterações da API

Revisão 1.1

Fixed

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

Revisão 1.0

Added

Primeiro lançamento