Documentação da API

Guia de integração da API vitaRoute

Início rápido

A API vitaRoute é baseada em REST e trabalha com JSON. Todas as requisições devem ser enviadas via HTTPS.

Base URL: https://api.vitaroute.ai

Crie uma conta gratuita
Gere uma chave API no Painel
Envie sua primeira requisição de otimização

Autenticação

Todas as requisições API requerem autenticação via o cabeçalho X-Api-Key.

X-Api-Key: vtr_live_xxxxxxxxxxxxxxxxxxxx

⚠️ Nota de segurança

Não inclua suas chaves API no código-fonte. Use variáveis de ambiente.

Endpoints

POST/api/optimization/optimize

Otimização avançada de rotas. As rotas mais eficientes são calculadas avaliando 20+ parâmetros com o algoritmo proprietário RL da vitaRoute.

POST/api/route/calculate

Cálculo básico de rotas. Plano de rota simples baseado em clusters.

POST/api/route/cluster-stops

Agrupa paradas existentes de acordo com a capacidade do veículo.

Esquema de requisição

Campo	Tipo	Descrição
`facilityLat`	float	Coordenada de latitude da instalação/depósito
`facilityLng`	float	Coordenada de longitude da instalação/depósito
`totalCapacity`	int	Capacidade máxima por veículo (padrão: 14)
`vehicleCount`	int	Sempre 0 — a quantidade de veículos é determinada automaticamente
`maxWalking`	int?	Distância máxima a pé (metros, padrão: 500)
`maxDuration`	int?	Duração máxima da rota (minutos, padrão: 90)
`maxClusterDiameterKm`	float	Diâmetro geográfico máximo das paradas no mesmo cluster (km, padrão: 25)
`minSavingsKm`	float	Economia mínima de distância necessária para mesclar uma parada (km, padrão: 0,3)
`maxDetourFactor`	float	Taxa máxima de desvio ao adicionar uma parada a uma rota existente (padrão: 0,6)
`minDistrictPassengers`	int	Número mínimo de passageiros para criar uma rota específica de distrito (padrão: 8)
`tripDirection`	string	Direção da viagem: 'to_facility' (para o depósito) ou 'from_facility' (do depósito)
`arrivalTimeAtDepot`	string?	Horário de chegada dos veículos ao depósito (ISO 8601 UTC). Se fornecido, a velocidade é calculada com base no perfil de tráfego; caso contrário, 28 km/h fixo é usado.
`useDistanceMatrix`	boolean	Usar a API Distance Matrix do Google Maps para distâncias de estrada precisas (padrão: false)
`nodes`	NodeInput[]	Lista de pessoal/localizações a otimizar

NodeInput

Campo	Tipo	Descrição
`id`	string	Identificador único de pessoal/localização
`name`	string	Nome do pessoal
`latitude`	float	Coordenada de latitude
`longitude`	float	Coordenada de longitude
`district`	string?	Nome do distrito (opcional, para regras de distrito)

Esquema de resposta

{
  "routes": [
    {
      "routeId": "uuid",
      "routeName": "GEBZE 1",
      "totalDuration": 45,
      "totalDistance": 28500,
      "nodeCount": 14,
      "totalLoad": 14,
      "stops": [
        {
          "stopIndex": 0,
          "latitude": 40.8962,
          "longitude": 29.1882,
          "nodes": [
            { "id": "1", "name": "Ali Yilmaz" }
          ]
        }
      ],
      "routeCenter": {
        "latitude": 40.9,
        "longitude": 29.2
      }
    }
  ]
}

Limites de taxa

Plan	Req./mês	Nós máx.	Simultâneo
Free	50	1	1
Starter	1,000	100	5
Growth	5,000	500	20
Enterprise	Ilimitado	Ilimitado	Personalizado

Quando o limite de taxa é excedido, uma resposta 429 Too Many Requests é retornada. O cabeçalho Retry-After especifica o tempo de espera.

Códigos de erro

400

Bad Request

JSON inválido ou campo obrigatório ausente

401

Unauthorized

Chave API ausente ou inválida

403

Forbidden

O limite do seu plano foi excedido

429

Too Many Requests

Limite de taxa excedido

500

Internal Server Error

Erro do servidor, entre em contato com o suporte

Exemplos de código

curl

curl -X POST https://api.vitaroute.ai/api/optimization/optimize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: vtr_live_your_key_here" \
  -d '{
    "facilityLat": 40.9139,
    "facilityLng": 29.1167,
    "totalCapacity": 16,
    "vehicleCount": 0,
    "maxWalking": 500,
    "maxDuration": 90,
    "maxClusterDiameterKm": 25,
    "minSavingsKm": 0.3,
    "maxDetourFactor": 0.6,
    "minDistrictPassengers": 8,
    "tripDirection": "to_facility",
    "arrivalTimeAtDepot": "2025-01-15T05:00:00Z",
    "useDistanceMatrix": false,
    "nodes": [
      { "id": "1", "name": "Ali Yilmaz", "latitude": 40.8962, "longitude": 29.1882, "district": "Kadikoy" },
      { "id": "2", "name": "Ayse Demir", "latitude": 40.9278, "longitude": 29.3125, "district": "Gebze" }
    ]
  }'

python

import requests

response = requests.post(
    "https://api.vitaroute.ai/api/optimization/optimize",
    headers={
        "Content-Type": "application/json",
        "X-Api-Key": "vtr_live_your_key_here"
    },
    json={
        "facilityLat": 40.9139,
        "facilityLng": 29.1167,
        "totalCapacity": 16,
        "vehicleCount": 0,
        "maxWalking": 500,
        "maxDuration": 90,
        "maxClusterDiameterKm": 25,
        "minSavingsKm": 0.3,
        "maxDetourFactor": 0.6,
        "minDistrictPassengers": 8,
        "tripDirection": "to_facility",
        "arrivalTimeAtDepot": "2025-01-15T05:00:00Z",
        "useDistanceMatrix": False,
        "nodes": [
            {"id": "1", "name": "Ali Yilmaz", "latitude": 40.8962, "longitude": 29.1882}
        ]
    }
)

data = response.json()
for route in data["routes"]:
    print(f"{route['routeName']}: {route['nodeCount']} stops, {route['totalDuration']} min")

javascript

const response = await fetch(
  "https://api.vitaroute.ai/api/optimization/optimize",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "vtr_live_your_key_here",
    },
    body: JSON.stringify({
      facilityLat: 40.9139,
      facilityLng: 29.1167,
      totalCapacity: 16,
      vehicleCount: 0,
      maxWalking: 500,
      maxDuration: 90,
      maxClusterDiameterKm: 25,
      minSavingsKm: 0.3,
      maxDetourFactor: 0.6,
      minDistrictPassengers: 8,
      tripDirection: "to_facility",
      arrivalTimeAtDepot: "2025-01-15T05:00:00Z",
      useDistanceMatrix: false,
      nodes: [
        { id: "1", name: "Ali Yilmaz", latitude: 40.8962, longitude: 29.1882 },
      ],
    }),
  }
);

const { routes } = await response.json();
routes.forEach(route => {
  console.log(`${route.routeName}: ${route.nodeCount} stops`);
});

C#

using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Api-Key", "vtr_live_your_key_here");

var payload = new {
    facilityLat = 40.9139,
    facilityLng = 29.1167,
    totalCapacity = 16,
    vehicleCount = 0,
    maxWalking = 500,
    maxDuration = 90,
    maxClusterDiameterKm = 25,
    minSavingsKm = 0.3,
    maxDetourFactor = 0.6,
    minDistrictPassengers = 8,
    tripDirection = "to_facility",
    arrivalTimeAtDepot = "2025-01-15T05:00:00Z",
    useDistanceMatrix = false,
    nodes = new[] {
        new { id = "1", name = "Ali Yilmaz", latitude = 40.8962, longitude = 29.1882 }
    }
};

var response = await client.PostAsJsonAsync(
    "https://api.vitaroute.ai/api/optimization/optimize",
    payload
);

var result = await response.Content.ReadFromJsonAsync<RouteResponse>();