Api de Rastreamento

1. Introdução

A API de Rastreamento é uma interface de programação que permite o acesso programático aos dados e funcionalidades do sistema de gerenciamento de frota GPSCorporativo. Esta API fornece endpoints REST para autenticação, monitoramento de veículos em tempo real, recuperação de históricos de percursos, telemetria avançada, envio de mensagens para dispositivos de bordo, e controle de atuadores do veículo.

A API utiliza o formato JSON para comunicação de dados e segue o padrão REST com métodos HTTP como GET e POST. Ela requer autenticação via login e implementa controles anti-abuso que limitam a frequência de requisições.

Esta documentação descreve uma coleção do Postman denominada "Testes", que contém requisições para interagir com a API do sistema de rastreamento GPSCorporativo. A coleção foi projetada para facilitar o teste e a integração com os serviços de rastreamento, monitoramento e comunicação com veículos através de uma interface REST.

Informações da Coleção do Postman

Nome da Coleção: Testes
ID Postman: 65270104-d3fd-4853-a9e9-6f3062fbfb22
Esquema: https://schema.getpostman.com/json/collection/v2.1.0/collection.json
Servidor Base: rastreamento.concept.inf.br (definido como variável de ambiente)
Base Path: /GPSCorporativo/rest/

2. Diagrama Conceitual do Sistema

                                  +------------------+
                                  |                  |
                                  |  Servidor API    |
                                  |  Rastreamento    |
                                  |                  |
                                  +--------+---------+
                                           |
                                           |
                         +----------------+------------------+
                         |                |                  |
                   +-----v------+  +------v------+  +-------v------+
                   |            |  |             |  |              |
                   | Sistema    |  | Aplicativo  |  | Integrações  |
                   | Web        |  | Motorista   |  | Externas     |
                   |            |  |             |  |              |
                   +-----+------+  +------+------+  +-------+------+
                         |                |                  |
                         |                |                  |
                   +-----v----------------v------------------v------+
                   |                                                |
                   |              Rastreadores                      |
                   |                  (Veículos)                  |
                   |                                                |
                   +------------------------------------------------+

O diagrama acima ilustra como os diferentes componentes do sistema GPSCorporativo se comunicam entre si. A API de Rastreamento atua como interface central que permite a comunicação bidirecional entre:

O Sistema Web (usado pelos gestores de frota)
O Aplicativo do Motorista (usado pelos condutores dos veículos)
Integrações Externas (sistemas de terceiros)
Os Rastreadores dos Veículos (que enviam dados de telemetria e recebem comandos)

Este fluxo de comunicação permite tanto o monitoramento quanto o controle remoto da frota.

3. Glossário Técnico

Termo	Definição
Rotograma	Planejamento detalhado de rota que inclui pontos de parada, tempos estimados e distâncias a percorrer.
Itinerário	Sequência ordenada de locais a serem visitados pelo veículo, com horários previstos.
Roteirização	Processo de planejamento e otimização de rotas para uma frota de veículos.
Telemetria	Conjunto de dados técnicos transmitidos pelo veículo, como velocidade, RPM, nível de combustível, etc.
Atuador	Dispositivo que controla mecanismos do veículo remotamente (ex: bloqueio de motor).
Ponto de Interesse (POI)	Local geograficamente definido que possui relevância para a operação.
Teclado	Dispositivo de bordo que permite comunicação bidirecional entre a central e o motorista.
JSESSIONID	Token de sessão usado para autenticação nas requisições após o login inicial.
Avisos	Notificações automáticas geradas pelo sistema (ex: excesso de velocidade, desvio de rota).
Identificador de Posição	Código único que identifica um registro específico de localização no sistema.

4. Arquitetura e Características Técnicas

4.1. Características Gerais

Tipo: REST API
Formato de Dados: JSON
Autenticação: Baseada em sessão (JSESSIONID)
Tempo da sessão: 60 segundos. Após 60 segundos, a sessão é expirada e precisa de uma nova autenticação.
Controle de Taxa: Implementado em todos os endpoints (rate limiting)
Versão Atual: 1.5 (Setembro 2024)

4.2. Controle Anti-Abuso

A API implementa um mecanismo de controle anti-abuso que limita as requisições por usuário:

Armazena timestamps das últimas requisições em um hashmap
Verifica o intervalo entre requisições (varia de 5 a 60 segundos dependendo do endpoint)
Retorna mensagem de erro se novas requisições forem feitas dentro do intervalo mínimo

4.3. Fluxo de Trabalho da API

Autenticação: O cliente deve primeiro se autenticar usando o endpoint de autenticação
Obtenção do Token de Sessão: Após autenticação bem-sucedida, um JSESSIONID é retornado
Chamadas às APIs: O cliente pode fazer chamadas aos diversos endpoints usando o JSESSIONID
Controle de Sessão: A sessão tem duração limitada e pode precisar ser renovada

5. Endpoints e Operações

5.1. Autenticação

Descrição: Autentica o usuário no sistema de rastreamento, obrigatório para utilização dos demais métodos.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/autenticar

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

Validações:

Retorno em caso de sucesso:

{
  "id": 123,
  "nome": "Nome do Cliente",
  "idVeiculo": 456,
  "idGrupoVeiculo": 789,
  "mensagemParaCliente": "Mensagem opcional para o cliente",
  "jsesionId": "ABC123XYZ"
}

Retorno em caso de erro:

{
  "id": 0
}

Instruções passo a passo:

Prepare os parâmetros login, senha e tipoAcesso
Envie uma requisição POST para o endpoint de autenticação
Armazene o valor de jsesionId retornado para utilizar nas próximas requisições
Inclua o jsesionId como cookie HTTP em todas as requisições subsequentes

5.2. Posição Atual dos Veículos

Descrição: Retorna a posição atual de todos os veículos associados ao usuário autenticado.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/rastrearVeiculos

Método: GET

Content-Type: application/x-www-form-urlencoded

Parâmetros: Nenhum (utiliza o JSESSIONID para identificação)

Validações:

Intervalo entre requisições deve ser superior a 30 segundos
Usuário deve estar autenticado

Retorno em caso de sucesso:

[
  {
    "idVeiculo": "123",
    "latitude": "-19.9322",
    "longitude": "-43.9352",
    "ignicao": "Ligado",
    "modelo": "F-4000",
    "tipoVeiculo": "CAMINHAOA",
    "velocidadeAtual": "60",
    "dataUltimaAtualizacao": "10:25 12/03/2025",
    "tempoParado": "00:00:00",
    "condutor": "João da Silva",
    "cpfCondutor": "123.456.789-00",
    "placa": "ABC1234",
    "ultimaLeituraSensorRS232": "Sensor data",
    "ultimoOdometro": "12345",
    "ultimoHorimetro": "987",
    "statusEntrada1": "false",
    "statusEntrada2": "true",
    "statusEntrada3": "false",
    "statusEntrada4": "false",
    "statusSaida1": "true",
    "statusSaida2": "false",
    "statusSaida3": "false"
  }
]

Retorno em caso de erro:

{
  "codigo": 99
}

Instruções passo a passo:

Certifique-se de estar autenticado e possuir um JSESSIONID válido
Envie uma requisição GET para o endpoint
Processe a lista de veículos retornada
Respeite o intervalo mínimo entre requisições (30 segundos)

5.3. Percursos Anteriores

Descrição: Recupera o histórico de percurso de um veículo específico em um intervalo de datas.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/rastrearVeiculoPorData

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String): Identificador do veículo
dataHoraInicio (String): Data e hora de início no formato YYYYMMDDHHmmss
dataHoraFim (String): Data e hora de fim no formato YYYYMMDDHHmmss
somenteParadas (String, opcional): "true" para retornar apenas paradas

Validações:

Intervalo entre requisições deve ser superior a 60 segundos
idVeiculo deve ser um número inteiro válido
Datas devem estar no formato YYYYMMDDHHmmss
dataHoraInicio deve ser anterior a dataHoraFim
O intervalo máximo permitido é de 7 dias

Retorno em caso de sucesso:

[
  {
    "indice": "1",
    "latitude": "-19.9322",
    "longitude": "-43.9352",
    "dataHoraGPS": "10:25 12/03/2025",
    "velocidadeAtual": "60",
    "odometro": "12345",
    "horimetro": "987",
    "tempoParado": "00:00:00",
    "ignicao": "Ligado",
    "descricaoPoI": "Nome do ponto de interesse"
  }
]

Retorno em caso de erro:

{
  "mensagem": "Mensagem de erro específica"
}

Instruções passo a passo:

Prepare os parâmetros idVeiculo, dataHoraInicio e dataHoraFim
Envie uma requisição POST para o endpoint
Processe a lista de pontos de rastreamento retornada
Atenção ao limite de 7 dias para o intervalo de pesquisa

5.4. Consulta de Posição por Identificador

Descrição: Recupera registros de rastreamento a partir de um identificador de posição para um ou mais veículos.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/rastrearPorIdentificador

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String, opcional): Identificador do veículo
identificadorPosicao (String): Identificador único da posição

Validações:

Intervalo entre requisições deve ser superior a 30 segundos
identificadorPosicao deve ser fornecido
Se idVeiculo for fornecido, deve ser um número inteiro

Retorno em caso de sucesso:

[
  [
    {
      "indice": "1",
      "idVeiculo": "123",
      "identificadorPos": "789012345",
      "latitude": "-19.9322",
      "longitude": "-43.9352",
      "dataRecebimentoGMT_3": "10:25 12/03/2025",
      "dataHoraGPSGMT_3": "10:24 12/03/2025",
      "velocidade": "60",
      "ignicao": "Ligado",
      "odometro": "12345",
      "horimetro": "987",
      "orientacao": "180"
    }
  ]
]

Retorno em caso de erro:

{
  "mensagem": "Mensagem de erro específica"
}

Instruções passo a passo:

Prepare o parâmetro identificadorPosicao (e opcionalmente idVeiculo)
Envie uma requisição POST para o endpoint
Processe a matriz de pontos de rastreamento retornada
Observe que o retorno é uma matriz de matrizes, com cada matriz interna representando um veículo

5.5. Consulta de Dados de Telemetria

Descrição: Recupera dados detalhados de telemetria de um veículo em um intervalo de datas.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/listarTelemetriaPorData

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String): Identificador do veículo
dataHoraInicio (String): Data e hora de início no formato YYYYMMDDHHmmss
dataHoraFim (String): Data e hora de fim no formato YYYYMMDDHHmmss

Validações:

Intervalo entre requisições deve ser superior a 30 segundos
Todos os parâmetros são obrigatórios
idVeiculo deve ser um número inteiro
Datas devem estar no formato YYYYMMDDHHmmss
dataHoraInicio deve ser anterior a dataHoraFim
O intervalo máximo permitido é de 7 dias

Retorno em caso de sucesso:

[
  {
    "indice": "1",
    "latitude": "-19.9322",
    "longitude": "-43.9352",
    "dataHoraGPS": "10:25 12/03/2025",
    "velocidadeAtual": "60",
    "odometro": "12345",
    "horimetro": "987",
    "ignicao": "Ligado",
    "rpm": "1800",
    "temperaturaMotor": "90",
    "combustivelUtilizado": "1.2",
    "nivelCombustivel": "45",
    "nivelCombustivelPercentual": "75",
    "pressaoPedalAcelerador": "80",
    "tempoEmMovimentoTotal": "120",
    "totalCombustivelUtilizado": "230.5",
    "totalCombustivelUtilizadoParado": "12.3",
    "pesoEixos": "2500",
    "informacaoTacografo": "Info do tacógrafo",
    "indicadores": "Indicadores diversos",
    "portaMotoristaAberta": "false",
    "portaPassageiroAberta": "false",
    "portaTraseiraEsquerdaAberta": "false",
    "portaTraseiraDireitaAberta": "false",
    "portaMalasAberto": "false",
    "caputAberto": "false",
    "cintoSegurancaLigado": "true",
    "arCondicionadoLigado": "true",
    "farolLigado": "true",
    "isExcessoVelocidade": "false",
    "corHexaFaixaRPM": "#00FF00",
    "pressaoOleoMotor": "3.5"
  }
]

Retorno em caso de erro:

{
  "mensagem": "Mensagem de erro específica"
}

Instruções passo a passo:

Prepare os parâmetros idVeiculo, dataHoraInicio e dataHoraFim
Envie uma requisição POST para o endpoint
Processe a lista de dados de telemetria retornada
Atenção ao limite de 7 dias para o intervalo de pesquisa

5.6. Listar Avisos por Veículo e Data

Descrição: Lista os avisos gerados por um veículo em uma data específica.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/listarAvisos

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String): Identificador do veículo
data (String): Data no formato YYYYMMDDHHmmss

Validações:

Intervalo entre requisições deve ser superior a 5 segundos
Ambos os parâmetros são obrigatórios

Retorno em caso de sucesso:

{
  "lista": [
    {
      "id": "123",
      "tipo": "ExcessoVelocidade",
      "tipoDescricao": "Excesso de Velocidade",
      "condutor": "João da Silva",
      "dataHora": "10:25 12/03/2025",
      "latitude": "-19.9322",
      "longitude": "-43.9352",
      "descricao": "Veículo ultrapassou o limite de velocidade",
      "dataHoraEnvioEmail": "10:26 12/03/2025"
    }
  ]
}

Retorno em caso de erro:

{
  "codigo": 99
}

Instruções passo a passo:

Prepare os parâmetros idVeiculo e data
Envie uma requisição POST para o endpoint
Processe a lista de avisos retornada
O retorno inclui um resumo e detalhes dos avisos no período

5.7. Acionar Atuadores

Descrição: Controla atuadores do veículo (bloqueio, saída 2 e saída 3).

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/acionarAtuadores

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String): Identificador do veículo
comando (String): Comando a ser enviado
senhaContato (String): Senha de contato para autorização

Comandos disponíveis:

Saída 1 (Bloqueio): "BLOQUEAR" / "DESBLOQUEAR"
Saída 2: "SPC_OUTPUT2_ACTIVATE" / "SPC_OUTPUT2_DESACTIVATE"
Saída 3: "SPC_OUTPUT3_ACTIVATE" / "SPC_OUTPUT3_DESACTIVATE"

Validações:

Intervalo entre requisições deve ser superior a 5 segundos
Todos os parâmetros são obrigatórios
Comando deve ser um dos valores permitidos

Retorno em caso de sucesso:

{
  "mensagem": "Comando enviado com sucesso"
}

Retorno em caso de erro:

{
  "codigo": 99
}

Instruções passo a passo:

Prepare os parâmetros idVeiculo, comando e senhaContato
Envie uma requisição POST para o endpoint
Verifique a mensagem de retorno para confirmar o envio
Aguarde pelo menos 5 segundos antes de enviar outro comando

5.8. Listar Mensagens do Teclado

Descrição: Recupera mensagens trocadas com o dispositivo de bordo (teclado).

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/listarMensagensTeclado

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String): Identificador do veículo
cpfMotorista (String, opcional): CPF do motorista
dataInicioMensagem (String, opcional): Data de início da mensagem (YYYYMMDDHHmmss)
dataFimMensagem (String, opcional): Data de fim da mensagem (YYYYMMDDHHmmss)
dataInicioRecebidaMensagem (String, opcional): Data de início do recebimento (YYYYMMDDHHmmss)
dataFimRecebidaMensagem (String, opcional): Data de fim do recebimento (YYYYMMDDHHmmss)

Validações:

Intervalo entre requisições deve ser superior a 5 segundos
idVeiculo é obrigatório
Pelo menos um conjunto de datas (mensagem ou recebimento) deve ser informado
Datas devem estar no formato correto

Retorno em caso de sucesso:

[
  {
    "placa": "ABC1234",
    "dataHora": "10:25 12/03/2025",
    "codigo": "123",
    "mensagem": "Texto da mensagem",
    "origem": "Motorista",
    "statusComandoMensagem": "Entregue",
    "odometroMensagem": "12345",
    "horimetroMensagem": "987",
    "latitudeMensagem": "-19.9322",
    "longitudeMensagem": "-43.9352",
    "localizacaoMensagem": "Av. Amazonas, 1234",
    "cpfMotorista": "123.456.789-00",
    "nomeMotorista": "João da Silva",
    "codigoIdentificaoLeitor": "XYZ123",
    "matriculaMotorista": "M1234"
  }
]

Retorno em caso de erro:

{
  "mensagem": "Mensagem de erro específica"
}

Instruções passo a passo:

Prepare o parâmetro idVeiculo e pelo menos um conjunto de datas
Envie uma requisição POST para o endpoint
Processe a lista de mensagens retornada
Observe que o veículo precisa estar associado ao cliente autenticado

5.9. Enviar Mensagem para Teclado

Descrição: Envia uma mensagem para o dispositivo de bordo (teclado) do veículo.

URL: http://rastreamento.concept.inf.br/GPSCorporativo/rest/enviarMensagemTeclado

Método: POST

Content-Type: application/x-www-form-urlencoded

Parâmetros:

idVeiculo (String): Identificador do veículo
mensagem (String): Texto da mensagem a ser enviada

Validações:

Intervalo entre requisições deve ser superior a 5 segundos
Ambos os parâmetros são obrigatórios

Retorno em caso de sucesso:

{
  "mensagem": "Mensagem enviada com sucesso"
}

Retorno em caso de erro:

{
  "codigo": 99
}

Instruções passo a passo:

Prepare os parâmetros idVeiculo e mensagem
Envie uma requisição POST para o endpoint
Verifique a mensagem de retorno para confirmar o envio
Aguarde pelo menos 5 segundos antes de enviar outra mensagem

6. Regras de Negócio e Validações

6.1. Regras Gerais

Autenticação e Autorização:
- Usuário deve estar autenticado para acessar qualquer endpoint (exceto o de autenticação)
- Usuário só pode acessar veículos associados à sua conta
- Existem dois tipos de acesso: "master" e "grupo"
Controle de Taxa de Requisições:
- Cada endpoint tem um limite de frequência de chamadas
- O IP e o login do usuário são usados para identificação
- Requisições feitas antes do intervalo mínimo são rejeitadas
Validação de Datas:
- Datas devem seguir o formato YYYYMMDDHHmmss
- Data inicial deve ser anterior à data final
- Intervalo máximo em consultas históricas é de 7 dias
- Datas são armazenadas e processadas em UTC mas exibidas em GMT-3
Formato de IDs e Parâmetros:
- IDs de veículos devem ser números inteiros
- Identificadores de posição devem ser números inteiros ou strings
- Comandos de atuadores devem ser um dos valores predefinidos

6.2. Validações Específicas

Bloqueio de Veículo:
- Requer senha de contato para autorização
- A operação é registrada em log para auditoria
- Limitado a uma operação a cada 5 segundos
Mensagens para Teclado:
- Tamanho da mensagem pode ser limitado pelo dispositivo de bordo
- Enviadas em tempo real quando o veículo está conectado
Consulta de Histórico:
- Opção para filtrar apenas paradas (economiza dados)
- Limite de 7 dias para evitar sobrecarga do sistema

7. Troubleshooting e Resolução de Problemas

7.1. Diagnóstico de Problemas Comuns

Problema	Possíveis Causas	Soluções
Autenticação sempre retorna 0	1. CPF ou CNPJ errados 2. Senha incorreta 3. Não informou os pontos, hífem e barra no CPF ou CNPJ	1. Informar o CPF e CNPJ com pontos, hífem e barra 2. Confirmar a senha na opções da plataforma WEB em Cofnguração -> Controle de Acesso 3. Verificar se o tipo usado é grupo para as senhas criadas no controle de aceso

7.2. Tabela de Códigos de Erro

Código	Descrição	Procedimento de Resolução
99	Usuário não autenticado ou sessão expirada	Realizar nova autenticação através do endpoint correspondente
101	Múltiplas requisições em intervalo proibido	Aguardar o tempo mínimo entre requisições para o endpoint específico
102	Parâmetros inválidos ou ausentes	Verificar documentação e corrigir parâmetros da requisição

7.3. Fluxogramas de Decisão

7.3.1. Diagnóstico de Falhas de Autenticação

[Início] → [Tentativa de Autenticação] → [Falha?]
    ↓ Sim                                 ↓ Não
[Credenciais Corretas?] → [Sessão Ativa] → [Fim]
    ↓ Não                ↓ Sim
[Corrigir Credenciais] [Aguardar 60 segundos desde última autenticação]
    ↓                    ↓
    └─────→ [Tentar Novamente] ───→ [Fim]

7.3.2. Resolução de Problemas de Rastreamento

[Início] → [Veículo visível no sistema?]
    ↓ Não                     ↓ Sim
[Última transmissão < 24h?] [Posição atualizada?]
    ↓ Não         ↓ Sim      ↓ Não       ↓ Sim
[Verificar      [Verificar  [Verificar  [Sistema
 equipamento]    conexão]    intervalo]   normal]
    ↓             ↓           ↓           ↓
    └─────────────┴───────────┴───────────→ [Fim]

8. Versões

Versão	Data de Lançamento	Principais Mudanças
1.5	Setembro 2024	Adicionado suporte para sensores adicionais de telemetria e melhorias na segurança
1.4	Março 2024	Implementada telemetria avançada e relatórios de consumo de combustível
1.3	Outubro 2023	Adicionado controle remoto de atuadores e comunicação bidirecional
1.2	Maio 2023	Melhorias na performance e suporte a múltiplos veículos por requisição
1.1	Janeiro 2023	Correções de bugs e expansão da documentação
1.0	Setembro 2022	Versão inicial com funcionalidades básicas de rastreamento

9. Limitações Conhecidas do Sistema

Intervalo de Consultas Históricas: Consultas de histórico são limitadas a um período máximo de 7 dias para evitar sobrecarga do sistema.
Frequência de Atualização: A posição atual dos veículos é atualizada conforme a configuração do dispositivo, tipicamente entre 30 segundos e 5 minutos.
Conexão com Dispositivos: Comandos enviados para veículos só são processados quando o dispositivo está online e com conectividade.
Tamanho de Mensagens: Mensagens enviadas para o teclado do motorista são limitadas a 160 caracteres por limitações de hardware.
Simultaneidade de Comandos: O sistema não permite o envio simultâneo de múltiplos comandos para o mesmo veículo. É necessário aguardar a confirmação do primeiro comando.
Retenção de Dados: Os dados históricos detalhados ficam disponíveis por até 5 anos. Depende do plano contratado pelo cliente. Após esse período,os dados são apagados.
Precisão Geográfica: A precisão da localização depende do dispositivo GPS instalado no veículo e das condições ambientais, podendo variar entre 2 e 15 metros.
Compatibilidade de Navegadores: A interface web é otimizada para Chrome, Firefox e Edge. Outros navegadores podem apresentar limitações visuais.
Atuação em Áreas sem Cobertura: Veículos em áreas sem cobertura móvel não receberão comandos até retornarem a uma área com sinal.

10. Perguntas Frequentes (FAQ)

Como obtenho o identificador (ID) de um veículo?
- O ID do veículo pode ser obtido através do endpoint "Posição Atual dos Veículos" ou ao realizar a autenticação, caso o usuário tenha um veículo único associado.
Quanto tempo dura uma sessão após autenticação?
- A sessão tem duração de 60 segundos conforme documentado na seção 4.1. Após esse período, é necessário autenticar-se novamente.
Por que recebo um erro de "múltiplas requisições"?
- Cada endpoint tem um limite de frequência de chamadas. Você deve respeitar o intervalo mínimo entre requisições (de 5 a 60 segundos, dependendo do endpoint).
Como enviar um comando de bloqueio/desbloqueio de veículo?
- Utilize o endpoint "Acionar Atuadores" com o parâmetro comando igual a "BLOQUEAR" ou "DESBLOQUEAR" e forneça a senha de contato para autorização.
Quais formatos de data são aceitos pela API?
- A API aceita apenas datas no formato YYYYMMDDHHmmss (exemplo: 20250312102530 para 12/03/2025 10:25:30).
Por que minha consulta de histórico retorna "Rota máxima pesquisável é no intervalo de 7 dias"?
- Para evitar sobrecarga do sistema, as consultas de histórico estão limitadas a um intervalo máximo de 7 dias.
O que significa o código de erro 99?
- O código 99 indica que o usuário não está autenticado ou que a sessão expirou.
Como faço para consultar os avisos de um veículo?
- Utilize o endpoint "Listar Avisos por Data" fornecendo o ID do veículo e a data desejada.
Posso monitorar múltiplos veículos simultaneamente?
- Sim, o endpoint "Posição Atual dos Veículos" retorna informações de todos os veículos associados ao usuário autenticado.
Quais dados de telemetria estão disponíveis?
- A API fornece dados detalhados como velocidade, RPM, temperatura do motor, nível de combustível, estado das portas, uso do cinto de segurança, entre outros.
O que fazer quando um veículo não aparece no mapa?
- Verifique se o dispositivo está ligado, se o veículo tem permissão associada ao seu usuário e consulte a última transmissão para determinar se há problemas de conectividade.
Como resolver erros de sincronização no aplicativo do motorista?
- Verifique a versão do aplicativo, a conexão de internet do dispositivo e tente limpar o cache. Se persistir, reinstale a aplicação.
Por que o roteirizador não está considerando todas as restrições configuradas?
- Verifique se não há conflitos entre restrições e se todas estão corretamente configuradas. Algumas restrições podem ter precedência sobre outras.
Como posso saber se um comando foi recebido pelo veículo?
- Os comandos enviados são registrados no sistema e você pode verificar o status através do histórico de comandos na interface web ou consultando os logs do sistema.

11. Exemplos de Implementação

11.1. Exemplo de Rastreamento em Tempo Real

// Exemplo de código JavaScript para rastreamento em tempo real
async function monitorarVeiculosEmTempoReal() {
    // 1. Autenticar no sistema
    const credenciais = {
        login: "empresa@exemplo.com.br",
        senha: "senhaSegura123",
        tipoAcesso: "grupo"
    };
    
    const respAuth = await fetch('http://rastreamento.concept.inf.br/GPSCorporativo/rest/autenticar', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: new URLSearchParams(credenciais)
    });
    
    const authData = await respAuth.json();
    const jsessionId = authData.jsesionId;
    
    // 2. Configurar intervalo para atualização a cada 30 segundos
    setInterval(async () => {
        // 3. Obter posição atual dos veículos
        const respVeiculos = await fetch('http://rastreamento.concept.inf.br/GPSCorporativo/rest/rastrearVeiculos', {
            method: 'GET',
            headers: {
                'Cookie': `JSESSIONID=${jsessionId}`
            }
        });
        
        const veiculos = await respVeiculos.json();
        
        // 4. Processar e exibir os dados
        veiculos.forEach(veiculo => {
            console.log(`Veículo ${veiculo.placa} - Posição: ${veiculo.latitude},${veiculo.longitude}`);
            console.log(`Velocidade: ${veiculo.velocidadeAtual} km/h - Status: ${veiculo.ignicao}`);
            
            // Aqui você adicionaria código para atualizar um mapa ou interface
        });
    }, 30000); // 30 segundos
}

monitorarVeiculosEmTempoReal();

11.2. Exemplo de Análise Histórica

// Exemplo de código JavaScript para análise histórica de percurso
async function analisarPercursoHistorico(idVeiculo, dataInicio, dataFim) {
    // 1. Autenticar no sistema
    const credenciais = {
        login: "empresa@exemplo.com.br",
        senha: "senhaSegura123",
        tipoAcesso: "grupo"
    };
    
    const respAuth = await fetch('http://rastreamento.concept.inf.br/GPSCorporativo/rest/autenticar', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: new URLSearchParams(credenciais)
    });
    
    const authData = await respAuth.json();
    const jsessionId = authData.jsesionId;
    
    // 2. Consultar histórico de percurso
    const params = {
        idVeiculo: idVeiculo,
        dataHoraInicio: dataInicio, // Formato: YYYYMMDDHHmmss
        dataHoraFim: dataFim,       // Formato: YYYYMMDDHHmmss
        somenteParadas: "false"
    };
    
    const respHistorico = await fetch('http://rastreamento.concept.inf.br/GPSCorporativo/rest/rastrearVeiculoPorData', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/x-www-form-urlencoded',
            'Cookie': `JSESSIONID=${jsessionId}`
        },
        body: new URLSearchParams(params)
    });
    
    const historico = await respHistorico.json();
    
    // 3. Processar os dados históricos
    let distanciaTotal = 0;
    let tempoMovimento = 0;
    let tempoParado = 0;
    
    for (let i = 1; i < historico.length; i++) {
        const pontoAtual = historico[i];
        const pontoAnterior = historico[i-1];
        
        // Calcular distância entre pontos (exemplo simplificado)
        const distancia = calcularDistanciaEntrePontos(
            pontoAnterior.latitude, pontoAnterior.longitude,
            pontoAtual.latitude, pontoAtual.longitude
        );
        
        distanciaTotal += distancia;
        
        // Analisar tempos de movimento e parada
        if (pontoAtual.velocidadeAtual > 0) {
            tempoMovimento++;
        } else {
            tempoParado++;
        }
    }
    
    // 4. Retornar análise
    return {
        idVeiculo: idVeiculo,
        periodo: {
            inicio: dataInicio,
            fim: dataFim
        },
        pontos: historico.length,
        distanciaTotal: distanciaTotal.toFixed(2) + " km",
        tempoMovimento: formatarTempo(tempoMovimento),
        tempoParado: formatarTempo(tempoParado),
        velocidadeMedia: (distanciaTotal / tempoMovimento * 3600).toFixed(2) + " km/h"
    };
}

// Funções auxiliares
function calcularDistanciaEntrePontos(lat1, lon1, lat2, lon2) {
    // Implementação da fórmula de Haversine para cálculo de distância
    // entre coordenadas geográficas
    // Código simplificado para o exemplo
    return 0.5; // km
}

function formatarTempo(minutos) {
    const horas = Math.floor(minutos / 60);
    const min = minutos % 60;
    return `${horas}h ${min}min`;
}

// Exemplo de uso
analisarPercursoHistorico(
    "3375",
    "20250310000000", // 10/03/2025 00:00:00
    "20250310235959"  // 10/03/2025 23:59:59
).then(analise => {
    console.log("Análise do percurso histórico:", analise);
});

12. Referências Cruzadas

Componente	Documentação Relacionada	Seção Relevante
Sistema Web	Manual do Sistema Web	Capítulo 4: Monitoramento de Frota
Aplicativo do Motorista	Guia do Aplicativo	Seção 2.3: Comunicação com a Central
Roteirizador	Manual do Roteirizador	Capítulo 5: Integração com Rastreamento
API de Integração	Documentação de Integração	Seção 3.1: Autenticação e Segurança

Vínculos entre Componentes e Funcionalidades

Monitoramento em Tempo Real: Para implementações avançadas de monitoramento em tempo real, consulte a seção 5.2 deste documento e a seção 4.2 do Manual do Sistema Web.
Roteirização com Rastreamento: Para otimizar rotas com base em dados históricos, consulte a seção 5.3 deste documento e o Capítulo 3 do Manual do Roteirizador.
Comunicação com Motoristas: Para configurar mensagens e alertas automáticos, consulte as seções 5.8 e 5.9 deste documento e a Seção 2.3 do Guia do Aplicativo.
Telemetria e Manutenção Preventiva: Para implementar manutenção baseada em dados de telemetria, consulte a seção 5.5 deste documento e o Capítulo 6 do Manual do Sistema Web.

13. Representações Estruturadas das Entidades

13.1. Estrutura de Veículo (JSON)

{
  "id": 3375,
  "placa": "ABC1234",
  "tipo": "CAMINHAOA",
  "modelo": "F-4000",
  "ano": 2022,
  "chassi": "9BFFT35P3CD123456",
  "capacidade": {
    "peso": 3500,
    "volume": 24,
    "passageiros": 3
  },
  "dispositivo": {
    "id": 98765,
    "modelo": "GP1500",
    "imei": "123456789012345",
    "dataInstalacao": "20230215"
  },
  "telemetria": {
    "sensores": [
      "rpm",
      "temperatura",
      "combustivel",
      "pressao_oleo",
      "cinto",
      "portas"
    ],
    "intervaloPadrao": 30,
    "intervaloParado": 300
  },
  "limites": {
    "velocidadeMaxima": 80,
    "rpmMaximo": 2500,
    "horasOperacao": 12
  }
}

13.2. Estrutura de Motorista (JSON)

{
  "id": 1234,
  "nome": "João da Silva",
  "cpf": "123.456.789-00",
  "matricula": "M1234",
  "cnh": {
    "numero": "12345678900",
    "categoria": "D",
    "validade": "20260531"
  },
  "contato": {
    "telefone": "11999998888",
    "email": "joao.silva@email.com"
  },
  "acessoApp": {
    "login": "joao.silva",
    "ultimoAcesso": "20250311103045",
    "versaoApp": "2.3.7"
  },
  "veiculoAtual": 3375,
  "status": "EmRota"
}

13.3. Estrutura de Rota (JSON)

{
  "id": 5678,
  "nome": "Entrega Centro - 12/03/2025",
  "veiculo": 3375,
  "motorista": 1234,
  "status": "EmAndamento",
  "criacao": "20250311153045",
  "inicio": {
    "planejado": "20250312080000",
    "real": "20250312075532"
  },
  "fim": {
    "planejado": "20250312180000",
    "real": null
  },
  "paradas": [
    {
      "ordem": 1,
      "cliente": "Empresa A",
      "endereco": "Av. Amazonas, 1234",
      "coordenadas": {
        "latitude": -19.9322,
        "longitude": -43.9352
      },
      "horario": {
        "planejado": "20250312090000",
        "previsto": "20250312092500",
        "real": "20250312093012"
      },
      "status": "Concluido"
    },
    {
      "ordem": 2,
      "cliente": "Empresa B",
      "endereco": "Rua dos Carijós, 456",
      "coordenadas": {
        "latitude": -19.9182,
        "longitude": -43.9372
      },
      "horario": {
        "planejado": "20250312110000",
        "previsto": "20250312114500",
        "real": null
      },
      "status": "EmAndamento"
    }
  ],
  "metricas": {
    "distanciaPlanejada": 28.5,
    "distanciaPercorrida": 15.7,
    "consumoPlanejado": 8.5,
    "consumoReal": 9.2
  }
}