# Núclea — Concentração de Contrapartes

> Quanto da movimentação de boletos da empresa depende de uma única contraparte — o maior cliente (recebimento) ou o maior fornecedor (pagamento) — nos últimos 12 meses, medido pela Núclea, a câmara de compensação do sistema bancário.

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

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Mede a **dependência da empresa de uma única contraparte** na movimentação de boletos dos últimos 12 meses, direto da **Núclea** (ex-CIP) — a câmara que compensa os boletos do sistema bancário brasileiro. É o indicador clássico de risco de concentração: uma empresa que recebe 80% dos boletos de um único pagador quebra junto com ele.
>
> Cada chamada lê **uma perspectiva** e é cobrada individualmente. Para ter as duas leituras (clientes e fornecedores), faça duas chamadas.

## Requisição

### cURL

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

### Python

```python
import requests

resp = requests.get(
    "https://app.fontedata.com/api/v1/consulta/nuclea-concentracao-transacionado",
    params={"cnpj": "SEU_CNPJ", "perspectiva": "recebimento"},
    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-concentracao-transacionado");

url.search = new URLSearchParams({
  "cnpj": "SEU_CNPJ",
  "perspectiva": "recebimento"
}).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 cobre a movimentação do CNPJ raiz completo (matriz e filiais). | formato: 00.000.000/0000-00 |
| `perspectiva` | texto | não | Lado da leitura. `recebimento` (padrão) mede quanto dos boletos recebidos vem do maior pagador — dependência de poucos clientes, a leitura clássica de risco de crédito. `pagamento` mede quanto dos boletos pagos vai para o maior beneficiário — dependência de fornecedores. | `recebimento` |

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - **`consta`**: `true` quando há boletos registrados na perspectiva consultada. `consta: false` é um desfecho **normal**: a mesma empresa pode ter registros numa perspectiva e não ter na outra (quem só emite boleto não necessariamente paga por boleto). A consulta é cobrada normalmente — foi executada na base de origem.
> - **`maiorContrapartePercentual`**: a fatia da maior contraparte, de 0 a 100. Ex.: `34.06` = 34,06% de tudo que a empresa recebeu em boleto veio de um único pagador.
> - **`perspectiva`** e **`escopo`**: qual lado foi lido (boletos recebidos ou pagos).
> - **`janelaMeses`**: janela de apuração (12 meses retroativos).
> - **`abrangencia`**: CNPJ completo — matriz e filiais somadas.
> - **`mesReferencia`**: mês da carga de dados (AAAAMM).

### Exemplo de resposta

```json
{
  "cnpj": "33000167000101",
  "consta": true,
  "escopo": "boletos recebidos",
  "abrangencia": "CNPJ completo (matriz e filiais)",
  "janelaMeses": 12,
  "perspectiva": "recebimento",
  "mesReferencia": "202607",
  "maiorContrapartePercentual": 23.47
}
```

### 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á boletos registrados para o CNPJ na perspectiva consultada. Quando não há, a resposta vem com consta: false e uma mensagem explicativa — a outra perspectiva pode ter registros — e a consulta é cobrada normalmente, pois foi executada na base de origem."
    },
    "escopo": {
      "type": [
        "string",
        "null"
      ],
      "description": "O que a leitura cobre: boletos recebidos (perspectiva recebimento) ou boletos pagos (perspectiva pagamento)."
    },
    "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."
    },
    "perspectiva": {
      "type": [
        "string",
        "null"
      ],
      "description": "Lado da leitura aplicado nesta resposta: recebimento (concentração dos boletos recebidos, por pagador) ou pagamento (concentração dos boletos pagos, por beneficiário)."
    },
    "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."
    },
    "maiorContrapartePercentual": {
      "type": [
        "number",
        "null"
      ],
      "description": "Percentual do valor de boletos concentrado na maior contraparte, de 0 a 100 (ex.: 34.06 significa 34,06%). Na perspectiva recebimento, é a fatia do maior pagador (o maior cliente); na pagamento, a fatia do maior beneficiário (o maior fornecedor). Quanto maior o percentual, maior a dependência de uma única contraparte."
    }
  },
  "description": "Grau de concentração da movimentação de boletos da empresa na sua maior contraparte, nos últimos 12 meses, medido na infraestrutura de compensação do sistema bancário. Na perspectiva de recebimento, responde 'quanto do que a empresa recebe vem do maior cliente?'; na de pagamento, 'quanto do que ela paga vai para o maior fornecedor?'."
}
```

## 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. |
| `400` | Parâmetro obrigatório ausente ou inválido para esta consulta. Verifique os campos exigidos pelo endpoint. | O parâmetro `perspectiva` recebeu um valor diferente de `recebimento` ou `pagamento`. |
| `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**: detectar dependência excessiva de um único cliente antes de conceder limite — receita concentrada é receita frágil.
> - **Avaliação de fornecedores e parceiros**: medir se um distribuidor ou representante depende de um único fornecedor.
> - **Due diligence comercial**: entender a estrutura real de clientes/fornecedores de uma empresa, que não aparece em dado cadastral.

## Cobertura — leia antes de interpretar

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> Esta leitura cobre **apenas boletos**. Recebimentos por Pix, TED ou cartão não entram no cálculo de concentração. `consta: false` significa "sem boletos na perspectiva consultada no período" — **não** significa que a empresa está inativa nem que não tem clientes ou fornecedores. Para o volume total transacionado (boleto + cartão + TED), use a consulta **Núclea — Valor Histórico Transacionado** (`nuclea-historico-transacionado`).

---

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