Quickstart

Realiza tu primera llamada autenticada a la API de Routal en menos de cinco minutos.

Esta guía te lleva desde "ninguna cuenta" hasta una llamada exitosa a la API. Lleva unos cinco minutos.

1. Consigue una API key

Las API keys viven en el dashboard del planner. Abre tu cuenta de Routal en planner.routal.com y ve a Settings → Developers → API Keys, o salta directamente a:

planner.routal.com/h/settings/developers/api-keys

Pincha en Create key, dale un label descriptivo (p. ej. staging-integration) y copia el valor. La key empieza por api_key_. Trátala como una contraseña — concede el mismo acceso que el usuario que la creó.

Si aún no tienes cuenta en Routal, inicia un trial.

2. Lanza tu primera petición

Un buen primer endpoint es GET /v2/vehicles — devuelve los vehicles de tu flota para un proyecto. project_id es obligatorio.

curl -G 'https://api.routal.com/v2/vehicles' \
  --data-urlencode 'private_key=YOUR_KEY' \
  --data-urlencode 'project_id=YOUR_PROJECT_ID'

Sustituye YOUR_KEY por el valor que copiaste arriba, y YOUR_PROJECT_ID por el ID hex de 24 caracteres del proyecto (visible en la URL de tu proyecto en el dashboard).

Respuesta esperada

La respuesta usa el envelope paginado estándar. Los campos vienen del schema real VehicleData del spec.

{
  "total": 4,
  "limit": 20,
  "offset": 0,
  "pages": 1,
  "page": 1,
  "docs": [
    {
      "id": "4f75d991ac359f8c4c79d762",
      "organization_id": "4f75d991ac359f8c4c79d762",
      "project_id": "4f75d991ac359f8c4c79d762",
      "external_id": "the_external_id",
      "label": "Van 01",
      "plate": "2596KHO",
      "vehicle_model": "Transit",
      "brand": "Ford",
      "color": "#089747",
      "enabled": true,
      "default_provides": ["frozen"],
      "created_at": "2026-05-21T10:00:00.000Z"
    }
  ]
}

Un vehicle tiene muchos más campos (defaults de capacidad, time windows, etc.) — consulta API Reference → Vehicle para el schema completo.

Si no funcionó

Status	Causa probable
`401 Unauthorized`	`private_key` ausente o inválida. Cada fallo de auth con API key se reporta como `highway.apiKey.error.not_found`.
`400 Bad Request`	Falta el `project_id` (es obligatorio) o un nombre de parámetro mal escrito.
`404 Not Found`	URL incorrecta. La base es `https://api.routal.com`, sin slash final.

Consulta Errors para la referencia completa de machine codes.

3. Crea tu primer plan

Un Plan agrupa stops, vehicles y routes para una ventana de entrega. POST /v2/plan lo crea. project_id es obligatorio como query parameter.

curl -X POST 'https://api.routal.com/v2/plan?private_key=YOUR_KEY&project_id=YOUR_PROJECT_ID' \
  -H 'Content-Type: application/json' \
  -d '{
    "label": "Hello Routal",
    "execution_date": "2026-05-22"
  }'

La respuesta lleva el id del plan más contadores agregados. A partir de ahí puedes añadir stops, attach routes y llamar a POST /v2/plan/{id}/optimize para calcular asignaciones óptimas.

{
  "id": "4f75d991ac359f8c4c79d762",
  "organization_id": "4f75d991ac359f8c4c79d762",
  "project_id": "4f75d991ac359f8c4c79d762",
  "label": "Hello Routal",
  "status": "planning",
  "execution_date": "2026-05-22",
  "completed_stops": 0,
  "canceled_stops": 0,
  "pending_stops": 0,
  "incomplete_stops": 0,
  "total_stops": 0,
  "total_routes": 0,
  "created_at": "2026-05-21T10:05:00.000Z"
}

¿Qué viene después?

Recorre un escenario completo en la sección Recetas — cada una abre con una tarjeta TL;DR para que te identifiques en segundos.
Explora la API Reference para cada endpoint, parámetro y schema.
Lee Authentication — rotación de keys, buenas prácticas de seguridad, qué pueden y qué no pueden hacer las API keys hoy.
Suscríbete a Webhooks para que tus sistemas reaccionen a eventos de ciclo de vida de plan y stop en tiempo real.
Entiende el Lifecycle de plans, routes y stops antes de construir lógica con estados.
¿Trabajas con un asistente de IA? Apunta tu bloque de contexto LLM al archivo de reglas de tu editor.

¿Comentarios? Escríbenos a developers@routal.com o por el chat del dashboard del planner.