Webservice de Roteirização

Introdução

A API da Concept Tecnologia oferece uma solução completa para gerenciamento de entregas, roteamento de veículos e controle de despesas de frota. Esta plataforma permite que empresas automatizem o processo de entrega, desde a importação de pedidos até a roteirização eficiente e o monitoramento das despesas associadas aos veículos.

O sistema foi projetado para otimizar rotas de entrega, reduzir custos operacionais e aumentar a eficiência logística, utilizando tecnologias de geolocalização e algoritmos de roteirização para determinar os melhores caminhos para seus veículos de entrega, considerando diversos fatores como distância, tempo de atendimento e restrições de horários.

Componentes Principais da API

A API é dividida em três componentes principais, cada um responsável por um aspecto diferente do processo logístico:

1. Importador de Pedidos

Este componente permite a inserção e consulta de pedidos no sistema. É o ponto de entrada para todos os dados de entregas que serão posteriormente roteirizados.

2. Roteirizador de Pedidos (Automatizador)

Responsável pela criação de rotas otimizadas, agrupando pedidos por região, veículo e outros critérios, determinando a sequência ideal de entregas.

3. Importador de Despesas

Gerencia os custos operacionais relacionados aos veículos, como abastecimentos, manutenções e outras despesas, permitindo um controle financeiro da frota.

Detalhamento dos Componentes e Métodos

1. Importador de Pedidos (ImportadorPedidos)

Endpoint WSDL: http://52.6.27.50:8181/importadorPedidos?wsdl

Métodos Disponíveis:

importarPedidos: Permite inserir novos pedidos no sistema para posterior roteirização.

consultarStatusEntregaPedido: Verifica o status atual de um pedido no sistema.

converterEnderecoUsandoCEP: Converte um CEP em coordenadas geográficas e endereço completo.

listarItinerariosRoterizado: Lista todos os itinerários (paradas) de uma rota já criada.

listarItinerariosLote: Lista itinerários relacionados a um determinado número de lote.

listarItinerariosCarregamento: Lista itinerários relacionados a um carregamento específico.

listarPoIRoterizado: Lista os pontos de interesse incluídos em uma rota.

atualizarNumeroCarregamento: Atualiza o número de carregamento de uma viagem.

listarPedidosPorStatus: Recupera pedidos que estão em um determinado status (ex: separados, pendentes).

Métodos para alteração de status de pedidos:

Métodos para cancelamento de status:

2. Roteirizador de Pedidos (AutomatizadorFachada)

Endpoint WSDL: http://52.6.27.50:8181/automatizador?wsdl

Métodos Disponíveis:

roteirizarPedidos: Cria uma rota otimizada para entrega de pedidos.

listarMotoristas: Lista todos os motoristas cadastrados no sistema.

listarVeiculos: Lista todos os veículos disponíveis para roteirização.

cadastrarZona: Cadastra ou atualiza uma zona de entrega.

cadastrarLoja: Cadastra ou atualiza uma loja no sistema.

cadastrarVendedor: Cadastra ou atualiza um vendedor.

cadastrarMotorista: Cadastra ou atualiza um motorista.

3. Importador de Despesas (ImportadorDespesas)

Endpoint WSDL: http://52.6.27.50:8181/importadorDespesas?wsdl

Métodos Disponíveis:

importarDespesas: Permite inserir despesas relacionadas a veículos no sistema.

consultarDespesas: Consulta despesas registradas por período e/ou veículo.

Autenticação e Segurança

A autenticação na API é realizada por meio de três parâmetros presentes em praticamente todos os métodos:

  1. cpfCNPJ: CPF ou CNPJ do cliente que está acessando a API. Deve estar cadastrado no sistema da central de rastreamento.
  2. senhaCliente: Senha fornecida pela Concept Tecnologia para o cliente.
  3. senhaCentral: Senha fornecida pela Concept Tecnologia para acesso à central.

É importante manter essas credenciais em segurança, utilizando variáveis de ambiente ou sistemas de gestão de segredos.

Limitações e Boas Práticas

  1. A API utiliza SOAP (Simple Object Access Protocol), requerendo bibliotecas específicas para sua integração.
  2. Todas as datas devem ser enviadas no formato correto - para campos de data use objetos Date, para campos de hora use strings no formato "HH:MM".
  3. Ao trabalhar com coordenadas geográficas, certifique-se de que os valores estão dentro dos limites válidos (latitude entre -90 e 90, longitude entre -180 e 180).
  4. O sistema tem limitações na quantidade de pontos que podem ser roteirizados em uma única requisição (máximo de 23 pontos por chunk).
  5. Sempre verifique o retorno das chamadas para garantir que a operação foi bem-sucedida.
  6. Quando um pedido não tem coordenadas geográficas definidas, é possível obter essas informações através do código do ponto de interesse, endereço ou CEP.

Fluxos de Integração Típicos

Fluxo de Pedidos Completo

  1. Importação de Pedidos: Utilize o método importarPedidos para inserir novos pedidos no sistema.
  2. Liberação para Separação: Altere o status dos pedidos para "Liberado para Separação" usando alterarStatusVendaFinalizadoParaLiberadoSeparacao.
  3. Início de Separação: Quando a separação dos produtos começar, altere o status para "Em Separação" com alterarStatusLiberadoSeparacaParaEmSeparacao.
  4. Finalização da Separação: Após a separação completa, use alterarStatusEmSeparacaoParaSeparados.
  5. Liberação para Roteirização: Quando os pedidos estiverem prontos para entrega, use alterarStatusSeparadosParaLiberadosRoteirizacao.
  6. Roteirização: Utilize o método roteirizarPedidos para criar uma rota otimizada.
  7. Acompanhamento: Use consultarStatusEntregaPedido ou listarItinerariosRoterizado para acompanhar o status de entrega.

Fluxo de Gestão de Despesas

  1. Registro de Despesas: Utilize o método importarDespesas para registrar despesas de veículos.
  2. Consulta de Despesas: Use consultarDespesas para analisar os gastos por veículo ou período.

Glossário de Termos

Principais Objetos e Modelos de Dados

PedidoRotaVO

Representa um pedido de entrega, contendo:

ItinerarioViagemVO

Representa uma parada em uma rota de entrega:

ViagemVO

Representa uma rota completa de entregas:

DespesaVO

Representa uma despesa relacionada a um veículo:

Tratamento de Erros Comuns

  1. Erro de Autenticação: Verifique se o CPF/CNPJ e senhas estão corretos.
  2. Erro de Dados Inválidos: Verifique se todos os campos obrigatórios estão preenchidos corretamente.
  3. Erro de Geocodificação: Se as coordenadas não puderem ser encontradas, tente fornecer um endereço mais completo ou um CEP válido.
  4. Erro de Roteirização: Verifique se todos os parâmetros necessários foram informados e se o veículo tem capacidade suficiente para os pedidos.
  5. Erro de Status Inválido: Certifique-se de que os pedidos estão no status correto antes de tentar alterá-los.
  6. Erro de Entidade Não Encontrada: Verifique se zonas, lojas, vendedores e motoristas estão previamente cadastrados no sistema.

Integração com Java

Como a API utiliza SOAP, a integração com Java é facilitada pelo uso da ferramenta wsimport para gerar os stubs de cliente. O documento fornece um script ANT para gerar automaticamente as classes necessárias:

<project default="wsimport">
  <target name="wsimport">
    <exec executable="/usr/lib/jvm/jdk1.6.0_45/bin/wsimport">
      <arg line="-keep -s ./src -p concept.gps.wsclient -d ./bin http://52.6.27.50:8181/importadorPedidos?wsdl"/>
    </exec>
  </target>
</project>

Após gerar os stubs, você pode usar as classes para acessar a API, como mostrado nos exemplos de código fornecidos na documentação.

Conclusão

A API de Roteamento de Entregas e Gestão de Frotas da Concept Tecnologia é uma solução completa que permite automatizar o processo logístico, desde a importação de pedidos até a roteirização e controle de despesas. Com uma integração correta, é possível otimizar rotas, reduzir custos operacionais e melhorar a experiência de entrega para os clientes.

Para começar a utilizar a API, é necessário obter as credenciais com a Concept Tecnologia e configurar a integração seguindo as boas práticas mencionadas neste documento. Em caso de dúvidas ou problemas durante a integração, o suporte técnico da Concept está à disposição para ajudar.

Revision #8
Created 26 March 2025 18:51:13 by Moises Reis Filho
Updated 28 August 2025 16:08:15 by Moises Reis Filho