# 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.