API de Registro de Empresas: Extração Automatizada de KYB

Quando uma sessão de verificação de empresas começa, a Didit consulta registros oficiais de empresas para obter e validar as informações da empresa. Essa consulta automatizada é a base de todo o processo de verificação de empresas.

Consulta ao registro

A Didit se conecta aos registros de empresas dos países compatíveis para obter dados oficiais. No fluxo hospedado, o usuário seleciona o país de constituição e preenche o nome da empresa, o número de registro ou ambos. É obrigatório informar pelo menos um deles. Os números de registro são normalizados quando o registro exige (por exemplo, os números de empresas do Reino Unido são completados com zeros à esquerda até oito dígitos). Quando os dois identificadores são informados, a consulta ao registro combina os dois.

Preenchimento prévio da busca com `expected_details`

Se você já conhece a empresa, envie expected_details (company_name, registry_country, registration_number) ao criar a sessão. O fluxo hospedado pré-seleciona e bloqueia o país (e também o estado, no caso de registros estaduais como US-CA), preenche os campos de busca correspondentes e executa automaticamente a busca informada. Assim, o usuário chega diretamente ao resultado da empresa dele. Os dois campos continuam editáveis para que o usuário possa corrigir uma informação errada. Trata-se apenas de preenchimento prévio: selecionar uma empresa diferente da informada não gera aviso.

Tipos de busca

As buscas no registro aceitam dois modos:

Modo	Descrição
Exato	Corresponde exatamente ao nome da empresa ou ao número de registro
Contém	Corresponde às empresas cujo nome contém o termo buscado. Útil quando o nome jurídico exato não é conhecido

Fluxo de busca

A consulta ao registro segue um fluxo assíncrono:

Buscar

A Didit consulta o registro com o país selecionado e os identificadores informados: nome da empresa, número de registro ou os dois combinados. O campo searched_by da resposta indica como os resultados foram encontrados (name, registration_number ou registration_number_and_name), e a interface hospedada oferece, nos resultados por número de registro, a opção de um toque “Pesquisar como nome da empresa” para refazer a busca. A busca é executada de forma assíncrona.

Consultar resultados

Consulte periodicamente o status da busca até que os resultados estejam disponíveis. Registros grandes podem levar alguns segundos para retornar resultados.

Selecionar a empresa

Analise as empresas retornadas e selecione a correspondência correta. A Didit vincula a empresa selecionada à verificação KYB e preenche todos os dados disponíveis.

Confirmar e continuar

Confirme ou corrija os dados da empresa e continue para a próxima etapa configurada. Alguns registros retornam o perfil da empresa antes de o relatório de propriedade ficar pronto. Esse relatório continua sendo processado em segundo plano enquanto o solicitante conclui etapas independentes, como o envio de documentos. O preenchimento prévio a partir do registro não bloqueia o formulário de pessoas-chave: o solicitante pode inserir as pessoas manualmente, e as pessoas disponíveis no registro aparecem antes do envio, à medida que o relatório chega. Decisões personalizadas que dependem do relatório continuam aguardando o relatório, em vez de presumir o resultado. Suas correções são preservadas quando o relatório chega. Um relatório pendente não conta como verificação de registro concluída nem como aprovação automática, e o faturamento do registro usa o nível efetivamente entregue.

Envio manual

Se a empresa não for encontrada no registro, envie os dados da empresa manualmente. A sessão continua com os dados informados, e is_from_registry é definido como false.

Dados obtidos

Campo	Descrição
`company_name`	Nome jurídico registrado junto à autoridade
`registration_number`	Número oficial de registro ou de constituição da empresa
`country_code`	País de constituição (ISO 3166-1 alpha-3)
`company_type`	Tipo de pessoa jurídica (Ltd, LLC, PLC, SA, GmbH, SL etc.)
`registry_status`	Status atual da empresa no registro (`active`, `dissolved`, `struck_off` etc.)
`incorporation_date`	Data em que a empresa foi registrada originalmente
`registered_address`	Endereço oficial da sede registrada
`tax_number`	Número de identificação fiscal, quando disponível
`alternative_names`	Nomes comerciais, nomes fantasia (DBA), nomes jurídicos anteriores ou nomes no idioma original, como valor de texto
`legal_entity_identifier`	LEI, para instituições financeiras e entidades listadas em bolsa
`nature_of_business`	Descrição curta da atividade da empresa (no idioma do registro)
`registered_capital`	Capital autorizado / emitido, como um objeto `{amount, currency}`
`location_of_registration`	Cidade / subdivisão do registro oficial
`control_scheme`	Estrutura de controle / governança, quando o registro a disponibiliza
`website`, `email`, `phone`	Dados de contato constantes no registro
`addresses[]`	Outros endereços registrados ou comerciais
`industries[]`	Códigos de classificação setorial (SIC, NACE ou equivalentes locais)
`accounts`	Datas de arquivamento, quando informadas, incluindo `last_annual_return_date` e `last_agm_date`. Declarações anuais e assembleias são diferentes das demonstrações financeiras.
`financial_summary`	Resumo de dados financeiros, quando o registro os publica (receita, funcionários, status de arquivamento)
`confirmed_by_user_at`	Data e hora em que o usuário final confirmou ou editou os dados do registro
`last_console_edit_at`	Data e hora da última edição feita por um analista no console
`is_editable`	`true` enquanto os dados obtidos do registro ainda puderem ser editados pelo usuário final no fluxo hospedado
`is_from_registry`	`true` para empresas obtidas do registro, `false` para entrada manual
`fetch_status`	`pending`, `resolved` ou `failed`: estado da consulta ao registro
`verification_status`	`verified`, `failed` ou `unknown`

Status da empresa

Status	Descrição
Ativa	A empresa está ativa e em situação regular
Dissolvida	A empresa foi formalmente dissolvida
Baixada	Removida do registro (por exemplo, por descumprimento de obrigações)
Em liquidação	A empresa está em processo de liquidação
Inativa	Registrada, mas sem atividade comercial no momento

Empresas com status diferente de Ativa podem ser sinalizadas ou recusadas automaticamente, dependendo da configuração do seu fluxo de verificação.

Indicador de origem dos dados

Cada registro de empresa inclui um indicador is_from_registry:

true: os dados foram obtidos de um registro oficial de empresas
false: os dados foram enviados manualmente porque a empresa não foi encontrada no registro

O campo fetch_status indica se a consulta ao registro foi concluída, falhou ou ainda está em andamento.

Níveis de dados e preços

No fluxo hospedado, selecionar uma empresa gera a cobrança da consulta ao registro, mesmo que o solicitante saia antes de confirmar os dados ou concluir a verificação. Se o relatório estiver pronto no momento da seleção, o nível entregue é cobrado imediatamente. Se a propriedade ainda estiver pendente, o Lite é cobrado na seleção e apenas a diferença de preço é cobrada quando um nível superior for entregue. Se a propriedade não estiver disponível, nenhum adicional de propriedade se aplica. O total usa os preços cotados na seleção e nunca ultrapassa a cotação do nível solicitado. A seleção e qualquer ajuste posterior de propriedade contam como uma única consulta ao registro; ler o relatório adquirido ou confirmar seus dados não gera nova cobrança. Em contratos existentes com tarifa fixa, é contabilizada uma consulta ao registro na seleção, sem uma segunda unidade de contrato pela entrega posterior da propriedade. As buscas em fluxos hospedados não têm tarifa de busca separada. As buscas avulsas pela API podem gerar uma tarifa de $0.50 por requisição bem-sucedida; consulte faturamento de buscas. Consulte os preços de registro KYB para ver a tabela completa por país.

Nível	O que você recebe
Lite	Os campos acima: perfil da empresa, identificadores, status, endereço registrado, atividade e administradores
Acionistas	Lite mais os acionistas diretos (pessoas físicas e pessoas jurídicas) com suas faixas de participação
UBOs	Acionistas mais os beneficiários finais identificados ao longo da cadeia de propriedade

Um fluxo hospedado escolhe o nível por país em Workflows → KYB Registry Check → Countries. Quando o registro não tem nenhum dado de propriedade para uma empresa, uma requisição de Acionistas ou UBO é entregue e cobrada no nível mais alto que os registros do país podem fornecer, geralmente o Lite. Uma empresa que não é encontrada e é inserida manualmente (is_from_registry: false) é cobrada a uma tarifa fixa de $0.75: a busca foi realizada mesmo sem retornar nenhum registro.

Exemplo: resposta do nível Lite

O Lite retorna apenas o perfil da empresa, sem acionistas, UBOs nem estrutura de propriedade:

{
  "company_name": "ACME HOLDINGS PTY LTD",
  "registration_number": "094447122",
  "country_code": "AU",
  "registry_status": "active",
  "incorporation_date": "2000-09-12",
  "company_type": "Proprietary Limited",
  "registered_address": "Sydney, NSW, 2000",
  "tax_number": null,
  "vat_number": null,
  "website": null,
  "is_from_registry": true
}

O nível Acionistas adiciona ownership_structure e os dados dos acionistas, além de diretores/administradores. O nível UBOs também identifica os beneficiários finais com os percentuais de participação. Consulte Propriedade e Administradores e diretores.

Dados do registro vs dados fornecidos pelo usuário

A Didit mantém os dados retornados pelo registro e os dados confirmados pelo usuário como registros de auditoria separados, com uma visão canônica consolidada usada pelas verificações posteriores. Cada empresa contém três blocos relacionados:

Campo	Descrição
`registry_data`	O detalhamento normalizado do registro feito pela Didit: o resultado de propriedade (`ownership_error`, `section_errors`, `ubo_resolution`), as correções feitas com update-data e dados do registro que não têm campo próprio. Suas chaves variam conforme a empresa e não constituem um contrato estável.
`user_provided_data`	O que o usuário final confirmou ou editou durante a etapa de confirmação do registro no fluxo hospedado.
Campos canônicos de nível superior (`company_name`, `registration_number`, `country_code`, `incorporation_date` etc.)	A versão consolidada: dados confirmados pelo usuário quando existem, com os dados do registro como alternativa. Os recursos posteriores (verificação cruzada por OCR de documentos, Análise AML, avaliação de risco) são executados sobre a visão canônica.

O timestamp confirmed_by_user_at indica quando o usuário final confirmou ou editou os dados do registro. Enquanto esse timestamp for nulo e is_editable for true, o usuário final pode continuar modificando os campos no fluxo hospedado. Para empresas inseridas manualmente (is_from_registry: false), user_provided_data é a única fonte e is_editable passa a ser false depois que o usuário envia os dados. Os analistas podem ver as duas fontes lado a lado na revisão de sessões do Business Console e comparar o que o registro informou com o que o usuário confirmou.

Campos configuráveis do formulário de registro

Você controla quais campos de dados da empresa o fluxo de verificação hospedado solicita durante a etapa de confirmação do registro. Configure-os no Business Console: abra o editor de fluxos, selecione o nó KYB Registry check e mude para a aba Campos. Cada campo tem um dos três estados:

Estado	Comportamento
Oculto	O campo não é exibido no fluxo hospedado e não é coletado.
Opcional	O campo é exibido, e o usuário pode deixá-lo vazio.
Obrigatório	O campo é exibido e deve ser preenchido antes que o usuário possa enviar.

Três campos são sempre exibidos e sempre obrigatórios, pois identificam a empresa e não podem ser configurados: company_name, country_code e region (estado/região, quando o registro é regional). Os 16 campos configuráveis: registration_number, incorporation_date, legal_address, vat_number, alternative_names, tax_number, company_type, legal_entity_identifier, location_of_registration, nature_of_business, registered_capital_amount, registered_capital_currency, website, email, phone, control_scheme Por padrão, e em todos os fluxos existentes, apenas incorporation_date é Obrigatório. Todos os outros campos configuráveis estão marcados como Opcional, de modo que o formulário se comporta exatamente como antes de esta configuração existir. A obrigatoriedade é aplicada no servidor: enviar o formulário de registro com um campo obrigatório vazio retorna 400 com mensagens de erro por campo, e a interface hospedada exibe apenas os campos habilitados. Na API de fluxos, a configuração é o objeto kyb_registry_fields_config no nó KYB Registry. Consulte as configurações de recursos para ver o formato.

vat_number marcado como Obrigatório só é exigido para empresas constituídas em um país do regime de IVA da UE (veja abaixo). Para todos os outros países, o campo é tratado como opcional mesmo quando marcado como obrigatório, já que não há número de IVA da UE a coletar. O tax_number dessas empresas continua sendo validado quando informado.

Validação de VAT e de identificação fiscal

Quando a etapa de registro é enviada, a Didit valida o vat_number da empresa na fonte oficial do país dela. Se a empresa não tiver vat_number, o tax_number é validado no lugar dele. O número pode ser enviado com ou sem o prefixo do país e com qualquer separador (DE 123 456 789, DE123456789 e 123456789 são equivalentes para uma empresa alemã). Registros oficiais. Nestes países, o número é verificado em tempo real no registro governamental ou no registro oficial de empresas, que também retorna a razão social registrada (e, na maioria dos casos, o endereço):

País	Fonte
27 Estados-membros da UE e Irlanda do Norte (`XI`)	VIES da Comissão Europeia
Polônia	VIES e, em seguida, o registro de contribuintes de VAT do Ministério das Finanças (a “Lista Branca”) para uma empresa que o VIES não lista
Noruega	Centro de Registros de Brønnøysund (Registro Central de Coordenação de Pessoas Jurídicas)
Suíça	Registro UID do Escritório Federal de Estatística
Brasil	Cadastro CNPJ da Receita Federal
Colômbia	RUES, o Registro Único Empresarial e Social das câmaras de comércio
Costa Rica	Cadastro de contribuintes do Ministério da Fazenda (Hacienda)
Equador	Cadastro de contribuintes do Serviço de Rendas Internas (SRI)
Paraguai	Registro RUC da Direção Nacional de Tributação (DNIT)

Um SIREN ou SIRET francês, um RSIN holandês ou um número fiscal húngaro completo, enviado como número de VAT, é convertido no número de VAT correspondente antes da verificação. Números de VAT gregos são verificados automaticamente com o prefixo EL. Regras de dígito verificador. Nestes países não é possível consultar nenhum registro, então o número é verificado com base no formato oficial e nas regras de dígito verificador do país: Albânia, Andorra, Argentina, Austrália, Azerbaijão, Bielorrússia, Canadá, Chile, China, República Dominicana, Egito, El Salvador, Gana, Guatemala, Islândia, Índia, Indonésia, Israel, Japão, Quênia, Liechtenstein, México, Moldávia, Mônaco, Montenegro, Marrocos, Moçambique, Nova Zelândia, Macedônia do Norte, Peru, Rússia, San Marino, Sérvia, Singapura, África do Sul, Coreia do Sul, Taiwan, Tailândia, Tunísia, Turquia, Ucrânia, Reino Unido, Estados Unidos, Uruguai, Venezuela e Vietnã. Essas regras também se aplicam na UE quando um tax_number é uma identificação fiscal nacional sem número de VAT a verificar, como a Steuernummer alemã. Um tax_number declara apenas um identificador fiscal, não um registro de VAT, por isso, quando o VIES não o lista, o resultado recorre a essas regras em vez de invalid. Empresas de qualquer outro país recebem vat_validation_status: "not_applicable". O mesmo vale para sessões de sandbox, que nunca consultam um registro fiscal. O resultado é armazenado na empresa e exposto no payload de decisão de KYB:

Campo	Descrição
`vat_number`	O número de VAT como foi enviado
`vat_validation_status`	`valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` ou `not_applicable`
`vat_validated_number`	O número que foi verificado, conforme consta na fonte (por exemplo, o número de VAT derivado de um SIREN)
`vat_validation_source`	A fonte que determinou o status (veja abaixo)
`vat_validated_name`	Razão social registrada na fonte, quando ela a divulga
`vat_validated_address`	Endereço registrado na fonte, quando ela o divulga
`vat_checked_at`	Data e hora da verificação

Status	Significado
`valid`	O registro oficial confirmou que o número está registrado e ativo
`invalid`	O registro oficial não tem registro ativo para o número. Na UE, o VIES lista apenas empresas registradas para comércio intra-UE
`format_valid`	O número atende ao formato e às regras de dígito verificador do país; nenhum registro foi consultado
`invalid_format`	O número não atende ao formato ou às regras de dígito verificador do país
`could_not_validate`	O registro estava indisponível, então não foi possível verificar o número. Ele é verificado novamente na próxima vez que a verificação de registro for executada
`not_applicable`	Nenhum número de VAT ou identificação fiscal foi informado, o país não tem registro nem regras, ou a sessão é uma sessão de sandbox

vat_validation_source é um destes valores: eu_vies, pl_vat_white_list, no_brreg, ch_uid_register, br_receita_federal, co_rues, cr_hacienda, ec_sri, py_dnit ou format_rules. Quando um número tem o status valid, invalid, format_valid ou invalid_format, o resultado é mantido durante o restante da sessão e o registro não é consultado novamente, a menos que o número mude. Verificação cruzada da razão social. Quando o número é valid e a fonte divulga a razão social registrada, a Didit faz uma comparação aproximada (fuzzy) com o nome da empresa enviado. Uma divergência significativa gera o aviso KYB_COMPANY_VAT_NAME_MISMATCH sem alterar o status da sessão - é um sinal leve para os revisores. O additional_data dele traz registry_name, registry_source e submitted_name, além de vies_name quando a fonte é o VIES. Alguns Estados-membros da UE não divulgam a razão social nem o endereço; os campos retornam vazios e nenhuma comparação é feita. Ações configuráveis. Duas configurações no nó de verificação de registro de KYB controlam o efeito de uma verificação sem sucesso na sessão (valores REVIEW, DECLINE, NO_ACTION):

Configuração	É acionada quando	Padrão
`kyb_vat_invalid_action`	`vat_validation_status` é `invalid`, ou um `vat_number` é `invalid_format`	`REVIEW` - a sessão vai para Em revisão
`kyb_vat_unverified_action`	`vat_validation_status` é `could_not_validate`	`NO_ACTION` - nenhum efeito na sessão

Um tax_number que seja invalid_format é informado no payload sem acionar nenhuma ação, porque o campo fiscal de texto livre muitas vezes contém outro identificador da empresa. Cada resultado também gera o aviso correspondente (KYB_COMPANY_VAT_INVALID, KYB_COMPANY_VAT_COULD_NOT_VALIDATE) na verificação de registro - veja avisos de Verificação de empresas.

Cruzamento de dados

A Didit compara automaticamente os dados fornecidos pelo usuário / canônicos com os dados retornados pelo registro de empresas e com os dados de OCR extraídos dos documentos enviados:

Nome da empresa: correspondência aproximada (fuzzy matching) para considerar abreviações e diferenças de formatação
Número de registro: validação por correspondência exata
País: verificação de consistência entre o país informado e o país do registro de empresas
Endereço: geocodificação e normalização para a comparação

Qualquer inconsistência é sinalizada como aviso na sessão e fica visível para os analistas no console.

Resumo financeiro

Quando disponíveis, a Didit obtém do registro de empresas dados financeiros resumidos:

Receita ou faturamento
Número de funcionários
Códigos de setor SIC/NACE
Datas de apresentação e situação de conformidade

Campos adicionais do registro

Dependendo da cobertura da jurisdição, a resposta do registro também pode incluir:

alternative_names: nomes comerciais, nomes fantasia (DBA), denominações legais anteriores
legal_entity_identifier (LEI): para instituições financeiras e entidades listadas
website, email, phone: informações de contato constantes no registro
nature_of_business: descrição curta (no idioma do registro)
registered_capital: capital autorizado / emitido, como um objeto {amount, currency}

Todos os campos ficam no bloco business da decisão de KYB.

Confiança e status de verificação

Cada resposta do registro traz um verification_status:

Valor	Significado
`VERIFIED`	O registro retornou uma correspondência e os dados foram obtidos.
`FAILED`	O registro retornou uma correspondência, mas a obtenção dos dados falhou (por exemplo, resposta parcial).
`UNKNOWN`	A empresa não foi localizada em nenhum registro.

Combine-o com is_from_registry para orientar sua própria lógica nas etapas seguintes:

`is_from_registry`	`verification_status`	Significado
true	VERIFIED	Totalmente verificado no registro oficial
true	FAILED	Parcial: alguns campos podem estar desatualizados ou ausentes
false	UNKNOWN	Apenas dados fornecidos pelo usuário; nenhuma correspondência no registro

Resultados do cruzamento de dados

Cada cruzamento é executado por campo e retorna um destes valores:

MATCH: os dados fornecidos coincidem com o registro.
MISMATCH: divergência significativa. Sinalizada como aviso.
NO_DATA: um dos lados estava vazio; não é possível comparar.

As divergências ficam visíveis por campo na revisão da sessão no console.

O que determina o resultado

A situação da empresa, o país de constituição, os resultados de AML e a correspondência com os dados declarados alimentam a decisão como tags de aviso na verificação do registro de empresas e na Análise AML. Seu fluxo de verificação (workflow) decide se cada aviso leva à aprovação, à revisão ou à recusa. Consulte a avaliação de risco para ver os sinais e as chaves do fluxo que os controlam.

Países suportados

A cobertura varia por país: consulte os países suportados para ver o detalhamento dos níveis por região.

Próximos passos

Propriedade

Identificação de UBO e cadeias de propriedade.

Esquema de resposta

Onde cada campo aparece no payload.

Países suportados

Cobertura por região.

Primeiros passos

Recursos

Perfis de empresas

Referência

Console

API de Registro de Empresas: Extração Automatizada de KYB

Consulta ao registro

Preenchimento prévio da busca com `expected_details`

Tipos de busca

Fluxo de busca

Dados obtidos

Status da empresa

Indicador de origem dos dados

Níveis de dados e preços

Dados do registro vs dados fornecidos pelo usuário

Campos configuráveis do formulário de registro

Validação de VAT e de identificação fiscal

Cruzamento de dados

Resumo financeiro

Campos adicionais do registro

Confiança e status de verificação

Resultados do cruzamento de dados

O que determina o resultado

Países suportados

Próximos passos

Propriedade

Esquema de resposta

Países suportados

​Consulta ao registro

​Preenchimento prévio da busca com expected_details

​Tipos de busca

​Fluxo de busca

​Dados obtidos

​Status da empresa

​Indicador de origem dos dados

​Níveis de dados e preços

​Dados do registro vs dados fornecidos pelo usuário

​Campos configuráveis do formulário de registro

​Validação de VAT e de identificação fiscal

​Cruzamento de dados

​Resumo financeiro

​Campos adicionais do registro

​Confiança e status de verificação

​Resultados do cruzamento de dados

​O que determina o resultado

​Países suportados

​Próximos passos

Propriedade

Esquema de resposta

Países suportados

Consulta ao registro

Preenchimento prévio da busca com `expected_details`

Tipos de busca

Fluxo de busca

Dados obtidos

Status da empresa

Indicador de origem dos dados

Níveis de dados e preços

Dados do registro vs dados fornecidos pelo usuário

Campos configuráveis do formulário de registro

Validação de VAT e de identificação fiscal

Cruzamento de dados

Resumo financeiro

Campos adicionais do registro

Confiança e status de verificação

Resultados do cruzamento de dados

O que determina o resultado

Países suportados

Próximos passos