Integrar o Routal quando é a IA que escreve o código

A parte cara era conectar, não otimizar

Uma integração com um ERP raramente encalha no algoritmo. O otimizador organiza uma frota inteira em segundos. As semanas acumulam-se à volta: autenticar cada pedido, traduzir as encomendas do ERP para o formato de paragens que o Routal entende, paginar respostas longas, ler bem os códigos de erro, manter vivos os webhooks que avisam de cada mudança de estado. Essa canalização, multiplicada pela agenda de um programador, é o que durante anos transformou qualquer ligação num projeto com orçamento e responsável.

Fazer com que dois sistemas se entendam é um problema antigo e aborrecido. Os assistentes de programação tornaram-no, de repente, muito mais barato.

A virada foi dar contexto à IA

O código de integração quase já não se escreve do zero. Encarrega-se a um assistente. Descreves ao Cursor, ao Claude Code, ao Copilot ou ao chat que tiveres aberto aquilo de que precisas, e ele volta com uma primeira versão que quase se aguenta sozinha.

O "quase" pesa. Assim que o assistente toca numa API que não consta do seu treino, preenche as lacunas com aquilo que estatisticamente se parece com uma API: nomes de endpoint verosímeis, um cabeçalho de autenticação que não corresponde, parâmetros que ninguém chegou a implementar. O resultado compila sem reclamar e depois não responde, e perseguir uma alucinação custa mais do que teria custado escrever a chamada à mão.

A novidade deste último ano vive no outro extremo dessa conversa. As APIs começaram a publicar o seu contexto em ficheiros feitos para um modelo ler. O formato que se está a impor chama-se llms.txt. É primo do robots.txt, com a intenção ao contrário: onde um diz a um motor de busca por onde não passar, o outro entrega a um modelo o mapa completo da API. Endpoints, a forma de cada payload, o catálogo de erros, os detalhes que normalmente só se aprendem ao tropeçar, e o modelo mental que dá sentido a tudo o resto.

Com esse ficheiro à frente, o assistente deixa de improvisar. As chamadas saem bem à primeira e o que ocupava semanas cabe numa tarde. À pessoa fica a parte que nunca convém delegar: escolher o que construir e confirmar que o que foi construído aguenta.

O que o Routal põe em cima da mesa

O developers.routal.com nasceu dessa ideia. A intenção era que o teu assistente tenha à frente tudo o que o Routal sabe sobre si próprio antes de escreveres uma única linha.

A página gira à volta de uma frase, o Routal como o cérebro de rotas do teu ERP. As encomendas entram a partir de SAP, Dynamics 365, Navision, Odoo ou qualquer sistema que fale JSON; saem convertidas em rotas otimizadas; são despachadas para os condutores; e os webhooks devolvem cada entrega fechada ao teu sistema. O percurso inteiro cabe nessa linha.

Três ficheiros carregam com o trabalho pesado:

• llms.txt faz de índice: título, resumo e URL de cada página e cada endpoint, para que o modelo saiba o que existe e onde procurar.
• llms-full.txt é a versão integral. Toda a documentação condensada em cerca de 150 KB, calibrada para entrar de uma só peça na janela de contexto. É a referência oficial e regenera-se sozinha sempre que algo muda.
• openapi.json é a especificação OpenAPI 3.0, a que os geradores de clientes mastigam.

A isto juntam-se duas comodidades. Cada receita de integração tem um botão que a abre no ChatGPT, Claude, Copilot ou Gemini com o contexto já carregado, e há modelos para fixar todo o contexto nas regras do Cursor ou do Claude Code. A documentação está escrita para que um modelo a consuma tanto como tu a lês.

Como entregá-lo ao teu assistente

Não é preciso uma ferramenta específica. Serve a que já usas. Quatro passos.

1. Dá-lhe o contexto. Funciona igual em qualquer chat. Cola este endereço na conversa e pede o que precisas:

https://developers.routal.com/llms-full.txt

Se a tua ferramenta não aceitar links, abre o ficheiro e cola o texto diretamente. A partir daí o modelo tem o Routal inteiro à mão.

2. Para experimentar, zero configuração. Cada receita traz o botão "Open in AI assistant". Escolhes ChatGPT, Claude, Copilot ou Gemini e abre com o contexto e um prompt já escritos. É o caminho cómodo para testar um cenário antes de lhe dedicar tempo.

3. Para ir a sério, fixa-o uma vez. O contexto vive no ficheiro de regras do teu editor e aplica-se em cada sessão sem teres de te lembrar dele:

• No Cursor, o ficheiro .cursor/rules/routal.mdc
• No Claude Code, dentro do teu CLAUDE.md
• No Windsurf, Copilot ou outros, apontando para o URL de llms-full.txt

Convém rematar com uma ordem firme: que não invente endpoints, e que dê por inexistente tudo o que não apareça em llms-full.txt ou em openapi.json.

4. Confirma antes de confiares. Basta uma pergunta de controlo: "escreve uma chamada curl que crie um plano do Routal para amanhã". Se o contexto entrou bem, três sinais denunciam-no:

• a chave viaja como private_key na query string (o erro habitual é colocá-la num cabeçalho Authorization)
• aparece o project_id
• o URL base é api.routal.com, não o da documentação

Se algo desafinar, voltas a colar o llms-full.txt e pedes-lhe que o releia. Meio minuto e já sabes se o assistente está em condições de escrever código a sério.

A parte que não se delega

Fica um pormenor que não vale a pena disfarçar. O assistente redige o código; a responsabilidade continua onde sempre esteve. Alguém decide o que integrar e alguém assina que a autenticação, os webhooks e os casos limite se comportam antes de aquilo chegar a produção. A pergunta de controlo do passo quatro é exatamente essa assinatura.

E a qualidade do que sai está colada à qualidade do contexto que entra. Por isso o trabalho mudou de natureza mais do que de volume: de escrever o código repetido passou-se a cuidar do contexto, que nos cabe a nós, e a enunciar bem o problema e rever a resposta, que te cabe a ti. Sai mais curto e, com alguma sorte, mais interessante.

Por onde começar

O primeiro passo custa menos do que sugere a memória de integrações anteriores. Geras uma API key no painel do planner, abres developers.routal.com, colas o URL de llms-full.txt no teu assistente e pedes a primeira chamada. As receitas estão agrupadas pelo ritmo real de cada operação: batch noturno de distribuição B2B, esse batch com despacho ao vivo por cima, same-day, logística inversa, serviço de campo, serviços recorrentes. É provável que uma descreva a tua quase sem retoques.

O guia de integração com IA percorre o processo inteiro em detalhe. E se preferires vê-lo sobre as tuas próprias rotas antes de abrir o editor, escreve-nos.

Calcular a rota há anos que é a parte rápida. A cablagem que a liga à tua operação começa finalmente a mover-se à mesma velocidade.