Integra con IA

En 2026 la mayoría de los developers escriben código de API con un asistente de IA abierto en la pestaña de al lado. Routal expone tres recursos machine-readable que se conectan a cualquier asistente y le dan el contexto necesario para generar código correcto. Esta página es la guía de setup.

Los tres recursos

La mayoría querrá /llms-full.txt. Es la versión autoritativa y se mantiene sincronizada con la doc automáticamente.

Dos formas de pasarle el contexto a tu asistente

Zero setup — usa el botón "Open in AI"

Cada recipe page tiene un botón Open in AI assistant. Click → escoges ChatGPT, Claude, Copilot o Gemini → el asistente se abre con el contexto del recipe, la URL de llms.txt y un prompt parametrizado ya cargado. Sin archivos de configuración, sin reglas, sin setup.

Usa este camino si estás explorando escenarios o escribiendo código de Routal ocasionalmente.

Project rules — cabléalo en tu IDE una vez

Para un proyecto de integración activo, mete el contexto de Routal en el archivo de reglas de tu asistente. El modelo lo recoge automáticamente en cada sesión.

Cursor

Crea .cursor/rules/routal.mdc en la raíz de tu repo:

---
description: Routal API context
alwaysApply: true
---

Cuando escribas código que llame a api.routal.com, trata
https://developers.routal.com/llms-full.txt como la referencia autoritativa de
endpoints, payloads, error codes y gotchas. No inventes endpoints — si no está
en ese archivo o en https://developers.routal.com/openapi.json, no existe.

Reglas duras:
- La auth es el query parameter `?private_key=...` — NO `Authorization: Bearer`.
- Bifurca el manejo de errores por `message_id`, no por el texto de `message`.
- Usa endpoints bulk (POST /v2/stops, POST /v3/vehicles) en vez de loops single-create.
- Reacciona a webhooks en vez de hacer polling.

Claude Code

Añade a CLAUDE.md en la raíz de tu proyecto:

## Routal API integration

Referencia autoritativa de la API: https://developers.routal.com/llms-full.txt

Cuando escribas código que llame a api.routal.com:
- La auth es el query parameter `?private_key=...`, nunca un header `Authorization`.
- Bifurca por `error.message_id`, no por `error.message`.
- Prefiere endpoints bulk (POST /v2/stops, POST /v3/vehicles) en vez de loops.
- Suscríbete a webhooks en vez de hacer polling.

No inventes endpoints. Si no está en `/llms-full.txt` o `/openapi.json`, no existe.

Windsurf, GitHub Copilot u otros asistentes

La mayoría aceptan una URL como fuente de conocimiento vía su archivo de reglas. Apúntalos a https://developers.routal.com/llms-full.txt. Si tu herramienta no acepta URLs, copia el contenido del archivo directamente.

Verifica que el asistente tiene el contexto

Tras el cableado, hazle al asistente una pregunta de control. Un asistente bien primed produce algo como el snippet de abajo; uno sin primar intentará Authorization: Bearer, inventará un endpoint o se olvidará del project_id.

Prompt:

Escribe una llamada curl que cree un plan de Routal para mañana.

Respuesta esperada:

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": "Mañana", "execution_date": "2026-05-23" }'

Tres señales de que el asistente tiene el contexto:

• private_key va en el query string, no en Authorization.
• project_id se exige como query parameter.
• La URL base es api.routal.com, no developers.routal.com.

Si la respuesta sale mal, pega /llms-full.txt en la conversación como fallback y pídele al asistente que lo relea.

Los 10 hechos que todo asistente necesita

Si escribes un system prompt a mano, estas son las reglas load-bearing. Ya están dentro de /llms-full.txt — esto es solo el resumen humano para que verifiques lo que sale del asistente.

1. La auth es private_key como query parameter. Nunca Authorization: Bearer.
2. external_id es tu palanca de idempotencia. No hay header Idempotency-Key hoy. Patrón: POST /v2/stops/search por external_id → si existe, reúsalo; si no, créalo.
3. Bifurca por message_id. Los errores son { message, message_id: "highway.<context>.error.<reason>" }. El texto puede cambiar; el ID es estable.
4. Usa endpoints bulk. POST /v2/stops y POST /v3/vehicles aceptan arrays. Loops single-create queman el presupuesto de 2.000 req/min.
5. Suscríbete a webhooks, no hagas polling. Los webhooks se disparan en cada cambio de estado. El polling derrocha rate budget y va siempre con retraso.
6. POST /v2/plan/{id}/optimize no es retry-safe. Una segunda llamada puede mover stops si la primera completó. Si una está en curso obtienes highway.optimization.error.sync_optimization_already_progress — espera, no reintentes.
7. Dispatch envía un email; NO cambia el status del route. El route pasa a in_transit cuando el conductor abre el magic link, no cuando llamas a POST /v2/route/{id}/dispatch.
8. Los webhooks no tienen signature hoy. Autentícalos con un token en la URL (/webhooks/routal?token=...). Deduplica por (event_id, data.id, data.updated_at). Los webhooks se auto-desactivan tras 50 fallos consecutivos.
9. La paginación es offset-based — { total, limit, offset, pages, page, docs }. Fija siempre un sort para evitar duplicados bajo escrituras concurrentes.
10. Los deletes hacen cascade y no chequean el status. DELETE /v2/plan/{id} triunfa incluso si está in-progress. El único hard guard es is_locked: true en una route.

El modelo mental de Routal

Project (workspace de larga vida; vehicles, custom fields, integrations viven aquí)
  └── Plan (una ventana de ejecución — típicamente un día o un turno)
        ├── Stops (entregas / recogidas / servicios)
        ├── Vehicles (asignados al plan, sacados de la flota del project)
        └── Routes (lista ordenada de stops por vehicle, creada por el optimizador)

Status enums que verás en respuestas y webhooks:

• Plan: draft · planning · in_progress · finished
• Route: not_started · in_transit · finished
• Stop: pending · incomplete · completed · canceled

Routal computa las transiciones automáticamente. Los clients nunca llaman a un endpoint para avanzar el status. El route pasa a in_transit cuando el conductor abre el magic link; el plan pasa a finished cuando todas las routes están finished.

Lo que NO está en esta página

• El bloque completo de contexto de la API. Vive en /llms-full.txt — auto-generado desde cada doc page para que nunca se desfase. Apunta tu asistente a la URL en vez de mantener una copia separada.
• Code samples en TypeScript / Python / cURL. Cada endpoint page en la API Reference los tiene, y cada receta recorre la integración completa en los tres lenguajes.
• Un "cómo funciona Routal" general. Navega planner.routal.com para el lado producto, o lee Resource lifecycle para la máquina de estados del lado API.