> ## 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 registo de empresas: extração automática para KYB

> Consulte registos, valide o estado e extraia dados de empresas em 220+ países com a Didit. Desde $2.00 por verificação, sem contratos.

Quando uma sessão de verificação de empresas começa, são consultados os registos oficiais de empresas para obter e validar as informações da empresa. Esta consulta automatizada constitui a base de todo o processo de verificação de empresas.

## Pesquisa no registo

A Didit liga-se a registos de empresas dos países suportados para obter dados oficiais. No fluxo alojado, o utilizador seleciona o país de constituição e preenche o nome da empresa, o número de registo ou ambos, sendo obrigatório pelo menos um. Os números de registo são normalizados quando os registos o exigem (por exemplo, os números de empresas do Reino Unido são completados com zeros à esquerda até oito dígitos), e quando são fornecidos os dois identificadores, a pesquisa no registo combina-os.

### Pré-preenchimento da pesquisa com `expected_details`

Se já conhece a empresa, passe `expected_details` (`company_name`, `registry_country`, `registration_number`) ao [criar a sessão](https://docs.didit.me/pt/sessions-api/create-session.md). O fluxo alojado pré-seleciona e bloqueia o país (e o estado, para registos ao nível estadual como `US-CA`), pré-preenche os campos de pesquisa correspondentes e executa automaticamente a pesquisa com os dados indicados, de modo que o utilizador chega diretamente ao resultado da sua empresa. Ambos os campos continuam editáveis para que o utilizador possa corrigir uma indicação errada. É apenas um pré-preenchimento: selecionar uma empresa diferente da indicada não gera qualquer aviso.

### Tipos de pesquisa

As pesquisas no registo suportam dois modos:

| Modo | Descrição |
| - | - |
| **Exato** | Corresponde com precisão ao nome da empresa ou ao número de registo |
| **Contém** | Corresponde a empresas cujo nome contém o termo pesquisado, útil quando o nome jurídico exato é desconhecido |

### Fluxo de pesquisa

A pesquisa no registo segue um fluxo assíncrono:

**1. Pesquisa**

A Didit consulta o registo com o país selecionado e os identificadores fornecidos: nome da empresa, número de registo ou ambos combinados. O campo `searched_by` da resposta indica como os resultados foram correspondidos (`name`, `registration_number` ou `registration_number_and_name`), e a interface alojada oferece, com um toque, a opção «Pesquisar como nome da empresa», nos resultados obtidos por número de registo. A pesquisa é executada de forma assíncrona.

**2. Consultar resultados**

Consulte o estado da pesquisa até os resultados estarem resolvidos. Registos de grande dimensão podem demorar alguns segundos a devolver resultados.

**3. Selecionar empresa**

Reveja as empresas devolvidas e selecione a correspondência correta. A Didit associa 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 o passo configurado seguinte.
Alguns registos devolvem o perfil da empresa antes de o relatório de propriedade estar pronto; esse relatório continua em segundo plano enquanto o requerente completa passos independentes, como o envio de documentos.
O pré-preenchimento pelo registo não bloqueia o formulário de Pessoas-chave: o requerente pode introduzir pessoas manualmente, e as pessoas disponíveis no registo aparecem antes da submissão à medida que o relatório chega.
As decisões configuradas que dependem do relatório continuam a aguardar pelo relatório, em vez de adivinhar o seu resultado.
As suas correções são preservadas quando o relatório chega.
Um relatório pendente não conta como verificação de registo concluída nem como aprovação automática, e a faturação do registo usa o nível efetivamente entregue.

**5. Submissão manual**

Se a empresa não for encontrada no registo, submeta os dados da empresa manualmente. A sessão continua com os dados fornecidos, e `is_from_registry` fica definido como `false`.

### Dados obtidos

| Campo | Descrição |
| - | - |
| `company_name` | Nome jurídico tal como registado junto da autoridade |
| `registration_number` | Número oficial de registo ou de constituição da empresa |
| `country_code` | País de constituição (ISO 3166-1 alpha-3) |
| `company_type` | Tipo de entidade jurídica (Ltd, LLC, PLC, SA, GmbH, SL, etc.) |
| `registry_status` | Estado atual da empresa no registo (`active`, `dissolved`, `struck_off`, etc.) |
| `incorporation_date` | Data em que a empresa foi inicialmente registada |
| `registered_address` | Morada oficial da sede registada |
| `tax_number` | Número de identificação fiscal, quando disponível |
| `alternative_names` | Nomes comerciais, dbas, nomes jurídicos anteriores ou nomes na língua original, como valor de texto |
| `legal_entity_identifier` | LEI, para instituições financeiras e entidades cotadas |
| `nature_of_business` | Breve descrição da atividade (na língua do registo) |
| `registered_capital` | Capital autorizado / emitido, como objeto `{amount, currency}` |
| `location_of_registration` | Cidade / subdivisão do registo onde a empresa está inscrita |
| `control_scheme` | Esquema de controlo / governação, quando o registo o disponibiliza |
| `website`, `email`, `phone` | Dados de contacto constantes do registo |
| `addresses[]` | Moradas registadas ou comerciais adicionais |
| `industries[]` | Códigos de classificação setorial (SIC, NACE ou equivalentes locais) |
| `accounts` | Datas de apresentação quando reportadas, incluindo `last_annual_return_date` e `last_agm_date`. As declarações anuais e as assembleias são distintas das contas financeiras. |
| `financial_summary` | Dados financeiros resumidos quando o registo os publica (volume de negócios, número de funcionários, estado das apresentações) |
| `confirmed_by_user_at` | Data e hora em que o utilizador final confirmou ou editou os dados do registo |
| `last_console_edit_at` | Data e hora da última edição feita por um analista na consola |
| `is_editable` | `true` enquanto os dados de origem do registo ainda puderem ser editados pelo utilizador final no fluxo alojado |
| `is_from_registry` | `true` para empresas obtidas do registo, `false` para introdução manual |
| `fetch_status` | `pending`, `resolved` ou `failed`: estado da pesquisa no registo |
| `verification_status` | `verified`, `failed` ou `unknown` |

### Estados da empresa

| Estado | Descrição |
| - | - |
| **Ativa** | A empresa está atualmente ativa e em situação regular |
| **Dissolvida** | A empresa foi formalmente dissolvida |
| **Removida do registo** | Removida do registo (por exemplo, por incumprimento) |
| **Em liquidação** | A empresa está em processo de liquidação |
| **Inativa** | Registada, mas sem atividade comercial atual |

> [!WARNING]
>
> As empresas com um estado diferente de **Ativa** podem ser automaticamente sinalizadas ou recusadas, consoante a configuração do seu fluxo.

### Indicador de origem dos dados

Cada registo de empresa inclui uma flag `is_from_registry`:

* **`true`**: os dados foram obtidos de um registo oficial de empresas
* **`false`**: os dados foram introduzidos manualmente porque a empresa não foi encontrada no registo

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

## Níveis de dados e preços

No fluxo alojado, a seleção de uma empresa implica o custo da consulta ao registo, mesmo que o candidato saia antes de confirmar os dados ou de concluir a verificação.
Se o relatório estiver pronto no momento da seleção, o nível entregue é cobrado de imediato.
Se a propriedade ainda estiver pendente, o Lite é cobrado na seleção e só a diferença de preço é cobrada quando um nível superior for entregue.
Se a propriedade não estiver disponível, não se aplica qualquer sobretaxa de propriedade.
O total usa os preços cotados na seleção e nunca excede a cotação do nível pedido.
A seleção e qualquer ajuste posterior de propriedade contam como uma única consulta ao registo; a leitura do relatório adquirido ou a confirmação dos seus dados não volta a cobrar essa consulta.
Os contratos de tarifa fixa existentes contabilizam uma consulta ao registo na seleção, sem uma segunda unidade contratual para a entrega posterior da propriedade.
As pesquisas em fluxos alojados não têm taxa de pesquisa separada.
As pesquisas feitas diretamente pela API podem implicar uma taxa de \$0.50 por pedido bem-sucedido; consulte [faturação de pesquisas](https://docs.didit.me/pt/standalone-apis/kyb-registry-search.md). Consulte [preços do registo KYB](https://docs.didit.me/pt/getting-started/kyb-registry-pricing.md) para a tabela completa por país.

| Nível | O que obtém |
| - | - |
| **Lite** | Os campos acima: perfil da empresa, identificadores, estado, morada registada, atividade e administradores |
| **Shareholders** | Lite mais os acionistas diretos (pessoas singulares e entidades coletivas) com as respetivas faixas de propriedade |
| **UBOs** | Shareholders mais os beneficiários efetivos finais, identificados através da cadeia de propriedade |

Um fluxo alojado escolhe o nível por país em *Workflows → KYB Registry Check → Countries*. Quando o registo não tem nenhum registo de propriedade para uma empresa, um pedido de Shareholders ou UBOs é entregue e cobrado ao nível mais alto que os registos do país conseguem fornecer, normalmente Lite.

Uma empresa não encontrada e introduzida manualmente (`is_from_registry: false`) é cobrada um valor fixo de **\$0.75**: a pesquisa foi executada, mesmo que não tenha sido devolvido nenhum registo.

> [accordion] Exemplo: resposta do nível Lite
>
> O Lite devolve 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 Shareholders acrescenta `ownership_structure` e as entradas de acionistas, bem como os administradores e diretores. O nível UBOs resolve ainda os beneficiários efetivos com as respetivas percentagens de propriedade. Consulte [Propriedade](https://docs.didit.me/pt/business-verification/ownership.md) e [Administradores e diretores](https://docs.didit.me/pt/business-verification/officers.md).

## Dados do registo vs dados fornecidos pelo utilizador

A Didit mantém os dados devolvidos pelo registo e os dados confirmados pelo utilizador como **registos de auditoria separados**, com uma vista canónica unificada usada pelas verificações posteriores. Cada empresa tem três blocos relacionados:

| Campo | Descrição |
| - | - |
| `registry_data` | Dados do registo normalizados pela Didit: o resultado relativo à propriedade (`ownership_error`, `section_errors`, `ubo_resolution`), as correções feitas com [update-data](https://docs.didit.me/pt/sessions-api/update-data.md) e os factos do registo que não têm campo próprio. As suas chaves variam consoante a empresa e não são um contrato estável. |
| `user_provided_data` | O que o utilizador final confirmou ou editou na etapa de confirmação do registo no fluxo alojado. |
| Campos canónicos de nível superior (`company_name`, `registration_number`, `country_code`, `incorporation_date`, etc.) | A versão unificada: os dados confirmados pelo utilizador quando existem, com os dados do registo como alternativa. As funcionalidades posteriores (verificação cruzada com OCR de documentos, análise AML, avaliação de risco) são executadas sobre a vista canónica. |

O carimbo temporal `confirmed_by_user_at` marca o momento em que o utilizador final confirmou ou editou os dados do registo. Enquanto esse carimbo estiver nulo e `is_editable` for `true`, o utilizador final pode continuar a alterar os campos dentro do fluxo alojado.

Para as empresas introduzidas manualmente (`is_from_registry: false`), `user_provided_data` é a única fonte e `is_editable` passa a `false` depois de o utilizador submeter os dados.

Os analistas podem ver as duas fontes lado a lado na revisão da sessão na [Business Console](https://docs.didit.me/pt/business-verification/console.md) e comparar o que o registo indicou com o que o utilizador confirmou.

## Campos configuráveis do formulário de registo

Controla quais os campos de dados da empresa que o fluxo de verificação alojado pede durante o passo de confirmação do registo. Configure-os no Business Console: abra o editor de fluxos, selecione o nó **KYB Registry check** e mude para o separador **Campos**.

Cada campo tem um dos três estados:

| Estado | Comportamento |
| - | - |
| **Oculto** | O campo não é apresentado no fluxo alojado e não é recolhido. |
| **Opcional** | O campo é apresentado; o utilizador pode deixá-lo vazio. |
| **Obrigatório** | O campo é apresentado e tem de ser preenchido antes de o utilizador poder submeter. |

Três campos são sempre apresentados e são sempre obrigatórios, porque identificam a empresa e não podem ser configurados: `company_name`, `country_code` e `region` (estado/região, quando o registo é 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 predefinição, e para todos os fluxos existentes, apenas `incorporation_date` é **Obrigatório**; todos os outros campos configuráveis são **Opcionais**, pelo que o formulário se comporta exatamente como se comportava antes desta definição existir.

A obrigatoriedade é aplicada no servidor: se o formulário de registo for submetido com um campo obrigatório vazio, a resposta é `400` com mensagens de erro por campo, e a interface alojada apresenta apenas os campos ativados. Na API de fluxos, a definição é o objeto `kyb_registry_fields_config` no nó KYB Registry; consulte [configurações de funcionalidades](https://docs.didit.me/pt/management-api/workflows/feature-configs.md#registo-de-empresas-kyb) para a estrutura.

> [!NOTE]
>
> O `vat_number` marcado como **Obrigatório** só é exigido para empresas constituídas num país da UE com IVA (ver abaixo). Para todos os outros países, o campo é tratado como opcional, mesmo quando está marcado como obrigatório, porque não há número de IVA da UE a recolher. O `tax_number` continua a ser validado quando for fornecido.

## Validação de IVA e número de identificação fiscal

Quando o passo do registo é submetido, a Didit valida o `vat_number` da empresa na fonte oficial do respetivo país.
Uma empresa sem `vat_number` tem o `tax_number` validado em vez disso.
O número pode ser submetido com ou sem o prefixo do país e com quaisquer separadores (`DE 123 456 789`, `DE123456789` e `123456789` são equivalentes para uma empresa alemã).

**Registos oficiais.** Nestes países, o número é verificado em tempo real no registo governamental ou oficial de empresas, que também devolve o nome registado (e, na maioria dos casos, a morada):

| 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, para uma empresa que o VIES não listar, o registo de contribuintes de IVA do Ministério das Finanças (a «Lista Branca») |
| Noruega | Brønnøysund Register Centre (Central Coordinating Register for Legal Entities) |
| Suíça | Registo UID do Serviço Federal de Estatística |
| Brasil | Registo CNPJ da Receita Federal |
| Colômbia | RUES, o Registo Empresarial e Social Unificado das câmaras de comércio |
| Costa Rica | Registo de contribuintes do Ministério das Finanças (Hacienda) |
| Equador | Registo de contribuintes do Serviço de Impostos Internos (SRI) |
| Paraguai | Registo RUC da Direção Nacional de Impostos (DNIT) |

Um SIREN ou SIRET francês, um RSIN neerlandês ou um número fiscal húngaro completo, submetido como número de IVA, é convertido no número de IVA correspondente antes de ser verificado.
Os números de IVA gregos são verificados automaticamente com o prefixo `EL`.

**Regras de dígito de controlo.** Nestes países não é possível consultar nenhum registo, pelo que o número é verificado segundo o formato oficial e as regras de dígito de controlo 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, Listenstaine, México, Moldávia, Mónaco, Montenegro, Marrocos, Moçambique, Nova Zelândia, Macedónia do Norte, Peru, Rússia, São Marinho, Sérvia, Singapura, África do Sul, Coreia do Sul, Taiwan, Tailândia, Tunísia, Türkiye, Ucrânia, Reino Unido, Estados Unidos, Uruguai, Venezuela e Vietname.
Estas regras aplicam-se também na UE quando um `tax_number` é um número de identificação fiscal nacional sem número de IVA a verificar, como um Steuernummer alemão.
Um `tax_number` identifica apenas um número fiscal, não um registo de IVA. Assim, quando o VIES não o listar, o resultado recorre a estas regras em vez de `invalid`.

As empresas de qualquer outro país recebem `vat_validation_status: "not_applicable"`.
O mesmo acontece com as sessões de sandbox, que nunca contactam um registo fiscal.

O resultado fica guardado na empresa e é exposto no [payload de decisão KYB](https://docs.didit.me/pt/business-verification/response-schema.md#bloco-company):

| Campo | Descrição |
| - | - |
| `vat_number` | O número de IVA tal como foi submetido |
| `vat_validation_status` | `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` ou `not_applicable` |
| `vat_validated_number` | O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN) |
| `vat_validation_source` | A fonte que determinou o estado (ver abaixo) |
| `vat_validated_name` | Nome registado na fonte, quando esta o divulga |
| `vat_validated_address` | Morada registada na fonte, quando esta a divulga |
| `vat_checked_at` | Data e hora da verificação |

| Estado | Significado |
| - | - |
| `valid` | O registo oficial confirmou que o número está registado e ativo |
| `invalid` | O registo oficial não tem nenhum registo ativo para o número. Na UE, o VIES lista apenas as empresas registadas para o comércio intracomunitário |
| `format_valid` | O número cumpre o formato e as regras de dígito de controlo do país; nenhum registo foi consultado |
| `invalid_format` | O número não cumpre o formato ou as regras de dígito de controlo do país |
| `could_not_validate` | O registo estava indisponível, pelo que o número não pôde ser verificado. Será verificado de novo na próxima vez que a verificação do registo for executada |
| `not_applicable` | Não foi fornecido nenhum número de IVA ou identificação fiscal, o país não tem registo nem regras, ou a sessão é uma sessão de sandbox |

`vat_validation_source` é um dos seguintes 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 está `valid`, `invalid`, `format_valid` ou `invalid_format`, o resultado é mantido durante o resto da sessão e o registo não é consultado novamente, a menos que o número mude.

**Validação cruzada do nome.** Quando o número está `valid` e a fonte divulga o nome registado, a Didit compara-o de forma aproximada com o nome da empresa submetido.
Uma divergência significativa gera o aviso `KYB_COMPANY_VAT_NAME_MISMATCH` sem alterar o estado da sessão: trata-se de um sinal indicativo para os revisores.
O respetivo `additional_data` inclui `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 o nome nem a morada. Nesses casos, os campos vêm vazios e não é feita nenhuma comparação.

**Ações configuráveis.** Duas definições do nó de verificação do registo KYB controlam o que uma verificação sem êxito faz à sessão (valores `REVIEW`, `DECLINE`, `NO_ACTION`):

| Definição | É acionada quando | Predefinição |
| - | - | - |
| `kyb_vat_invalid_action` | `vat_validation_status` é `invalid`, ou um `vat_number` é `invalid_format` | `REVIEW`: a sessão passa para Em análise |
| `kyb_vat_unverified_action` | `vat_validation_status` é `could_not_validate` | `NO_ACTION`: sem efeito na sessão |

Um `tax_number` com `invalid_format` é reportado 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 do registo. Consulte [avisos de verificação de empresas](https://docs.didit.me/pt/business-verification/warnings.md#avisos-do-registo-kyb).

## Cruzamento de dados

A Didit compara automaticamente os dados fornecidos pelo utilizador ou canónicos com os devolvidos pelo registo e com os dados OCR extraídos dos documentos carregados:

* **Nome da empresa**: correspondência aproximada, para ter em conta abreviaturas e diferenças de formatação
* **Número de registo**: validação de correspondência exata
* **País**: verificação de consistência entre o país fornecido e o país do registo
* **Morada**: geocodificação e normalização para comparação

Quaisquer inconsistências são assinaladas como avisos na sessão e ficam visíveis para os analistas na consola.

## Resumo financeiro

Quando disponível, a Didit obtém do registo dados financeiros resumidos:

* Receita ou volume de negócios
* Número de colaboradores
* Códigos de atividade SIC/NACE
* Datas de entrega de documentos e estado de conformidade

## Campos adicionais do registo

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

* `alternative_names`: nomes comerciais, dbas, antigas denominações jurídicas
* `legal_entity_identifier` (LEI): para instituições financeiras e entidades cotadas
* `website`, `email`, `phone`: dados de contacto constantes do registo
* `nature_of_business`: breve descrição (no idioma do registo)
* `registered_capital`: capital autorizado ou emitido, como objeto `{amount, currency}`

Todos os campos ficam no bloco [`business`](https://docs.didit.me/pt/business-verification/response-schema) da decisão KYB.

## Confiança e estado de verificação

Cada resposta do registo inclui um `verification_status`:

| Valor | Significado |
| - | - |
| `VERIFIED` | O registo devolveu uma correspondência e os dados foram obtidos. |
| `FAILED` | O registo devolveu uma correspondência, mas a obtenção dos dados falhou (por exemplo, resposta parcial). |
| `UNKNOWN` | Não foi possível localizar a empresa em nenhum registo. |

Combine com `is_from_registry` para orientar a sua própria lógica a jusante:

| `is_from_registry` | `verification_status` | Significado |
| - | - | - |
| true | VERIFIED | Totalmente verificada face ao registo oficial |
| true | FAILED | Parcial: alguns campos podem estar desatualizados ou em falta |
| false | UNKNOWN | Apenas dados fornecidos pelo utilizador; sem correspondência no registo |

## Resultados do cruzamento de dados

Cada cruzamento é executado campo a campo e devolve um dos seguintes valores:

* `MATCH`: os dados fornecidos coincidem com o registo.
* `MISMATCH`: divergência significativa. Assinalada como aviso.
* `NO_DATA`: um dos lados estava vazio; não é possível fazer a comparação.

As divergências são visíveis campo a campo na revisão da sessão na consola.

## O que determina o resultado

O estado da empresa, o país de constituição, os resultados AML e a correspondência com os dados declarados alimentam a decisão como etiquetas de aviso na verificação do registo e na triagem AML. O seu fluxo decide se cada aviso conduz à aprovação, à revisão ou à recusa. Consulte a [avaliação de risco](https://docs.didit.me/pt/business-verification/risk-assessment.md) para ver os sinais e as chaves do fluxo que os controlam.

## Países suportados

A cobertura varia consoante o país: consulte [países suportados](https://docs.didit.me/pt/business-verification/supported-countries.md) para ver a distribuição de níveis por região.

## Próximos passos

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

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

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


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