Webservice de Roteirização

API de Roteamento de Entregas e Gestão de Frotas - Concept Tecnologia

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.

Recebe uma lista de objetos PedidoRotaVO contendo informações como número do pedido, endereço, coordenadas geográficas, data/hora, zona, loja, vendedor, entre outros.
É possível também cadastrar pontos de interesse (locais específicos) durante a importação.

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

Informa se um pedido foi entregue, está em rota, pendente, ou teve problemas durante a entrega.

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

Útil para pedidos que não possuem latitude/longitude definidas.

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

Mostra a sequência de entregas, horários previstos e status.

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:

alterarStatusVendaFinalizadoParaLiberadoSeparacao
alterarStatusLiberadoSeparacaParaEmSeparacao
alterarStatusEmSeparacaoParaSeparados
alterarStatusSeparadosParaLiberadosRoteirizacao
alterarStatusNaoEntreguesParaLiberadoSeparacao
alterarStatusNaoEntreguesParaLiberadoRoteirizacao

Métodos para cancelamento de status:

cancelar_LiberadoRoteirizacao
cancelar_Separados
cancelar_EmSeparacao
cancelar_LiberadosSeparacao

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.

Recebe parâmetros como lista de carregamentos, ponto de origem, ponto de destino, veículo, motorista e data/hora de início.
Utiliza algoritmos de otimização para definir a melhor sequência de entregas.
Considera janelas de tempo, capacidade do veículo, tempo de atendimento e outros fatores.

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.

As zonas são utilizadas para agrupar pedidos em regiões geográficas.

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.

Recebe informações como tipo de despesa, valor, quantidade, veículo, motorista, data/hora, etc.
Suporta diversos tipos de despesas, incluindo abastecimentos, manutenções e outras.

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

Permite filtrar despesas por placa de veículo e intervalo de datas.

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:

cpfCNPJ: CPF ou CNPJ do cliente que está acessando a API. Deve estar cadastrado no sistema da central de rastreamento.
senhaCliente: Senha fornecida pela Concept Tecnologia para o cliente.
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

A API utiliza SOAP (Simple Object Access Protocol), requerendo bibliotecas específicas para sua integração.
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".
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).
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).
Sempre verifique o retorno das chamadas para garantir que a operação foi bem-sucedida.
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

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

Fluxo de Gestão de Despesas

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

Glossário de Termos

Pedido: Solicitação de entrega de produtos a um cliente.
Carregamento: Agrupamento de pedidos que serão entregues em uma mesma rota ou viagem.
Lote: Agrupamento de pedidos para fins de controle interno.
Itinerário: Cada parada (entrega) de uma rota.
Rota ou Viagem: Sequência planejada de entregas para um veículo.
Ponto de Interesse (PoI): Local geograficamente identificado, como endereço de cliente, depósito, etc.
Zona: Região geográfica que agrupa pedidos para facilitar a roteirização.
Loja: Estabelecimento a partir do qual os pedidos são despachados.
Vendedor: Profissional responsável pela venda que gerou o pedido.
Status do Pedido: Estado atual do pedido (finalizado, liberado para separação, em separação, separado, liberado para roteirização, etc.).
Tempo de Atendimento: Tempo estimado para realizar a entrega em cada parada.
Janela de Entrega: Intervalo de horário permitido para realização da entrega.

Principais Objetos e Modelos de Dados

PedidoRotaVO

Representa um pedido de entrega, contendo:

numeroPedido: Identificador único do pedido
dataPedido: Data em que o pedido foi realizado
horaPedido: Hora em que o pedido foi realizado
valorPedido: Valor monetário do pedido
endereco: Endereço de entrega
latitude/longitude: Coordenadas geográficas do endereço
codigoPontoInteresse: Código do ponto de interesse (opcional)
descricao: Descrição adicional do pedido
peso/volume: Peso e volume total dos itens do pedido
horaEntregaInicial/horaEntregaFinal: Janela de horário para entrega
tempoAtendimento: Tempo estimado para realizar a entrega (em minutos)
zona/loja/vendedor: Informações sobre zona de entrega, loja de origem e vendedor
numeroCarregamento: Identificador do carregamento
numeroNotaFiscal: Número da nota fiscal
numeroLote: Identificador do lote
numeroGSM: Número de celular para envio de alertas
dataCompromissoEntrega/horaCompromissoEntrega: Data e hora prometidas para entrega
observacaoPedido: Observações adicionais sobre o pedido

ItinerarioViagemVO

Representa uma parada em uma rota de entrega:

numeroPedido: Pedido associado à parada
dataItinerarioViagem: Data prevista para a entrega
horaItinerarioViagem: Hora prevista para a entrega
status: Status atual da entrega (aberto, entregue, endereço fechado, etc.)
horaEntrega: Hora em que a entrega foi realizada
latitude/longitude: Localização da entrega
dataHoraCheckin/dataHoraCheckout: Momento em que o motorista chegou e saiu do local
tempoAtendimento: Tempo gasto na entrega

ViagemVO

Representa uma rota completa de entregas:

id: Identificador único da viagem
data: Data da viagem
horaInicio: Hora de início prevista
dataHoraFim: Data e hora previstas para o término
pontoSaida/pontoRetorno: Locais de origem e destino da rota
veiculo: Veículo que realizará a viagem
condutorViagem: Nome do motorista
qtdItinerarios: Quantidade de paradas
distanciaEstimadaEmKM: Distância total da rota
tempoEstimadoEmSegundos: Tempo estimado total da rota
polylineViagem: Representação codificada do trajeto para exibição em mapas

DespesaVO

Representa uma despesa relacionada a um veículo:

condutor: Nome do motorista
placa: Placa do veículo
data/hora: Data e hora da despesa
nome/descricao: Título e descrição da despesa
odometro: Odômetro do veículo no momento da despesa
quantidade/valor: Quantidade e valor unitário
tipo: Tipo de despesa (abastecimento, manutenção, etc.)
tipoCombustivel: Tipo de combustível (se aplicável)
fornecedor: Informações sobre o fornecedor do serviço ou produto

Tratamento de Erros Comuns

Erro de Autenticação: Verifique se o CPF/CNPJ e senhas estão corretos.
Erro de Dados Inválidos: Verifique se todos os campos obrigatórios estão preenchidos corretamente.
Erro de Geocodificação: Se as coordenadas não puderem ser encontradas, tente fornecer um endereço mais completo ou um CEP válido.
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.
Erro de Status Inválido: Certifique-se de que os pedidos estão no status correto antes de tentar alterá-los.
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.