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

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

> A Didit consulta registros de empresas, valida status e extrai dados em 220+ países. Desde $2.00 por consulta, conforme país e nível, sem contratos.

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](https://docs.didit.me/pt-br/sessions-api/create-session.md). 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:

**1. 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.

**2. Consultar resultados**

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

**3. 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.

**4. 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.

**5. 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 |

> [!WARNING]
>
> 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](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-search.md). Consulte os [preços de registro KYB](https://docs.didit.me/pt-br/getting-started/kyb-registry-pricing.md) 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.

> [accordion] Exemplo: resposta do nível Lite
>
> O Lite retorna apenas o perfil da empresa, sem acionistas, UBOs nem estrutura de propriedade:
>
> ```json theme={null}
> {
>   "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](https://docs.didit.me/pt-br/business-verification/ownership.md) e [Administradores e diretores](https://docs.didit.me/pt-br/business-verification/officers.md).

## 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](https://docs.didit.me/pt-br/sessions-api/update-data.md) 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](https://docs.didit.me/pt-br/business-verification/console.md) 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](https://docs.didit.me/pt-br/management-api/workflows/feature-configs.md#registro-kyb) para ver o formato.

> [!NOTE]
>
> `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](https://ec.europa.eu/taxation_customs/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](https://docs.didit.me/pt-br/business-verification/response-schema.md#bloco-company):

| 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](https://docs.didit.me/pt-br/business-verification/warnings.md#avisos-do-registro-kyb).

## 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`](https://docs.didit.me/pt-br/business-verification/response-schema) 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](https://docs.didit.me/pt-br/business-verification/risk-assessment.md) 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](https://docs.didit.me/pt-br/business-verification/supported-countries.md) para ver o detalhamento dos níveis por região.

## Próximos passos

> [card] [Propriedade](https://docs.didit.me/pt-br/business-verification/ownership.md)
>
> Identificação de UBO e cadeias de propriedade.

> [card] [Esquema de resposta](https://docs.didit.me/pt-br/business-verification/response-schema.md)
>
> Onde cada campo aparece no payload.

> [card] [Países suportados](https://docs.didit.me/pt-br/business-verification/supported-countries.md)
>
> Cobertura por região.


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