Integrar com IA

Em 2026 a maioria dos developers escreve código de API com um assistente de IA aberto na aba ao lado. A Routal expõe três recursos machine-readable que se conectam a qualquer assistente e dão o contexto necessário para gerar código correto. Esta página é o guia de setup.

Os três recursos

A maioria vai querer /llms-full.txt. É a versão autoritativa e fica sincronizada com a doc automaticamente.

Duas formas de dar o contexto ao seu assistente

Zero setup — use o botão "Open in AI"

Cada página de receita tem um botão Open in AI assistant. Click → escolha ChatGPT, Claude, Copilot ou Gemini → o assistente abre com o contexto da receita, a URL de llms.txt e um prompt parametrizado já carregado. Sem arquivos de configuração, sem regras, sem setup.

Use este caminho se estiver explorando cenários ou escrevendo código da Routal ocasionalmente.

Project rules — cableie no seu IDE uma vez

Para um projeto de integração ativo, coloque o contexto da Routal no arquivo de regras do seu assistente. O modelo o pega automaticamente em cada sessão.

Cursor

Crie .cursor/rules/routal.mdc na raiz do seu repo:

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

Quando escrever código que chama api.routal.com, trate
https://developers.routal.com/llms-full.txt como a referência autoritativa de
endpoints, payloads, error codes e pegadinhas. Não invente endpoints — se não
está nesse arquivo ou em https://developers.routal.com/openapi.json, não existe.

Regras duras:
- A auth é o query parameter `?private_key=...` — NÃO `Authorization: Bearer`.
- Bifurque o tratamento de erros por `message_id`, não pelo texto de `message`.
- Use endpoints bulk (POST /v2/stops, POST /v3/vehicles) em vez de loops single-create.
- Reaja a webhooks em vez de fazer polling.

Claude Code

Adicione em CLAUDE.md na raiz do seu projeto:

## Routal API integration

Referência autoritativa da API: https://developers.routal.com/llms-full.txt

Quando escrever código que chama api.routal.com:
- A auth é o query parameter `?private_key=...`, nunca um header `Authorization`.
- Bifurque por `error.message_id`, não por `error.message`.
- Prefira endpoints bulk (POST /v2/stops, POST /v3/vehicles) em vez de loops.
- Assine webhooks em vez de fazer polling.

Não invente endpoints. Se não está em `/llms-full.txt` ou `/openapi.json`, não existe.

Windsurf, GitHub Copilot ou outros assistentes

A maioria aceita uma URL como fonte de conhecimento via seu arquivo de regras. Aponte para https://developers.routal.com/llms-full.txt. Se sua ferramenta não aceita URLs, copie o conteúdo do arquivo diretamente.

Verifique que o assistente tem o contexto

Após o cabeamento, faça ao assistente uma pergunta de controle. Um assistente bem-primed produz algo como o snippet abaixo; um sem priming vai tentar Authorization: Bearer, inventar um endpoint ou esquecer o project_id.

Prompt:

Escreva uma chamada curl que cria um plan da Routal para amanhã.

Resposta 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": "Amanhã", "execution_date": "2026-05-23" }'

Três sinais de que o assistente tem o contexto:

• private_key fica na query string, não em Authorization.
• project_id é exigido como query parameter.
• A URL base é api.routal.com, não developers.routal.com.

Se a resposta sai errada, cole /llms-full.txt na conversa como fallback e peça ao assistente para reler.

Os 10 fatos que todo assistente precisa

Se você está escrevendo um system prompt à mão, estas são as regras load-bearing. Já estão dentro de /llms-full.txt — isto é só o resumo legível para que você confira o que sai do assistente.

1. A auth é private_key como query parameter. Nunca Authorization: Bearer.
2. external_id é sua alavanca de idempotência. Não há header Idempotency-Key hoje. Padrão: POST /v2/stops/search por external_id → se existe, reuse; senão, crie.
3. Bifurque por message_id. Erros são { message, message_id: "highway.<context>.error.<reason>" }. O texto pode mudar; o ID é estável.
4. Use endpoints bulk. POST /v2/stops e POST /v3/vehicles aceitam arrays. Loops single-create queimam o orçamento de 2.000 req/min.
5. Assine webhooks, não faça polling. Webhooks disparam em cada mudança de estado. Polling desperdiça rate budget e atrasa eventos reais.
6. POST /v2/plan/{id}/optimize não é retry-safe. Uma segunda chamada pode mover stops se a primeira completou. Se uma está rodando você recebe highway.optimization.error.sync_optimization_already_progress — espere, não tente de novo.
7. Dispatch envia um email; NÃO muda o status do route. O route vai para in_transit quando o motorista abre o magic link, não quando você chama POST /v2/route/{id}/dispatch.
8. Webhooks não têm signature hoje. Autentique com um token na URL (/webhooks/routal?token=...). Deduplique por (event_id, data.id, data.updated_at). Webhooks auto-desabilitam após 50 falhas consecutivas.
9. Paginação é offset-based — { total, limit, offset, pages, page, docs }. Sempre fixe um sort para evitar duplicatas sob escritas concorrentes.
10. Deletes fazem cascade e não checam status. DELETE /v2/plan/{id} funciona mesmo quando in-progress. O único hard guard é is_locked: true numa route.

O modelo mental da Routal

Project (workspace de longa duração; vehicles, custom fields, integrations vivem aqui)
  └── Plan (uma janela de execução — tipicamente um dia ou um turno)
        ├── Stops (entregas / coletas / serviços)
        ├── Vehicles (atribuídos ao plan, vindos da frota do project)
        └── Routes (lista ordenada de stops por vehicle, criada pelo otimizador)

Status enums que você vai ver em respostas e webhooks:

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

A Routal computa as transições automaticamente. Os clients nunca chamam um endpoint para avançar o status. O route vai para in_transit quando o motorista abre o magic link; o plan vai para finished quando todas as routes estão finished.

O que NÃO está nesta página

• O bloco completo de contexto da API. Mora em /llms-full.txt — auto-gerado de cada doc page para que nunca fique desatualizado. Aponte seu assistente para a URL em vez de manter uma cópia separada.
• Code samples em TypeScript / Python / cURL. Cada endpoint page na API Reference tem, e cada receita percorre a integração completa nas três linguagens.
• Um "como funciona a Routal" geral. Navegue planner.routal.com para o lado produto, ou leia Resource lifecycle para a máquina de estados do lado API.