Datasets

Visão Geral

A API KYB (Know Your Business) permite realizar análises completas de empresas (Pessoas Jurídicas) através da consulta de múltiplos datasets consolidados em um único processo. Esta API foi desenvolvida para apoiar processos de verificação empresarial, análise de crédito, compliance e due diligence, fornecendo informações abrangentes sobre empresas a partir do CNPJ.

Como Funciona

O processo de consulta KYB opera em duas etapas principais:

1. Iniciação do Processo

A primeira etapa consiste em iniciar o processo de KYB através do endpoint POST /onboarding/api/v1/know/business. Nesta requisição, você especifica:

CNPJ da empresa a ser consultada
Webhook URL para receber a resposta assíncrona
Credenciais de autenticação para o webhook (Basic Auth) — opcional
Datasets que deseja consultar (opcional; se não informado, consulta todos disponíveis)
ID do pacote de datasets (opcional)
Refresh dos dados (opcional) — forçar atualização dos dados

A API retorna imediatamente um requestId único que identifica o processo iniciado, juntamente com a data de criação da requisição.

2. Recuperação dos Resultados

Como o processamento dos datasets pode levar algum tempo (especialmente para consultas on-demand), a API funciona de forma assíncrona:

Via Webhook: Assim que o processamento for concluído, a API enviará automaticamente os resultados para a URL do webhook configurada
Via Polling: Alternativamente, você pode consultar o status do processo usando o endpoint GET /onboarding/api/v1/know/business/{requestId} com o requestId recebido na etapa anterior

Endpoint de Iniciação: POST /onboarding/api/v1/know/business

Estrutura da Requisição

{
  "cnpj": "12345678000100",
  "webhookUrl": "https://seusistema.com/webhook",
  "webhookBasicAuth": "usuario:senha",
  "datasets": ["basic", "kyc", "addresses"],
  "datasetPackageId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
  "refreshData": false
}

Parâmetros de Entrada

Campo	Tipo	Obrigatório	Descrição
`cnpj`	string	Sim	CNPJ da empresa a ser consultada (14 dígitos, apenas números)
`webhookUrl`	string (URI)	Sim	URL que receberá os resultados quando o processamento for concluído
`webhookBasicAuth`	string	Não	Autenticação básica para o webhook (username:password ou base64(‘username:password’))
`datasets`	array (string[])	Não	Lista de códigos de datasets PJ a serem consultados (ex.: `basic`, `kyc`, `addresses`). Se omitido, todos os disponíveis serão consultados
`datasetPackageId`	string (UUID)	Não	ID do pacote de datasets
`refreshData`	boolean	Não	Forçar atualização dos dados

Estrutura da Resposta (Iniciação)

{
  "requestId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
  "createdAt": "2025-10-17T10:30:00Z"
}

Campo	Tipo	Descrição
`requestId`	string (UUID)	Identificador único do processo iniciado
`createdAt`	string (ISO 8601)	Data e hora da criação da requisição

Códigos de Resposta HTTP

200 OK: Processo iniciado com sucesso
400 Bad Request: Requisição malformada (campos obrigatórios ausentes ou formato inválido)
500 Internal Server Error: Erro interno do servidor

Endpoint de Consulta: GET /onboarding/api/v1/know/business/

Parâmetros de Entrada

Parâmetro	Tipo	Localização	Descrição
`requestId`	string (UUID)	Path	Identificador único retornado na iniciação do processo

Estrutura da Resposta (Resultados)

A resposta retorna um objeto result com requestId, key (CNPJ consultado) e um array datasets, em que cada item possui o código do dataset (dataset) e os dados (data). A estrutura de data varia conforme o tipo de dataset.

{
  "result": {
    "requestId": "05be75cc-8f8a-414a-891f-434aa9b4e7a5",
    "key": "12345678000100",
    "datasets": [
      {
        "dataset": "basic",
        "data": { }
      },
      {
        "dataset": "kyc",
        "data": { }
      }
    ]
  }
}

Para a estrutura detalhada de data por tipo de dataset (basic, addresses, phones, kyc, etc.), consulte a documentação do endpoint GET /onboarding/api/v1/know/business/.

Códigos de Resposta HTTP

200 OK: Resultados recuperados com sucesso
400 Bad Request: RequestId inválido ou malformado
500 Internal Server Error: Erro interno do servidor

Datasets Disponíveis para PJ

A API KYB oferece 11 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):

CNPJ, razão social e nome fantasia
Data de fundação e de fechamento
País de registro, status na Receita Federal, regime tributário
Tipo de empresa, idade, natureza jurídica
Indicadores de matriz, conglomerado, estado da matriz
Atividades CNAE (principal e secundárias)

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

2. Endereços (`addresses`)

Endereços associados ao CNPJ:

Logradouro completo, complemento, bairro
Cidade, estado, CEP e país
Indicadores de endereço ativo e principal

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

3. Telefones (`phones`)

Telefones vinculados ao CNPJ:

Número de telefone
Código de área e código de país

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

4. Indicadores de Atividade (`activity_indicators`)

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

Faixa de funcionários e faixa de renda
Indicador de existência de atividade
Nível de atividade

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:

CNPJ principal e tipo do grupo
CNPJs do grupo
Total de empresas e total de empresas ativas

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

6. KYC e Compliance (`kyc`)

Informações regulatórias e de compliance:

Indicação de PPE e de sancionado atualmente
Histórico de PEP e histórico de sanções

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

7. Processos Judiciais e Administrativos (`processes`)

Processos envolvendo a empresa:

Lista de processos (número, nível do tribunal, tipo de parte, status, valor)
Total de processos

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

8. Certidão FGTS (`fgts_company`)

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

Status de regularidade (REGULAR/IRREGULAR)
Dados do estabelecimento, CEI quando aplicável
Link para arquivo da certidão (HTML/PDF), data de emissão e validade

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

9. Certidão Negativa de Débitos Trabalhistas (`labor_debt_certificate_company`)

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

Número do protocolo e da certidão, status (POSITIVA/NEGATIVA)
Data de expedição e validade, texto da certidão, link para PDF

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

10. Certidão PGFN (`pgfn_certificate_company`)

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

Origem, número do protocolo
URL do resultado e status

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

11. Certidão Negativa IBAMA (`ibama_cert_negativa_company`)

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

Número do protocolo, status da certidão (POSITIVA/NEGATIVA)
Data de validade, texto da certidão, link para PDF

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

Retorno dos Dados

A resposta do endpoint GET retorna os dados no objeto result, com o array result.datasets. Cada item desse array contém:

dataset: código do dataset (igual aos códigos usados na requisição: basic, addresses, kyc, etc.)
data: objeto com os dados do dataset; a estrutura de data varia conforme o tipo de dataset

Não há mapeamento entre códigos e “typeAlias”: a API utiliza os mesmos códigos na requisição e na resposta. Para a estrutura detalhada de cada data por tipo de dataset, consulte a documentação do GET /onboarding/api/v1/know/business/.

Primeiros Passos

Onboarding

Background Check

Liveness

Assinatura Digital

Visão Geral

Como Funciona

1. Iniciação do Processo

2. Recuperação dos Resultados

Endpoint de Iniciação: POST /onboarding/api/v1/know/business

Estrutura da Requisição

Parâmetros de Entrada

Estrutura da Resposta (Iniciação)

Códigos de Resposta HTTP

Endpoint de Consulta: GET /onboarding/api/v1/know/business/

Parâmetros de Entrada

Estrutura da Resposta (Resultados)

Códigos de Resposta HTTP

Datasets Disponíveis para PJ

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

2. Endereços (`addresses`)

3. Telefones (`phones`)

4. Indicadores de Atividade (`activity_indicators`)

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

6. KYC e Compliance (`kyc`)

7. Processos Judiciais e Administrativos (`processes`)

8. Certidão FGTS (`fgts_company`)

9. Certidão Negativa de Débitos Trabalhistas (`labor_debt_certificate_company`)

10. Certidão PGFN (`pgfn_certificate_company`)

11. Certidão Negativa IBAMA (`ibama_cert_negativa_company`)

Retorno dos Dados

Primeiros Passos

Onboarding

Background Check

Liveness

Assinatura Digital

​Visão Geral

​Como Funciona

​1. Iniciação do Processo

​2. Recuperação dos Resultados

​Endpoint de Iniciação: POST /onboarding/api/v1/know/business

​Estrutura da Requisição

​Parâmetros de Entrada

​Estrutura da Resposta (Iniciação)

​Códigos de Resposta HTTP

​Endpoint de Consulta: GET /onboarding/api/v1/know/business/

​Parâmetros de Entrada

​Estrutura da Resposta (Resultados)

​Códigos de Resposta HTTP

​Datasets Disponíveis para PJ

​1. Dados Cadastrais Básicos (basic)

​2. Endereços (addresses)

​3. Telefones (phones)

​4. Indicadores de Atividade (activity_indicators)

​5. Grupo Econômico de Primeiro Nível (economic_group_first_level)

​6. KYC e Compliance (kyc)

​7. Processos Judiciais e Administrativos (processes)

​8. Certidão FGTS (fgts_company)

​9. Certidão Negativa de Débitos Trabalhistas (labor_debt_certificate_company)

​10. Certidão PGFN (pgfn_certificate_company)

​11. Certidão Negativa IBAMA (ibama_cert_negativa_company)

​Retorno dos Dados

Visão Geral

Como Funciona

1. Iniciação do Processo

2. Recuperação dos Resultados

Endpoint de Iniciação: POST /onboarding/api/v1/know/business

Estrutura da Requisição

Parâmetros de Entrada

Estrutura da Resposta (Iniciação)

Códigos de Resposta HTTP

Endpoint de Consulta: GET /onboarding/api/v1/know/business/

Parâmetros de Entrada

Estrutura da Resposta (Resultados)

Códigos de Resposta HTTP

Datasets Disponíveis para PJ

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

2. Endereços (`addresses`)

3. Telefones (`phones`)

4. Indicadores de Atividade (`activity_indicators`)

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

6. KYC e Compliance (`kyc`)

7. Processos Judiciais e Administrativos (`processes`)

8. Certidão FGTS (`fgts_company`)

9. Certidão Negativa de Débitos Trabalhistas (`labor_debt_certificate_company`)

10. Certidão PGFN (`pgfn_certificate_company`)

11. Certidão Negativa IBAMA (`ibama_cert_negativa_company`)

Retorno dos Dados