---
title: "Score de Dados Cadastrais PJ"
description: "Confere a razão social informada com a do CNPJ e devolve um score numérico (100 = a razão social confere por inteiro). Serve para validar o cadastro de uma empresa antes de aprovar um cliente ou fornecedor. Cobrada quando a base devolve o score, inclusive 0. Não é cobrada quando o CNPJ ou a razão social são inválidos, quando a base não encontra o CNPJ ou não calcula o score, nem quando a base falha ou demora. Disponível para contas PJ."
lang: pt-BR
canonical: https://doc.apibrasil.io/apis/creditos/15ad5e09-de5b-11f1-98bb-bc24118aba26
markdown: https://doc.apibrasil.io/apis/creditos/15ad5e09-de5b-11f1-98bb-bc24118aba26.md
source: apibrasil-documentation
---

# Score de Dados Cadastrais PJ

> Confere a razão social informada com a do CNPJ e devolve um score numérico (100 = a razão social confere por inteiro). Serve para validar o cadastro de uma empresa antes de aprovar um cliente ou fornecedor. Cobrada quando a base devolve o score, inclusive 0. Não é cobrada quando o CNPJ ou a razão social são inválidos, quando a base não encontra o CNPJ ou não calcula o score, nem quando a base falha ou demora. Disponível para contas PJ.

- **Categoria:** Antifraude e Compliance
- **Cobrança:** por consulta, só com o Bearer Token
- **Preço:** R$ 1,49 por consulta
- **Limite:** 990.000 por mês
- **Cadastro:** exige CNPJ
- **Versão:** v2
- **Publicada por:** APIBrasil
- **Especificação OpenAPI:** https://doc.apibrasil.io/apis/creditos/15ad5e09-de5b-11f1-98bb-bc24118aba26/openapi.json

## Como chamar

**Endereço base:** `https://gateway.apibrasil.io/api/v2`

Autenticação: cabeçalho `Authorization: Bearer <token>`. Nada além disso.

Com `homolog: true` no corpo, o gateway responde de uma base fixa, com a forma real da resposta, e não cobra. O CPF 00000000000 é dessa base e não é de ninguém: use-o nos testes, nunca em produção.

## Endpoints (1 endpoint)

### 1. POST /consulta/cnpj/credits

⚠️ Aviso: Cobra quando a base devolve o score, inclusive 0. Não cobra entrada inválida (400), CNPJ não encontrado ou score não calculado (404), nem resposta fora do formato, falha ou demora da base (5xx).

Envie um POST com tipo=score-dados-cadastrais-pj e:
- cnpj (obrigatório): CNPJ da empresa, com ou sem máscara (dígito verificador conferido).
- razao_social (obrigatório): Razão social a conferir, até 150 caracteres. Pode ter & e dígitos. Quebra de linha vira espaço antes da consulta.

Confere a razão social informada com a do CNPJ e devolve um score numérico (100 = a razão social confere por inteiro). Serve para validar o cadastro de uma empresa antes de aprovar um cliente ou fornecedor. Cobrada quando a base devolve o score, inclusive 0. Não é cobrada quando o CNPJ ou a razão social são inválidos, quando a base não encontra o CNPJ ou não calcula o score, nem quando a base falha ou demora.

Respostas de erro (nenhuma é cobrada):
HTTP 400: CNPJ inválido (dígito verificador), razão social em branco ou acima de 150 caracteres, ou um dos dois campos faltando. Não chama a base.
HTTP 404: A base não encontrou o CNPJ ou não calculou o score. A base usa a mesma resposta quando não consegue concluir a consulta: o 404 não prova que o CNPJ não existe.
HTTP 502: A base recusou a consulta ou respondeu fora do formato (score que não é número de 0 a 100).
HTTP 503: A base está indisponível ou limitando as consultas.
HTTP 504: A base não respondeu em 30 s.

Em homologação (homolog=true), sem cobrança, a resposta traz dados fictícios no mesmo formato.

- **Método:** `POST`
- **Endereço:** `https://gateway.apibrasil.io/api/v2/consulta/cnpj/credits`
- **Versão da rota:** v2

**Cabeçalhos**

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `application/json` |
| `Authorization` | `Bearer $APIBRASIL_TOKEN` |

**Corpo da requisição**

```json
{
  "tipo": "score-dados-cadastrais-pj",
  "cnpj": "11222333000181",
  "razao_social": "EMPRESA FICTICIA DE TESTE LTDA",
  "homolog": true
}
```

**Em cURL**

```bash
curl -X POST "https://gateway.apibrasil.io/api/v2/consulta/cnpj/credits" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIBRASIL_TOKEN" \
  -d '{"tipo":"score-dados-cadastrais-pj","cnpj":"11222333000181","razao_social":"EMPRESA FICTICIA DE TESTE LTDA","homolog":true}'
```

Este endpoint aceita `homolog: true` no corpo: a resposta volta com dados válidos, `api_limit_for` igual a `homolog` e sem tarifação.

**Resposta de exemplo, do catálogo**

```json
{
  "user": {
    "first_name": "[omitido]",
    "email": "[omitido]",
    "cellphone": "[omitido]",
    "notification": "yes"
  },
  "balance": "398,510",
  "balance_before": "400,000",
  "tax": "1,490",
  "status_code": 200,
  "error": false,
  "message": "Dados validos! Voce foi tarifado em R$ 1,49.",
  "valor_consulta": 1.49,
  "api_limit_for": "credit",
  "homolog": false,
  "data": {
    "cnpj": "11222333000181",
    "razao_social": "EMPRESA FICTICIA DE TESTE LTDA",
    "validacao": {
      "score_dados_cadastrais": 100
    }
  }
}
```

Nos exemplos de resposta, os campos da conta que gerou o exemplo (`user.first_name`, `user.email`, `user.cellphone`) saem como `[omitido]`. O resto é o que o catálogo publica.

## Armadilhas: o que uma integração erra sem avisar

Apuradas nas respostas que o próprio catálogo publica. Em todas elas o código funciona no caminho feliz e falha em silêncio no resto:

1. **O erro chega no CORPO, com HTTP 200.**
   A resposta traz um campo `error` booleano e uma `message`. Checar só `response.ok` ou o status HTTP deixa passar falha como sucesso. Confira SEMPRE `error === false` antes de ler `data`.

2. **`balance`, `tax` e `extra_charges.total` são STRING em formato brasileiro — e o formato varia entre APIs.**
   Valores observados no catálogo: `"154,380"`, `"497,84"`, `"0,000"` e `"0.19"`. Vírgula em umas, ponto em outra; três casas decimais em umas, duas em outra. Em JavaScript, `parseFloat("154,380")` devolve `154` e perde os centavos sem erro nenhum, e `Number("154,380")` devolve `NaN`. Escreva um conversor que trate os dois separadores, e nunca use esses campos numa decisão financeira sem convertê-los.

3. **Cada chamada custa dinheiro.**
   Retry cego multiplica a conta. Nunca repita automaticamente um 4xx: parâmetro errado repetido continua errado e continua cobrando. Repita só tempo esgotado e 5xx, com recuo exponencial e um teto pequeno de tentativas.

4. **HTTP 402 é saldo insuficiente, e repetir não resolve.**
   É o único status que exige ação humana — recarregar. Trate-o como erro terminal, com mensagem própria, e não o jogue no mesmo balde dos 4xx genéricos.

5. **`extra_charges` cobra à parte do preço da consulta.**
   Quando o corpo pede serviços adicionais, a resposta traz cada um com o preço e um `total` que NÃO está incluso no valor base. Se você mostra custo a quem usa, some os dois.

## Ver também

- Especificação OpenAPI: https://doc.apibrasil.io/apis/creditos/15ad5e09-de5b-11f1-98bb-bc24118aba26/openapi.json
- Catálogo de APIs: [Catálogo de APIs](https://doc.apibrasil.io/apis.md)
- SDKs oficiais: [SDKs oficiais](https://doc.apibrasil.io/sdks.md)
- Índice da documentação: https://doc.apibrasil.io/llms.txt
- Versão HTML desta página: https://doc.apibrasil.io/apis/creditos/15ad5e09-de5b-11f1-98bb-bc24118aba26