Fundamentos

Antes de iniciar o desenvolvimento de suas integrações, familiarize-se com os principais conceitos de negócio que compõem o ecossistema de Gestão de Veículos.

Conceitos-Chave

• Marca: Representa o fabricante/montadora do veículo cadastrado na plataforma (ex: Renault, Chevrolet, Volkswagen). É o nó inicial na hierarquia de catalogação de veículos.

• Modelo: Representa a versão técnica e a motorização comercializável associada a uma marca. O modelo estabelece especificações estáticas, como o ano de início e fim de fabricação, o tipo de veículo (categoria) e se possui suporte nativo a planos de manutenção ou tabelas de preço.

• Veículo: Representa a unidade física (bem) que compõe a frota operacional de um cliente. Cada veículo está atrelado a um modelo específico, a uma placa de identificação única e armazena os dados de rodagem (odômetro/quilometragem), data de licenciamento, chassi e motoristas ativos.

• Manutenção Preventiva: O conjunto de planos e cronogramas de revisão baseados em tempo de uso ou quilometragem acumulada. O sistema indica o status de integridade do veículo a partir destes planos.

• Dados Técnicos (TecRmi): Uma integração especializada que valida se o veículo possui manuais, dados técnicos e cronogramas de serviços oficiais de fábrica disponíveis para carregamento automatizado.

Hierarquia Cadastral de Veículos

Os dados de frota seguem uma estrutura relacional estrita na plataforma. Para que um veículo seja registrado, ele depende da existência de entidades geográficas, do cliente responsável, do bloco operacional e da especificação precisa do modelo de fabricação:

Marca (brandId) → Modelo (modelId) → Veículo

Cliente (clientId) → Bloco Operacional (blockId) → Cidade (cityId) → Veículo

Entidades de Frota na API

Relação Geral entre os Recursos

A árvore de composição abaixo demonstra graficamente como as propriedades internas e externas se associam a um registro de veículo:

Veículo → Modelo (modelId) → Marca (brandId)

Veículo → Cliente (clientId) → Bloco (blockId) → Endereço → Cidade (cityId)

Veículo → Motoristas Associados (driversName)

Veículo → Status de Saúde (isPreventiveUpToDate, warning, danger)

Fluxo de Trabalho (Workflow)

Esta seção descreve os caminhos de integração recomendados para garantir que sua aplicação utilize as APIs de frota de forma otimizada e livre de inconsistências cadastrais.

Pré-requisitos de Integração

• Consumir as credenciais de autenticação válidas (Bearer Token enviado no cabeçalho Authorization).

• Garantir o provisionamento prévio de Clientes, Blocos e Localizações geográficas (conforme detalhado no Módulo de Clientes).

• Compreender os mapeamentos de dados estruturados na etapa de Fundamentos.

Fluxo 1: Resolução de Catálogo para Cadastro de Veículo

Para cadastrar um novo veículo físico, você não deve enviar o nome da marca ou do modelo como texto simples. Primeiro, filtre e resolva o identificador correto a partir da base histórica da API:

Consultar Marcas → obter brandId → Filtrar Modelos por Marca → obter modelId → Enviar POST /api/vehicles

1. Obter Marca: Chame a API de marcas disponíveis para recuperar a lista de fabricantes e localizar o brandId correspondente.

2. Filtrar Modelo: Utilize o brandId obtido para buscar os modelos compatíveis com o veículo cadastrado e identifique o modelId correto.

3. Efetuar o Registro: Use o modelId e demais dados estruturados (placa, chassi, odômetro, cliente e cidade) para chamar o endpoint de cadastro de veículos.

Fluxo 2: Monitoramento de Saúde da Frota e Manutenção

O status de manutenção preventiva de um veículo é dinâmico e depende da constante atualização do odômetro e do encerramento de ordens de serviço. Siga o fluxo periódico de verificação:

Consumir GET /api/vehicles/{id}/preventives → Validar Status

Se warning ou danger: true → Agendar Manutenção / Alertar Gestor.

Se false → Operação Normal / Frota em Dia.

Nota de Integração: Atualizações do odômetro do veículo (como quilometragem percorrida enviada por aplicativos ou telemetria) recalculam de forma assíncrona o indicador isPreventiveUpToDate. Sempre consuma este endpoint para emitir notificações preventivas ao motorista e evitar sinistros ou quebras de garantia.

Fluxo 3: Fluxo de Extração de Indicadores da Frota (Dashboard)

Ao construir painéis visuais para gestores de frotas, execute as chamadas seguindo a ordem de agregação de dados para reduzir a latência e o consumo de banda de rede:

1. Consultar Indicadores / Infográficos (Agregado)

2. Listar Veículos com Filtros Ativos (paginado)

3. Detalhar Perfil do Veículo Selecionado (Individual)

Referência de Endpoints

Erros e Resolução de Problemas

Sempre que a sua aplicação interagir com as nossas APIs, verifique os códigos de status HTTP para determinar o sucesso ou a necessidade de correção das requisições de veículos.

Códigos de Status HTTP

Dicas de Resolução de Problemas

• Consistência de Odômetro: Ao enviar dados de odômetro via integração, certifique-se de que o sistema de origem não está enviando valores zerados ou desatualizados, o que causa erro de consistência lógica 422 Unprocessable Entity caso o histórico do veículo já possua medições superiores.

• Inconsistência em Alertas de Preventivas (warning ou danger): Se o veículo consta em estado de alerta (danger: true) mesmo após a passagem por manutenção física, verifique se a ordem de serviço preventiva foi devidamente encerrada e integrada à nossa plataforma para reiniciar o cálculo de prazos de revisão.

• Catálogo TecRmi Indisponível: Nem todos os modelos de veículos possuem compatibilidade de fábrica ou tabelas técnicas mapeadas na base de parceiros terceiros. Se hasServicePlan retornar false no endpoint /tecrmi-data-availability, você poderá cadastrar os planos de forma manual diretamente no painel administrativo.