# Núclea — Predição de Valor Transacionado

> Projeção de quanto a empresa deve receber em boleto, TED e cartão no próximo mês, modelada sobre os últimos 12 meses de movimentação real compensada pela Núclea, a câmara de compensação do sistema bancário.

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

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Projeta **quanto a empresa deve receber no próximo mês** em boleto, TED e cartão. A projeção é modelada sobre os **últimos 12 meses** de movimentação real da empresa compensada pela **Núclea** (ex-CIP), a câmara de compensação do sistema bancário — parte de transações que de fato aconteceram, não de faturamento declarado ou estimado por porte.
>
> Use junto com a consulta **Núclea — Valor Histórico Transacionado** (`nuclea-historico-transacionado`): o histórico diz o que a empresa recebeu em 12 meses; a predição, o que ela deve receber no mês seguinte. Para comparar os dois, use a **média mensal** do histórico (valor de 12 meses ÷ 12): predição abaixo da média sugere desaceleração; acima, crescimento. A comparação entre os dois revela tendência — uma predição bem abaixo do histórico sugere desaceleração.

## Requisição

### cURL

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

### Python

```python
import requests

resp = requests.get(
    "https://app.fontedata.com/api/v1/consulta/nuclea-predicao-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-predicao-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 projeção cobre o 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á base de movimentação para projetar. `consta: false` é um desfecho **normal** (veja "Cobertura" abaixo) e é cobrado normalmente — a consulta foi executada na base de origem.
> - **`valorPrevisto`**: o valor projetado para o próximo mês, em reais. É **estimativa modelada, não garantia** — trate como ordem de grandeza, não como compromisso.
> - **`valorPrevistoNumerico`**: o mesmo valor em número, pronto para cálculo.
> - **`janelaMeses`**: horizonte da projeção (1 — o próximo mês). A base do modelo são os últimos 12 meses de movimentação.
> - **`escopo`** e **`abrangencia`**: o que a projeção cobre e em que nível (CNPJ completo, matriz e filiais).
> - **`mesReferencia`**: mês da carga de dados usada como base (AAAAMM).

### Exemplo de resposta

```json
{
  "cnpj": "33000167000101",
  "consta": true,
  "escopo": "recebimentos previstos em boleto, TED e cartão no próximo mês",
  "abrangencia": "CNPJ completo (matriz e filiais)",
  "janelaMeses": 1,
  "mesReferencia": "202607",
  "valorPrevisto": "R$ 165.000,00",
  "valorPrevistoNumerico": 165000
}
```

### 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á base de movimentação para projetar. Quando o CNPJ não tem 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 projeção cobre: recebimentos previstos em boleto, TED e cartão no próximo mês."
    },
    "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": "Horizonte da projeção, em meses. Nesta consulta, o próximo mês (1). A projeção é modelada sobre os últimos 12 meses de movimentação."
    },
    "mesReferencia": {
      "type": [
        "string",
        "null"
      ],
      "description": "Mês da carga de dados usada como base da projeção, no formato AAAAMM. A base é atualizada mensalmente."
    },
    "valorPrevisto": {
      "type": [
        "string",
        "null"
      ],
      "description": "Valor projetado de recebimentos para o próximo mês, formatado em reais (ex.: R$ 165.000,00). É uma estimativa modelada, não uma garantia — e cobre apenas os meios de recebimento medidos (boleto, TED e cartão)."
    },
    "valorPrevistoNumerico": {
      "type": [
        "number",
        "null"
      ],
      "description": "O mesmo valor em formato numérico, pronto para cálculo (ex.: 165000.00)."
    }
  },
  "description": "Projeção do valor que a empresa deve receber em boleto, TED e cartão no próximo mês, modelada sobre os últimos 12 meses de movimentação real compensada pela Núclea. É uma estimativa para frente construída a partir de transações que de fato aconteceram — não de 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.
>
> - **Concessão de crédito**: dimensionar limite e prazo com base na capacidade de recebimento projetada, não só no passado.
> - **Antecipação de recebíveis**: estimar o fluxo futuro de boletos e cartão que a empresa tem a receber.
> - **Acompanhamento de carteira**: comparar predição com histórico para detectar clientes em desaceleração antes do atraso.

## Cobertura — leia antes de interpretar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> A projeção cobre **boleto, TED e cartão**. O **Pix não entra**, nem dinheiro em espécie. Empresas que recebem majoritariamente por Pix (varejo de baixo tíquete, SaaS, e-commerce, serviços digitais) podem retornar `consta: false` ou valores muito abaixo da realidade — isso descreve o **perfil de recebimento** da empresa, não a saúde dela. O produto rende mais em negócios B2B que cobram por boleto: indústria, atacado, distribuição, construção, transporte.

---

Página em HTML: https://fontedata.com/docs/credito-e-score/nuclea-predicao-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