Quickstart

Faça sua primeira chamada autenticada à API da Routal em menos de cinco minutos.

Este guia leva você de "nenhuma conta" a uma chamada de API bem-sucedida. Leva cerca de cinco minutos.

1. Obtenha uma API key

As API keys ficam no dashboard do planner. Abra sua conta da Routal em planner.routal.com e vá em Settings → Developers → API Keys, ou pule direto para:

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

Clique em Create key, dê um label descritivo (ex.: staging-integration) e copie o valor. A chave começa com api_key_. Trate-a como uma senha — ela concede o mesmo acesso do usuário que a criou.

Se você ainda não tem conta na Routal, inicie um trial.

2. Faça sua primeira requisição

Um bom primeiro endpoint é GET /v2/vehicles — retorna os vehicles da sua frota para um projeto. project_id é obrigatório.

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

Substitua YOUR_KEY pelo valor que você copiou acima, e YOUR_PROJECT_ID pelo ID hex de 24 caracteres do projeto (visível na URL do seu projeto no dashboard).

Resposta esperada

A resposta usa o envelope paginado padrão. Os campos vêm do schema real VehicleData no 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"
    }
  ]
}

Um vehicle tem muito mais campos (defaults de capacidade, time windows, etc.) — veja API Reference → Vehicle para o schema completo.

Se não funcionou

Status	Causa provável
`401 Unauthorized`	`private_key` ausente ou inválida. Toda falha de auth com API key aparece como `highway.apiKey.error.not_found`.
`400 Bad Request`	Falta `project_id` (obrigatório) ou erro de digitação no nome de um parâmetro.
`404 Not Found`	URL incorreta. A base é `https://api.routal.com`, sem barra no final.

Veja Errors para a referência completa de machine codes.

3. Crie seu primeiro plan

Um Plan agrupa stops, vehicles e routes para uma janela de entrega. POST /v2/plan cria um. project_id é obrigatório 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"
  }'

A resposta traz o id do plan mais contadores agregados. A partir daí você pode adicionar stops, anexar routes e chamar POST /v2/plan/{id}/optimize para calcular atribuições ótimas.

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

E agora?

Percorra um cenário completo na seção Receitas — cada uma abre com um cartão TL;DR para você se identificar em segundos.
Navegue pela API Reference para cada endpoint, parâmetro e schema.
Leia Authentication — rotação de chaves, boas práticas de segurança, o que as API keys podem e não podem fazer hoje.
Assine Webhooks para que seus sistemas reajam a eventos de ciclo de vida de plan e stop em tempo real.
Entenda o Lifecycle de plans, routes e stops antes de construir lógica baseada em estado.
Trabalha com um assistente de IA? Aponte seu bloco de contexto LLM para o arquivo de regras do seu editor.

Feedback? Mande um email para developers@routal.com ou fale conosco pelo chat no dashboard do planner.