API de Garantia
Introdução
O objetivo da API de Reivindicação de Garantia é melhorar a experiência do usuário ao enviar solicitações de garantia no BOSSWeb. A meta é reduzir o tempo necessário e o número de entradas manuais para completar os formulários, pré-preenchendo a reivindicação rascunho com informações de uma ordem de reparo. O revendedor então acessa o BOSSWeb para completar a reivindicação.
Somente reivindicações de unidade em rascunho podem ser criadas através da API, que são reivindicações relacionadas a problemas de veículos cobertos por uma garantia.
Por Onde Começar? Leia 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 ao 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çõ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: Reclamação
Este recurso é usado para trabalhar com uma reclamação de garantia.
Representação JSON
{
"dealer_no": "0000694307",
"vin": "2BPSMBMB2MV000203",
"odometer": "1050.5",
"rro_creation_date": "2022-01-10T08:20:50Z",
"date_of_repair": "2022-01-10T14:10:09Z",
"causal_part": "415129449",
"system_code": "1-Engine",
"work_order_no": "4334-01",
"symptom_description": "The part broke. Customer heard noise.",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "415129449",
"quantity": 1
}
]
}Propriedades
Property | Type | Definition | Notes |
|---|---|---|---|
dealer_no * | string | Code that uniquely identifies a dealer. It must be 10 characters. If less than 10 characters, add '0' at the beginning. | Length: 10 |
vin * | string | The Vehicle Identification Number (VIN). | Max Length: 18 |
odometer * | number | Unit odometer value (Km or miles) from the repair order. | Precision: 0.1 Max Length: 18 |
rro_creation_date * | string | The last date and time at which this resource has changed, in ISO 8601 format | yyyy-mm-ddThh:mm:ssZ |
date_of_repair* | string | Date of Repair, in ISO 8601 format | yyyy-mm-ddThh:mm:ssZ |
system_code* | string | One of: "1-Engine", "2-Fuel System", "3-Ignition", "4-Starting", "5-Transmission / Propulsion", "6-Braking", "7-Steering / Suspension / Front Drive System", "8-Suspension / Rear Drive System", "9-Body", "10-Electrical", "11-Accessories, Special Tools, Others", "12-Hull Structure", "13-CARB and EPA Regulations", "14-CARB Regulations", "15-Battery and Tyres" | |
casual_part* | string | The part number of the part that is defective. | Max Length: 18 |
symptom_description* | string | The description of the symptoms that prompted the customer to investigate. | Max Length: 512 |
remedy_description* | string | The solution description of the dealer to fix the problem. | Max Length: 512 |
defect_description* | string | The description of the issue provided by the dealer | Max Length: 512 |
work_order_number* | string | Work order number (document identifier) + Job number 👉 The value in the work_order_number field must be unique. | Max Length: 15 <work_order>-<job code> |
installed_parts | array | The list of parts to be installed on the vehicle. |
|
installed_parts.item_id | string | The ID of each part to be installed. | Max Length: 18 |
installed_parts.quantity | integer | The quantity of the part to be installed. |
|
* Esses campos são obrigatórios.
Recurso: Job
Este recurso é usado para recuperar o status de criação de uma solicitação preliminar para um job.
Representação JSON
{
"job_id": "DMS-20221219007781",
"claim_status": "failed",
"failure_reason": "Unit is out of Warranty",
"claim_number": null
}Propriedades
Propriedade | Tipo | Definição |
|---|---|---|
job_id | string | O ID do job que processa a criação do rascunho da reivindicação de garantia. |
claim_status | string | O status da criação do rascunho da reivindicação de garantia. |
failure_reason | string | A razão pela qual um rascunho de reivindicação de garantia não foi criado. Por exemplo: "Unidade fora da garantia". |
claim_number | string | O campo contém o número da reivindicação quando o rascunho da reivindicação de garantia é criado. |
Recurso: Trabalhos
Este recurso é usado para recuperar o status de criação de reivindicação em rascunho para uma lista de trabalhos.
É retornado ao chamar o serviço Get com uma lista de jobs.
Representação JSON
{
"items": [
{
"job_id": "DMS-20230420009063",
"claim_status": "success",
"failure_reason": null,
"claim_number": "C010469"
},
{
"job_id": "DMS-20230420009064",
"claim_status": "success",
"failure_reason": null,
"claim_number": "C010470"
},
{
"job_id": "DMS-20221104000204",
"claim_status": "failed",
"failure_reason": "Part Price API is not responding",
"claim_number": null
},
{
"job_id": "DMS-20230710032398",
"claim_status": "failed",
"failure_reason": "Unit claims are disabled on this unit due to campaign inclusion. At least one outstanding campaign repair has to be completed before unit claims will be enabled. Campaign claims need to be fulfilled directly in Tavant.",
"claim_number": null
}
]
}Propriedades
Propriedade | Tipo | Definição |
|---|---|---|
items | Lista de objetos | |
job_id | string | O ID do trabalho que está processando a criação do rascunho de reivindicação de garantia. |
claim_status | string | O status da criação do rascunho de reivindicação de garantia. |
failure_reason | string | O motivo pelo qual um rascunho de reivindicação de garantia não foi criado. Por exemplo: "Unidade está fora da garantia". |
claim_number | string | O campo contém o número da reivindicação quando o rascunho da reivindicação de garantia é criado. |
Limitações e Restrições
Tipos de Reivindicação
Esta API é limitada à criação de rascunhos de reivindicações de unidade. Reivindicações de peças e reivindicações de campanha não são suportadas.
Entendendo a Garantia
Esta seção dá continuidade às informações fornecidas na seção anterior Introdução e discute os diferentes serviços da API de Garantia com mais detalhes.
Visão de Processo em Alto Nível
A imagem abaixo apresenta uma visão em alto nível do processo preliminar de solicitação de garantia.
O concessionário seleciona uma ordem de reparo fechada no DMS e inicia a função de rascunho de solicitação de garantia.
O DMS exibe uma janela para permitir que o concessionário insira as informações necessárias que não estão disponíveis na ordem de reparo:
- O código do sistema.
- O número da peça causal.
- As descrições de sintoma, reparo e defeito.
Após fornecer as informações necessárias, o concessionário envia o rascunho da solicitação de garantia.
As informações do rascunho da solicitação de garantia são enviadas para a API de Garantia, que as encaminha para a API da Tavant.
A Tavant cria um job com as informações do rascunho da solicitação de garantia e o adiciona à fila de processamento.
O ID do job é retornado ao DMS por meio da API de Garantia.
A Tavant processa o job na fila e o rascunho da solicitação de garantia é criado após um momento.
O rascunho da solicitação de garantia fica então disponível no BOSSWeb para conclusão.
O concessionário acessa o BOSSweb, completa e envia a solicitação de garantia.

Enquanto a Tavant processa os jobs, o seu DMS deve consultar a API de Garantia para obter o status do job. Quando o job é concluído e o rascunho da solicitação de garantia é criado, o número da solicitação retornado deve ser salvo e exibido ao concessionário.
Dessa forma, o concessionário sabe quando pode acessar o BOSSWeb para concluir a solicitação.

Status de Criação no BOSSWeb
No BOSSWeb, o concessionário tem acesso às Transferências do DMS no módulo de gestão de Garantia, que mostra as solicitações de garantia em rascunho enviadas pelo DMS.
Rascunho
A visualização mostra solicitações de garantia em rascunho por padrão. A Número de Confirmação na coluna mostra o ID do trabalho que a API de Garantia retorna ao seu DMS na carga de resposta de Criação.

O menu de status permite que o concessionário altere o filtro.

Bem-sucedido
A visualização Bem-sucedido mostra as solicitações de garantia em rascunho criadas pelo processo da Tavant. O botão Ir para Solicitação permite que o concessionário acesse a solicitação em rascunho para concluir e enviar a solicitação.

Falhou
O Falhou exibe as solicitações de reivindicação de garantia em rascunho que falharam. O concessionário pode clicar no botão Ver Erros para obter os detalhes do erro.
Quando você chama para obter o status do trabalho, geralmente receberá o mesmo erro através da API de Garantia.

Em Andamento
A visualização Em Andamento mostra as solicitações de reivindicação de garantia em rascunho que ainda estão na fila da Tavant e aguardando processamento.
Na maioria das vezes, esta visualização fica vazia.
Possíveis Erros
A criação da reivindicação de garantia em rascunho é rejeitada se:
- O Número do Concessionário é inválido.
- O VIN é inválido.
- O número da Peça Causal é inválido.
- Um campo obrigatório, exceto a Descrição do Sintoma, está vazio.
- O Código do Sistema é inválido ou está vazio.
- Um campo de data usa um formato inválido.
- O Número da Ordem de Serviço está sem o número do trabalho.
- Uma reivindicação de garantia em rascunho já foi enviada para o trabalho da ordem de reparo.
Se um número de peça instalada não for uma peça BRP, a peça será excluída da criação da reivindicação.
Referência da API
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/claim' \
--header 'Dealer-Number: 0000694307' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 20OZBLG4sVhTtmfEexlUQEw9OFiY' \
--data '{
"dealer_no": "0000691888",
"vin": "2BPSGDNA1NV000302",
"odometer": 1090.5,
"rro_creation_date": "2023-02-10T09:35:38-05:00",
"date_of_repair": "2023-02-11T09:35:38-05:00",
"causal_part": " 705203477 ",
"system_code": "11-Accessories, Special Tools, Others",
"work_order_no": "3001-02",
"symptom_description": "The part broke. Customer heard noise. By Maxime",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "219800518",
"quantity": 2
}
]
}'curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20230705032364' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs?jobs_id=DMS-20221104000204,DMS-20230710032398,DMS-20230420009063,DMS-20230420009064' \
--header 'Dealer-Number: 0000691695' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'Como Fazer
Esta seção fornece informações sobre como obter resultados específicos com a API.
Criar uma Solicitação de Garantia Rascunho
A resposta é um exemplo rápido de como criar uma solicitação de garantia em rascunho para um número VIN específico.
Altere o número do revendedor ou VIN para criar diferentes solicitações para diferentes linhas de produtos.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/claim' \
--header 'Dealer-Number: 0000694307' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
"dealer_no": "0000691888",
"vin": "3JBUKAP46NK000775",
"odometer": 1090.5,
"rro_creation_date": "2023-02-10T09:35:38-05:00",
"date_of_repair": "2023-02-11T09:35:38-05:00",
"causal_part": " 705203477 ",
"system_code": "11-Accessories, Special Tools, Others",
"work_order_no": "200-10",
"symptom_description": "The part broke. Customer heard noise. By Maxime",
"remedy_description": "",
"defect_description": "",
"installed_parts": [
{
"item_id": "219800518",
"quantity": 2
}
]
}'Obter o Status de uma Solicitação de Garantia Rascunho
Obtém o status de uma solicitação de garantia rascunho enviada.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20221219007781' \
--header 'Authorization: Bearer 6dVfKN4VFqsl0DMDRfHPLUOunwBx'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.
Erro 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.
Vários problemas podem causar um código de status 400; os mais comuns estão listados na tabela abaixo.
Postar
Resposta | Resolução |
|---|---|
Retornado se o número do concessionário não for inserido, estiver muito curto ou muito longo {
"status": "400",
"id": "rrt-07545d3b30b8d2411-b-ea-6909-1591317-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "O parâmetro 'Dealer-Number' é obrigatório, mas está ausente."
},
{
"message": "[Caminho '/dealer_no'] String \"12345678\" é muito curta (comprimento: 8, mínimo exigido: 10): []"
}
]
}
}
}
| Para produzir uma resposta adequada, um número de concessionário válido contendo exatamente 10 dígitos deve ser inserido. Ele não pode ser maior nem menor. |
Retornado se a peça causal não for inserida ou não for válida. {
"status": "400",
"id": "rrt-0ef8248cf88949471-c-ea-11756-1695836-1.1",
"title": "bad_request",
"meta": {
"service": "15",
"detail": "Número de causal_part inválido ABC."
}
}
--------------------------------------
{
"status": "400",
"id": "rrt-0e20a46609994a8ad-c-ea-22696-1603343-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "O objeto possui propriedades obrigatórias ausentes ([\"causal_part\"]): []"
}
]
}
}
}
| Uma peça causal válida deve ser inserida para produzir uma resposta adequada. |
Retornado quando um código de sistema não é inserido ou não é válido. {
"status": "400",
"id": "rrt-007c58ce55d14f4ff-d-ea-23462-1707968-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "[Caminho '/system_code'] Valor da instância (\"16-ABCD\") não encontrado no enum (valores possíveis: [\"1-Engine\",\"2-Fuel System\",\"3-Ignition\",\"4-Starting\",\"5-Transmission / Propulsion\",\"6-Braking\",\"7-Steering / Suspension / Front Drive System\",\"8-Suspension / Rear Drive System\",\"9-Body\",\"10-Electrical\",\"11-Accessories, Special Tools, Others\",\"12-Hull Structure\",\"13-CARB and EPA Regulations\",\"14-CARB Regulations\",\"15-Battery and Tyres\"]): []"
}
]
}
}
}
| Um código de sistema válido deve ser inserido para produzir uma resposta adequada. Um dos códigos de sistema abaixo deve ser inserido. "1-Motor" "2-Sistema de Combustível" "3-Ignição" "4-Partida" "5-Transmissão / Propulsão" "6-Freios" "7-Direção / Suspensão / Sistema de Tração Dianteira" "8-Suspensão / Sistema de Tração Traseira" "9-Carroceria" "10-Elétrico" "11-Acessórios, Ferramentas Especiais, Outros" "12-Estrutura do Casco" "13-Regulamentos CARB e EPA" "14-Regulamentos CARB" "15-Bateria e Pneus" |
Obter
Resposta | Resolução |
|---|---|
Retornado quando o ID do trabalho não é inserido na URL. {
"status": "400",
"id": "rrt-07cdd77f98c381924-d-ea-22529-1664059-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "request validation failed",
"payload": {
"details": [
{
"message": "Query parameter 'jobs_id' is required on path '/warranties/jobs' but not found in request.: []"
}
]
}
}
} | Um ID de trabalho válido deve ser inserido na URL para verificar o status de uma solicitação. Um exemplo de um trabalho se parece com isto: DMS-20221219007781
|
401 Não Autorizado
O código 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 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 Não Encontrado é retornado pelo serviço Obter Status do Job quando o ID do job solicitado não é encontrado.
{
"status": "404",
"id": "rrt-07cdd77f98c381924-d-ea-22528-1664528-1.1",
"title": "not_found",
"meta": {
"service": "17",
"detail": "job_id 00000000 not found"
}
}Requisitos DSP
Requisitos Funcionais
ID | Tipo | Requisito |
|---|---|---|
1 | Obrigatório | A minuta da reivindicação de garantia deve ser criada a partir de uma ordem de reparo. |
2 | Obrigatório | Mensagens de erro devem ser mostradas ao concessionário. |
3 | Obrigatório | A lista de números de reivindicações enviadas deve ser mostrada 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 |
|
|
2 |
|
|
3 |
|
|
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ários | 1 a 3 |
Duração | 1 semana |
Validação 1 | Enviar uma captura de tela do status de criação de um rascunho de solicitação de garantia para um VIN para cada linha de produto suportada pelo concessionário. |
Validação 2 | Um concessionário deve ser capaz de encontrar VINs "Em garantia" para produzir uma resposta adequada. |
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 Garantia. Este ambiente do Postman contém variáveis usadas pelas consultas e está configurado para se conectar ao ambiente de teste.
Coleções
A coleção DMS - Garantia inclui exemplos de chamadas de API para criar um rascunho de reivindicação de garantia e recuperar o status do trabalho.