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)
Datasets que deseja consultar (opcional - se não informado, consulta todos disponíveis)

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": "12345678000195",
  "webhookUrl": "https://seusistema.com/webhook",
  "webhookBasicAuth": "usuario:senha",
  "dossieFormat": "json",
  "datasets": [
    { "dataset": "addresses_extended_pj" },
    { "dataset": "phones_extended_pj" },
    { "dataset": "activity_indicators" }
  ]
}

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á a notificação quando os resultados estiverem prontos
`webhookBasicAuth`	string	Sim	Credenciais no formato “usuario:senha” para autenticação Basic Auth no webhook
`dossieFormat`	string	Não	Formato do dossiê retornado. Valores aceitos: `"json"` (padrão)
`datasets`	array	Não	Lista de datasets específicos a serem consultados. Se omitido, todos os datasets disponíveis serão consultados

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)

{
  "result": {
    // Objeto contendo todos os datasets solicitados
    // A estrutura varia de acordo com os datasets consultados
  }
}

O campo result contém um objeto com os dados consolidados de todos os datasets solicitados. A estrutura específica depende dos datasets incluídos na requisição inicial.

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 12 datasets especializados que podem ser combinados conforme a necessidade da sua aplicação:

1. Endereços Estendidos (`addresses_extended`)

Retorna informações detalhadas sobre endereços associados ao CNPJ, incluindo:

Logradouro, número, complemento
Bairro, cidade, UF e CEP
Frequência e quantidade de passagens do endereço
Datas de primeira e última aparição
Indicadores de confiabilidade do endereço

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

2. Telefones Estendidos (`phones_extended`)

Fornece dados sobre telefones vinculados ao CNPJ:

Número de telefone e tipo (fixo/celular)
Frequência de observações nos registros
Indicadores de uso e confiabilidade
Histórico de primeira e última aparição

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

3. Indicadores de Atividade (`activity_indicators`)

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

Indicador binário de atividade (ativo/inativo)
Faixa de faturamento estimado
Nível de atividade (escala 0-1)
Quantidade estimada de funcionários
Presença digital (existência de website)
Histórico de passagens do CNPJ

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

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

Mapeia o grupo econômico relacionado à empresa:

Total de sócios e suas participações
Empresas relacionadas no primeiro nível
Distribuição geográfica (estados e cidades)
Quantidade de pessoas e endereços no grupo
Níveis de atividade (mínimo e máximo) do grupo
Faixas de faturamento agregadas

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

5. Certidão FGTS (`ondemand_fgts_company`)

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

Status de regularidade (REGULAR/IRREGULAR)
Dados do estabelecimento consultado
CEI (Cadastro Específico do INSS) 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.

6. Certidão Negativa de Débitos Trabalhistas (`ondemand_cert_labor_debt_absence_company`)

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

Número do protocolo e da certidão
Status (POSITIVA/NEGATIVA)
Indicador de existência de débitos
Data de expedição e período de validade
Texto completo da certidão
Link para arquivo PDF

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

7. Processos Judiciais e Administrativos (`processes`)

Histórico completo de processos envolvendo a empresa:

Identificação e numeração dos processos
Partes envolvidas (autor, réu, outros)
Natureza e assunto do processo
Andamentos e movimentações processuais
Órgão/tribunal de origem
Resumo quantitativo por tipo de processo

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

8. Certidão PGFN (`ondemand_pgfn_company`)

Consulta on-demand de débitos tributários federais:

Status da certidão (POSITIVA/NEGATIVA)
Número do certificado
Datas de emissão e validade
Indicador de liberação
Detalhes sobre débitos quando existentes

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

9. Certidão Negativa IBAMA (`ondemand_ibama_cert_negativa_company`)

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

Número do protocolo
Status da certidão (POSITIVA/NEGATIVA)
Indicador de débitos ou embargos
Data de validade
Texto da certidão
Link para arquivo PDF

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

10. KYC e Compliance (`kyc`)

Informações regulatórias e de compliance:

Sanções e restrições nacionais e internacionais
Pessoas Politicamente Expostas (PEP) no quadro societário
Listas de observância e alertas regulatórios
Origem e detalhamento das restrições
Histórico de sanções

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

11. Exposição e Perfil na Mídia (`media_profile_and_exposure`)

Análise de presença em notícias e mídia:

Indicadores de volume de exposição
Análise de sentimento (positivo/negativo/neutro)
Lista de notícias e menções relevantes
Fontes e datas das publicações
Resumo por período temporal

Quando usar: Análise de reputação, monitoramento de imagem, due diligence reputacional.

12. Dados Cadastrais Básicos (`quod_basic`)

Informações cadastrais e Score de crédito:

Razão social e nome fantasia
Situação cadastral atualizada
Natureza jurídica e CNAEs
Pendências financeiras
Score de crédito
Histórico de consultas
Indicadores de inadimplência

Quando usar: Análise de crédito, decisões de limite, avaliação de risco de inadimplência.

Retorno dos Dados

Quando você receber os resultados do dossiê, os dados estarão organizados por “typeAlias” (nome de exibição). A tabela abaixo mapeia esses nomes para os códigos de dataset utilizados na requisição:

Dataset (Request)	TypeAlias (Retorno)
`activity_indicators`	INDICADORES DE ATIVIDADES
`addresses_extended`	ENDEREÇOS
`economic_group_first_level`	GRUPO ECONÔMICO DE PRIMEIRO NÍVEL
`kyc`	KYC E COMPLIANCE
`media_profile_and_exposure`	EXPOSIÇÃO E PERFIL NA MÍDIA
`ondemand_cert_labor_debt_absence_company`	CERTIDÃO NEGATIVA DE DÉBITOS TRABALHISTAS
`ondemand_fgts_company`	CERTIDÃO FGTS
`ondemand_ibama_cert_negativa_company`	CERTIDÃO NEGATIVA DO IBAMA
`ondemand_pgfn_company`	CERTIDÃO PGFN
`phones_extended`	TELEFONES
`processes`	PROCESSOS JUDICIAIS E ADMINISTRATIVOS
`quod_basic`	DADOS CADASTRAIS BÁSICOS

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. Endereços Estendidos (`addresses_extended`)

2. Telefones Estendidos (`phones_extended`)

3. Indicadores de Atividade (`activity_indicators`)

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

5. Certidão FGTS (`ondemand_fgts_company`)

6. Certidão Negativa de Débitos Trabalhistas (`ondemand_cert_labor_debt_absence_company`)

7. Processos Judiciais e Administrativos (`processes`)

8. Certidão PGFN (`ondemand_pgfn_company`)

9. Certidão Negativa IBAMA (`ondemand_ibama_cert_negativa_company`)

10. KYC e Compliance (`kyc`)

11. Exposição e Perfil na Mídia (`media_profile_and_exposure`)

12. Dados Cadastrais Básicos (`quod_basic`)

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. Endereços Estendidos (addresses_extended)

​2. Telefones Estendidos (phones_extended)

​3. Indicadores de Atividade (activity_indicators)

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

​5. Certidão FGTS (ondemand_fgts_company)

​6. Certidão Negativa de Débitos Trabalhistas (ondemand_cert_labor_debt_absence_company)

​7. Processos Judiciais e Administrativos (processes)

​8. Certidão PGFN (ondemand_pgfn_company)

​9. Certidão Negativa IBAMA (ondemand_ibama_cert_negativa_company)

​10. KYC e Compliance (kyc)

​11. Exposição e Perfil na Mídia (media_profile_and_exposure)

​12. Dados Cadastrais Básicos (quod_basic)

​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. Endereços Estendidos (`addresses_extended`)

2. Telefones Estendidos (`phones_extended`)

3. Indicadores de Atividade (`activity_indicators`)

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

5. Certidão FGTS (`ondemand_fgts_company`)

6. Certidão Negativa de Débitos Trabalhistas (`ondemand_cert_labor_debt_absence_company`)

7. Processos Judiciais e Administrativos (`processes`)

8. Certidão PGFN (`ondemand_pgfn_company`)

9. Certidão Negativa IBAMA (`ondemand_ibama_cert_negativa_company`)

10. KYC e Compliance (`kyc`)

11. Exposição e Perfil na Mídia (`media_profile_and_exposure`)

12. Dados Cadastrais Básicos (`quod_basic`)

Retorno dos Dados