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: Viagem, Motoristas, Veículos.

• FRETEBRAS- As APIs envolvidas são: Token, Tipos, Carrocerias, Especies, Preços, Fretes, Renovar e Concretizar. Para obter mais informações, acesse: https://developer.fretebras.com.br/visualizar.html?doc=centralAssinante

03. INTEGRAÇÃO

Oferta de Frete → Incluir

Foi disponibilizada no menu da viagem as opções para realizar o vínculo entre as viagens do tipo 3=Planejadas e a Oferta de Frete.

Ao acionar o menu, o usuário deve preencher os campos referentes a Oferta de Frete, e no momento que concluir a operação, as informações serão enviadas a plataforma FreteBras; caso a operação seja incluída com sucesso, será retornado um Id do frete; caso ocorra algum o erro, o mesmo será exibido em tela.

Esse ID é uma numeração única, que identificará a Oferta de Frete da unidade, e o mesmo ID constará na plataforma da FreteBras.

Oferta de Frete →Visualizar

Foi disponibilizada no menu da viagem a opção para visualizar a Oferta de Frete registrada.

Oferta de Frete →Renovação

A cada 7 dias úteis a oferta de frete expira automaticamente, e sendo assim é necessário realizar a renovação para que a mesma continue ativa.

Foi disponibilizada no menu da viagem a opção para Renovar a Oferta de Frete. Ao fim da renovação a data do frete (DM2_DTFRT) será atualizada com a data corrente.

Oferta de Frete →Alteração

Foi disponibilizada no menu da viagem a opção para Alterar a Oferta de Frete. A alteração pode ser realizada para atualizar ou complementar alguma informação que não foi enviada durante a sua criação.  O ID do frete deve continuar o mesmo.

Oferta de Frete →Concluir

As Ofertas de Frete ficam disponíveis aos motoristas profissionais de carga, e caso o motorista tenha interesse ele deve realizar o contato direto com a empresa ofertante. A empresa deve realizar o cadastramento do Motorista e Veículo, e informar o Código do Motorista e Código do Veículo na Oferta de Frete.

Foi disponibilizada no menu da viagem a opção para Concluir a Oferta de Frete. Ao realizar a conclusão da oferta, a mesma ficará com o status igual a 2=Concretizada (DM2_STATUS).

As informações que serão enviadas para a FreteBras são: Placa do Veículo e CPF do Motorista. A inclusão de ambos pode ser realizada dentro da opção Oferta de Frete → Concluir. 

Após concretizar a oferta de frete, a mesma não poderá receber alterações e o processo será encerrado, ficando a cargo da empresa a continuidade no processo da viagem. 

Oferta de Frete →Excluir

Foi disponibilizada no menu da viagem a opção para Excluir a Oferta de Frete. Apenas Ofertas de Frete com status igual a 1=Em aberto (DM2_STATUS) podem ser excluídas.

04. ESCOPO

A comunicação com as APIS e plataforma Frebras ocorrem a partir das rotinas:

• Configurador Fretebras→ Testar Conexão;
• Viagem Planejada (DTQ_TIPVIA=3) → Outras Ações → Oferta de Frete;
  • Incluir
    • Tipos de Veículos - DM2_TIPVEI;
    • Tipos de Carrocerias - DM2_TIPCAR;
    • Tipos de Preço - DM2_TIPPRE;
    • Espécie de Carga - DM2_TIPESP;
  • Alterar;
    • Tipos de Veículos - DM2_TIPVEI;
    • Tipos de Carrocerias - DM2_TIPCAR;
    • Tipos de Preço - DM2_TIPPRE;
    • Espécie de Carga - DM2_TIPESP;
  • Renovar;
  • Concretizar;
  • Deletar;

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.

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. 

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;