Webservice de Roteirização

REFAZER

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

Introdução

Esta documentação detalha a API de Webservice para o Sistema de Gerenciamento de Frota CONCEPT RASTREAMENTO, que oferece funcionalidades para importação de pedidos, roteirização de entregas, gerenciamento de despesas, e controle de frota. A API utiliza SOAP (Simple Object Access Protocol) e está estruturada em diversos módulos para atender diferentes necessidades operacionais.

Visão Geral dos Módulos

O sistema está dividido em três módulos principais:

1. Importador de Pedidos - Gerencia cadastro, consulta e status de pedidos
2. Roteirizador de Pedidos - Realiza a otimização de rotas para entregas
3. Importador de Despesas - Gerencia despesas relacionadas aos veículos da frota

Detalhamento dos Módulos

1. Importador de Pedidos

Propósito

Permite importar, consultar e gerenciar pedidos no sistema. Facilita o rastreamento de entregas e a atualização de status.

Endpoints

• URL: http://52.6.27.50:8181/importadorPedidos?wsdl

Métodos Principais

1.1 Importar Pedidos (importarPedidos)

Parâmetros:

• listaPedidos: Lista de objetos PedidoRotaVO
• cpfCNPJ: String - CPF/CNPJ do cliente (formato xx.xxx.xxx/xxxx-xx)
• senhaCliente: String - Senha fornecida pela Concept Tecnologia
• senhaCentral: String - Senha fornecida pela Concept Tecnologia

Estrutura do PedidoRotaVO:

Campo	Tipo	Descrição	Obrigatório	Validações
numeroPedido	String	Número do pedido (chave única)	Sim	Não pode ser vazio
valorPedido	double	Valor do pedido	Sim	-
codigoPontoInteresse	String	Código do cliente	Não	Deve existir no sistema ou ser criado
latitude	String	Latitude do local de entrega	Não*	Valores entre -90 e 90
longitude	String	Longitude do local de entrega	Não*	Valores entre -180 e 180
endereco	String	Endereço do local de entrega	Sim	-
dataPedido	Date	Data do pedido	Sim	Data válida
horaPedido	String	Hora do pedido (formato HH:MM)	Sim	Valores entre 00:00 e 23:59
descricao	String	Descrição adicional do pedido	Não	-
qtdItensPedido	double	Quantidade de itens do pedido	Não	-
peso	double	Peso em kg do pedido	Não	-
volume	double	Volume em m³ do pedido	Não	-
horaEntregaInicial	String	Horário inicial permitido (HH:MM)	Sim	Valores entre 00:00 e 23:59
horaEntregaFinal	String	Horário final permitido (HH:MM)	Sim	Valores entre 00:00 e 23:59
tempoAtendimento	int	Tempo estimado para entrega (minutos)	Sim	Valor > 0
zona	ZonaVO	Zona onde será feita a entrega	Sim	Deve existir no sistema
loja	LojaVO	Loja que fará a entrega	Sim	Deve existir no sistema
vendedor	VendedorVO	Vendedor que fez o pedido	Sim	Deve existir no sistema
numeroCarregamento	String	Número do agrupador/carregamento	Não	Máximo 45 caracteres
numeroGSM	String	Número celular para alertas	Não	Formato válido de celular
numeroNotaFiscal	String	Número da nota fiscal	Não	Máximo 45 caracteres
dataCompromissoEntrega	Date	Data compromisso da entrega	Sim	Data válida
horaCompromissoEntrega	String	Hora compromisso da entrega (HH:MM)	Sim	Valores entre 00:00 e 23:59
numeroLote	String	Número de lote	Não	Máximo 45 caracteres
cadastrarPontoInteresse	Boolean	Flag para cadastrar ponto de interesse	Não	-
poi	PontosInteresseVO	Ponto de interesse a ser cadastrado	Não	Obrigatório se cadastrarPontoInteresse=true
cep	String	Número do CEP	Não	Formato 99999999
observacaoPedido	String	Campo texto de observação	Não	-

* Obrigatório ao menos um dos três: latitude/longitude, codigoPontoInteresse ou endereço

Estrutura do ZonaRotaVO:

Campo	Tipo	Descrição	Obrigatório
id	int	Identificador da zona	Não
nome	String	Nome da zona	Sim
codigoZona	String	Código da zona	Sim

Estrutura do LojaRotaVO:

Campo	Tipo	Descrição	Obrigatório
id	int	Identificador da loja	Não
nome	String	Nome da loja	Sim
codigoLoja	String	Código da loja	Sim

Estrutura do VendedorRotaVO:

Campo	Tipo	Descrição	Obrigatório
id	int	Identificador do vendedor	Não
nome	String	Nome do vendedor	Sim
codigoVendedor	String	Código do vendedor	Sim

Estrutura do PontosInteresseVO:

Campo	Tipo	Descrição	Obrigatório
codigo	String	Código do Ponto de Interesse	Sim
nome	String	Nome do Ponto de Interesse	Sim
descricao	String	Descrição do Ponto de Interesse	Sim
latitude	String	Latitude	Sim
longitude	String	Longitude	Sim
identificar	boolean	Identificar nos avisos e percurso	Não
enviarAlerta	boolean	Enviar alerta ao ser visitado	Não
raio	double	Raio em KM	Sim
horaInicialRestricao	Time	Horário início permitido de visita	Não
horaFinalRestricao	Time	Horário fim permitido de visita	Não
grupo	GrupoPontoInteresseVO	Grupo do Ponto de Interesse	Sim

Retorno: ResultadoImportacaoVO

• comSucesso: boolean - Indica se a operação foi bem-sucedida
• mensagem: String - Descrição do resultado da operação

1.2 Consultar Status da Entrega (consultarStatusEntregaPedido)

Parâmetros:

• pedido: PedidoRotaVO (apenas o campo numeroPedido é necessário)
• cpfCNPJ: String - CPF/CNPJ do cliente
• senhaCliente: String - Senha do cliente
• senhaCentral: String - Senha da central

Retorno: ResultadoConsultaStatusVO

• comSucesso: boolean - Indica se a operação foi bem-sucedida
• mensagem: String - Descrição do resultado da operação
• itinerarioViagem: ItinerarioViagemVO - Detalhes do itinerário da viagem

Estrutura do ItinerarioViagemVO:

Campo	Tipo	Descrição
numeroPedido	String	Número do pedido
dataItinerarioViagem	Date	Data prevista da entrega
status	StatusItinerarioViagem	Status da entrega
horaEntrega	Timestamp	Data e hora da entrega
horaRota	Time	Hora prevista da entrega
idViagem	int	Número da viagem correspondente
dataHoraCheckin	Timestamp	Data e hora do checkin
dataHoraCheckout	Timestamp	Data e hora do checkout
tempoAtendimento	int	Tempo de atendimento em minutos
listaOcorrencias	List<ErroItinerarioRotaVO>	Lista de ocorrências do Itinerário

Estrtura do ErroItinerarioRotaVO:

Campo	Tipo	Descrição
id	INT	identificador
status	[PENDENTE, TRATADO]	String
nomeTipoErro	String	Nome do tipo do erro.
tratativa	String	Tratativa registrada na ocorrência.
dataHoraCadastro	Timestamp	Data/hora do cadastro da ocorrência.
dataHoraAlteracao	Timestamp	Data/hora que a ocorrência foi alterada.

Valores possíveis para StatusItinerarioViagem:

• ABERTO
• ENTREGUE
• PENDENTE
• ENDERECO_FECHADO
• ENDERECO_ERRADO
• ENDERECO_NAO_LOCALIZADO
• ADIADO

1.3 Converter Endereço usando CEP (converterEnderecoUsandoCEP)

Parâmetros:

• listaPedidos: Lista de PedidoRotaVO (apenas numeroPedido e cep são necessários)
• cpfCNPJ: String
• senhaCliente: String
• senhaCentral: String

Retorno: ResultadoConversaoEnderecoPeloCEPVO

• comSucesso: boolean
• mensagem: String
• listaPedidos: Lista de PedidoRotaVO com endereço, latitude e longitude preenchidos

1.4 Listar Itinerários de Carregamento (listarItinerariosCarregamento)

Parâmetros:

• numeroCarregamento: String
• cpfCNPJ: String
• senhaCliente: String
• senhaCentral: String

Retorno: ResultadoConsultaListaItinerariosVO

• comSucesso: boolean
• mensagem: String
• lista: Lista de ItinerarioViagemVO

1.5 Gerenciamento de Status de Pedidos

O sistema permite alterações de status de pedidos através de vários métodos:

• alterarStatusVendaFinalizadoParaLiberadoSeparacao
• alterarStatusLiberadoSeparacaParaEmSeparacao
• alterarStatusEmSeparacaoParaSeparados
• alterarStatusSeparadosParaLiberadosRoteirizacao
• alterarStatusNaoEntreguesParaLiberadoSeparacao
• alterarStatusNaoEntreguesParaLiberadoRoteirizacao
• cancelar_LiberadoRoteirizacao
• cancelar_Separados
• cancelar_EmSeparacao
• cancelar_LiberadosSeparacao

Todos estes métodos recebem parametrização similar:

• listaPedidos: Lista de PedidoRotaVO (apenas numeroPedido é necessário)
• cpfCNPJ, senhaCliente, senhaCentral: String

O método alterarStatusLiberadoSeparacaParaEmSeparacao também recebe:

• compromissoSeparacao: String - Data/hora esperada para o fim da separação

Retorno: ResultadoAlteracaoStatusPedidosVO

• comSucesso: boolean
• mensagem: String
• listaPedidosAlterados: Lista de PedidoRotaVO com status alterado

2. Roteirizador de Pedidos

Propósito

Otimiza as rotas de entrega, considerando restrições de tempo, capacidade do veículo e outras configurações.

Endpoints

• URL: http://52.6.27.50:8181/automatizador?wsdl

Métodos Principais

2.1 Roteirizar Pedidos (roteirizarPedidos)

Parâmetros:

• idViagem: int - Para novas viagens use 0, para atualizar use o código existente
• listaCarregamentos: List<String> - Lista de carregamentos a serem roteirizados
• codigoPontoInteresseOrigem: String - Ponto de partida do veículo
• codigoPontoInteresseDestino: String - Ponto de retorno do veículo
• dataHoraInicioRota: Date - Data/hora planejada para início da viagem
• placaVeiculo: String - Placa do veículo
• nomeCondutor: String - Nome do motorista
• isAgruparPedidosMesmoCliente: boolean - Considera tempo único para pontos repetidos
• cpfCNPJ, senhaCliente, senhaCentral: String - Credenciais

Retorno: ResultadoRoteirizacaoVO

• comSucesso: boolean
• mensagem: String
• idRoteirizacao: int - Identificador da roteirização criada

2.2 Listar Motoristas (listarMotoristas)

Parâmetros:

• cpfCNPJ, senhaCliente, senhaCentral: String

Retorno: ResultadoConsultaMotoristasVO

• comSucesso: boolean
• mensagem: String
• lista: Lista de MotoristaVO

Estrutura do MotoristaVO:

Campo	Tipo	Descrição
id	int	Identificador do motorista
nome	String	Nome do motorista
cpf	String	CPF do motorista
cnh	String	Número da CNH
matricula	String	Matrícula
rg	String	RG
endereco	String	Endereço
telefones	String	Telefones
senhaAcesso	String	Senha para app Motorista
categoriaCNH	String	Categoria da CNH
observacoesGerais	String	Observações

2.3 Listar Veículos (listarVeiculos)

Parâmetros:

• cpfCNPJ, senhaCliente, senhaCentral: String

Retorno: ResultadoConsultaVeiculosVO

• comSucesso: boolean
• mensagem: String
• lista: Lista de VeiculoRoteirizacaoVO

Estrutura do VeiculoRoteirizacaoVO:

Campo	Tipo	Descrição
id	int	Identificador do veículo
placa	String	Placa do veículo
motorista	MotoristaVO	Motorista atual do veículo

2.4 Cadastrar Entidades

O sistema permite cadastrar/atualizar várias entidades:

• cadastrarMotorista
• cadastrarZona
• cadastrarLoja
• cadastrarVendedor

Cada método recebe o objeto correspondente e as credenciais de acesso.

3. Importador de Despesas

Propósito

Gerencia despesas relacionadas aos veículos da frota, como abastecimento, manutenção e outras despesas.

Endpoints

• URL: http://52.6.27.50:8181/importadorDespesas?wsdl

Métodos Principais

3.1 Importar Despesas (importarDespesas)

Parâmetros:

• listaDespesas: Lista de DespesaVO
• cpfCNPJ, senhaCliente, senhaCentral: String - Credenciais

Estrutura do DespesaVO:

Campo	Tipo	Descrição	Obrigatório	Validações
condutor	String	Nome do condutor do veículo	Sim	Não pode ser nulo
placa	String	Placa do veículo	Sim	Deve existir no sistema
data	Date	Data da despesa	Sim	Data válida
hora	String	Hora da despesa (formato HH:MM)	Sim	Formato válido
nome	String	Título para a despesa	Sim	Não pode ser nulo
descricao	String	Texto com descrição da despesa	Não	-
odometro	int	Odômetro do veículo	Sim	> 0, deve ser coerente com registros anteriores
quantidade	BigDecimal	Quantidade da despesa	Sim	Não pode ser nulo
tipo	Enum	Tipo da despesa (TipoDespesa)	Sim*	Deve ser valor válido do enum
tipoGenerico	String	Tipo genérico da despesa	Sim*	Deve existir nos tipos cadastrados
valor	BigDecimal	Valor unitário da despesa	Sim	Não pode ser nulo
tipoCombustivel	Enum	Tipo do combustível (TipoCombustivel)	Condicional	Obrigatório para abastecimentos
fornecedor	FornecedorDespesaVO	Fornecedor da despesa	Não	Se informado, precisa ser válido

* Um dos dois campos (tipo ou tipoGenerico) deve ser preenchido

Valores possíveis para TipoDespesa:

• ABASTECIMENTO
• ABASTECIMENTO_EXTERNO
• ABASTECIMENTO_EXTERNO_A_VISTA
• ABASTECIMENTO_EXTERNO_CARTAO
• [outros tipos de despesas conforme configuração do sistema]

Valores possíveis para TipoCombustivel:

• GASOLINA_COMUM
• GASOLINA_ADITIVADA
• ETANOL
• DIESEL_COMUM
• DIESEL_S10
• [outros tipos de combustíveis conforme configuração do sistema]

Estrutura do FornecedorDespesaVO:

Campo	Tipo	Descrição	Obrigatório
id	int	Identificador do fornecedor	Não
nome	String	Nome do fornecedor	Sim, para novos
CNPJCPF	String	CPF ou CNPJ do fornecedor	Sim
razaoSocial	String	Razão social do fornecedor	Não
endereco	String	Endereço do fornecedor	Não
telefones	String	Telefones do fornecedor	Não
emails	String	Email do fornecedor	Não
isCadastrar	Boolean	Indica se deve cadastrar se não for encontrado	Não

Retorno: ResultadoImportacaoVO

• comSucesso: boolean
• mensagem: String

3.2 Consultar Despesas (consultarDespesas)

Parâmetros:

• cpfCNPJ, senhaCliente, senhaCentral: String - Credenciais
• placaVeiculo: String - Placa do veículo (opcional)
• dataInicial: String - Data início do período (formato AAAAMMDD)
• dataFinal: String - Data fim do período (formato AAAAMMDD)

Retorno: ResultadoConsultaListaDespesasVO

• comSucesso: boolean
• mensagem: String
• lista: Lista de DespesaVO - Despesas encontradas no período

Fluxo de Trabalho

O fluxo de trabalho típico do sistema envolve as seguintes etapas:

1. Importação de Pedidos

   • Cadastrar pedidos no sistema
   • Verificar status e detalhes dos pedidos

2. Planejamento de Rotas

   • Agrupar pedidos por carregamento
   • Definir veículos e motoristas
   • Roteirizar pedidos para otimização de entregas

3. Execução de Entregas

   • Monitorar status de entregas
   • Atualizar status conforme progresso

4. Gestão de Despesas

   • Registrar despesas relacionadas aos veículos
   • Consultar histórico de despesas

Instruções Passo a Passo

Como Importar Pedidos

1. Preparar a lista de pedidos a serem importados

   • Criar objetos PedidoRotaVO com os dados necessários
   • Garantir que todos os campos obrigatórios estejam preenchidos

2. Chamar o método importarPedidos

   importarPedidos(listaPedidos, cpfCNPJ, senhaCliente, senhaCentral)
   

3. Verificar resposta

   • Checar campo comSucesso do retorno
   • Se falha, verificar mensagem de erro para correção

Como Roteirizar Pedidos

1. Preparar os dados necessários

   • Número de carregamentos
   • Pontos de origem e destino
   • Veículo e motorista
   • Data/hora de início

2. Chamar o método roteirizarPedidos

   roteirizarPedidos(0, listaCarregamentos, codigoPontoInteresseOrigem, 
                     codigoPontoInteresseDestino, dataHoraInicioRota, 
                     placaVeiculo, nomeCondutor, isAgruparPedidosMesmoCliente, 
                     cpfCNPJ, senhaCliente, senhaCentral)
   

3. Guardar o ID da roteirização retornado para uso futuro

Como Gerenciar Status de Pedidos

1. Preparar lista de pedidos

   • Criar objetos PedidoRotaVO com apenas numeroPedido preenchido

2. Chamar o método de alteração de status adequado

   alterarStatusVendaFinalizadoParaLiberadoSeparacao(listaPedidos, cpfCNPJ, senhaCliente, senhaCentral)
   

3. Verificar resposta para confirmar alteração

Como Importar Despesas

1. Preparar lista de despesas

   • Criar objetos DespesaVO com todos os dados necessários
   • Verificar compatibilidade (ex: combustível compatível com veículo)

2. Chamar o método importarDespesas

   importarDespesas(listaDespesas, cpfCNPJ, senhaCliente, senhaCentral)
   

3. Verificar resposta para confirmar importação

Validações e Regras de Negócio

Pedidos

1. Identificação única

   • Pedidos devem ter números únicos
   • Para clientes com numeração por data, pedidos do mesmo número em datas diferentes são permitidos
   • Para clientes com numeração por loja, pedidos com mesmo número em lojas diferentes são permitidos

2. Geolocalização

   • Ao menos uma das formas de localização deve ser fornecida:
     • Latitude e longitude
     • Código de ponto de interesse
     • Endereço para geocodificação
   • Se o endereço for fornecido sem latitude/longitude, o sistema tenta geocodificar
   • Se o CEP for fornecido, o sistema tenta localizar por CEP

3. Horários de Entrega

   • Hora de entrega final deve ser posterior à inicial
   • Horários devem estar no formato HH:MM válido

4. Integridade Referencial

   • Zona, loja e vendedor devem existir no sistema
   • Se ponto de interesse não existir, pode ser cadastrado junto ao pedido

Despesas

1. Validações de Abastecimento

   • Tipo de combustível deve ser compatível com o veículo
   • Quantidade não pode ser superior à capacidade do tanque
   • Odômetro deve ser coerente com registros anteriores

2. Integridade Referencial

   • Veículo deve existir no sistema
   • Fornecedor deve existir ou ter flag para cadastro

Roteirização

1. Restrições de Tempo

   • Respeita janelas de tempo para entregas
   • Considera jornadas de trabalho e intervalos

2. Capacidade do Veículo

   • Verifica peso e volume total dos pedidos
   • Respeita limites do veículo selecionado

3. Otimização

   • Agrupamento por zona ou cliente
   • Ordenação para minimizar distância percorrida

Perguntas Frequentes

Gerais

1. Como obter as credenciais de acesso ao webservice?

   • Entre em contato pelo email suporte@concept.inf.br ou pelo telefone (86) 3301-1878 para solicitar as senhas e liberação no firewall.

2. O que fazer quando recebo um erro de "Senha inválida"?

   • Verifique se está usando as credenciais corretas (cpfCNPJ, senhaCliente e senhaCentral)
   • Confirme se o CNPJ está no formato correto (xx.xxx.xxx/xxxx-xx)
   • Verifique se o cliente está cadastrado na central

Pedidos

3. Como atualizar um pedido já cadastrado?

   • Não é possível alterar pedidos já cadastrados. É necessário cancelar o pedido e cadastrar um novo.

4. Como funciona o agrupamento de pedidos por cliente?

   • Ativando o parâmetro isAgruparPedidosMesmoCliente, pedidos com o mesmo código de ponto de interesse serão tratados como uma única parada, considerando apenas o tempo de atendimento do primeiro pedido.

5. Como cadastrar pontos de interesse junto com os pedidos?

   • Configure o campo cadastrarPontoInteresse como true no pedido
   • Preencha todos os dados do objeto poi (PontosInteresseVO)
   • Certifique-se de que o grupo do ponto de interesse existe no sistema

Roteirização

6. O que significa o erro "Não é possível roteirizar os pedidos"?

   • Pode ocorrer quando não é possível calcular uma rota válida para os pontos informados
   • Verifique se os pontos possuem coordenadas válidas e acessíveis

7. Como atualizar uma roteirização existente?

   • Use o método roteirizarPedidos passando o ID da roteirização existente
   • A roteirização anterior será excluída e uma nova será criada

8. É possível considerar restrições de tempo nas entregas?

   • Sim, através dos campos horaEntregaInicial e horaEntregaFinal dos pedidos

Despesas

9. Como cadastrar um novo fornecedor junto com a despesa?

   • Preencha os dados do fornecedor no objeto FornecedorDespesaVO
   • Configure o campo isCadastrar como true
   • Informe o nome e CNPJ/CPF corretamente

10. Por que recebo erro de "Odômetro inválido"?

    • O valor do odômetro deve ser maior que o da última despesa registrada e menor que a próxima
    • Verifique se não há inversão cronológica nas despesas

Considerações Finais

Esta API oferece uma solução completa para gerenciamento de entregasentregas, roteamento de veículos e frota,controle permitindode despesas de frota. Esta plataforma permite que empresas automatizem o processo de entrega, desde a importação de pedidos,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:

<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. ACom uma integração dessascorreta, funcionalidadesé possibilitapossível maiorotimizar eficiênciarotas, operacionalreduzir custos operacionais e melhoriamelhorar noa atendimentoexperiência aode cliente,entrega atravéspara doos rastreamento em tempo real das entregas e otimização das rotas.clientes.

Para utilizaçcomeçar a utilizar a API, é necessário obter as credenciais com a Concept Tecnologia e configurar a integração correta do sistema, é essencial seguirseguindo as validaçõesboas epráticas regrasmencionadas deneste negóciodocumento. documentadas, garantindo a integridade dos dados e o funcionamento adequado de todas as operações.

Em caso de dúvidas ou problemas nãodurante cobertosa nesta documentaçintegração, entre em contato com o suporte técnico.cnico da Concept está à disposição para ajudar.