> ## Documentation Index
> Fetch the complete documentation index at: https://docs.engineapi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cadastro por CNPJ

> Como consultar dados da Receita, Simples Nacional e inscrições estaduais sem consumir crédito novamente a cada acesso.

`GET /v1/cadastros/{cnpj}` consulta a CNPJá no primeiro acesso e conserva o
resultado na plataforma. O cadastro não vence por prazo. As chamadas seguintes
usam o cache até que você peça uma atualização explícita.

Por padrão, a resposta inclui os campos do `/office` da CNPJá, o Simples/MEI e
as inscrições estaduais de todas as UFs. A engineAPI acrescenta `fetched_at`,
`source_updated`, `fonte` e `cobranca`.

```bash cURL theme={null}
curl "https://api.engineapi.com.br/v1/cadastros/37335118000180" \
  -H "x-api-key: YOUR_API_KEY"
```

```json Resposta resumida theme={null}
{
  "taxId": "37335118000180",
  "updated": "2026-08-15T12:00:00.000Z",
  "company": {
    "name": "EMPRESA SINTÉTICA LTDA",
    "simples": { "optant": true, "since": "2020-06-05" },
    "simei": { "optant": false, "since": null }
  },
  "registrations": [],
  "fetched_at": "2026-08-30T20:00:00.000Z",
  "source_updated": "2026-08-15T12:00:00.000Z",
  "fonte": "cache",
  "cobranca": {
    "datasets_extras": [],
    "consumiu_credito": false,
    "creditos": 0
  }
}
```

`fonte: "cnpja"` indica que esta requisição foi ao provedor. `fonte: "cache"`
indica que nenhuma chamada foi feita.

## Atualização explícita

Use `refresh=true` somente quando houver um fato que justifique nova consulta.
O motivo é obrigatório e aceita três valores:

* `cliente_avisou`: o cliente informou mudança cadastral;
* `sefaz_recusou`: uma recusa fiscal indica cadastro desatualizado;
* `saneamento`: atualização operacional iniciada pela plataforma.

```bash cURL theme={null}
curl "https://api.engineapi.com.br/v1/cadastros/37335118000180?refresh=true&motivo=cliente_avisou" \
  -H "x-api-key: YOUR_API_KEY"
```

Refresh sem motivo válido devolve `400 VALIDATION_ERROR` e não chama a CNPJá.

## Datasets cobrados à parte

`geocoding` e `suframa` não são pedidos por padrão. Para solicitá-los, use
`datasets` com uma lista separada por vírgula:

```bash cURL theme={null}
curl "https://api.engineapi.com.br/v1/cadastros/37335118000180?datasets=geocoding,suframa" \
  -H "x-api-key: YOUR_API_KEY"
```

A resposta informa os itens pedidos em `cobranca.datasets_extras` e o consumo
medido em `cobranca.creditos`. O resultado desses datasets não entra no cache
comum e nunca é servido a outro parceiro.

## Saldo e consumo do parceiro

`GET /v1/cadastros/creditos` retorna o saldo da conta do provedor e somente o
consumo mensal do parceiro autenticado. Quando o saldo está abaixo de 20, a
resposta traz `alerta.codigo: "CNPJA_SALDO_BAIXO"`.

Se não houver saldo para a consulta, a API devolve `503` com o código
`CNPJA_SALDO_INSUFICIENTE`. Tente novamente depois que a conta for recarregada;
não repita em laço.