API de Artigos
Introdução
A API de Artigos permite que seus concessionários visualizem um PDF de artigo em seu DMS para um número de artigo específico.
Quando um cliente leva uma unidade para manutenção ou reparo, uma parte importante das atividades do concessionário é usar os artigos aplicáveis à campanha de garantia da unidade. Ao usar os artigos, seu concessionário pode ver a campanha de garantia.
Um artigo fornece informações sobre:
- Problema
- Solução
- Peças necessárias
- Ações corretivas
O artigo detalha tudo e inclui imagens, garantindo que seus concessionários não tenham problema em corrigir a questã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:
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 o BRP | | | Um pouco mais ainda |
Autenticação
A API está usando 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)
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: Artigos
O recurso de artigo fornece informações sobre um artigo específico.
Representação JSON
{
"article_no": "000136021",
"article_descr": "SKI-DOO 2019-11 Fuel Injector - Potential Leak_136589_WSC11Y019S02_en",
"article_url": "https://brp--qauat--c.visualforce.com/apex/Article_Detail_Warranty_Bulletin?lang=en_US&id=kAA0c000000KzTR#googtrans(en|en)",
"last_publish_date": "2019-07-03T12:52:50Z",
"content_type": "PDF",
"content":"pdf…!@#$%^&DFRUIJHKODFGHUJK^&U*I(OGHJKHJKKJbase64dsadasadsdasa"
}
Propriedades
Propriedade | Tipo | Definição | Notas |
|---|---|---|---|
article_no* | string | A string usada para identificar o artigo. | Comprimento máximo: 18 |
article_descr | string | Descrição do artigo. | String |
article_url | string | A URL é usada para exibir o artigo no BOSSweb. | String |
last_publish_date | Date-time | Data e hora em que o artigo foi publicado. Em formato ISO 8601. | Formato: yyyy-mm-ddThh:mm:ssZ |
content_type | string | Descrição do tipo do artigo. Um dos:
| Comprimento máximo: 3 |
content | string | Detalhes do artigo.
| String Máxima |
Limitações e Restrições
URL do Artigo
Para usar a URL do artigo para exibir o conteúdo do artigo, o revendedor deve estar conectado ao BOSSWeb.
O conteúdo do artigo é armazenado no SalesForce. O revendedor só pode acessá-lo através do BOSSWeb, razão pela qual a URL é uma URL do Centro de Conhecimento do BOSSWeb.
A forma preferencial de exibir o conteúdo do artigo é usar o PDF.
O PDF é codificado em base64 e deve ser convertido para um PDF binário antes de ser exibido.
Disponibilidade de Idiomas
Nem todos os artigos são traduzidos para todos os idiomas.
Se o idioma solicitado não estiver disponível, o artigo será exibido em inglês.
Referência da API
curl --request POST 'https://qa-cloud-api.brp.com/dcp/v3/article/000020951?language=fr-CA' \
--header 'Dealer-Number: 0000690006' \
--header 'Authorization: Bearer REPLACE_ME'Como Fazer
Esta seção fornece informações sobre como obter resultados específicos com a API.
Obter Artigos em Francês
A consulta abaixo é um exemplo rápido de como obter o Artigo em francês.
curl --location 'https://qa-cloud-api.brp.com/dcp/v3/article/000020951?language=fr-CA' \
--header 'Dealer-Number: 0000690006' \
--header 'Authorization: Bearer YOUR ACCESS TOKEN'Uma vez convertido da codificação base64 para PDF, o documento pode ser exibido e se parece com a imagem abaixo.
Tratamento de Erros
Esta seção apresenta vários cenários de chamadas inadequadas ou incorretas, que resultam em mensagens de erro e resultados indevidos.
400 Requisição Inválida
O código de status 400 é geralmente visto 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, e 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-22691-415152-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "ECMA 262 regex \"^[a-z]{2}-[A-Z]{2}$\" does not match input string \"AA-BBB\": []"
}
]
}
}
} | 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 É necessário inserir um formato de idioma válido para produzir uma resposta adequada. |
Retornado quando o número do revendedor está ausente. {
"status": "400",
"id": "rrt-0bde02a11a182b18f-b-ea-22692-415715-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "Header parameter 'Dealer-Number' is required on path '/article/{article_no}' but not found in request.: []"
}
]
}
}
} | Um número de revendedor deve ser fornecido no cabeçalho da solicitação. |
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, 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
O código de status 404 Not Found é retornado quando o artigo não é encontrado.
Resposta | Resolução |
|---|---|
Retornado quando o número do artigo inserido não é encontrado {
"status": "404",
"id": "rrt-00a574511a562afb5-b-ea-22206-2601758-1.1",
"title": "not_found",
"meta": {
"service": "03",
"detail": "Erro no backend",
"payload": {
"status": "404",
"errors": [
{
"title": "Artigo 123456789 não foi encontrado",
"code": "not_found"
}
]
}
}
} | Um número de artigo correto deve ser inserido para que a API possa retornar uma resposta adequada. Para que um número de artigo seja correto, ele deve ser encontrado na lista de números de artigos. |
Requisitos do DSP
Requisitos Funcionais
ID | Tipo | Requisito |
|---|---|---|
1 | Obrigatório | Mensagens de erro devem ser exibidas ao concessionário. |
2 | Obrigatório | Os artigos aplicáveis à campanha devem ser exibidos aos concessionários. |
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 teste antes que você possa iniciar a fase piloto do concessionário.
ID | Teste | Resultado Esperado |
|---|---|---|
1 | Chamar a Article API para cada idioma que seu DMS suporta. Artigo nº: 000136062 | Exibir todas as informações relevantes do artigo referentes ao número de artigo inserido. |
2 | Chamar a API com um número de artigo inválido. Artigo nº: 123456789 | Um log de erro é exibido com status 400 "Artigo não foi encontrado" |
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 revendedores | 1 a 3 |
Duração | 1 semana |
Validação 1 | Envie uma captura de tela de um artigo para um ou dois números de artigo, para cada revendedor no piloto. |
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 Artigos. 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 DMS - Artigos contém exemplos de chamadas de API para recuperar um artigo.