Planejamento

Nesta documentação, você encontrará todas as informações necessárias para listar explorar informações a respeito dos planejamento de rota por meio de nossa API.

Autenticação

Antes de começar a utilizar os endpoints relacionados aos planejamento de rotas, certifique-se de incluir as credenciais de autenticação adequadas no cabeçalho de suas solicitações. Sem autenticação válida, você não terá permissão para acessar, pesquisar ou modificar informações. Para ter acesso a documentação dessa etapa clique aqui

Cadastrar

Através desta URL, você poderá cadastrar planejamentos para o sistema otimizar (caso solicitado) e utilizar no aplicativo.

POST

https://api.webrota.com.br/import/route_plan

A busca de veículos possilita o uso dos seguintes parâmetros:

Nome	Tipo	Obrigatório	Padrão	Descrição
optimize	Booleano	Sim	True	Indica se o planejamento será otimizado ou seguirá a ordem informada
geocoding	Booleano	Sim	True	Indica se será necessário obter a localização por meio do endereço passado
source	Booleano	Sim	G	Parâmetro para indicar a fonte de roteirização.
data	Coleção	Sim		Conjunto de dados com as configurações da rota
has_time_window	Booleano	Sim	False	Parâmetro para considerar os horários na otimização da rota
is_async	Booleano	Sim	False	Flag que indica se a otimização do planejamento será feita durante o processo de criação do mesmo ou por rotina individual

Dados Gerais

Nome	Tipo	Obrigatório	Descrição
date_time_start	Data e hora	Sim	Data e horário inicial do planejamento das entregas.
date_time_end	Data e hora	Sim	Data e horário final do planejamento das entregas
vehicle_plate	Texto	Não	Placa do veículo que irá executar o planejamento.
document_number	Texto	Não	CPF do motorista que irá executar o planejamento.
external_code	Texto	Sim	Título de identificação do planejamento da entrega
vehicle_plates	Coleção	Não	Lista de placas de veículos que poderão executar parte do planejamento.
entity	Coleção	Não	Lista de placas de veículos que poderão executar parte do planejamento.
route_points	Coleção	Sim	Relação de pontos de execução do planejamento.

Para os parâmetros de vehicle_plate e document_number, ambos podem ser adicionados juntos. Porém, para vehicle_plates e document_numbers apenas um deles deve ser informado.

Entidade

Nome	Tipo	Obrigatório	Descrição
document_number	Texto	Sim	CPF do motorista que irá executar o planejamento
vehicle_plate	Texto	Sim	Placa do veículo que irá executar o planejamento
helper	Texto	Não	CPF do ajudante que auxiliará na execução do planejamento.

Ponto da Rota

Nome	Tipo	Obrigatório	Descrição
order	Inteiro	Não	Campo que especifica a ordem de entrega. Caso o parâmetro de otimização esteja True a ordem informada pelo usuário será ignorada
name	Texto	Sim	Nome de identificação do ponto de entrega (número da nota fiscal, nome do cliente, etc)
info	Texto	Não	Informações que podem ser importantes ao executor no momento da rota. Elas serão exibidas no aplicativo para o executor.
address	Endereço	Não	Endereço do planejamento. Caso não seja informado, deve ser passado as coordenadas do local
type	Texto	Não	Partida Coleta Entrega Chegada
latitude	Decimal	Não	Latitude da coordenada do ponto de execução
longitude	Decimal	Não	Longitude da coordenada do ponto de execução
external_code	Texto	Não	Identificador que pode ser usado para sistemas terceiros para informar seu código interno.
axles	Intero	Não	Número de eixos máximo permitido para os veículos que poderão atender o ponto
delivery_time	Inteiro	Não	Tempo a ser considerado para a entrega em segundos
time_window	Data e horário	Não	Janela de tempo que determina o horário exato para quando esse ponto deve ser executado
route_point_items	Coleção	Não	Conjunto de itens destinados ao ponto. Quando ativado a opção "Exigir conferência de carga", esses itens serão usados para checagem de carga
disable_signature_check	Booleano	Não	Desabilita necessidade de informar assinatura para um ponto específico quando o planejamento estiver marcado para exigir assinatura de todos os pontos
disable_picture	Booleano	Não	Desabilita necessidade de tirar foto para um ponto específico quando o planejamento estiver marcado para tirar foto de todos os pontos

Items do ponto

Nome	Tipo	Obrigatório	Descrição
external_code	Texto	Sim	Código de referência. É o valor usado para conferência de carga
value	Decimal	Não	Valor total do item informado
description	Texto	Não	Campo aberto para breve descrição do item
quantity	Decimal	Não	Quantidade do item
capacity	Inteiro	Não	Capacidade requerida pelo item

Exemplo de chamada
{
  "optimize": true,
  "geocoding": true,
  "source": "G",
  "data": {
    "date_time_start": "2020-05-16T00:33:00.000Z",
    "date_time_end": "2020-05-16T00:33:00.000Z",
    "vehicle_plate": "VEI-0001",
    "document_number": "12345678901",
    "external_code": "IMPORT API 0001",
    "route_points": [
      {
        "order": 0,
        "name": "Ponto 1",
        "address": "Uberaba - MG, Brasil",
        "type": "PA",
        "latitude": -19.747367,
        "longitude": -47.939154
      },
      {
        "order": 1,
        "name": "Ponto 2",
        "address": "Uberlândia - MG, Brasil",
        "type": "PE",
        "latitude": -18.912753,
        "longitude": -48.275484
      },
      {
        "order": 2,
        "name": "Ponto 3",
        "address": "Delta - MG, Brasil",
        "type": "CH",
        "latitude": -19.971927,
        "longitude": -47.775768
      }
    ]
  }
  
}

Exemplo de retorno
{
  "route_points": "Quantidade de pontos roteirizados com sucesso.",
  "wrong_lines": "[]",
  "wrong_route_plans": "[]",
  "unassigned_points": "Lista com os pontos que não foram possíveis de seradicionados a rota"
}

Pesquisar

A busca de de planejamento possilita o uso dos seguintes parâmetros:

GET

https://api.webrota.com.br/import/route_plan

Nome	Tipo	Obrigatório	Padrão	Descrição
begin_date	Texto	Não		Data e hora prevista do início do planejamento
end_date	Texto	Não		Data e hora prevista do fim do planejamento
user_id	Inteiro	Não		Código do agente executor.
vehicle_id	Inteiro	Não		Código do veículo executor.
route_plan_code	Texto	Não		Código de execução do planejamento
route_plan_statuses	Coleção	Não		P: Aguardando execução E: Em execução C: Concluído W: Aguardando otimização I: Falha na otimização R: Otimizando
includes	Coleção	Não	user_excluded vehicle vehicle.device user	Este parâmetro retorna os dados adicionais referentes às entidades complementares ao planejamento

Exemplo de retorno
{
  "data": [
    {
      "id": 123,
      "status": "P",
      "total_time": 10523,
      "date_time_end": "2023-07-25T17:03:00+00:00",
      "date_time_start": "2023-07-24T17:03:00+00:00",
      "vehicle": {
        "title": "PLC-1234",
        "device": {
          "id": 13005,
          "serial": "12356",
        },
        "capacity": 5,
        "plate": "PLC-1234",
        "id": 2675
      },
      "date_created": "2023-07-24T08:00:30+00:00",
      "vehicle_id": 123,
      "total_distance": 8572,
      "total_points": 6,
      "external_code": "Teste P&D",
      "total_capacity": 4,
      "route_id": 123,
      "user_id": 123,
      "user": {
        "name": "Entregador",
        "id": 2351,
        "login": "1234567890"
      },
      "source": "M"
    }
  ]
}

Obter informações de execução de um planejamento

Obtenha informações dos planejamentos e dos dados referentes à execução de seus pontos.

GET

https://api.webrota.com.br/import/route_plan

Nome	Tipo	Obrigatório	Padrão	Descrição
route_plan_id	Inteiro	Sim		Código de planejamento
includes	Coleção	Sim	user_excluded route_points route_points.routes_info route_points.route_point_items vehicle user	Este parâmetro retorna os dados adicionais referentes às entidades complementares ao planejamento

Exemplo de retorno
{
  "data": [
    {
      "id": 123,
      "total_time": 9426,
      "user": {
        "name": "Entregador 1",
        "id": 123
      },
      "total_points": 3,
      "external_code": "CODIGO-DO-SEU-ERP",
      "date_created": "2023-07-24T18:01:38+00:00",
      "date_time_start": "2023-07-24T15:00:22+00:00",
      "total_distance": 34159.00,
      "vehicle": {
        "id": 123,
        "plate": "PLC-1234"
      },
      "route_points": [
        {
          "duration": 1170,
          "external_code": "CODIGO-DO-SEU-ERP",
          "routes_info": [
            {
              "latitude": -18.0000000,
              "return_date": "2023-07-24T18:43:21+00:00",
              "longitude": -48.0000000,
              "pictures": "hash-imagem.png"
            }
          ],
          "order": 1,
          "optimized_order": 1,
          "distance": 16.86,
          "latitude": -18.0000000,
          "longitude": -48.00000,
          "address": "Praça Doutor Duarte 10, Uberlândia, Minas Gerais",
          "status": "E",
          "time_scheduled": "2023-07-24T15:19:52+00:00",
          "name": "CODIGO-DA-SUA-NOTA + Nome do seu cliente",
          "type": "PE"
        }
      ],
      "date_time_end": "2023-11-01T15:00:22+00:00",
      "status": "C",
      "total_capacity": 0
    }
  ]
}

Obter informações de execução de um ponto

Obtenha informações referentes a um ponto específico de um planejamento.

Nome	Tipo	Obrigatório	Padrão	Descrição
route_plan_id	Inteiro	Sim		Código interno do ponto
external_code	Texto	Sim		Código externo usado durante integração para o ponto
includes	Coleção	Sim	routes_info	Este parâmetro retorna os dados adicionais referentes às entidades complementares ao ponto

GET

https://api.webrota.com.br/import/route_point

Exemplo de retorno
{
  "data": [
    {
      "external_code": "123",
      "longitude": -48.0000,
      "disable_picture": null,
      "distance": 16.86,
      "latitude": -18.0000,
      "time_scheduled": "2023-07-24T15:19:52+00:00",
      "duration": 1170,
      "id": 123,
      "type": "PE",
      "optimized_order": 1,
      "routes_info": [
        {
          "route_return_reason_id": null,
          "longitude": -48.0000,
          "id": 123,
          "route_executed_reason_id": null,
          "return_date": "2023-07-24T18:43:21+00:00",
          "route_return_reason": null,
          "pictures": "hash-imagem.png",
          "signature_img": "hash-imagem.png",
          "route_executed_reason": null,
          "hodometer_picture": null,
          "latitude": -18.0000
        }
      ],
      "name": "Seu Identificador",
      "order": 1,
      "address": "Rua FLOR DA INDIA 224 CHACARAS PARQUE MARAVILHA Uberlândia",
      "status": "E",
      "time_window": null,
      "capacity": null
    }
  ]
}

Esses são os status que podem ser assumidos por um ponto:

Status	Nome	Descrição
P	Planejamento	Ponto ainda não visitado na rota. Pronto para realização
R	Realizado	Ponto que foi executado sendo partida ou chegada
E	Entregue	Ponto de entrega já realizado na rota
D	Devolvido	Ponto que teve sua conclusão marcada como devolvido pelo agente
M	Realizado manualmente	Ponto que não foi executado pelo agente no local mas executado posteriormente

Planejamento

Autenticação​

Cadastrar​

Dados Gerais​

Entidade​

Ponto da Rota​

Items do ponto​

Pesquisar​

Obter informações de execução de um planejamento​

Obter informações de execução de um ponto​