# 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. - 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: 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 - **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 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: ```xml ``` 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.