--- name: rn description: "Rota Nacional — API de IA compatível com OpenAI e Anthropic, com a barreira de privacidade (CPF, CNPJ, e-mail, telefone e nomes) antes do modelo. Use quando a tarefa envolver Rota Nacional, rota-nacional.ia.br, modelos rota/* ou limpeza de dados pessoais por API." --- # Rota Nacional — skill para agentes **Live:** https://rota-nacional.ia.br **Local:** https://dev.rota-nacional.ia.br **Descoberta:** `GET /api/` · `/llms.txt` · `/llms-full.txt` · `/openapi.json` · `/developers` **MCP:** `POST https://rota-nacional.ia.br/mcp` **Por setor:** `/pt/solucoes/` · `/en/solutions/` — o fluxo, um exemplo real da barreira e a integração para saúde, atendimento, recrutamento, gestão pública, jurídico, contabilidade, pesquisa e agentes de WhatsApp **n8n:** `/integracoes/rota-atendimento-n8n.json` é o fluxo importável de atendimento. Guia: `/pt/solucoes/agentes-de-whatsapp/#n8n` ou `/en/solutions/whatsapp-agents/#n8n`. Usa HTTP Request para chat completions, com Bearer Auth separado do JSON. Recebe `{message: string}` (1 a 8.000 caracteres) de outro fluxo e devolve `{reply, model}`. O exemplo manual é fictício. Erro interrompe a execução; não há retry automático. Não salva dados de execução nem envia WhatsApp. O fluxo chamador deve manter a mesma retenção e controlar autenticação do canal, duplicatas e encaminhamento humano. Chave: `Authorization: Bearer ` — a criada na conta (Chaves de API, `mmk_…`) ou uma `sk-rota-…` de antes. A barreira roda ANTES de qualquer modelo, pela política da organização: `placeholder` (marcadores `[CPF_1]`, `[PESSOA_1]`…), `redact` (remove), `block` (recusa com 422) ou `monitor` (só registra). O `policy` do pedido só endurece a da organização; texto do prompt nunca muda a política. Respostas trazem categorias e contagens, nunca os valores. Conta nova: 30 dias de teste com cota nos modelos de chat; depois, crédito pré-pago em reais por Pix, no botão do saldo da barra do painel (`/pt/app/creditos/`, em inglês `/en/app/credits/`, abre a janela dele), em pacotes de R$ 10, 25, 50 ou 100. As capacidades `rn.*` pela chave pagam por uso desde a primeira chamada, do saldo da organização: R$ 0,002 por mensagem moderada, R$ 0,0002 por texto vetorizado, R$ 0,01 por MB de áudio transcrito, R$ 0,02 por mil caracteres de voz, R$ 0,10 por minuto de música, R$ 0,01 por composição, R$ 0,01 por página de OCR lida (reserva `max_pages`, padrão 40, e devolve o resto), R$ 0,05 por página revisada e R$ 0,10 por imagem (tabela em `/pt/docs/#precos` e no `quota` de `GET /api/`). Sem saldo, a resposta é 402 no formato x402: `accepts` (USDC na Base, mínimo de US$ 0,001), `preco_brl` e `buy_credit_url`; repita com `PAYMENT-SIGNATURE` (x402 v2) ou `X-PAYMENT` (v1) para pagar só a chamada (o recibo volta em `PAYMENT-RESPONSE` e em `X-PAYMENT-RESPONSE`). Sem worker para a capacidade, 503 `capability_unavailable` e nada é cobrado. O débito do saldo volta se o job falhar, for cancelado ou vencer na fila. O laboratório do painel não cobra. Sem chave e sem conta, as rotas pagas aceitam x402 (dono, 07/10/2026: "tem que aceitar x402 sem conta em tudo"): as capacidades `rn.*`, o chat e as mensagens dos modelos vendidos por crédito (o preço é o teto: a entrada estimada e o `max_tokens`, padrão 1.024, que passa a ir no pedido) e a limpeza de privacidade (R$ 0,001 por mil caracteres; a extração, R$ 0,01 por MB). O 402 traz o preço e o `accepts`; repita com `PAYMENT-SIGNATURE` (v2) ou `X-PAYMENT` (v1). A carteira que paga vira a conta dela aqui: o uso, os jobs e o saldo que sobra (o troco do mínimo, a sobra do chat, o estorno) ficam nela. Para gastar o saldo, envie `X-Carteira: `: o 402 pede só a diferença, no mínimo do x402, e o saldo usado é sempre o da carteira que pagou. A carteira vinculada a uma conta ("Entrar com carteira cripto" no site) paga para a conta, e o que ela pagou antes passa para a conta ao entrar. O job assíncrono se acompanha pelo `token` das URLs do 202 (`GET /v1/jobs/:id?token=…`). Sem chave, `GET /v1/capabilities` é público, e os modelos sem preço por uso respondem 403 `model_not_sold_per_use`. ## Operações | Tool | HTTP | |------|------| | `api_index` | `GET /api/` | | `listar_modelos` | `GET /v1/models` — ids `rota/*` e para que serve cada um; público | | `conversar` | `POST /v1/chat/completions` — corpo da OpenAI, `stream: true` em SSE; `rota/auto` escolhe o modelo | | — | `POST /v1/messages` — a API Messages da Anthropic (Claude Code: `ANTHROPIC_BASE_URL` = a origem, `ANTHROPIC_AUTH_TOKEN` = a chave, `ANTHROPIC_MODEL` = um id `rota/*`) | | `limpar_dados_pessoais` | `POST /v1/privacy/clean` — `text`, `input` ou `items`; sem modelo nenhum | | `listar_radar` | `GET /api/radar` — bookmarks atualizados diariamente, notícias e fatos relevantes; público | | `listar_cyber` | `GET /api/cyber` — segurança e assuntos relacionados; público | | `listar_guias` | `GET /api/guias` — orientação útil ao RN derivada somente do Radar; público | | `listar_novidades` | `GET /api/conteudo/novidades` — IDs e datas por área; público | | — | `POST /v1/privacy/jobs` e `GET /v1/privacy/jobs/:id` — a mesma limpeza em lote, consultável | | — | `POST /v1/privacy/extract` — PDF (ou imagem, OCR beta) até 25 MB → texto já limpo | | — | `POST /v1/audio/transcriptions` — áudio até 25 MB → transcrição já limpa | | — | `GET /v1/capabilities` — o que os workers conectados executam agora | | — | `GET /api/slot`, `POST /api/slot/exibicao` e `GET /api/slot/ir/:oferta` — a oferta da casa que o pacote Pi (`pi-rn`) mostra no turno; só contadores, sem código nem prompt; agente não precisa chamar | | — | `POST /v1/moderations` — prévia; formato da OpenAI (`input` texto ou lista, até 32) com a política da organização em `categories` (até 16, cada uma com `name`, `violation` e, se quiser, `not_violation` e `exception`); sem `categories`, a taxonomia geral (`violence`, `hate`, `fraud`…); `cutoff` `precision` (padrão) ou `balanced`; devolve `results[]` com `flagged`, `score`, `cutoff`, `categories`, `category_scores` e `category_cutoffs` (na taxonomia geral, cada categoria tem o próprio corte), sem repetir o texto | | — | `POST /v1/embeddings`, `/v1/audio/speech`, `/v1/audio/music`, `/v1/audio/compositions`, `/v1/images/generations`, `/v1/images/edits`, `/v1/ocr`, `/v1/documents/fidelity/jobs`, `/v1/documents/review/jobs` — prévia; as assíncronas devolvem 202 com `status_url` | | — | `GET /v1/jobs/:id`, `GET /v1/jobs/:id/result`, `DELETE /v1/jobs/:id` — o job de uma capacidade | O painel (`/pt/app/`, em inglês `/en/app/`) fala com `/api/app/*` pela sessão da conta (não pela chave), na organização do `X-Organization-Id`: `GET /api/app/perfil`, `POST /api/app/aceite` (os Termos e a retenção legal, antes de tudo), `GET /api/app/resumo`, `GET /api/app/quota`, `GET /api/app/uso` (`?cursor=`, `?limit=`), `GET`/`POST /api/app/modelos`, `PATCH /api/app/organizacao` e `POST /api/app/privacy/clean`; o saldo e as compras, `GET /api/credito/asaas/saldo`. O laboratório (`/pt/app/experimentar/`, em inglês `/en/app/try/`) testa ao vivo cada capacidade `rn.*` pela sessão: `GET /api/app/lab/estado` (as ferramentas, o uso de 24 h e a fila), `POST /api/app/lab/:ferramenta` (a mesma rota `/v1/*`, com teto por organização em 24 h) e o job em `GET /api/app/lab/jobs/:id` (espera longa com `?desde=`), `GET …/result` e `DELETE`. As chaves são as da conta (`/api/account/keys`) e a compra é o Pix da casa (`/api/credito/asaas`). A home mostra os números públicos de `GET /api/public/stats`. O radar (`GET /api/radar`, `/pt/radar/`), o cyber (`GET /api/cyber`, `/pt/cyber/`) e os guias (`GET /api/guias`, `/pt/guias/`, em inglês `/en/guides/`) são páginas públicas: o texto é da Rota, a fonte original vai no fim. Quando houver utilidade pertinente, a peça oferece um exemplo da API. `acoes.pt` e `acoes.en` devolvem o bloco com `id`, `tipo`, `posicao` (parágrafo a partir de zero), `rotulo`, `titulo`, `condicao`, `acao` e `href`, ou `null`. O destino é documentação local. Abrir o exemplo não executa a API nem cobra. Não trate a ausência de bloco como falta de conteúdo. O modelo decide quando um bookmark sustenta orientação útil ao RN e pode virar Guia; o bookmark continua no Radar. Cyber não gera Guias, e notícias gerais da Inova não entram no acervo. Não há corte de quantidade no histórico. As listas API usam `?page=`, com vinte peças por página até o fim. Acompanhe o acervo inteiro por `/feed.xml`, `/feed.json` e por área/idioma, como `/pt/guias/feed.xml` ou `/en/guides/feed.json`. O OKF em `/okf/index.md` contém um Markdown por artigo. `GET /api/conteudo/novidades` fornece IDs para contagem local; o histórico de leitura fica no navegador. A newsletter usa a conta com e-mail verificado, assuntos e consentimento em `/pt/newsletter/`. `GET /api/newsletter` consulta a assinatura; `PUT /api/newsletter` salva a escolha com CSRF e consentimento. `POST /api/newsletter/cancelar` cancela pelo token de uma entrega; GET nunca cancela. Cadastro requer a migração do módulo; envio fica desligado até a ativação do correio. Nunca assine uma pessoa sem autorização. Erros: 401 chave errada ou revogada (sem `Authorization`, a rota paga responde 402); 402 sem saldo nem pagamento; 403 conta aguardando liberação, teste encerrado, modelo fora da organização ou origem de rede fora da política; 422 bloqueio da barreira; 429 limite por minuto ou cota; 503 sem worker para a capacidade. Imagem ou documento dentro do chat são recusados: extraia antes com `/v1/privacy/extract`. Nunca envie dado real de teste: use textos fictícios. A detecção tem limites; confira o resultado para o seu processo. ## Ferramentas de inferência O gateway nativo usa `/v1/providers/{provider}/` seguido do caminho original do provedor. Exige chave RN de organização e conexão privada ativa com aceite nativo registrado. Esse caminho envia o conteúdo original, sem aplicar a barreira. O catálogo `rota/*` mantém a política de privacidade. Nunca troque um caminho pelo outro sem avaliar esse contrato. O modelo conserva seu identificador nativo. `X-RN-Connection-Id` fixa uma conexão da organização. Arquivos, lotes e respostas anteriores permanecem na conexão que os criou. A ferramenta MCP `native_responses` chama a conexão privada de Responses. Ela recebe `model`, `input`, `max_output_tokens` e `store`. Uma falha do gateway retorna ao consumidor. Não há repetição após enviar ao provedor. Consulte `/openapi.json` e [o estado da migração](../../../docs/migracao-gateway.md). O módulo Bots abre em `/pt/app/bots/` ou `/en/app/bots/`. Ele oferece até quatro bots com instruções próprias, conversa, memória comum e encaminhamento de respostas. No navegador, usa a sessão do painel e o `X-Organization-Id`. Consulte `GET /api/app/bots`, configure por `PATCH`, envie por `POST /api/app/bots/mensagens` com UUID em `id` e cancele por `POST /api/app/bots/cancelar`. `GET /api/app/bots/eventos` transmite o estado por SSE, com reconexão a cada 25 segundos. O administrador libera agentes externos em “Conectar agente”. Depois, a chave RN da organização usa `consultar_bots`, `atualizar_memoria_bots`, `registrar_resultado_bot`, `enviar_ao_bot` e `cancelar_bot`, por `/mcp` ou `/v1/bots*`. Leia o espaço antes de trabalhar. Atualização de memória exige `versao`; em 409, releia e concilie. Preserve o UUID ao repetir envio ou registro de resultado. Resultado externo aparece com origem MCP. Envie `origem` ao pedir revisão de outro bot. Para acompanhar uma tarefa, consulte a cada dez segundos. Desligar a conexão recusa novos acessos. `configurar_bot` continua exigindo sessão e papel administrativo, inclusive para excluir um bot. Escrita por sessão exige CSRF. O administrador escolhe gravação, desligada por padrão. Sem gravação, o conteúdo vive somente em RAM por 30 minutos após a última alteração ou até reiniciar. Com gravação, fica cifrado na infra do RN: até 20 mensagens por bot, 30 dias por mensagem, e expiração do espaço após 30 dias sem alteração. Cada inferência usa o limite e o crédito da organização. Não repita automaticamente uma tarefa que falhou. O RN não oferece acesso a arquivos, shell, A2A nem ACP neste módulo. O cliente externo executa suas próprias capacidades e publica o resultado; o RN não importa suas sessões privadas. `rota/local` fica fora porque sua fila tem outro contrato de gravação e cancelamento. Em `/pt/app/ferramentas/` ou `/en/app/tools/`, compare até dois modelos. O endpoint `POST /api/app/playground` exige sessão, aceite e a organização ativa. Recebe `model`, `prompt` (até 4.000 caracteres), `max_tokens` (1–512) e `temperature` (0–2). Cada modelo usa uma chamada da cota ou do crédito. Esta comparação usa a rodada normal de inferência e a política de privacidade. Ela difere do laboratório de capacidades. A mesma tela gera exemplos em curl, JavaScript, Python e JSON, com `ROTA_API_KEY`. Não coloque chaves de provedores em exemplos ou no navegador. A administração da plataforma permite conferir a conexão, descobrir modelos, consultar o saldo quando o provedor o informa e testar uma frase sintética. Rotas autorizadas podem alternar por prioridade, custo interno, tempo observado, rodízio, quantidade de tentativas ou peso da chave. A recuperação respeita o preço ao cliente e nunca repete uma resposta já iniciada. Saúde e esperas são locais ao processo; configuração e permissões ficam no MySQL.