Integração HUB/FMS

Documentação detalhada online da API

Para garantir uma compreensão abrangente e facilitar a interação com nossas APIs, disponibilizamos a documentação detalhada que permite a visualização e interação direta com a API a partir de um navegador web.

Para acessar a documentação detalhada online da API, clique no link a seguir:

Frotas - Senior X Platform

Autenticação e Token

Para utilizar as API’s é necessário a autenticação, o que se aplica a todas as primitivas. Para isso, siga os manuais disponíveis nos links abaixo:

Requisições GET

Para requisições do tipo GET, não é necessário enviar inputs diretamente no corpo da requisição. Entretanto, é possível utilizar os campos como filtros e enviá-los como parâmetros na URL.

Por exemplo, a URL abaixo demonstra como aplicar filtros com query string em uma requisição de busca por abastecimentos de veículos:

platform.senior.com.br/t/senior.com.br/bridge/1.0/rest/FMS/frotas/apis/abastecimento?filter=placa eq '123' and dataAbastecimento eq '2024-01-24T09:00:00Z'

Neste exemplo, os parâmetros query parameters ou query params são usados como filtros, da placa e dataAbastecimento, diretamente na URL após o ponto de interrogação, permitindo que a API retorne resultados específicos com base nos critérios fornecidos.

Os parâmetros também são usados como filtros de página - Ex.: "size=10&offset=0", onde size representa a quantidade de registros (totalElements) e offset é o índice da página (totalPages).

Definição de FILTROS de consulta

Geralmente todos os campos aceitos no Inputs são considerados como filtros, exceto aqueles explicitamente documentados para não serem utilizados dessa forma. Não suportamos filtros no corpo da requisição (body), apenas com query parameters.

Definição de HEADERs

Atenção para a API veiculosLiberadosMotoristaTelemetria, que possui um header importante: X-Senior-Timeout, com valor máximo de 60, indicando o tempo de timeout. Caso não seja informado, o valor padrão será de 30 segundos.

Notificação de Inclusão de Alteração

Nosso sistema (envia a notificação) para um sistema receptor (que recebe a notificação) e precisa oferecer suporte a essa funcionalidade.

Evento Disparador: A Senior possui um cadastro de um conjunto definido de eventos que podem disparar um webhook. Estes eventos devem ser cadastrados antecipadamente.
Sistema Receptor: O sistema que deseja receber notificações via webhook deve fornecer a URL do endpoint que receberá as notificações, além dos dados de autenticação e segurança, caso necessário.

Para saber mais, clique no link abaixo:

Integração via Eventos - Events Hub | Senior X Platform APIs

As API's Veículos, Motoristas, Cartões x Veículos e Ordem de serviço possuem um fluxo de comunicação via webhooks, possibilitando sinalizar a existência de novos dados ao sistema parceiro.

APIs para recepção de Notificações

Quando houver a inserção ou atualização de um registro no módulo FMS, o Parceiro receberá informações do novo dado e poderá fazer uma chamada à API do FMS para obter os dados completos do cadastro correspondente.

Para cada API do FMS, o parceiro precisa implementar uma API própria que será responsável por receber as notificações enviadas pelo FMS para posterior consulta.
- Assim o parceiro precisa disponibilizar para cada Tipo de Evento (Veículos, Motoristas e Cartões x Veículos etc…), uma API do tipo POST que receba os campos LISTADOS nos EVENTs da documentação Frotas - Senior X Platform como entrada, correspondente ao tipo de evento;
- A autenticação suportada é Basic Auth ou autenticação (desaconselhado);
- As APIs de Notificação enviam apenas os campos chaves para que posteriormente possa ser realizada buscas em nossas APIs.

Importante!

O sistema receptor deve sempre nos enviar um status HTTP 200 após receber a mensagem, pois a notificação tem apenas o objetivo de informar. Isso ocorre porque nosso webhook funciona em fila, e, caso não receba o HTTP 200, realizará novas tentativas. No entanto, não enviará mensagens posteriores, enfileirando todo o processamento até receber uma confirmação de OK.

Rabbitmq

Para garantir que os serviços possam consumir os dados das filas do RabbitMQ, é essencial configurar o Shovel corretamente na plataforma e também no config de cada serviço.

Shovel: é um componente do RabbitMQ responsável por transferir mensagens entre diferentes filas, exchanges ou brokers. Ele atua como um conector, garantindo que as informações fluam conforme necessário dentro do ambiente integrado.

Como configurar o Shovel na Plataforma:

Acesse Tecnologia > Configuração > Por Tenant:
Preencha os campos destacados no exemplo a seguir:

Como configurar o Rabbit no config de cada serviço:

Será necessário preencher no config de cada serviço de integração, as informações do Rabbit em utilização para que o serviço saiba de qual Rabbit consumir as filas. Para isso, dentro do config, preencha as informações conforme exemplo abaixo:

QueueTimeToLive: Define o TTL das mensagens em milissegundos. Os valores permitidos são:
- 86400000 (Padrão): 24 horas.
- -1: TTL desativado (mensagens permanecem indefinidamente). - Máximo: 2147483647 milissegundos.
x-max-length: Propriedade opcional no JSON de SRV. Define o limite máximo de mensagens na fila.
- Se omitido, o valor padrão será 5000.
- Se configurado como -1, a fila não terá limite. - Valores acima de 2147483647 serão automaticamente ajustados para 5000.
QueueLimit: Configuração que lê o valor definido no JSON para ajustar a fila.

Para saber mais, confira o detalhamento técnico sobre Shovel e Rabbit nos links abaixo:

Processos

Telemetria:

Recebemos informações sobre a posição e eventos dos veículos;
Disponibilizamos uma lista de veículos e motoristas habilitados a dirigir;
Notificamos sobre inclusão ou alteração de: Veículos e funcionários.

Abastecimento:

Recebemos abastecimentos;
Disponibilizamos uma lista de cartões e veículos;
Notificamos sobre inclusão e alteração de: Funcionários e cartões de abastecimento.

Ordem de Serviço:

Recebemos as Peças , Serviços, Anexos e Alterações na situação da OS.
Disponibilizamos a Ordem de Serviço;
Notificamos sobre inclusão de: Ordem de serviço.

Multas:

Recebemos:
- Multas
- Acompanhamentos
- Anexos
Disponibilizamos uma lista de veículos liberados para monitoramento;
Notificamos sobre inclusão de: Veículos.

APIs Básicas

Item	Ações principais	Link da API
Abastecimento	Busca Abastecimentos enviados e Grava abastecimentos	GET\POST: /frotas/apis/abastecimento
Abastecimento	Lista cartões vinculados a veículos	GET: /frotas/apis/abastecimentoCartaoVeiculo
Telemetria	Envia eventos de telemetria	POST: /frotas/apis/telemetriaEvento
	Envia posições	POST: /frotas/apis/telemetria
	Busca veículos liberados por motorista.	GET: /frotas/apis/ veiculosLiberadosMotorista
Ordem de Serviço	Altera dados de OS	POST: /frotas/apis/alteraOrdemServico
	Enviar e alterar serviços de OS	POST: /frotas/apis/servicoExternoOrdemServico
	Enviar e alterar peças de OS	POST: / frotas/apis/pecaExternaOrdemServico
Multas	Envia/altera multa	POST/PUT: /frotas/apis/multaTransito
	Envia acompanhamentos de multas	POST: /frotas/apis/acompanhamentoMultaTransito
	API’s para envio de Anexos:	POST: /frotas/queries/obterUrlUploadAnexo POST: /frotas/apis/salvarAnexoOrdemServico
	Busca veículos liberados para monitoramento de multa de trânsito	GET: /frotas/apis/veiculosLiberadosMonitoramentoMultaTransito

Veja também a lista completa de APIs disponíveis:

Reprocessamento de Eventos de Ordens de Serviços

A rotina de Reprocessamento de Eventos de Ordens de Serviços (Reenvio de Webhook para Ordens de Serviço) tem o objetivo de garantir que fornecedores parceiros recebam corretamente as notificações de novas Ordens de Serviço, mesmo em caso de falhas no Webhook. Isso ajuda a prevenir atrasos operacionais e problemas na prestação de serviços.

Para o correto funcionamento da rotina, atualize o módulo GFV e o TMSXT para a versão 3.29.11 ou superior.

Como funciona?

A rotina permite a gestão dos registros de integração das Ordens de Serviço com o HUB/FMS. Caso um fornecedor não tenha recebido a notificação, é possível Reprocessar. Ao reprocessar, o sistema irá excluir e recriar o registro na tabela OfiOrdHub, garantindo o reenvio do evento.

Caminho da rotina: módulo GFV > Utilitários > Integração HUB/FMS > Reprocessamento de Eventos de Ordens de Serviços.

Campos da Tela:

Fornecedor: indica o fornecedor responsável pela OS. A edição deste campo é bloqueada após a integração;
Data Emissão: apresenta a data em que a OS foi emitida no sistema;
Data Integração HUB: apresenta a data em que a OS foi integrada ou reintegrada ao HUB/FMS;
Situação OS: opção que sempre estará marcada como Aberta para obrigar exibir todas as OS que ainda estão em aberto;
Protocolo Fornecedor: opção que sempre estará marcada como Não Recebido para obrigar a exibir todas as OS que foram enviadas ao hub, mas que não houve retorno de recebimento do fornecedor;
Reprocessar: permite reenviar eventos de OS para o HUB/FMS caso não tenham sido processados corretamente;
Integ. Hub: será exibida a data que foi integrado ou reprocessado;
OS: código da OS;
Código: código da empresa;
Empresa: descrição da empresa;
Inscrição: do fornecedor;
Fornecedor: descrição do fornecedor.

PORTAL DE DOCUMENTAÇÃO
Gestão de Frotas \| FMS - versão 3.32