Exibir origem

CONTEÚDO

01. INTEGRAÇÃO OFERTAS DE FRETE - SIGATMS X FRETEBRAS

A solução FreteBras é uma plataforma que disponibiliza ofertas de carga para caminhoneiros autônomos, através da publicação dos anúncios de frete das empresas assinantes. O caminhoneiro visualiza as cargas próximas em seu Smartphone e entra em contato com a empresa anunciante para negociar diretamente o frete, sem intermediários.

A FreteBras não participa diretamente do fechamento das negociações! Ela, portanto, não monetiza sobre as transações efetuadas (match). Na prática funciona como um grande portal de classificados! Elimina agentes tradicionais de frete do processo, no entanto não faz a conexão entre as partes.

Com a base expressiva de empresas e motoristas conquistada, e as facilidades oferecidas por suas ferramentas, tornou-se referência neste mercado.

Diante deste cenário o módulo Gestão de Transportes (SIGATMS) uniu a sua expertise em gestão de transporte com a solução Fretebras para que transportadores, embarcadores em geral, e agenciadores publiquem suas ofertas de frete, tendo como objetivo a negociação de motoristas autônomos e até mesmo transportadores (Pessoa jurídica). Após a publicação da oferta diretamente pelo módulo Gestão de Transportes (SIGATMS), a oferta de frete estará vinculada a um viagem planejada, e todas as operações das Ofertas de Frete serão realizadas dentro do módulo: Inclusão, Alteração, Renovação, Concretização e Exclusão.

Dessa maneira, ganha-se agilidade ao vincular as viagens planejadas (tipo 3=Planejada) e ofertas de frete.

O módulo passa a utilizar as APIs fornecidas pela Fretebras para solucionar e consumir os serviços da plataforma:

Autenticação - Obter Token de acesso - POST- /oauth/token
Veículos - Lista tipos de veículos - GET - v1/veículos/tipos
Carrocerias - Lista carrocerias de veículos - GET - v1/veiculos/carrocerias
Espécies - Lista espécies de carga - GET - v1/especies
Tipos de preço - Lista os tipos de preço - GET - v1/tipos/precos
Criar frete - Cria oferta de frete por assinante- POST - v1/assinantes/fretes
Altera frete - Altera uma oferta de frete - PUT - /v1/assinantes/fretes/{id}
Deleta frete - Deleta uma oferta de frete - DELETE - /v1/assinantes/fretes/{id}
Renovar frete - Renova uma oferta de frete - PUT - /v1/assinantes/fretes/{id}/renovar
Fechar Frete - Concretiza uma oferta de frete - POST - /v1/assinantes/fretes/{id}/concretizar

02. SISTEMAS ENVOLVIDOS

SIGATMS - As funcionalidades e rotinas que estão envolvidas no processão são: Cadastro de Clientes, Cadastro de Solicitante, Cadastro de Sequência de Endereço, Cadastro de Referências Geográficas, Viagem, Cadastro Roteirizador, Limpeza de Histórico de Integração.
MAPLINK - As APIs envolvidas são: GeoCode, Planning, Trip, Tolls e Map Display. Para obter mais informações, acesse: https://maplink.global/apis-maplink/

03. INTEGRAÇÃO

A integração tem como objetivo otimizar o processo de entrega e/ou coleta dos transportadores que utilizam o módulo SIGATMS.

Para que toda a solução funcione perfeitamente é necessário obter as coordenadas geográficas de todos os clientes, de acordo com os respectivos endereços. Para isso utilizamos a api GeoCode que retorna a latitude e longitude de acordo com o endereço enviado. As informações recebidas são gravadas no Cadastro de Referências Geográficas.

Os documentos serão ordenados na viagem, de acordo com a melhor sequência de entrega/coleta sugerida pela a api Planning.

Após obtido a melhor sequência de entrega/coleta a api Trip sugere a melhor rota para o veículo realizar, de acordo com a melhor sequência de entrega/coleta.

De acordo com a rota sugerida, obtém-se os gastos com pedágio de acordo com a quantidade de eixos dos veículos, através da api Tolls, e os valores de pedágio são atualizados automaticamente dentro da viagem.

Toda a visualização dos pontos de entrega/coleta, rota e praças de pedágio serão exibidas dentro do SIGATMS em um mapa, através da funcionalidade Map Display.

04. ESCOPO

A comunicação com as APIS e plataforma Maplink ocorreram a partir das rotinas: Cadastro de Clientes, Sequência de Endereço, Cadastro de Solicitantes e Wizard para envio das filiais (Cadastro de referências geográficas) para a api GeoCode; e também a partir das Viagens em Aberto para as apis Planning, Trip, Tolls e MapDisplay (Plotagem de mapas).

As informações enviadas serão detalhadas abaixo.

Foram criadas novas funcionalidades no SIGATMS para complementar e auxiliar na integração como um todo:

Cadastro Roteirizador: Foi criado o cadastro para armazenar as informações referente a integração como client_id, client_secret, app_id, app_code, URL Callback, URL Mapa e etc.. Muitos desses dados serão fornecidos pela MapLink. É possível também definir o tipo de retorno que a Maplink irá fornecer, pode-se optar pelo retorno por callback (webservice rest), em que o SIGATMS irá aguardar as respostas automaticamente. Ou pode-se realizar a integração via Ações Relacionadas no menu da viagem.
Consulta Histórico de Integração: As informações trafegadas pelas apis: planning, trip e tolls serão armazenadas na tabela DLU - Histórico de Integração.
Limpeza do Histórico de Integração: Criado a funcionalidade para eliminar fisicamente as informações referente ao histórico de integração.
Bloqueio de Viagem: Criado o bloqueio RT - Roteirizador, para ser acionado durante o fechamento da viagem, caso as respostas das apis ainda não tenham sido recebidas.
Gravação da viagem: Ao utilizar a integração com o tipo de retorno = Callback, as informações para a planning, serão enviadas automaticamente ao final da gravação da viagem.
Webservice REST WSTMSMapLink: Criado webservice REST para subir o serviço que ficará aguardando o callback da Maplink.
Cadastro de Referências Geográficas: Criado o Wizard de Filiais para que a api Geocode seja acionada a partir dos endereços das filiais do sistema.
Plotagem do mapa: Plota o mapa tmsshowrota.html após o processamento completo das apis: planning, trip e tolls.
Viagem em Aberto: O envio de informações pode ser apenas realizado para viagens cujo status esteja em aberto.

Linha Microsiga Protheus > Integração SIGATMS X Fretebras (Integrações - SIGATMS) > image2019-8-22_11-33-57.png

IMPORTANTE!

Não é escopo desse documento descrever a instalação do ERP Protheus, nem suas configurações básicas.
Para utilização da integração, o módulo SIGATMS na versão 12.1.23 (ou superior) do Protheus deve estar com o ambiente atualizado com a última versão de RPO e o dicionário disponível na Central de Downloads TOTVS.
Para obter mais informações sobre como atualizar o dicionário de dados do Protheus 12, clique aqui.
A inteligência para fornecimento das melhores rotas e/ou sequência de entrega/coleta é responsabilidade da MapLink.
Deve-se preencher corretamente as informações país, estado, cidade, bairro, endereço e cep. O preenchimento incorreto dos campos ocasionará em coordenadas geográficas erradas e/ou inexistentes.
- Deve-se preencher corretamente as informações citadas acima para:
  - Cadastro de filiais;
  - Cadastro de clientes;
  - Sequência de endereço;
  - Cadastro de solicitantes;
Deve-se preencher corretamente as informações capacidade máxima, volume máximo, altura externa, comprimento externo e largura externa do cadastro de veículos. O preenchimento incorreto dos campos ocasionará falhas de integração e/ou inconsistência no cálculo das APIs.

05. PRÉ-REQUISITOS PARA INSTALAÇÃO/IMPLANTAÇÃO/UTILIZAÇÃO

Premissas para o correto funcionamento:

Protheus versão 12.1.23 ou superior.
Build superior à 131217A.
Dicionário de dados atualizado com tabelas referente a integração.
Repositório de dados atualizado com programas referente a integração;
Servidor de WebService deve estar corretamente configurado.
Servidor REST deve estar corretamente configurado.
Módulo SIGATMS deve estar corretamente configurado.
Possuir licenças Maplink.
Parâmetro de integração MV_ROTAINT habilitado.
Arquivos HTML
- Os arquivos html (tmsshowrota.html, pedagio.png, tmsimg32.png e totvstec.js) devem estar na pasta definida na seção HTTP, tag PATH do appserver.ini.
Menu SIGATMS.xnu atualizado.

06. INSTALAÇÃO/ATUALIZAÇÃO

Este tópico tem por objetivo orientar a instalação da integração, visando o seu funcionamento completo. Instalação de produtos ou ferramentas necessárias podem referenciar outros documentos existentes, desde que estejam disponíveis no repositório de documentação da TOTVS ou sejam enviados junto com o documento da integração em si.

As informações mínimas necessárias para teste do tópico são:

Execute a rotina UPDDISTR - Atualizador de dicionário e base de dados - UPDDISTR.
Configure o servidor REST - 01. Configuração.
Configure o serviço de WebService - Configurar Portais e Webservices.
Os arquivos tmsshowrota.html, pedagio.png, tmsimg32.png e totvstec.js devem estar na pasta definida na seçao http, tag path do appserver.ini.
Habilite o parâmetro mv_rotaint.
Atualize o menu sigatms.xnu.

07. PROTHEUS

No módulo SIGATMS acesse o menu Cadastro > Roteirizador > Config. Integração (TMSAO52) para acessar o Cadastro de Roteirizador.

Clique em Incluir;
No campo ID Cliente informe o client_id fornecido pela Maplink;
No campo Cliente Secret informe o client_secret fornecido pela Maplink;
No campo Tempo Token preencha com o tempo que o token irá expirar;
- Pode-se preencher com 00:59;
No campo URL CallBack informe a URL do servidor REST com o endpoint WSTMSMaplink;
- Exemplo: http://localhost:8091/rest/api/tms/v1/wstmsmaplink;
No campo URL Mapa informe a URL do webservice aonde encontra-se o arquivo tmsshowrota.html;
- Exemplo: http://localhost:8020/ws/tmsshowrota.html;
No campo App ID GeoCode informe o app_id fornecido pela Maplink para consumo da api GeoCode;
No campo App Code GeoCode informe o app_code fornecido pela Maplink para consumo da api GeoCode;
No campo Tipo de Retorno informe:
- 1=Callback para o retorno da solução MapLink ocorrer através do servidor Rest e o envio ser realizado ao final da gravação da viagem de maneira automática;
- 2=Aguardar retorno roteirizador para o acesso e envio de informações Maplink ser realizado apenas via menu;

No módulo SIGATMS acesse o menu Diversos > Limpeza Histórico Roteirizador (TMSAO53) para acessar a rotina Limpeza de Histórico.

Clique em Perguntas para filtrar a limpeza do histórico (DLU) de acordo com o número da viagem;
Clique em Informações e Executar para excluir fisicamente os registros;

08. FLUXO DAS INFORMAÇÕES

09. CADASTROS

GEOCODE

As rotinas Cadastro de Cliente, Sequência de Endereço e Cadastro de Solicitantes foram atualizadas para que ao final da gravação as informações referentes ao endereço sejam enviadas automaticamente para a api GeoCode a fim de obter as coordenadas geográficas do respectivo endereço. As coordenadas geográficas recebidas são gravadas na tabela DAR - Referência Geográficas, e é possível visualiza-las através da rotina Cadastro de Referências Geográficas - TMSAO15.Envio:

País;
Estado;
Cidade;
Bairro;
Rua;
Número;
CEP;

As informações recebidas são:

Latitude;
Longitude;

10. INTEGRAÇÃO

PLANNING

O objetivo da integração com a API Planning é otimizar os pontos de entrega/coleta e reordenar os documentos da viagem.

A rotina de viagem foi alterada para que quando o campo Tipo de Retorno (DLV_TIPRET) da tabela Dados Cadastrais Roteirizador (DLV) esteja igual a 1=CallBack; a informações sejam enviadas automaticamente para a api Planning.

Pode-se também acionar a rotina a partir do menu criado na rotina Viagem (TMSA144): Ações Relacionadas > Roteirizador > Integra.

Envio:

callback
- Endpoint em que se encontra o serviço Rest - O endpoint deverá ser incluído no Cadastro Roteirizador (TMSAO52), campo URL CallBack (DLV_URLCAL);
logisticconstraints
- Duração em tempo das operações de transporte (DTW);
  - DC6_DURAC é o campo que contém a duração das operações de transporte;
  - As operações enviadas são:
    - Chegada de Viagem - MV_ATIVCHG;
    - Saída de Viagem - MV_ATIVSAI;
    - Chegada em Cliente - MV_ATVCHGC;
    - Saída do Cliente - MV_ATVSAIC;
    - Descarregamento - MV_ATIVDCA;
depots
- Coordenadas geográficas do endereço da filial (SM0);
legislationprofiles
- "DEFAULT";
operations
- Informações dos documentos de entrega/coleta;
  - Número do documento;
  - Destinatário;
  - Prioridade;
  - Produto;
  - Tipo : DELIVERY ou COLLECTION;
  - Local de origem: Filial;
  - Peso;
  - Volume;
products
- Produtos enviados nas notas fiscais;
sites
- Coordenadas geográficas do endereços dos destinatários (Cliente, Solicitante ou Sequência de endereço);
vehicletypes
- Volume máximo do veículo da viagem - DA3_VOLMAX;
- Capacidade máxima do veículo da viagem - DA3_CAPACM;
- Tamanho do veículo - DA3_COMEXT;
vehicles
- Legislação vigente: "DEFAULT";
- Janela de disponibilidade
  - Data atual;
  - Hora atual;
  - 1 dia após a data atual;
  - "23:59";
- Local de origem: Filial;
- Local de chegada: Filial;
- Máximo de rotas: 1;
optmizationprofile: "BRAZIL37";
tripsprofile: "BRAZIL";

TRIP

O objetivo da integração com a api Trip é roteirizar os pontos de entrega/coleta e sugerir a melhor rota.

Envio:

points
- Coordenadas geográficas dos destinatários;
profilename: "BRAZIL";
calculationmode - De acordo com a opção Modo de Cálculo (mv_par02) informado nas propriedades do roteirizador (Pergunte TMSAO46): Acesse a rotina Cadastro Roteirizador (TMSAO52) > Outras Ações > Propriedades Roteirizador;
- 1=THE_FASTEST - Indica que a rota deverá ser calculada considerando o caminho mais rápido;
- 2=THE_SHORTEST - Indica que a rota deverá ser calculada considerando o caminho mais curto;
callback
- Endpoint em que se encontra o serviço Rest - O endpoint deverá ser incluído no Cadastro Roteirizador (TMSAO52), campo URL CallBack (DLV_URLCAL);
startdate: Data e Horário atual;
useRealSpeeds - De acordo com a opção User velocidade real? (mv_par03) informado nas propriedades do roteirizador (Pergunte TMSAO46): Acesse a rotina Cadastro Roteirizador (TMSAO52) > Outras Ações > Propriedades Roteirizador;
- 1 = true - Indica que deverá considerar o histórico de velocidade para o mesmo dia da semana e horário;
- 2 = false - Indica que deverá considerar a velocidade da via;
vehiclespecification - Informações dos veículos
- Altura máxima: DA3_ALTEXT;
- Comprimento máximo: DA3_COMEXT;
- Máxima distância entre eixos: DA3_COMEXT;
- Capacidade máxima: DA3_CAPACM;
- Capacidade máxima para materiais perigosos: DA3_CAPACM;
- Capacidade máxima para materiais explosivos: DA3_CAPACM;
- Capacidade máxima para materiais poluentes: DA3_CAPACM;
- Capacidade máxima por eixo: DA3_CAPACM / DTR_QTDEIX;
- Largura máxima: DA3_LAREXT;

TOLLS

A API Tolls fornece os valores e as praças de pedágio que existem no percurso da rota. Após obter os valores de pedágio dentro do complemento da viagem (DTR_VALPDG).

Envio:

legs
- Rota e percurso calculado pela api TRIP;
- Eixos - De acordo com a opção Calcula retorno filial? (mv_par01) informado nas propriedades do roteirizador (Pergunte TMSAO46): Acesse a rotina Cadastro Roteirizador (TMSAO52) > Outras Ações > Propriedades Roteirizador :
  - 1=Sim - É enviada a quantidade de eixos (DTR_QTDEIX) e após a última entrega/coleta é adicionado um novo trecho retornando a filial e nesse último trecho é utilizado a quantidade de eixos do campo (DTR_QTDEIXV);
  - 2=Não - É enviada a quantidade de eixos (DTR_QTDEIX);
source: DEFAULT;

MAPDISPLAY

Essa funcionalidade permite a exibição do mapa e os pontos de coleta/entrega. O mapa será exibido quando todas as etapas da integração citadas acima forem concluídas com sucesso.

O mapa pode ser consultado a partir da rotina Viagem > Outras Ações > Roteirizador > Consulta (TMSAO50) após entrar na rotina Controle Integração TMS X Roteirizador acesse a opção Outras Ações > Vis. Mapa.

Linha Microsiga Protheus > Integração SIGATMS X Fretebras (Integrações - SIGATMS) > image2019-8-21_16-6-1.png

11. LIMITAÇÕES/RESTRIÇÕES GERAIS

A integração ocorrerá somente quando o parâmetro MV_ROTAINT estiver habilitado.

Além disso, é necessário que esteja cadastrado e configurado corretamente:

GEOCODE

Cadastro de Cliente envia requisição para API Geocode.
Sequência de Endereço envia requisição para API Geocode.
Cadastro de Solicitantes envia requisição para APIGeocode.
Wizard de filiais envia requisição para API Geocode.

A API deverá retornar as coordenadas geográficas, retornando corretamente as informações apenas se os cadastros estiverem com os campos: país, estado, cidade, bairro, rua, número e CEP preenchidos corretamente.

PLANNING

O envio de informações e tratamento das informações poderá ser realizado de duas maneiras:

Automaticamente ao gravar a viagem. (DLV_TIPRET = 1-CallBack);
- O servidor REST deverá estar cadastrado corretamente;
- O campo DLV_URLCAL deverá estar preenchido com o Endpoint do serviço WSTMSMapLink;
- As informações planning serão enviadas automaticamente;
- O sistema irá processar e enviar as mensagens Trip e Tolls automaticamente após o retorno do processamento da MapLink;
Manualmente, ao acessar na rotina de viagem a opção Outras Ações > Roteirizador > Integra;

TRIP

O envio de informações e tratamento das informações poderá ser realizado de duas maneiras:

Automaticamente ao gravar a viagem. (DLV_TIPRET = 1-CallBack);
- O servidor REST deverá estar cadastrado corretamente;
- O campo DLV_URLCAL deverá estar preenchido com o Endpoint do serviço WSTMSMapLink;
- As informações trip serão enviadas automaticamente;
- O sistema irá processar e enviar a mensagem Tolls automaticamente após o retorno do processamento da MapLink;
Manualmente, ao acessar na rotina de viagem a opção Outras Ações > Roteirizador > Integra;

TOLLS

O envio de informações e tratamento das informações poderá ser realizado de duas maneiras:

Automaticamente ao gravar a viagem. (DLV_TIPRET = 1-CallBack);
- O servidor REST deverá estar cadastrado corretamente;
- O campo DLV_URLCAL deverá estar preenchido com o Endpoint do serviço WSTMSMapLink;
- As informações tolls serão enviadas automaticamente;
Manualmente, ao acessar na rotina de viagem a opção Outras Ações > Roteirizador > Integra;

12. COMO FAZER

INTEGRAÇÃO

No SIGATMS habilite o parâmetro de integração MV_ROTAINT.
Acesse a rotina Dados Cadastrais Roteirizador e cadastre as informações de acordo com as configurações e assinatura Maplink.
Atualize o cadastro de: Clientes, Sequência de Endereço e Solicitantes.
Na rotina Cadastro de Referências Geográficas, clique em Outras Ações > Wizard Filiais.
Selecione as filiais que deseja obter as coordenadas geográficas, e prossiga a operação.
Na rotina Viagem, clique em Outras Ações > Roteirizador > Integra.
Aguarde o envio das informações e a respectiva plotagem do mapa.

13. CHECKLIST DE SUPORTE DE APLICAÇÃO

CHECKLIST DE VERIFICAÇÕES

Relacione os itens de verificações para que o Atendente possa:
- Identificar a build utilizada;
- Identificar se a conexão com a internet está estável;
- Identificar se servidor webservice está com funcionamento correto;
- Identificar se servidor Rest está com o funcionamento correto;
- Identificar se o cliente destinatário (Cliente, Sequência de Endereço ou Solicitante) está com o endereço cadastrado corretamente;
- Verificar se foi obtido as referências geográficas para o cliente destinatário;
- Verificar se foi obtido as referências geográficas para a filial;
- Verificar se os campos do cadastro de veículos estão preenchidos corretamente: DA3_CAPACM, DA3_VOLMAX, DA3_COMEXT, DA3_LAREXT,DA3_ALTEXT;