Bem-vindo à documentação do Módulo de Telemetria (KM). Este módulo é responsável por concentrar, gerenciar e processar dados de sensores, coordenadas geográficas, odômetros virtuais e eventos de alertas mecânicos gerados diretamente pelos veículos integrados na plataforma.

Esta documentação está dividida em 4 seções principais:

Fundamentos — Entenda as regras de negócio e os conceitos-chave.
Fluxo de Trabalho (Workflow) — Compreenda a ordem correta das integrações e o fluxo de dados.
Referência de Endpoints — Veja as especificações técnicas de cada rota (Headers, Payloads e Schemas).
Erros e Resolução de Problemas — Saiba como tratar as respostas da API e solucionar problemas.

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 Telemetria da plataforma.

Conceitos-Chave

Telemetria: Representa a coleta e transmissão automatizada de dados operacionais de um veículo em movimento. A plataforma utiliza estes dados principalmente para monitorar o desgaste de componentes e prever manutenções com base em regras de uso real.
Quilometragem (KM) e Odometria: A quilometragem acumulada do veículo é a variável central para a ativação de planos de revisão preventiva. A atualização deste dado via API força a reavaliação de todas as regras de manutenção pendentes para a frota.
VIN (Vehicle Identification Number / Chassi): O número do chassi é a chave de identificação global do veículo. Para a realização de ações de telemetria baseadas em eventos físicos, a API exige primeiro a resolução do chassi textual para o identificador interno numérico do veículo (id), garantindo acoplamento seguro e validação de propriedade.

Resolução de VIN para ID Interno

VIN / Chassi (Texto) → resolva para → vehicleId (integer) → atualize → Odômetro / KM

Eventos de Telemetria

Eventos representam anomalias, desgastes ou condições mecânicas reportadas pelo veículo em tempo real (ex: desgaste de pastilhas de freio, nível baixo de fluido de freio ou alertas do sistema ABS). Cada tipo de evento possui:

Código de Evento (code): Chave identificadora única do sinal técnico.
Nível de Gravidade (severityLevel): Classificação de criticidade do sinal.
Gatilho de Serviço (triggerServiceEvent): Flag booleana que define se a recepção deste evento deve abrir de forma automática uma nova solicitação de serviço na oficina.

Entidades de Telemetria na API

Entidade de Telemetria	Identificador em API	Descrição
Veículo	`id` ou `vehicleId`	Código numérico exclusivo gerado internamente para o veículo.
Evento de Telemetria	`id` (do evento)	ID interno que define as regras e a criticidade de um alerta técnico.
Código de Sinal	`code`	Nome técnico internacional do evento gerado pelo veículo (ex: ABS, BRAKE_FLUID).

Relação Geral entre os Recursos

A árvore estrutural abaixo demonstra graficamente como as informações de telemetria se aninham dentro do cadastro do veículo e do cliente:

Cliente → Veículo (Identificado por VIN / id)

Veículo → Eventos de Alerta (ABS, Desgaste de Pastilhas, Fluido de Freio) → Configuração de Criticidade (severityLevel, triggerServiceEvent)

Fluxo de Trabalho (Workflow)

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

Pré-requisitos de Integração

Consumir as credenciais de autenticação válidas (Bearer Token) nos headers das requisições.
Validar as placas ou códigos de chassi (VIN) correspondentes aos veículos ativos de sua frota.
Compreender os mapeamentos de dados detalhados na etapa de Fundamentos.

Fluxo 1: Atualização de Quilometragem por VIN (Chassi)

Para reportar o odômetro atualizado de um veículo a partir de um leitor de telemetria que apenas possui a informação do chassi, execute a esteira de chamadas abaixo:

Consumir GET /api/vehicles/filters?plateVinBrandModel={VIN} → Validar Array content

Se vazio → Fim (Veículo não cadastrado).

Se localizado → Extrair id do primeiro elemento (content[0]) → Fornecer Coordenadas e Quilometragem → Consumir PUT /api/vehicles/{id}/update-km

Buscar Identificador: Envie o VIN para buscar os metadados do veículo na plataforma de forma a extrair o id interno.
Atualizar KM: De posse do id, monte a requisição contendo a nova medição de odômetro (mileage), a cidade e as coordenadas de latitude e longitude do momento da leitura.

Nota de Integração: O envio de valores de quilometragem menores do que os já gravados anteriormente no banco de dados resultará em rejeição automática por inconsistência de odometria.

Fluxo 2: Gestão de Regras de Alertas de Telemetria

Os alertas mecânicos gerados pelos veículos podem ser personalizados para decidir quais eventos devem forçar uma parada de manutenção. O fluxo de gerenciamento segue as seguintes etapas:

Consultar Eventos Cadastrados POST /api/telemetry-event/search (Filtro por código) → Identificar ID do Alerta → Executar PUT /api/telemetry-event/{id} → Atualizar severityLevel e triggerServiceEvent

Referência de Endpoints

Gestão de Veículos e Quilometragem

Consultar ID do Veículo por VIN

Retorna a listagem de veículos correspondentes ao parâmetro de busca de placa, chassi ou marca. Útil para obter o id interno para ações de atualização de KM.

Endpoint: /api/vehicles/filters

Método: GET

Query Parameters:

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`page`	integer	Não	0	Número da página a ser recuperada.
`size`	integer	Não	30	Limite de registros por página.
`plateVinBrandModel`	string	Sim	-	Parâmetro de busca contendo o VIN (Chassi) do veículo.

Exemplo de Requisição:

GET /api/vehicles/filters?page=0&size=10&plateVinBrandModel=35715965478964455 HTTP/1.1
Host: api.developer.platform.com
Authorization: Bearer <TOKEN>
Content-Type: application/json

Exemplo de Resposta (Status 200 OK):

{
  "content": [
    {
      "id": 11225,
      "modelYear": 2023,
      "chassisNumber": "35715965478964455",
      "licensePlate": "SMI0604",
      "initialMileage": 14600,
      "firstMileage": 0,
      "vtvExpiration": "",
      "modelId": 7369,
      "blockId": 1551,
      "clientId": 1732,
      "cityId": 38881,
      "city": {
        "id": 38881,
        "name": "Hamburg",
        "state": {
          "id": 119,
          "name": "Hamburg",
          "country": {
            "id": 5,
            "name": "Germany",
            "code": "DE"
          }
        }
      },
      "registrationDate": "2025-04-15T16:37:43.941+00:00",
      "brandId": 32,
      "model": {
        "id": 7369,
        "motor": "1.4",
        "brandName": "AUDI",
        "description": "A3 1.4 TFSI",
        "displayName": "A3 1.4 TFSI 1.4 (2023 - 2023)",
        "category": "RIDE"
      },
      "block": {
        "id": 1551,
        "blockCode": "MVP",
        "tag": "Test MVP",
        "parentId": null,
        "parent": {
          "id": 1732,
          "clientCode": "MVPFL",
          "corporateName": "Test-FleetalityMVP",
          "taxIdentifier": "1788",
          "isParent": true
        }
      },
      "client": {
        "id": 1732,
        "clientCode": "MVPFL",
        "corporateName": "Test-FleetalityMVP",
        "isParent": true
      },
      "telemetryCapable": false,
      "documentDate": "2023-03-14"
    }
  ]
}

Atualizar Quilometragem com o ID do veículo

Submete uma nova coordenada de posicionamento e leitura de odômetro para o veículo correspondente ao ID informado no path da URL.

Endpoint: api/vehicles/{id}/update-km

Método: PUT

Headers: Content-Type: application/json

Exemplo de Payload de Envio (Request Body):

{
  "city": "Curitiba",
  "vehicleId": 11225,
  "longitude": -49.28226766428372,
  "latitude": -25.44234940722716,
  "mileage": 20003
}

Detalhe dos Campos de Entrada (Request Schema):

Campo	Tipo	Obrigatório	Descrição
`vehicleId`	integer	Sim	Deve corresponder exatamente ao ID numérico enviado na rota.
`mileage`	double	Sim	Novo valor acumulado do odômetro do veículo.
`latitude`	double	Sim	Coordenada geográfica de latitude do veículo no instante da leitura.
`longitude`	double	Sim	Coordenada geográfica de longitude do veículo no instante da leitura.
`city`	string	Não	Nome textual da cidade correspondente ao ponto físico da atualização.

Exemplo de Resposta (Status 200 OK):

{
  "message": "Quilometragem do veículo atualizada com sucesso.",
  "payLoad": {
    "id": 11225,
    "modelYear": 2023,
    "chassisNumber": "35715965478964455",
    "licensePlate": "SMI0604",
    "initialMileage": 14600,
    "firstMileage": 0,
    "telemetryCapable": true,
    "documentDate": "2025-08-26"
  },
  "warning": false
}

Eventos de Telemetria

Pesquisar Eventos de Telemetria

Consulta a lista paginada de todos os alertas técnicos cadastrados na base, permitindo filtros por termos textuais de código de falha.

Endpoint: api/telemetry-event/search

Método: POST

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
`page`	integer	Não	Índice de paginação inicial.
`size`	integer	Não	Quantidade máxima de registros a retornar na página.

Exemplo de Payload de Envio (Request Body):

{
  "code": "Brake"
}

Exemplo de Resposta (Status 200 OK):

{
  "content": [
    {
      "id": 1,
      "code": "ABS",
      "displayValue": "Sistema de Freios Antibloqueio (ABS)",
      "severityLevel": 0,
      "triggerServiceEvent": true
    },
    {
      "id": 3,
      "code": "BRAKE_FLUID",
      "displayValue": "Aviso de Fluido de Freio",
      "severityLevel": 0,
      "triggerServiceEvent": true
    },
    {
      "id": 4,
      "code": "BRAKE_LINING",
      "displayValue": "Aviso de Desgaste das Pastilhas de Freio",
      "severityLevel": 0,
      "triggerServiceEvent": true
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 15,
    "sort": [],
    "offset": 0,
    "unpaged": false,
    "paged": true
  },
  "last": true,
  "totalPages": 1,
  "totalElements": 3,
  "size": 15,
  "number": 0,
  "first": true,
  "numberOfElements": 3,
  "empty": false
}

Atualizar as informações do Alerta

Ajusta a criticidade e o comportamento operacional do recebimento de um sinal técnico de veículo por meio do seu ID relacional.

Endpoint: api/telemetry-event/{id}

Método: PUT

Headers: Content-Type: application/json

Exemplo de Payload de Envio (Request Body):

{
  "severityLevel": 2,
  "triggerServiceEvent": true
}

Detalhe dos Campos de Entrada (Request Schema):

Campo	Tipo	Obrigatório	Descrição
`severityLevel`	integer	Sim	Grau de relevância da falha no painel administrativo (0 a 5).
`triggerServiceEvent`	boolean	Sim	Determina se o disparo criará automaticamente uma manutenção.

Exemplo de Resposta (Status 200 OK):

{
  "id": 1,
  "code": "ABS",
  "displayValue": "Sistema de Freios Antibloqueio (ABS)",
  "severityLevel": 2,
  "triggerServiceEvent": true
}

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.

Códigos de Status HTTP

Status HTTP	Causa Provável	Ação Recomendada
200 OK	A leitura de dados de telemetria ou alteração foi processada com sucesso.	Continue com a leitura do payload de confirmação de envio.
400 Bad Request	Envio de coordenadas inválidas, dados nulos ou falha de regra lógica interna.	Revise os formatos de coordenadas de GPS e valide se o odômetro não possui valor inferior ao registro anterior do veículo.
401 Unauthorized	Token de autenticação inexistente ou expirado na requisição.	Obtenha uma nova credencial ativa de segurança com suas chaves de API e anexe ao cabeçalho.
403 Forbidden	Usuário/Integração sem autorização de acesso ao escopo de Telemetria.	Verifique se as permissões de telemetria de frotas estão ativas em sua conta.
404 Not Found	ID do veículo ou ID do evento de telemetria inexistente na base.	Certifique-se de que o ID interno do veículo consultado a partir da etapa do VIN ainda permanece ativo e válido.
500 Internal Server Error	Erro inesperado ao realizar o processamento nos servidores.	Capture os detalhes e tente realizar o envio novamente após um intervalo curto de tempo.

Dicas de Resolução de Problemas

Erro de Resolução de Chassi (VIN Não Encontrado): Caso a chamada ao endpoint /api/vehicles/filters retorne um array vazio ("content": []), certifique-se de que o VIN enviado não possui espaços em branco, hifens ou pontuações adicionais. O VIN precisa ter exatamente 17 caracteres alfanuméricos.
Coordenadas Fora de Posição: Certifique-se de enviar as coordenadas geográficas de latitude e longitude utilizando pontos decimais (ex: -25.442349) em vez de vírgulas. A passagem incorreta de tipos de dados gerará um erro do tipo 400 Bad Request antes mesmo do processamento da quilometragem.
Atualização Sequencial: Equipamentos de telemetria que disparam pulsos muito rápidos devem gerenciar a ordenação sequencial dos pacotes. Se um pacote com quilometragem inferior de um pulso de rede atrasado for enviado após uma atualização de maior valor, o pacote atrasado será rejeitado pela regra de integridade de odometria.