Desenvolvedores | Torêva — API pública, agentes e integrações

Início rápido

Nenhum cadastro, nenhuma chave, nenhum cabeçalho obrigatório. Três chamadas cobrem o ciclo inteiro de descoberta:

# 1. O que existe
curl https://toreva.com.br/api/v1

# 2. Se está de pé
curl https://toreva.com.br/api/v1/status

# 3. Como o erro se parece
curl -i https://toreva.com.br/api/v1/rota-inexistente

A terceira chamada devolve HTTP 404 com corpo JSON — não uma página HTML de erro. Caminhos fora de /api/ que não existem também devolvem 404 real, com corpo em markdown quando o Accept pede.

Nenhuma das três pede cadastro, chave ou cabeçalho. Se você é um agente e quer o guia completo de quando acionar a Torêva, comece por /agent-instructions.md.

Endpoints públicos

Todos são GET, sem autenticação, servidos a partir de https://toreva.com.br.

Endpoint	Tipo	O que devolve
`GET /api/v1`	`application/json`	Índice da versão: endpoints, política de versão, limite de taxa e onboarding.
`GET /api/v1/status`	`application/json`	Estado do serviço público, componente a componente.
`POST /.well-known/mcp`	`application/json`	Handshake do servidor MCP, transporte Streamable HTTP, sem autenticação.
`GET /.well-known/openapi.json`	`application/json`	Descrição OpenAPI 3.1 dos endpoints públicos.
`GET /.well-known/api-catalog`	`application/linkset+json`	Linkset de descoberta (RFC 9727).
`GET /.well-known/agent-skills/index.json`	`application/json`	Habilidades declaradas para agentes.
`GET /.well-known/mcp/server-card.json`	`application/json`	Cartão do servidor WebMCP exposto pelo site.
`GET /llms.txt`	`text/plain`	Mapa do domínio para modelos de linguagem.
`GET /agent-instructions.md`	`text/markdown`	Quando usar a Torêva, quando não usar e como chamar.
`GET /docs/api.md`	`text/markdown`	Referência da API em markdown.
`GET /auth.md`	`text/markdown`	Regras de autenticação para agentes.

A descrição formal está em OpenAPI 3.1 (também em /openapi.json); a referência em prosa, em /docs/api.md. Todas as operações declaram operationId único e schema tipado de resposta e de erro, para function calling funcionar sem adivinhação.

Erros em JSON

Qualquer resposta sob /api/ é JSON, inclusive as de erro. O formato é sempre o mesmo, com código estável para o cliente decidir e dica de resolução para quem está depurando:

{
  "error": {
    "code": "not_found",
    "status": 404,
    "message": "Endpoint não encontrado.",
    "hint": "Consulte https://toreva.com.br/api para a lista de endpoints públicos.",
    "documentation": "https://toreva.com.br/developers"
  }
}

code	status	Quando acontece
`not_found`	`404`	O caminho sob /api/ não existe. Confira o índice em /api/v1.
`method_not_allowed`	`405`	O método não é aceito. Os endpoints públicos são somente leitura (GET, HEAD, OPTIONS).
`rate_limited`	`429`	Limite de taxa excedido. Aguarde o que o Retry-After indicar antes de repetir.
`upstream_unavailable`	`502`	O serviço de origem não respondeu — 502, 503 e 504 são normalizados nesse código. Repita com backoff exponencial.
`endpoint_sunset`	`410`	O endpoint foi desligado depois do prazo anunciado no cabeçalho Sunset.

Trate error.code como contrato e error.message como texto para humanos: a mensagem pode ser reescrita, o código não.

Versionamento e depreciação

A versão fica no caminho: /api/v1/…. Versão corrente: v1. O caminho sem versão, /api/…, é um apelido da versão estável corrente e muda de destino quando houver v2 — use no terminal, nunca numa integração.

Toda resposta traz API-Version com a versão que respondeu. Se você chamou /api/status e leu API-Version: v1, o endereço estável equivalente é /api/v1/status.

Quando um endpoint entra em depreciação, as respostas dele passam a carregar Deprecation (RFC 9745) com a data em que a depreciação começou, e Sunset (RFC 8594) com a data em que ele deixa de responder. O aviso mínimo é de 180 dias para uma versão inteira e de 90 dias para um endpoint isolado. Depois do Sunset, a resposta vira 410 com error.code igual a endpoint_sunset.

Deprecation: @1788307200
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://toreva.com.br/docs/versioning.md>; rel="deprecation"

A política completa, com o que conta como mudança compatível e o que exige versão nova, está em /docs/versioning.md.

Servidor MCP

A Torêva publica um servidor MCP (Model Context Protocol) próprio, com transporte Streamable HTTP e sem autenticação. É JSON-RPC 2.0 sobre POST:

curl -X POST https://toreva.com.br/.well-known/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
       "clientInfo":{"name":"meu-cliente","version":"1.0"}}}'

O endpoint também responde em /mcp. GET devolve 405: este servidor não abre stream SSE, e a especificação prevê exatamente esse retorno.

Ferramentas expostas:

Ferramenta	O que faz
`consultar_cnpj_publico`	Dados cadastrais públicos de uma empresa brasileira pelo CNPJ. Não devolve endereço, CEP, telefone, e-mail nem quadro societário — esses campos exigem conta gratuita, e a resposta lista quais são em `gated_fields`.
`get_toreva_url`	URL canônica de um destino público.
`explain_toreva_workflow`	O fluxo de prospecção, para quem serve e para quem não serve.
`check_toreva_status`	Estado dos serviços, componente a componente.

Os documentos em markdown do site também são expostos como resources MCP. Metadados completos em /.well-known/mcp/server-card.json.

Markdown por negociação de conteúdo

As páginas preparadas para agentes respondem em markdown quando o pedido traz Accept: text/markdown, e em HTML caso contrário. As duas representações vivem na mesma URL e a resposta carrega Vary: Accept, para nenhum cache intermediário entregar a versão errada.

curl -H "Accept: text/markdown" https://toreva.com.br/
curl -H "Accept: text/markdown" https://toreva.com.br/developers

Endereços diretos, sem negociação: /index.md, /developers.md, /docs/api.md e /auth.md.

Recursos para agentes

/llms.txt — mapa do domínio em uma leitura só.
Agent skills — habilidades declaradas, com hash de integridade por arquivo.
MCP server card — ferramentas WebMCP registradas pelo próprio site via navigator.modelContext.
API catalog — linkset de descoberta, também anunciado no cabeçalho Link da home.

O robots.txt declara Content-Signal: ai-train=no, search=yes, ai-input=yes: a leitura por agentes é bem-vinda, o treinamento de modelos com o conteúdo não.

Ambiente de testes e onboarding

Os endpoints públicos são o ambiente de testes. Eles são somente leitura, não têm efeito colateral, não gravam nada e devolvem os mesmos dados em qualquer chamada — pode apontar sua suíte para eles sem credencial e sem risco.

O que	Disponível	Como
Acesso sem autenticação	Sim	`curl https://toreva.com.br/api/v1` — sem cadastro, sem chave, sem cabeçalho.
Ambiente de testes	Sim	Os próprios endpoints públicos, somente leitura. Mesma URL de produção.
Servidor MCP sem autenticação	Sim	`POST /.well-known/mcp`, transporte Streamable HTTP.
Teste gratuito da plataforma	Sim	app.toreva.com.br/criar-conta, sem cartão de crédito, com amostra de 10 leads.
Emissão automática de chave de API	Não	Ainda não existe no painel. Acesso a dados de conta é liberado caso a caso — escreva para contato@toreva.com.br.
Sandbox com dados sintéticos	Não	Não há. Se a sua integração precisa de um, descreva o caso de uso no e-mail acima.

Essa tabela é verificável: cada linha marcada como disponível responde agora, sem credencial, no endereço indicado. O estado de cada afirmação também sai em JSON no bloco onboarding de /api/v1.

Autenticação e chaves de API

Nada neste domínio exige autenticação. Os dados de conta — leads, CRM, cadências, cobrança — pertencem à aplicação em app.toreva.com.br e ficam atrás da sessão do usuário.

Ainda não existe emissão automática de chave de API pelo painel. Para integrar com dados de conta, crie a conta na plataforma e escreva para contato@toreva.com.br com o escopo pretendido. As regras que um agente deve seguir antes de agir em nome de um usuário estão em /auth.md.

Metadados OAuth publicados, para clientes que fazem descoberta automática: authorization server e protected resource.

Limite de taxa

120 requisições por minuto por cliente, com rajada de 60 liberada de imediato. Toda resposta sob /api/ anuncia o teto, para você se auto-regular antes de bater nele:

API-Version: v1
RateLimit: limit=120, remaining=117, reset=43
RateLimit-Limit: 120
RateLimit-Remaining: 117
RateLimit-Reset: 43
RateLimit-Policy: "public-api";q=120;w=60

RateLimit-Remaining é o saldo real daquele cliente naquele instante, e RateLimit-Reset é uma contagem regressiva de verdade: os segundos que faltam para o próximo slot vagar. A janela é deslizante de 60 segundos, então o saldo volta aos poucos, e não de uma vez na virada do minuto.

Mandamos os dois formatos: os campos separados, que a maioria dos clientes já lê, e o campo estruturado único RateLimit do rascunho novo do IETF. Use o que a sua biblioteca entender.

Ao estourar, a resposta é 429 com error.code: "rate_limited" e um Retry-After calculado — os segundos exatos até haver saldo, não um palpite fixo.

A contagem é por cliente e por instância. Um anteparo separado, bem acima desse teto, protege o serviço de enxurrada; se você o encostar, também recebe 429, com Retry-After.

Boas práticas

Repita 429 respeitando o Retry-After, e 502 com backoff exponencial. Não repita 404, 405 nem 410: eles não mudam sozinhos.
Use ETag/If-None-Match onde a resposta oferecer.
Identifique seu cliente no User-Agent, com um contato. É assim que conseguimos avisar antes de mudar algo que quebra você.
As fichas de Consulta CNPJ vêm dos dados abertos da Receita Federal e podem ser retiradas a pedido do titular. Não presuma que uma URL que respondeu 200 vai responder para sempre.

Suporte

Dúvidas de integração, pedido de acesso ou aviso de quebra: contato@toreva.com.br. Para assuntos de conta e protocolo, use a central de suporte.

Operado por SOUTH UNION AI TECH LTDA, CNPJ 40.747.827/0001-88.

Integre com a Torêva