Webservice de Roteirização

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

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 entregas e frota, permitindo importação de pedidos, roteirização otimizada e controle de despesas. A integração dessas funcionalidades possibilita maior eficiência operacional e melhoria no atendimento ao cliente, através do rastreamento em tempo real das entregas e otimização das rotas.

Para utilização correta do sistema, é essencial seguir as validações e regras de negócio documentadas, garantindo a integridade dos dados e o funcionamento adequado de todas as operações.

Em caso de dúvidas ou problemas não cobertos nesta documentação, entre em contato com o suporte técnico.