# Núclea — Valor Histórico Transacionado

> Quanto a empresa efetivamente recebeu em boleto, cartão e TED nos últimos 12 meses, medido pela Núclea (ex-CIP), a câmara de compensação do sistema bancário — movimentação real, não estimada.

- **Consulta:** `nuclea-historico-transacionado`
- **Categoria:** Crédito & Score
- **Preço:** R$ 6,44 por consulta
- **Endpoint:** `GET https://app.fontedata.com/api/v1/consulta/nuclea-historico-transacionado`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/credito-e-score/nuclea-historico-transacionado

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Mede quanto a empresa **efetivamente recebeu** em boleto, cartão e TED nos últimos 12 meses, direto da **Núclea** (ex-CIP) — a câmara que compensa boletos, TEDs e cartões no sistema bancário brasileiro. Não é estimativa por porte ou setor, nem faturamento declarado: é o valor que de fato transitou e foi compensado. A leitura soma matriz e filiais (CNPJ raiz completo), mesmo que você informe o CNPJ de uma filial.
>
> A base é atualizada mensalmente — o campo `mesReferencia` indica a carga usada na apuração.

## Requisição

### cURL

```bash
curl -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/nuclea-historico-transacionado?cnpj=SEU_CNPJ"
```

### Python

```python
import requests

resp = requests.get(
    "https://app.fontedata.com/api/v1/consulta/nuclea-historico-transacionado",
    params={"cnpj": "SEU_CNPJ"},
    headers={"X-API-Key": "SUA_CHAVE"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

### Node.js

```javascript
const url = new URL("https://app.fontedata.com/api/v1/consulta/nuclea-historico-transacionado");

url.search = new URLSearchParams({
  "cnpj": "SEU_CNPJ"
}).toString();

const resp = await fetch(url, {
  method: "GET",
  headers: { "X-API-Key": "SUA_CHAVE" }
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Parâmetros

| Nome | Tipo | Obrigatório | Descrição | Exemplo |
|---|---|---|---|---|
| `cnpj` | CNPJ | sim | CNPJ da empresa, com ou sem máscara. Pode ser de matriz ou de filial — a leitura soma a movimentação do CNPJ raiz completo (matriz e filiais). | formato: 00.000.000/0000-00 |

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - **`consta`**: `true` quando há movimentação registrada na janela. `consta: false` é um desfecho **normal** desta consulta (veja "Cobertura" abaixo) e é cobrado normalmente — a consulta foi executada na base de origem.
> - **`valorTransacionado`**: o total recebido nos últimos 12 meses, em reais. **Não é faturamento** — é o que transitou em boleto, cartão e TED.
> - **`valorTransacionadoNumerico`**: o mesmo valor em número, pronto para cálculo.
> - **`janelaMeses`**: janela de apuração (12 meses retroativos).
> - **`escopo`** e **`abrangencia`**: o que a soma cobre e em que nível (CNPJ completo, matriz e filiais).
> - **`mesReferencia`**: mês da carga de dados (AAAAMM).

### Exemplo de resposta

```json
{
  "cnpj": "33000167000101",
  "consta": true,
  "escopo": "recebimentos em boleto, cartão e TED",
  "abrangencia": "CNPJ completo (matriz e filiais)",
  "janelaMeses": 12,
  "mesReferencia": "202607",
  "valorTransacionado": "R$ 2.347.815,60",
  "valorTransacionadoNumerico": 2347815.6
}
```

### Schema da resposta

```json
{
  "type": "object",
  "properties": {
    "cnpj": {
      "type": [
        "string",
        "null"
      ],
      "description": "CNPJ consultado, sem máscara — eco do parâmetro informado."
    },
    "consta": {
      "type": [
        "boolean",
        "null"
      ],
      "description": "true quando há movimentação registrada para o CNPJ na janela consultada. Quando não há registros no recorte (boleto, TED e cartão), a resposta vem com consta: false e uma mensagem explicativa — e a consulta é cobrada normalmente, pois foi executada na base de origem."
    },
    "escopo": {
      "type": [
        "string",
        "null"
      ],
      "description": "O que a soma cobre: recebimentos em boleto, cartão e TED."
    },
    "abrangencia": {
      "type": [
        "string",
        "null"
      ],
      "description": "Abrangência da leitura: CNPJ completo — matriz e filiais somadas, ainda que a consulta informe o CNPJ de uma filial."
    },
    "janelaMeses": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Tamanho da janela de apuração, em meses. Nesta consulta, 12 meses retroativos."
    },
    "mesReferencia": {
      "type": [
        "string",
        "null"
      ],
      "description": "Mês da carga de dados usada na apuração, no formato AAAAMM. A base é atualizada mensalmente; a janela de 12 meses termina neste mês."
    },
    "valorTransacionado": {
      "type": [
        "string",
        "null"
      ],
      "description": "Valor total recebido nos últimos 12 meses, formatado em reais (ex.: R$ 1.234.567,89). Importante: é o valor que transitou em boleto, cartão e TED — não é o faturamento da empresa. Vendas recebidas por Pix ou em dinheiro não entram nesta soma."
    },
    "valorTransacionadoNumerico": {
      "type": [
        "number",
        "null"
      ],
      "description": "O mesmo valor em formato numérico, pronto para cálculo (ex.: 1234567.89)."
    }
  },
  "description": "Valor total que a empresa efetivamente recebeu nos últimos 12 meses em boleto, cartão e TED, medido na infraestrutura de compensação do sistema bancário. É movimentação real compensada — não é estimativa estatística nem faturamento declarado."
}
```

## Códigos de erro

| Código | Mensagem | Quando acontece |
|---|---|---|
| `400` | CNPJ inválido: dígito verificador não confere. | O CNPJ enviado não passa na validação de dígito verificador. |
| `402` | Saldo insuficiente para realizar a consulta. | A conta não tem saldo para cobrir o preço da consulta. |
| `503` | A consulta de indicadores transacionais está temporariamente indisponível — instabilidade na base de origem, não na sua requisição. Tente novamente em alguns minutos. | A base de origem não respondeu ou devolveu erro transitório. |
| `504` | A consulta excedeu o tempo limite. Tente novamente. | A base de origem não respondeu dentro do tempo limite. |

## Quando usar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - **Análise de crédito PJ**: dimensionar limite com base em recebimento real, não em faturamento presumido.
> - **Validação de faturamento informado**: comparar o que o cliente declara com o que efetivamente transita em boleto, cartão e TED.
> - **Prospecção e qualificação B2B**: separar empresas operantes de CNPJs sem movimentação bancária relevante.

## Cobertura — leia antes de interpretar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> A base cobre **boleto, TED e cartão**. O **Pix não entra** nesta leitura, nem dinheiro em espécie. Consequências práticas:
>
> - **A leitura funciona muito bem** para negócios B2B que cobram por boleto: indústria, atacado, distribuição, construção, transporte.
> - **A leitura subestima** empresas que recebem majoritariamente por Pix ou maquininha própria: varejo de baixo tíquete, SaaS, e-commerce, serviços digitais. Para essas, `consta: false` (ou um valor baixo) significa "não recebe pelos meios cobertos" — **não** significa que a empresa não fatura.
>
> Trate `consta: false` como informação sobre o **perfil de recebimento** da empresa, nunca como prova de inatividade.

---

Página em HTML: https://fontedata.com/docs/credito-e-score/nuclea-historico-transacionado
Catálogo completo: https://fontedata.com/docs
OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json
Conectar via MCP: https://fontedata.com/docs/mcp