# Visão geral A API Torêva entrega ao seu sistema os dados de empresas brasileiras a partir do CNPJ. Os dados vêm da base de dados abertos da Receita Federal, carregada e mantida pela Torêva. ## O que a API devolve Uma chamada devolve, para cada CNPJ: - **Dados cadastrais:** razão social, nome fantasia, situação cadastral, data de abertura, natureza jurídica, porte e capital social. - **Endereço:** logradouro, número, complemento, bairro, município, UF e CEP. - **Contato:** telefones e e-mail informados à Receita. - **CNAEs:** a atividade principal e as secundárias, com código e descrição. - **Sócios:** nome, tipo, qualificação, data de entrada e faixa etária. - **Filiais:** a matriz e todos os estabelecimentos com a mesma raiz de CNPJ. A resposta também informa de qual carga mensal da Receita o dado veio. O formato completo está em [Consulta de CNPJ](https://toreva.com.br/developers/consulta-cnpj). - **URL base:** `https://api.toreva.com.br` - **Versão atual:** `v1` - **Contrato OpenAPI:** `https://api.toreva.com.br/v1/openapi.json` - **Referência interativa (Swagger):** [`https://api.toreva.com.br/v1/docs`](https://api.toreva.com.br/v1/docs) Use o OpenAPI para gerar o cliente na sua linguagem. Assim você não precisa escrever o modelo de dados à mão. ## Início rápido 1. Crie sua conta em [`https://app.toreva.com.br/criar-conta/api`](https://app.toreva.com.br/criar-conta/api). 2. Coloque saldo na [carteira](https://app.toreva.com.br/carteira) ou assine uma faixa mensal. Os valores estão em [Preços e cobrança](https://toreva.com.br/developers/precos-e-cobranca). 3. Gere a chave na tela **API** do app, em [`https://app.toreva.com.br/desenvolvedor`](https://app.toreva.com.br/desenvolvedor). Copie a chave na hora: ela aparece uma única vez. 4. Guarde a chave na variável de ambiente `TOREVA_API_KEY` do servidor que vai chamar a API. 5. Faça a primeira chamada com um dos exemplos abaixo. ### curl ```bash curl https://api.toreva.com.br/v1/cnpj/19729868000155 \ -H "Authorization: Bearer $TOREVA_API_KEY" ``` ### Node.js (`fetch`) Precisa do Node 18 ou mais novo. Salve como `consulta.mjs` e rode `node consulta.mjs`. ```js const cnpj = "19.729.868/0001-55".replace(/[./-]/g, ""); const resposta = await fetch(`https://api.toreva.com.br/v1/cnpj/${cnpj}`, { headers: { Authorization: `Bearer ${process.env.TOREVA_API_KEY}` }, }); const ehJson = resposta.headers.get("content-type")?.includes("application/json"); const corpo = ehJson ? await resposta.json() : null; if (!resposta.ok || !corpo) { throw new Error(`Falha na consulta: ${corpo?.code ?? `HTTP ${resposta.status}`}`); } console.log(corpo.razaoSocial, corpo.situacaoCadastral.descricao); ``` ### Python (`requests`) Instale a biblioteca com `pip install requests`. ```python import os import re import requests cnpj = re.sub(r"[./-]", "", "19.729.868/0001-55") resposta = requests.get( f"https://api.toreva.com.br/v1/cnpj/{cnpj}", headers={"Authorization": f"Bearer {os.environ['TOREVA_API_KEY']}"}, timeout=30, ) e_json = resposta.headers.get("Content-Type", "").startswith("application/json") corpo = resposta.json() if e_json else None if not resposta.ok or corpo is None: codigo = (corpo or {}).get("code") or f"HTTP {resposta.status_code}" raise RuntimeError(f"Falha na consulta: {codigo}") print(corpo["razaoSocial"], corpo["situacaoCadastral"]["descricao"]) ``` Os exemplos só leem o corpo como JSON quando o `Content-Type` é JSON. Em erro, usam o `code` da resposta ou, sem ele, o status HTTP. Veja [Erros e limites](https://toreva.com.br/developers/erros-e-limites). Os exemplos removem só a pontuação do CNPJ. Nunca remova tudo o que não for dígito: o CNPJ alfanumérico tem letras. Veja o motivo em [Consulta de CNPJ](https://toreva.com.br/developers/consulta-cnpj). ## Próximos passos - [Autenticação](https://toreva.com.br/developers/autenticacao): como enviar e proteger a chave. - [Erros e limites](https://toreva.com.br/developers/erros-e-limites): os códigos de erro e quando repetir uma chamada. - [Integrar com IA](https://toreva.com.br/developers/integrar-com-ia): instruções prontas para o seu assistente de código. ## Suporte Escreva para `suporte@toreva.com.br`. Inclua o `X-Request-Id` da chamada: com ele a gente localiza exatamente o que aconteceu. --- # Autenticação Toda chamada precisa de uma chave. Você gera a chave na tela **API** do app, em `https://app.toreva.com.br/desenvolvedor`. A chave pertence à sua empresa e é gerada por um administrador de uma conta com plano ativo. Uma conta avulsa já se qualifica assim que é criada. Envie a chave no cabeçalho `Authorization`: ``` Authorization: Bearer tor_live_ABCDEFGH2345_xxxxxxxxxxxxxxxxxxxxxxxxx ``` Se o seu sistema não deixa mudar o cabeçalho `Authorization`, use `X-API-Key`: ``` X-API-Key: tor_live_ABCDEFGH2345_xxxxxxxxxxxxxxxxxxxxxxxxx ``` Nos exemplos desta documentação, a chave fica na variável de ambiente `TOREVA_API_KEY`. Não escreva a chave no código. ## O que você precisa saber sobre a chave ### Ela aparece uma única vez A chave aparece no momento em que é gerada, e nunca mais. A Torêva guarda só um resumo criptográfico dela: nem a gente consegue recuperá-la. Se você perder a chave, revogue e gere outra. ### Ela é um segredo de servidor Não coloque a chave em código que roda no navegador nem em aplicativo distribuído. Qualquer pessoa consegue ler a chave nesses lugares. A API não aceita chamadas de páginas web (não há CORS liberado) justamente para que esse erro não passe despercebido. ### O trecho do meio identifica a chave Em `tor_live_ABCDEFGH2345_...`, o trecho `ABCDEFGH2345` identifica a chave. Ele não é secreto. Você pode citá-lo num chamado de suporte, e é por ele que a chave aparece no app. ### Revogar tem efeito em até 1 minuto Revogue a chave na hora se suspeitar de vazamento. Para não interromper a integração, gere a chave nova antes e troque no seu servidor. ## Erros de autenticação Chave ausente, inválida, revogada ou expirada recebe `401 API_KEY_INVALID`. Repetir a chamada com a mesma chave devolve o mesmo erro. Veja todos os códigos em [Erros e limites](https://toreva.com.br/developers/erros-e-limites). --- # Consulta de CNPJ ``` GET /v1/cnpj/{cnpj} ``` O `{cnpj}` pode vir com ou sem máscara. A API aceita **CNPJ alfanumérico** (IN RFB nº 2.229/2024), em que as 12 primeiras posições podem ter letras. > **Atenção ao integrar:** não aplique `replace(/\D/g, '')` ou equivalente no CNPJ antes de enviar. Num CNPJ alfanumérico isso remove as letras em silêncio e produz outro número, sem erro nenhum. Remova só a pontuação (`.`, `/`, `-`). ## Exemplo ```bash curl https://api.toreva.com.br/v1/cnpj/19729868000155 \ -H "Authorization: Bearer $TOREVA_API_KEY" ``` Resposta `200`: ```json { "cnpj": "19729868000155", "cnpjFormatado": "19.729.868/0001-55", "raiz": "19729868", "razaoSocial": "Empresa Exemplo Ltda", "nomeFantasia": "Exemplo", "matrizFilial": "matriz", "situacaoCadastral": { "codigo": "02", "descricao": "Ativa", "data": "2019-04-01", "motivo": null }, "situacaoEspecial": null, "dataAbertura": "2005-11-03", "idadeAnos": 20, "naturezaJuridica": { "codigo": "2062", "descricao": "Sociedade Empresária Limitada" }, "porte": { "codigo": "05", "descricao": "Demais" }, "capitalSocial": 100000, "endereco": { "logradouro": "Rua Um", "numero": "100", "complemento": null, "bairro": "Centro", "municipio": "São Paulo", "codigoMunicipio": "7107", "uf": "SP", "cep": "01310100" }, "contato": { "telefones": [{ "ddd": "11", "numero": "40028922", "formatado": "(11) 4002-8922" }], "email": "contato@exemplo.com.br" }, "cnaePrincipal": { "codigo": "6201500", "descricao": "Desenvolvimento de programas de computador sob encomenda" }, "cnaesSecundarios": [{ "codigo": "6202300", "descricao": "..." }], "socios": [ { "nome": "Fulano de Tal", "tipo": "Pessoa física", "qualificacao": "Sócio-Administrador", "dataEntrada": "2010-04-15", "faixaEtaria": "41 a 50 anos" } ], "estabelecimentos": [ { "cnpj": "19729868000236", "matrizFilial": "filial", "nomeFantasia": null, "situacaoCadastral": { "codigo": "02", "descricao": "Ativa" }, "municipio": "Campinas", "uf": "SP" } ], "fonte": { "origem": "Receita Federal do Brasil", "referencia": "2026-07", "atualizadoEm": "2026-08-01", "possuiCorrecoes": false } } ``` ## Convenções do contrato Valem para todos os campos, em todos os endpoints: | Regra | O que significa | |---|---| | Datas em ISO-8601 | Sempre `AAAA-MM-DD`. Nunca `dd/mm/aaaa` | | Dinheiro em número | `capitalSocial: 100000`, não `"R$ 100.000,00"` | | Códigos em texto | `"02"`, `"6201500"`. O zero à esquerda conta | | Ausência é `null` | Nunca string vazia | | Sem máscara nos identificadores | `cnpj` e `cep` vêm só com os caracteres do valor | ## Campos que merecem atenção **`situacaoCadastral.codigo`:** `01` Nula, `02` Ativa, `03` Suspensa, `04` Inapta, `08` Baixada. Compare o **código**, não a descrição. O texto pode mudar, o código não. **`estabelecimentos`:** a matriz e as filiais com a mesma raiz de 8 posições, incluindo o próprio CNPJ consultado. **`fonte.referencia`:** de qual carga mensal da Receita o dado veio. Use para saber a idade da informação. **`fonte.possuiCorrecoes`:** `true` indica que algum campo foi corrigido sobre o que a Receita publica, em geral a pedido do próprio titular. O dado entregue já é o corrigido. ## Erros e cobrança CNPJ inválido recebe `400 INVALID_CNPJ` e CNPJ fora da base recebe `404 NOT_FOUND`. Nenhum dos dois é cobrado. Os demais códigos estão em [Erros e limites](https://toreva.com.br/developers/erros-e-limites), e as regras de cobrança em [Preços e cobrança](https://toreva.com.br/developers/precos-e-cobranca). --- # Erros e limites ## Formato dos erros Todos os erros da API seguem o mesmo formato: ```json { "code": "NOT_FOUND", "message": "CNPJ não encontrado.", "requestId": "9f2c..." } ``` **Trate pelo `code`, não pela mensagem.** Os textos podem mudar, os códigos não. Guarde o `requestId` no seu log: é por ele que o suporte localiza a chamada. - Quando a chamada é recusada antes de chegar à consulta (`401` e `429`), o `requestId` pode vir `null` e o cabeçalho `X-Request-Id` pode não vir. - Um erro gerado fora da API, na sua rede ou num proxy, pode chegar sem corpo JSON. Um cliente robusto confere o status HTTP e o `Content-Type` antes de ler o corpo. ## Códigos | HTTP | `code` | O que fazer | |---|---|---| | 400 | `INVALID_CNPJ` | Formato ou dígito verificador inválido. Confira antes de reenviar | | 401 | `API_KEY_INVALID` | Chave ausente, inválida, revogada ou expirada. Não repita a chamada | | 403 | `INSUFFICIENT_BALANCE` | Sem saldo e sem franquia disponível. Recarregue a carteira no app | | 404 | `NOT_FOUND` | CNPJ não encontrado na base | | 408 | `CNPJ_LOOKUP_TIMEOUT` | A consulta demorou demais. Pode repetir | | 429 | `RATE_LIMITED` | Reduza o ritmo. Respeite o cabeçalho `Retry-After` | | 500 | `INTERNAL_ERROR` | Erro inesperado. Repita com espera crescente e, se persistir, fale com o suporte informando o `requestId` | | 503 | `CNPJ_SOURCE_UNAVAILABLE` | Base indisponível no momento. Pode repetir | | 503 | `SERVICE_UNAVAILABLE` | A API está fora do ar ou reiniciando (resposta da borda). Pode repetir | Um caminho que não existe sob `/v1` responde HTTP `404` sem o campo `code`. ## Quando repetir Em `408`, `429`, `500` e `503`, repita a chamada com espera crescente (*backoff*). Nos demais códigos, repetir devolve o mesmo erro. Repetir é seguro: a mesma consulta dentro de 24 horas não é cobrada de novo. Veja [Preços e cobrança](https://toreva.com.br/developers/precos-e-cobranca). ## Limites | Limite | Valor | |---|---| | Por chave | 10 requisições por segundo | | Por IP | 20 requisições por segundo, com pico de 40 | Acima do limite, a API responde `429 RATE_LIMITED`. ## Cabeçalhos da resposta | Cabeçalho | Conteúdo | |---|---| | `X-Request-Id` | Identificador da chamada, para o suporte | | `X-Toreva-Charged` | `true` quando a consulta contou como consulta cobrável, seja debitada do saldo, seja coberta pela franquia do mês; `false` quando o mesmo CNPJ é reconsultado dentro de 24 horas | | `X-Toreva-Balance-Cents` | Saldo restante da carteira, em centavos. Vem nas respostas `200` | --- # Preços e cobrança Você paga por consulta. Há duas formas de pagar: saldo avulso na carteira ou uma faixa mensal. ## Avulso Cada consulta custa **R$ 0,12**, debitada da carteira pré-paga da sua empresa. Você coloca saldo na carteira do app, em [`https://app.toreva.com.br/carteira`](https://app.toreva.com.br/carteira). A recarga mínima é de **R$ 10**. ## Faixas mensais | Plano | Preço por mês | Consultas inclusas | |---|---|---| | API 1 mil | R$ 49 | 1.000 | | API 5 mil | R$ 149 | 5.000 | | API 20 mil | R$ 399 | 20.000 | - A franquia renova no dia 1º de cada mês. Consultas que sobram não passam para o mês seguinte. - O que passar da franquia sai do saldo da carteira, a **R$ 0,12** por consulta. - Para trocar de faixa, cancele a atual; a nova pode ser assinada quando o período terminar. Até lá, o que passar da franquia sai do saldo a R$ 0,12 por consulta. Você gera as chaves, acompanha o consumo e assina a faixa mensal na tela **API** do app, em [`https://app.toreva.com.br/desenvolvedor`](https://app.toreva.com.br/desenvolvedor). Conta da plataforma completa (Plano Base): o preço por consulta e a franquia mensal aparecem em API › Plano e preços, no app. ## Uma cobrança por CNPJ a cada 24 horas Consultar o **mesmo CNPJ** de novo dentro de 24 horas **não gera nova cobrança**. A resposta vem completa. O cabeçalho `X-Toreva-Charged` vem `true` quando a consulta contou como consulta cobrável, seja debitada do saldo, seja coberta pela franquia do mês; `false` quando o mesmo CNPJ é reconsultado dentro de 24 horas. A janela é de 24 horas a partir da consulta cobrada. Reconsultar dentro dela não a estende. Por isso, repetir uma chamada depois de uma falha de rede é seguro: você não paga duas vezes pelo mesmo dado. ## O que não é cobrado - CNPJ não encontrado (`404`). - CNPJ inválido (`400`). - Qualquer erro. Você só paga por resposta entregue. ## Sem saldo Sem saldo e sem franquia disponível, a API responde `403 INSUFFICIENT_BALANCE` **antes** de consultar. Nenhum dado é entregue e nada é debitado. Configure a recarga automática na carteira do app para não interromper a integração. Nas respostas `200`, o cabeçalho `X-Toreva-Balance-Cents` informa o saldo restante da carteira. --- # Dados pessoais e LGPD A resposta contém dados pessoais: telefone, e-mail e o nome dos sócios. **Ao usar esta API, você se torna controlador do tratamento que fizer com esses dados** e assume as obrigações da LGPD que vêm com ele. Em particular: 1. **Finalidade legítima.** Use os dados só para a finalidade declarada em contrato. 2. **Sem revenda do dado bruto.** É proibido redistribuir ou revender a base, no todo ou em parte. 3. **Sem varredura em massa.** A API existe para consulta pontual. Enumerar a base de forma sistemática viola o contrato. 4. **Respeite as exclusões.** Um titular pode pedir a remoção do próprio registro. A partir daí, aquele CNPJ responde `404` para todos, inclusive para você. **Se você guarda cópia local do dado, você também precisa removê-la.** Reconsulte os registros que você armazena com a frequência compatível com o seu uso. 5. **Encaminhe pedidos de titular** para `privacidade@toreva.com.br`. ## O que a Torêva registra A Torêva registra cada consulta (qual empresa, qual chave, qual CNPJ e quando) por exigência de rastreabilidade. **O conteúdo devolvido não é registrado.** A Torêva pode auditar padrões de uso e suspender chaves que violem estes termos. --- # Integrar com IA Copie o bloco abaixo e entregue ao seu assistente de código. O mesmo texto está no botão **Copiar instruções para IA** da tela **API** do app. ```md # Integração com a API Torêva Você vai integrar a API Torêva neste projeto. - Documentação completa em um arquivo: https://toreva.com.br/llms-full.txt - Contrato OpenAPI: https://api.toreva.com.br/v1/openapi.json - URL base: https://api.toreva.com.br - Autenticação: cabeçalho `Authorization: Bearer `. Leia a chave da variável de ambiente `TOREVA_API_KEY`. Nunca escreva a chave no código nem a use em código que roda no navegador. - Consulta: `GET /v1/cnpj/{cnpj}`. Aceita CNPJ com ou sem máscara e CNPJ alfanumérico: remova só `.`, `/` e `-`, nunca tudo que não for dígito. - Trate erros pelo campo `code` da resposta, não pela mensagem. Repita com espera crescente só em 408, 429, 500 e 503. - A mesma consulta em até 24 horas não é cobrada de novo (cabeçalho `X-Toreva-Charged`). Leia a documentação antes de escrever o cliente. ``` ## Arquivos para agentes - [`https://toreva.com.br/llms.txt`](https://toreva.com.br/llms.txt): índice da documentação, com um link `.md` por página. - [`https://toreva.com.br/llms-full.txt`](https://toreva.com.br/llms-full.txt): toda a documentação em um arquivo só. - [`https://api.toreva.com.br/v1/openapi.json`](https://api.toreva.com.br/v1/openapi.json): o contrato OpenAPI. Toda página desta documentação também existe em Markdown: acrescente `.md` ao endereço, como em `https://toreva.com.br/developers/consulta-cnpj.md`. ## Como usar - **Claude:** cole o bloco no começo da conversa ou salve no arquivo `CLAUDE.md` do projeto. - **Cursor:** salve o bloco como regra do projeto, na pasta `.cursor/rules`. - **ChatGPT:** cole o bloco no começo da conversa e anexe o `llms-full.txt` se ele não conseguir abrir links. --- # Versionamento A versão está no caminho: `/v1`. - **Mudança compatível, sem aviso:** campo novo na resposta ou valor novo num campo de texto livre. **Seu cliente deve ignorar os campos que não conhece.** - **Mudança incompatível, com nova versão:** remover um campo, renomear um campo ou mudar o tipo de um campo. Isso vira `/v2`, e o `/v1` continua no ar durante a transição. O contrato da versão atual está em `https://api.toreva.com.br/v1/openapi.json`.