API de Garantia

45 min

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:

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.

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

Criar Rascunho de Reivindicação de Garantia

Criar uma reivindicação de garantia para um VIN específico.

POST

/warranties/claim

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
        }
    ]
}'

Get Job Status

Get the claim status by using the job number returned by the Create service.

GET

/warranties/jobs/{job_id}

curl --location 'https://qa-cloud-api.brp.com/dcp/v4/warranties/jobs/DMS-20230705032364' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Obter Status dos Jobs

Obter os status de uma lista de jobs.

GET

warranties/jobs?jobs_id={{jobids}}

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.

Criar uma Solicitação de Garantia Rascunho

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.

Obter o Status de uma Solicitação de Garantia Rascunho

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	Crie uma reivindicação de garantia com o seguinte VIN. 2BPSGDNA1NV000302 Obtenha o status da reivindicação para o Job_id fornecido ao criar a reivindicação.	Um ID de trabalho é criado no nível da API, e um rascunho é criado no Tavant. O rascunho foi criado com sucesso e não há erro no log da API. Um status de “Sucesso” deve aparecer no log da API.
2	Crie uma reivindicação de garantia para um VIN fora da garantia. 3JBUKAP46NK000775 Obtenha o status da reivindicação para o Job_id fornecido ao criar a reivindicação.	Um ID de trabalho é criado no nível da API, e um rascunho é criado no Tavant. O rascunho foi criado com sucesso e não há erro no log da API. Um status de “Falha” deve aparecer no log da API com o motivo da falha “Unidade fora da garantia”.
3	Crie uma reivindicação de garantia com o seguinte VIN e peça causal 2BPSGDNA1NV000302 705203477 Obtenha o status da reivindicação para o Job_id fornecido ao criar a reivindicação.	Um ID de trabalho é criado no nível da API, e um rascunho é criado no Tavant. O rascunho foi criado com sucesso e não há erro no log da API. Um status de “Sucesso” deve aparecer no log da API.

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.

Teste - Ambiente DSP

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.

DMS - Garantia

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