# Portal do desenvolvedor Torêva Espelho em markdown de . Servido também por negociação de conteúdo: `curl -H "Accept: text/markdown" https://toreva.com.br/developers`. Os endpoints de descoberta da Torêva são públicos, somente leitura e não exigem chave. Eles são o ambiente de testes: o que você chama aqui é exatamente o que roda em produção. Se você é um agente, comece por , que diz **quando** acionar a Torêva e quando não acionar. ## Início rápido ``` curl https://toreva.com.br/api/v1 curl https://toreva.com.br/api/v1/status curl -i https://toreva.com.br/api/v1/rota-inexistente ``` A terceira chamada devolve HTTP 404 com corpo JSON. 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. ## Endpoints públicos Servidos a partir de `https://toreva.com.br`, sem autenticação. | 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. | | `GET /.well-known/openapi.json` | `application/json` | Descrição OpenAPI 3.1. Também em `/openapi.json`. | | `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 MCP. | | `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 /docs/versioning.md` | `text/markdown` | Versionamento e depreciação. | | `GET /auth.md` | `text/markdown` | Regras de autenticação para agentes. | Todas as operações do OpenAPI 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: ```json { "error": { "code": "not_found", "status": 404, "message": "Endpoint não encontrado.", "hint": "Consulte https://toreva.com.br/api/v1 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. | | `method_not_allowed` | `405` | A API pública é somente leitura: GET, HEAD ou OPTIONS. | | `rate_limited` | `429` | Limite de taxa excedido. Respeite o `Retry-After`. | | `upstream_unavailable` | `502` | Origem não respondeu — 502, 503 e 504 são normalizados aqui. | | `endpoint_sunset` | `410` | Endpoint desligado depois do prazo anunciado no `Sunset`. | Trate `error.code` como contrato e `error.message` como texto para humanos. ## Versionamento e depreciação A versão fica no caminho: `/api/v1/…`. Versão corrente: **v1**. O caminho sem versão, `/api/…`, é 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. Quando um endpoint entra em depreciação, as respostas passam a carregar: ``` Deprecation: @1788307200 Sunset: Wed, 01 Jul 2026 00:00:00 GMT Link: ; rel="deprecation" ``` `Deprecation` (RFC 9745) marca quando a depreciação começou; `Sunset` (RFC 8594) quando o endpoint deixa de responder. Aviso mínimo: **180 dias** para uma versão inteira, 90 dias para um endpoint isolado. Depois do `Sunset`, a resposta é `410` com `error.code` igual a `endpoint_sunset`. Política completa: ## Limite de taxa **120 requisições por minuto por cliente**, com rajada de 60 liberada de imediato. Toda resposta sob `/api/` anuncia o teto: ``` 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` é contagem regressiva de verdade: os segundos até 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 e o campo estruturado único `RateLimit` do rascunho novo do IETF. Ao estourar: `429` com `error.code: "rate_limited"` e um `Retry-After` calculado — os segundos exatos até haver saldo. A contagem é por cliente e por instância. Um anteparo separado, bem acima desse teto, protege o serviço de enxurrada. ## Servidor MCP Servidor MCP de primeira parte, transporte **Streamable HTTP**, **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"}}}' ``` Também responde em `/mcp`. `GET` devolve `405`: não há stream SSE, e a especificação prevê esse retorno. | Ferramenta | O que faz | | --- | --- | | `consultar_cnpj_publico` | Dados cadastrais públicos de uma empresa brasileira pelo CNPJ. | | `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. | `consultar_cnpj_publico` **não** devolve endereço completo, CEP, telefone, e-mail nem quadro societário: esses campos exigem conta gratuita no site, e a resposta lista quais são em `gated_fields`. Os documentos em markdown do site também são expostos como *resources* MCP. Metadados: ## Markdown por negociação de conteúdo `/` e `/developers` respondem markdown quando o pedido traz `Accept: text/markdown`, e HTML caso contrário. As duas representações vivem na mesma URL e a resposta carrega `Vary: Accept`. ``` curl -H "Accept: text/markdown" https://toreva.com.br/ curl -H "Accept: text/markdown" https://toreva.com.br/developers ``` Endereços diretos: `/index.md`, `/developers.md`, `/agent-instructions.md`, `/docs/api.md`, `/docs/versioning.md` e `/auth.md`. ## Ambiente de testes e onboarding | O que | Disponível | Como | | --- | --- | --- | | Acesso sem autenticação | **Sim** | `curl https://toreva.com.br/api/v1` | | Ambiente de testes | **Sim** | Os próprios endpoints públicos, somente leitura. | | Servidor MCP sem autenticação | **Sim** | `POST /.well-known/mcp` | | Teste gratuito da plataforma | **Sim** | , sem cartão de crédito. | | Emissão automática de chave de API | **Não** | Liberado caso a caso: contato@toreva.com.br | | Sandbox com dados sintéticos | **Não** | Não há. Descreva o caso de uso no e-mail acima. | Cada linha marcada como disponível responde agora, sem credencial. O mesmo estado sai em JSON no bloco `onboarding` de . ## 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 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 e escreva para contato@toreva.com.br com o escopo pretendido. Regras completas: . Metadados OAuth publicados: `/.well-known/oauth-authorization-server` e `/.well-known/oauth-protected-resource`. ## Boas práticas - Repita `429` respeitando o `Retry-After`, e `502` com backoff exponencial. Não repita `404`, `405` nem `410`. - Use `ETag`/`If-None-Match` onde a resposta oferecer. - Identifique seu cliente no `User-Agent`, com um contato. - As fichas de `/consulta-cnpj/` podem ser retiradas a pedido do titular. Uma URL que respondeu 200 hoje pode responder 404 amanhã. ## Suporte Dúvidas de integração, pedido de acesso ou aviso de quebra: contato@toreva.com.br. Telefone e WhatsApp: +55 62 98111-7700. Todos os canais: . Operado por SOUTH UNION AI TECH LTDA, CNPJ 40.747.827/0001-88, com sede em Rua Tiradentes, 2352, Sala 02, Parque Industrial, São José do Rio Preto/SP, CEP 15025-050.