Documentación de la API

Guía de integración de la API vitaRoute

Inicio rápido

La API vitaRoute está basada en REST y trabaja con JSON. Todas las solicitudes deben enviarse a través de HTTPS.

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

Cree una cuenta gratuita
Genere una clave API desde el Panel
Envíe su primera solicitud de optimización

Autenticación

Todas las solicitudes de API requieren autenticación mediante el encabezado X-Api-Key.

X-Api-Key: vtr_live_xxxxxxxxxxxxxxxxxxxx

⚠️ Nota de seguridad

No incluya sus claves API en el código fuente. Use variables de entorno.

Endpoints

POST/api/optimization/optimize

Optimización avanzada de rutas. Las rutas más eficientes se calculan evaluando 20+ parámetros con el algoritmo propietario RL de vitaRoute.

POST/api/route/calculate

Cálculo básico de rutas. Plan de ruta simple basado en clústeres.

POST/api/route/cluster-stops

Agrupa las paradas existentes según la capacidad del vehículo.

Esquema de solicitud

Campo	Tipo	Descripción
`facilityLat`	float	Coordenada de latitud de la instalación/depósito
`facilityLng`	float	Coordenada de longitud de la instalación/depósito
`totalCapacity`	int	Capacidad máxima por vehículo (predeterminado: 14)
`vehicleCount`	int	Siempre 0 — el número de vehículos se determina automáticamente
`maxWalking`	int?	Distancia máxima a pie (metros, predeterminado: 500)
`maxDuration`	int?	Duración máxima de la ruta (minutos, predeterminado: 90)
`maxClusterDiameterKm`	float	Diámetro geográfico máximo de las paradas en el mismo clúster (km, predeterminado: 25)
`minSavingsKm`	float	Ahorro mínimo de distancia requerido para fusionar una parada (km, predeterminado: 0,3)
`maxDetourFactor`	float	Ratio máximo de desvío al agregar una parada a una ruta existente (predeterminado: 0,6)
`minDistrictPassengers`	int	Mínimo de pasajeros requeridos para crear una ruta específica de distrito (predeterminado: 8)
`tripDirection`	string	Dirección del viaje: 'to_facility' (hacia el depósito) o 'from_facility' (desde el depósito)
`arrivalTimeAtDepot`	string?	Hora de llegada de los vehículos al depósito (ISO 8601 UTC). Si se proporciona, la velocidad se calcula según el perfil de tráfico; de lo contrario se usan 28 km/h fijos.
`useDistanceMatrix`	boolean	Usar la API Distance Matrix de Google Maps para distancias de ruta precisas (predeterminado: false)
`nodes`	NodeInput[]	Lista de personal/ubicaciones a optimizar

NodeInput

Campo	Tipo	Descripción
`id`	string	Identificador único de personal/ubicación
`name`	string	Nombre del personal
`latitude`	float	Coordenada de latitud
`longitude`	float	Coordenada de longitud
`district`	string?	Nombre del distrito (opcional, para reglas de distrito)

Esquema de respuesta

{
  "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
      }
    }
  ]
}

Límites de velocidad

Plan	Sol./mes	Nodos máx.	Simultáneo
Free	50	1	1
Starter	1,000	100	5
Growth	5,000	500	20
Enterprise	Ilimitado	Ilimitado	Personalizado

Cuando se supera el límite de velocidad, se devuelve una respuesta 429 Too Many Requests. El encabezado Retry-After especifica el tiempo de espera.

Códigos de error

400

Bad Request

JSON inválido o campo obligatorio faltante

401

Unauthorized

Clave API faltante o inválida

403

Forbidden

Se ha superado el límite de su plan

429

Too Many Requests

Límite de velocidad superado

500

Internal Server Error

Error del servidor, contacte con el soporte

Ejemplos 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>();