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

# Consultar dados cadastrais

> Consulte dados cadastrais de CPF e CNPJ com a chave de API da plataforma.

> [!WARNING]
>
> Este recurso é exclusivo de **Chargefy for Platforms**. Use uma chave secreta
> de plataforma com escopo `platform_admin` no servidor da sua aplicação.

Envie o CPF ou CNPJ na URL para receber todos os dados cadastrais disponíveis
para aquele documento. O tipo é identificado automaticamente. A consulta
funciona antes de cadastrar uma organização filha e usa somente a chave da
plataforma, sem precisar do header `Organization`.

Uma plataforma pode consultar o CNPJ de uma loja durante o cadastro e preencher
razão social, endereço e contatos. Para uma pessoa, o CPF permite preencher
nome, nascimento e os contatos disponíveis na base.

**document** `string` *required*

CPF com 11 dígitos ou CNPJ com 14 dígitos e dígitos verificadores válidos.
Prefira enviar sem pontuação. Se enviar pontuação, codifique o valor como
segmento de URL, incluindo a barra do CNPJ como `%2F`.

> [!NOTE]
>
> Os dados vinculados a um CPF podem conter imprecisões ou estar desatualizados,
> inclusive endereço, telefone e e-mail. Confirme as informações com o titular
> antes de utilizá-las. A consulta não comprova identidade ou titularidade dos
> contatos.

### Consultar CPF

O objeto `person` reúne identificação, contato, endereço, poder aquisitivo e
registro eleitoral. Os valores abaixo são ilustrativos.

```bash CPF theme={"theme":"css-variables"}
curl "https://api.chargefy.io/v1/document/11144477735" \
  -H "Authorization: Bearer {{API_KEY}}"
```

```bash CNPJ theme={"theme":"css-variables"}
curl "https://api.chargefy.io/v1/document/37335118000180" \
  -H "Authorization: Bearer {{API_KEY}}"
```

```json 200 (CPF) theme={"theme":"css-variables"}
{
  "object": "document",
  "company": null,
  "currency": "brl",
  "document": "11144477735",
  "document_type": "cpf",
  "livemode": true,
  "person": {
    "address": {
      "city": "São Paulo",
      "country": null,
      "line1": "Exemplo",
      "line2": "Sala 2",
      "municipality_code": null,
      "neighborhood": "Centro",
      "number": "10",
      "postal_code": "01001000",
      "state": "SP",
      "street_type": "Rua"
    },
    "birthdate": "1990-01-02",
    "email": "nome@email.com",
    "first_name": "Cliente",
    "full_name": "Cliente de Exemplo",
    "last_name": "de Exemplo",
    "phone": {
      "area_code": "11",
      "country_code": "55",
      "number": "999999999",
      "type": null
    },
    "purchasing_power": {
      "category": "Médio",
      "category_code": "3",
      "income_amount": 250075,
      "income_range": "De R$ 2.000 a R$ 3.000"
    },
    "voter_record": {
      "registration": "001234567890",
      "section": "0020",
      "zone": "001"
    }
  },
  "updated_at": null
}
```

```json 200 (CNPJ) theme={"theme":"css-variables"}
{
  "object": "document",
  "company": {
    "address": {
      "city": "São Paulo",
      "country": {
        "code": "76",
        "name": "Brasil"
      },
      "line1": "Rua Exemplo",
      "line2": "Sala 2",
      "municipality_code": "3550308",
      "neighborhood": "Centro",
      "number": "10",
      "postal_code": "01001000",
      "state": "SP",
      "street_type": null
    },
    "capital_amount": 1000050,
    "emails": [
      {
        "address": "nome@email.com",
        "domain": "email.com",
        "ownership": "CORPORATE"
      }
    ],
    "is_headquarters": true,
    "jurisdiction": null,
    "legal_name": "EMPRESA EXEMPLO LTDA",
    "legal_nature": {
      "code": "2062",
      "name": "Sociedade Empresária Limitada"
    },
    "main_activity": {
      "code": "6311900",
      "name": "Tratamento de dados"
    },
    "mei": {
      "optant": false,
      "since": null
    },
    "members": [
      {
        "agent": {
          "person": {
            "age_range": null,
            "country": null,
            "document": "***654321**",
            "name": "Representante exemplo",
            "type": "NATURAL"
          },
          "role": {
            "code": "5",
            "name": "Administrador"
          }
        },
        "person": {
          "age_range": "31-40",
          "country": {
            "code": "76",
            "name": "Brasil"
          },
          "document": "***123456**",
          "name": "Sócio exemplo",
          "type": "NATURAL"
        },
        "role": {
          "code": "49",
          "name": "Sócio-Administrador"
        },
        "since": "2020-06-05"
      }
    ],
    "opening_date": "2020-06-05",
    "phones": [
      {
        "area_code": "11",
        "country_code": "55",
        "number": "999999999",
        "type": "MOBILE"
      },
      {
        "area_code": "11",
        "country_code": "55",
        "number": "33333333",
        "type": "LANDLINE"
      }
    ],
    "secondary_activities": [
      {
        "code": "6201501",
        "name": "Desenvolvimento de programas de computador sob encomenda"
      }
    ],
    "simples_nacional": {
      "optant": true,
      "since": "2020-06-05"
    },
    "size": {
      "acronym": "ME",
      "code": "1",
      "name": "Microempresa"
    },
    "special_status": null,
    "special_status_date": null,
    "status": {
      "code": "2",
      "name": "Ativa"
    },
    "status_date": "2020-06-05",
    "status_reason": null,
    "suframa": [],
    "trade_name": "Empresa exemplo"
  },
  "currency": "brl",
  "document": "37335118000180",
  "document_type": "cnpj",
  "livemode": true,
  "person": null,
  "updated_at": "2026-11-12T12:00:00Z"
}
```

```json 400 theme={"theme":"css-variables"}
{
  "error": {
    "code": "invalid_request",
    "message": "Provide a valid CPF or CNPJ.",
    "param": "document",
    "type": "invalid_request_error"
  }
}
```

```json 401 theme={"theme":"css-variables"}
{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key.",
    "type": "authentication_error"
  }
}
```

```json 403 theme={"theme":"css-variables"}
{
  "error": {
    "code": "permission_denied",
    "message": "A platform API key is required.",
    "type": "authentication_error"
  }
}
```

```json 404 theme={"theme":"css-variables"}
{
  "error": {
    "code": "document_not_found",
    "message": "Document not found.",
    "param": "document",
    "type": "invalid_request_error"
  }
}
```

```json 503 theme={"theme":"css-variables"}
{
  "error": {
    "code": "document_lookup_unavailable",
    "message": "Document lookup is temporarily unavailable. Try again later.",
    "type": "api_error"
  }
}
```

### Consultar CNPJ

O objeto `company` reúne cadastro, situação, contatos, atividades econômicas,
porte, regimes tributários e quadro societário. Todos os contatos e sócios
retornados pela fonte são incluídos.

## Campos da resposta

Cada campo do contrato está sempre presente. Escalares e objetos sem dados
retornam `null`; listas sem registros retornam `[]`. Valores monetários são
inteiros na menor unidade da moeda (centavos em `brl`) e usam a moeda `brl`.

**object** `string`

Sempre `document`.

**company** `object | null`

Dados empresariais para CNPJ. Retorna `null` para CPF.

**company.address** `object | null`

Endereço cadastral disponível.

**company.address.city** `null | string`

Município.

**company.address.country** `object | null`

País, com código e nome quando disponíveis.

**company.address.country.code** `null | string`

Código da classificação, preservado como texto.

**company.address.country.name** `null | string`

Nome ou descrição.

**company.address.line1** `null | string`

Nome do logradouro.

**company.address.line2** `null | string`

Complemento do endereço.

**company.address.municipality\_code** `null | string`

Código IBGE do município.

**company.address.neighborhood** `null | string`

Bairro.

**company.address.number** `null | string`

Número, preservado como texto.

**company.address.postal\_code** `null | string`

CEP, preservado como texto.

**company.address.state** `null | string`

Sigla da unidade federativa.

**company.address.street\_type** `null | string`

Tipo do logradouro, quando disponível separadamente.

**company.capital\_amount** `null | number`

Capital social na menor unidade da moeda (centavos em `brl`). Por exemplo, `1000050` representa R\$ 10.000,50.

**company.emails** `array`

Todos os e-mails retornados pela fonte.

**company.emails\[].address** `null | string`

Endereço de e-mail.

**company.emails\[].domain** `null | string`

Domínio do e-mail.

**company.emails\[].ownership** `null | string`

Classificação do contato informada pela fonte, como `CORPORATE`, `PERSONAL` ou
`ACCOUNTING`.

**company.is\_headquarters** `null | boolean`

Indica se o estabelecimento é a matriz.

**company.jurisdiction** `null | string`

Ente federativo responsável, quando aplicável.

**company.legal\_name** `null | string`

Razão social.

**company.legal\_nature** `object | null`

Natureza jurídica, com código e descrição.

**company.legal\_nature.code** `null | string`

Código da classificação, preservado como texto.

**company.legal\_nature.name** `null | string`

Nome ou descrição.

**company.main\_activity** `object | null`

Atividade econômica principal, com código CNAE e descrição.

**company.main\_activity.code** `null | string`

Código da classificação, preservado como texto.

**company.main\_activity.name** `null | string`

Nome ou descrição.

**company.members** `array`

Quadro de sócios e administradores.

**company.members\[].agent** `object | null`

Representante legal do sócio, quando disponível.

**company.members\[].agent.person** `object | null`

Identificação do sócio ou representante, quando disponível.

**company.members\[].agent.person.age\_range** `null | string`

Faixa etária informada pela fonte.

**company.members\[].agent.person.country** `object | null`

País, com código e nome quando disponíveis.

**company.members\[].agent.person.country.code** `null | string`

Código da classificação, preservado como texto.

**company.members\[].agent.person.country.name** `null | string`

Nome ou descrição.

**company.members\[].agent.person.document** `null | string`

Documento do sócio ou representante como informado pela fonte. CPF pode vir
parcialmente oculto.

**company.members\[].agent.person.name** `null | string`

Nome ou descrição.

**company.members\[].agent.person.type** `null | string`

Tipo de pessoa, como `NATURAL`, `LEGAL`, `FOREIGN` ou `UNKNOWN`.

**company.members\[].agent.role** `object | null`

Qualificação societária, com código e descrição.

**company.members\[].agent.role.code** `null | string`

Código da classificação, preservado como texto.

**company.members\[].agent.role.name** `null | string`

Nome ou descrição.

**company.members\[].person** `object | null`

Identificação do sócio ou representante, quando disponível.

**company.members\[].person.age\_range** `null | string`

Faixa etária informada pela fonte.

**company.members\[].person.country** `object | null`

País, com código e nome quando disponíveis.

**company.members\[].person.country.code** `null | string`

Código da classificação, preservado como texto.

**company.members\[].person.country.name** `null | string`

Nome ou descrição.

**company.members\[].person.document** `null | string`

Documento do sócio ou representante como informado pela fonte. CPF pode vir
parcialmente oculto.

**company.members\[].person.name** `null | string`

Nome ou descrição.

**company.members\[].person.type** `null | string`

Tipo de pessoa, como `NATURAL`, `LEGAL`, `FOREIGN` ou `UNKNOWN`.

**company.members\[].role** `object | null`

Qualificação societária, com código e descrição.

**company.members\[].role.code** `null | string`

Código da classificação, preservado como texto.

**company.members\[].role.name** `null | string`

Nome ou descrição.

**company.members\[].since** `null | string`

Data de início do vínculo ou enquadramento.

**company.mei** `object | null`

Enquadramento no MEI.

**company.mei.optant** `null | boolean`

Indica opção ou enquadramento no regime.

**company.mei.since** `null | string`

Data de início do vínculo ou enquadramento.

**company.opening\_date** `null | string`

Data de abertura no formato `YYYY-MM-DD`.

**company.phones** `array`

Todos os telefones retornados pela fonte.

**company.phones\[].area\_code** `null | string`

DDD.

**company.phones\[].country\_code** `null | string`

Código telefônico do país, como `55`.

**company.phones\[].number** `null | string`

Número, preservado como texto.

**company.phones\[].type** `null | string`

Tipo informado pela fonte.

**company.secondary\_activities** `array`

Atividades econômicas secundárias, com códigos CNAE e descrições.

**company.secondary\_activities\[].code** `null | string`

Código da classificação, preservado como texto.

**company.secondary\_activities\[].name** `null | string`

Nome ou descrição.

**company.simples\_nacional** `object | null`

Opção pelo Simples Nacional.

**company.simples\_nacional.optant** `null | boolean`

Indica opção ou enquadramento no regime.

**company.simples\_nacional.since** `null | string`

Data de início do vínculo ou enquadramento.

**company.size** `object | null`

Porte empresarial.

**company.size.acronym** `null | string`

Sigla do porte.

**company.size.code** `null | string`

Código da classificação, preservado como texto.

**company.size.name** `null | string`

Nome ou descrição.

**company.special\_status** `object | null`

Situação especial, quando aplicável.

**company.special\_status.code** `null | string`

Código da classificação, preservado como texto.

**company.special\_status.name** `null | string`

Nome ou descrição.

**company.special\_status\_date** `null | string`

Data da situação especial.

**company.status** `object | null`

Situação cadastral, com código e descrição.

**company.status.code** `null | string`

Código da classificação, preservado como texto.

**company.status.name** `null | string`

Nome ou descrição.

**company.status\_date** `null | string`

Data da situação cadastral.

**company.status\_reason** `object | null`

Motivo da situação cadastral, quando disponível.

**company.status\_reason.code** `null | string`

Código da classificação, preservado como texto.

**company.status\_reason.name** `null | string`

Nome ou descrição.

**company.suframa** `array`

Inscrições SUFRAMA retornadas pela fonte. Lista vazia quando não há dados
disponíveis.

**company.suframa\[].approval\_date** `null | string`

Data de aprovação do projeto.

**company.suframa\[].approved** `null | boolean`

Indica aprovação do projeto.

**company.suframa\[].incentives** `array`

Incentivos fiscais retornados para a inscrição.

**company.suframa\[].incentives\[].basis** `null | string`

Base legal do incentivo.

**company.suframa\[].incentives\[].benefit** `null | string`

Benefício fiscal.

**company.suframa\[].incentives\[].purpose** `null | string`

Finalidade do incentivo.

**company.suframa\[].incentives\[].tax** `null | string`

Tributo incentivado.

**company.suframa\[].number** `null | string`

Número, preservado como texto.

**company.suframa\[].since** `null | string`

Data de início do vínculo ou enquadramento.

**company.suframa\[].status** `object | null`

Situação cadastral, com código e descrição.

**company.suframa\[].status.code** `null | string`

Código da classificação, preservado como texto.

**company.suframa\[].status.name** `null | string`

Nome ou descrição.

**company.trade\_name** `null | string`

Nome fantasia.

**currency** `string`

Moeda dos valores monetários, sempre `brl`.

**document** `string`

CPF ou CNPJ consultado, sem pontuação.

**document\_type** `string`

Tipo do documento, `cpf` ou `cnpj`.

**livemode** `boolean`

`true` com chave de produção e `false` com chave de teste. Ambos consultam os
dados disponíveis para o documento informado.

**person** `object | null`

Dados pessoais para CPF. Retorna `null` para CNPJ.

**person.address** `object | null`

Endereço cadastral disponível.

**person.address.city** `null | string`

Município.

**person.address.country** `object | null`

País, com código e nome quando disponíveis.

**person.address.country.code** `null | string`

Código da classificação, preservado como texto.

**person.address.country.name** `null | string`

Nome ou descrição.

**person.address.line1** `null | string`

Nome do logradouro.

**person.address.line2** `null | string`

Complemento do endereço.

**person.address.municipality\_code** `null | string`

Código IBGE do município.

**person.address.neighborhood** `null | string`

Bairro.

**person.address.number** `null | string`

Número, preservado como texto.

**person.address.postal\_code** `null | string`

CEP, preservado como texto.

**person.address.state** `null | string`

Sigla da unidade federativa.

**person.address.street\_type** `null | string`

Tipo do logradouro, quando disponível separadamente.

**person.birthdate** `null | string`

Data de nascimento no formato `YYYY-MM-DD`.

**person.email** `null | string`

E-mail cadastral disponível.

**person.first\_name** `string`

Primeira palavra do nome.

**person.full\_name** `string`

Nome completo. Pode ser retornado sem acentos.

**person.last\_name** `string`

Demais palavras do nome.

**person.phone** `object | null`

Telefone cadastral disponível.

**person.phone.area\_code** `null | string`

DDD.

**person.phone.country\_code** `null | string`

Código telefônico do país, como `55`.

**person.phone.number** `null | string`

Número, preservado como texto.

**person.phone.type** `null | string`

Tipo informado pela fonte.

**person.purchasing\_power** `object | null`

Classificação de poder aquisitivo presente na base consultada.

**person.purchasing\_power.category** `null | string`

Descrição da categoria de poder aquisitivo.

**person.purchasing\_power.category\_code** `null | string`

Código da categoria na classificação.

**person.purchasing\_power.income\_amount** `null | number`

Renda registrada na base, na menor unidade da moeda (centavos em `brl`). Por exemplo, `250075` representa R\$
2.500,75. Retorna `null` quando não existe um valor numérico utilizável.

**person.purchasing\_power.income\_range** `null | string`

Descrição da faixa de renda registrada.

**person.voter\_record** `object | null`

Dados de registro eleitoral presentes na base consultada.

**person.voter\_record.registration** `null | string`

Número do título de eleitor, preservado como texto.

**person.voter\_record.section** `null | string`

Seção eleitoral, preservada como texto.

**person.voter\_record.zone** `null | string`

Zona eleitoral, preservada como texto.

**updated\_at** `null | string`

Data de atualização informada pela fonte, em ISO 8601. Retorna `null` quando
essa data não está disponível, como na consulta de CPF.

## Disponibilidade dos dados

A consulta está disponível sem cota própria ou por chave. A capacidade e a
atualização das fontes ainda determinam quando uma consulta pode ser atendida.
Chaves de teste e produção consultam os dados reais disponíveis para o documento.

A consulta de CNPJ informa a data de atualização em `updated_at`. O CPF de um
sócio pode vir parcialmente oculto na fonte e é devolvido nesse formato.

## Erros

| HTTP | Código | Quando ocorre |
| - | - | - |
| `400` | `invalid_request` | Documento ausente, malformado ou com dígitos verificadores inválidos. |
| `401` | `authentication_failed` | Chave ausente, inválida, revogada ou expirada. |
| `403` | `permission_denied` | Chave de organização ou outra credencial sem acesso de plataforma. |
| `404` | `document_not_found` | Documento não encontrado na fonte consultada. |
| `405` | `method_not_allowed` | Método diferente de `GET`. |
| `503` | `document_lookup_unavailable` | Fonte temporariamente indisponível, inclusive por capacidade ou tempo de resposta. |

Repita uma consulta que retornou `503` após um intervalo. Um `404` significa
que a consulta foi concluída sem encontrar o documento.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.