> ## Documentation Index
> Fetch the complete documentation index at: https://docs-platform.services-valid.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Pessoa Jurídica

# Datasets de Pessoa Jurídica

<Note>
  Os datasets de certidões e de status\_person são processados apenas no modo assíncrono (`POST /person/async`), por serem consultas mais demoradas. Em consultas sync, eles aparecem em `failedDatasets` com a mensagem *Dataset disponível apenas na consulta assíncrona.* Os demais datasets da lista podem ser usados em sync e async.
</Note>

API KYB oferece datasets especializados que podem ser combinados conforme a necessidade da sua aplicação. Os códigos abaixo são os mesmos utilizados no corpo da requisição (campo `datasets`) e no retorno (campo `result.datasets[].dataset`).

### **1. Dados Cadastrais Básicos (**`basic`**)**

Informações cadastrais da empresa (Pessoa Jurídica):

**Quando usar**: Análise de crédito, validação cadastral, avaliação de perfil da empresa.

* **cnpj** (string): CNPJ
* **name** (string): Razão social
* **fantasyName** (string): Nome fantasia
* **foundingDate** (string): Data de fundação
* **dissolutionDate** (string): Data de fechamento
* **nationality** (string): País de registro
* **taxIdStatus** (string): Status do CNPJ na Receita Federal
* **taxRegime** (string): Regime tributário
* **companyType** (string): Tipo de empresa
* **age** (number): Idade da empresa em anos
* **isHeadquarter** (boolean): É matriz do grupo
* **headquarterState** (string): Estado da matriz
* **isConglomerate** (boolean): É conglomerado
* **legalNature** (object): Natureza jurídica (code, description)
* **activities** (array): Atividades CNAE. Cada item possui: **isMain** (boolean), **code** (string), **activity** (string)

### **2. Endereços (**`addresses`**)**

Endereços associados ao CNPJ:

**Quando usar**: Validação de endereço, análise de estabilidade geográfica, verificação de consistência cadastral.

Lista de endereços. O array contém objetos com:

* **streetAddress** (string): Logradouro completo
* **addressLocality** (string): Cidade
* **addressRegion** (string): Estado
* **postalCode** (string): CEP
* **addressCountry** (string): País
* **complement** (string): Complemento
* **neighborhood** (string): Bairro
* **isActive** (boolean): Endereço ativo
* **isMain** (boolean): Endereço principal

### **3. Telefones (**`phones`**)**

Telefones vinculados ao CNPJ:

**Quando usar**: Validação de contato, análise de canais de comunicação.

Lista de telefones. O array contém objetos com:

* **number** (string): Número de telefone
* **areaCode** (string): Código de área
* **countryCode** (string): Código de país

### **4. Indicadores de Atividade (**`activity_indicators`**)**

Métricas sobre o nível de atividade da empresa:

**Quando usar**: Avaliação de capacidade financeira, análise de porte empresarial, validação de operação ativa.

### **5. Grupo Econômico de Primeiro Nível (**`economic_group_first_level`**)**

Grupo econômico relacionado à empresa:

**Quando usar**: Análise de exposição a riscos compartilhados, mapeamento de estrutura societária, due diligence.

* **mainCompanyTaxId** (string): CNPJ principal
* **economicGroupType** (string): Tipo do grupo
* **companyDocNumbers** (array): CNPJs do grupo
* **totalCompanies** (number): Total de empresas
* **totalActiveCompanies** (number): Empresas ativas

### **6. Relacionamentos economicos (**`relationships`**)**

Retorna QSA atual

**Quando usar**: Análise de exposição a riscos compartilhados, mapeamento de estrutura societária, due diligence.

* **relatedEntityTaxIdNumber** (string)
* **relatedEntityTaxIdType** (string)
* **relatedEntityTaxIdCountry** (string)
* **relatedEntityName** (string)
* **relationshipType** (string)
* **relationshipName** (string)
* **relationshipLevel** (string)
* **relationshipDataOrigin** (string)
* \*\*creationDate \*\*(string)
* **lastUpdateDate**  (string)
* **relationshipStartDate** (string)
* **relationshipEndDate** (string)

### **7. Emails Pessoas relacionadas (**`related_people_emails`**):**

**Quando usar:** enriquecimento de dados e lead.

Dataset retorna:

* **relationshipType** (string)
* **email** (string)
* **isActive** (boolean)
* **isMain** (boolean)

### **8. Telefones pessoas relacionadas (related\_people\_phones):**

**Quando usar:** enriquecimento de dados e lead.

* **relationshipType** (string)
* **number** (string)
* **areaCode** (string)
* **countryCode** (string)
* **isActive** (boolean)
* **isMain** (boolean)

### **9. KYC e Compliance (**`kyc`**)**

Informações regulatórias e de compliance:

**Quando usar**: Processos de KYC/compliance, prevenção à lavagem de dinheiro (PLD), análise de risco reputacional.

* **isCurrentlyPEP** (boolean): É PPE atualmente
* **isCurrentlySanctioned** (boolean): Sancionado atualmente
* **pepHistory** (array): Histórico de PPE. Cada item possui:
  * **level** (string): Nível do PPE
  * **jobTitle** (string): Cargo
  * **state** (string): Estado
  * **isCurrentlyPEP** (boolean): É PPE atualmente
* **sanctionsHistory** (array): Histórico de sanções. Cada item possui:
  * **source** (string): Fonte da sanção
  * **type** (string): Tipo de sanção
  * **isCurrentlySanctioned** (boolean): Sancionado atualmente

### **10. Processos Judiciais e Administrativos (**`processes`**)**

Processos envolvendo a empresa:

**Quando usar**: Avaliação de riscos jurídicos, análise de reputação, due diligence legal.

* **processes** (array): Lista de processos. O array contém objetos com:
  * **number** (string): Número do processo
  * **courtLevel** (number): Nível do tribunal
  * **partyType** (string): Tipo de parte no processo
  * **status** (string): Situação do processo
  * **value** (number): Valor do processo
* **totalProcesses** (number): Total de processos

### **11. Certidão FGTS (**`fgts_company`**)**

**Disponibilidade**: apenas assíncrono (`POST /person/async`).

Consulta on-demand da certidão de regularidade do FGTS da empresa:

**Quando usar**: Verificação de compliance trabalhista, análise de risco em contratações, processos licitatórios.

* **certificates** (array): Lista de certidões. Cada item contém:
  * **origin** (string): Origem
  * **protocolNumber** (string): Protocolo
  * **fileUrl** (string): URL do resultado
  * **status** (string): Status da certidão

### **12. Certidão Negativa de Débitos Trabalhistas (**`labor_debt_certificate_company`**)**

**Disponibilidade**: apenas assíncrono (`POST /person/async`).

Consulta on-demand da CNDT (Certidão Negativa de Débitos Trabalhistas):

**Quando usar**: Due diligence pré-contratual, análise de crédito, processos de compliance.

* **certificates** (array): Lista de certidões. Cada item contém:
  * **origin** (string): Origem
  * **protocolNumber** (string): Protocolo
  * **fileUrl** (string): URL do resultado
  * **status** (string): Status da certidão

### **13. Certidão PGFN (**`pgfn_certificate_company`**)**

**Disponibilidade**: apenas assíncrono (`POST /person/async`).

Certidões de débitos tributários federais (PGFN):

**Quando usar**: Análise de compliance fiscal, verificação de regularidade tributária, processos de crédito.

* **origin** (string): Origem
* **protocolNumber** (string): Protocolo
* **fileUrl** (string): URL do resultado
* **status** (string): Status

### **14. Certidão Negativa IBAMA (**`ibama_cert_negativa_company`**)**

**Disponibilidade**: apenas assíncrono (`POST /person/async`).

Consulta on-demand de embargos e débitos ambientais:

**Quando usar**: Due diligence ambiental, processos licitatórios, análise de riscos ESG.

* **certificates** (array): Lista de certidões. Cada item contém:
  * **origin** (string): Origem
  * **protocolNumber** (string): Protocolo
  * **fileUrl** (string): URL do resultado
  * **status** (string): Status da certidão

### 15. Indicadores de atividade (`activity_indicators`)

Indicadores de atividade da empresa.

* **employeesRange** (string): Faixa de funcionários
* **incomeRange** (string): Faixa de renda
* **hasActivity** (boolean): Tem atividade
* **activityLevel** (number): Nível de atividade

## Uso no request

Sync e async usam a **mesma URI** em cada modo. Escolha o body conforme a forma de selecionar os datasets:

| Objetivo                         | URI                                                  | Campo obrigatório no body |
| -------------------------------- | ---------------------------------------------------- | ------------------------- |
| Escolher datasets específicos    | `POST /bureau/api/v1/bureau/person/sync` ou `/async` | `datasets`                |
| Reutilizar um pacote de datasets | `POST /bureau/api/v1/bureau/person/sync` ou `/async` | `datasetPackageId`        |

No modo sync, datasets marcados como **apenas assíncrono** não são processados: os demais datasets da requisição seguem normalmente e os async-only retornam em `failedDatasets`.

### Exemplos

Consulta por datasets específicos:

```json theme={"theme":"catppuccin-latte"}
{
  "datasets": ["basic", "addresses", "kyc"]
}
```

Consulta por pacote de datasets:

```json theme={"theme":"catppuccin-latte"}
{
  "datasetPackageId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5"
}
```