> ## 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 KYB: Pesquisa e Seleção de Empresas > Pesquise registos de empresas na Didit e obtenha o nível necessário: Lite (seleção), acionistas ou beneficiários efetivos, por país. ## Endpoints e faturação As pesquisas autónomas bem-sucedidas que usam uma fonte de dados de empresas paga custam **\$0.50 por pedido**, independentemente do número de empresas candidatas. Resultados vazios, pesquisas falhadas e resultados fornecidos apenas por outras fontes não são faturados. A obtenção posterior do perfil é faturada à parte. A obtenção é vendida em três níveis de dados, cada um com um endpoint, com preço por país ([preços por país](https://docs.didit.me/pt/getting-started/kyb-registry-pricing.md)): | Endpoint | O que obtém | Preço | | - | - | - | | [`POST /v3/kyb/search/`](https://docs.didit.me/pt/standalone-apis/kyb-registry-search) | Empresas candidatas: nome, número de registo, estado, tipo | \$0.50 quando são devolvidos resultados de fontes pagas | | [`POST /v3/kyb/select/`](https://docs.didit.me/pt/standalone-apis/kyb-registry-select) | **Lite**: o perfil da empresa (identificadores, estado, forma jurídica, data de constituição, morada registada, atividade, dados de contacto) e os administradores | Preço Lite: \$2.00-\$3.00 consoante o país | | [`POST /v3/kyb/shareholders/`](https://docs.didit.me/pt/standalone-apis/kyb-registry-shareholders) | Lite mais os acionistas diretos com as respetivas faixas de participação | Preço Shareholders: \$5.00-\$22.00 consoante o país | | [`POST /v3/kyb/ubo/`](https://docs.didit.me/pt/standalone-apis/kyb-registry-ubo) | Shareholders mais os beneficiários efetivos finais, apurados através da cadeia de propriedade | Preço UBO: \$9.00-\$96.00 consoante o país | `select` é o nível Lite: é o que um fluxo de KYB alojado fatura por uma verificação no registo ao nível Lite, e mantém o contrato que sempre teve. Europa designa o EEE, o Reino Unido e a Suíça. Uma pesquisa Shareholders ou UBO consulta a fonte de propriedade que serve o nível. Quando essa fonte responde que não tem a empresa, a pesquisa consulta também as outras fontes de registo do país, para que uma empresa que a fonte de propriedade não lista continue a ser oferecida como candidata, em vez de terminar em introdução manual. As candidatas encontradas desta forma mantêm o nível pedido: ao obtê-las, a fonte de propriedade é novamente consultada e, se continuar a não ter a empresa, o perfil Lite é entregue e faturado, com `registry_ownership_status: "not_held"`. > [!NOTE] > > **Paga-se pelo nível entregue.** Cada resposta inclui `registry_tier_requested` e `registry_tier_delivered`. Quando os registos do país não têm dados de propriedade, ou quando o registo não dispõe de qualquer informação de propriedade para a empresa selecionada, o pedido de propriedade é entregue e faturado ao nível mais alto disponível (normalmente Lite), e `registry_ownership_status` indica o motivo. Um pedido UBO cujo relatório resultante não identifica nenhuma pessoa singular como beneficiário efetivo é entregue e faturado como Shareholders. > [!NOTE] > > **Versionamento.** Os endpoints Shareholders e UBO existem apenas em `/v3/`. A taxa de pesquisa autónoma também se aplica a `/v2/kyb/search/`; a obtenção do perfil é faturada à parte. ## Estado da propriedade `registry_ownership_status` indica o que aconteceu à parte de propriedade de um pedido Shareholders ou UBO: | Valor | Significado | | - | - | | `not_requested` | A chamada foi uma consulta Lite, por isso não foi pedida informação sobre propriedade. | | `delivered` | O registo forneceu os dados de propriedade, e o nível indicado em `registry_tier_delivered` é o que é cobrado. | | `not_held` | O registo de propriedade respondeu e não inclui esta empresa, por isso não tem nenhum registo de propriedade para fornecer. A empresa foi encontrada por outra das fontes de registo do país. O perfil Lite é entregue e faturado em seu lugar, com `registry_data.ownership_error: "company_not_found"`. | | `unavailable` | Os dados de propriedade não foram fornecidos por qualquer outro motivo: o registo não indica nenhum proprietário, ou não devolveu a secção de propriedade, ou não foi possível consultá-lo. `registry_data.ownership_error` indica qual. O perfil Lite é entregue e faturado em seu lugar. | | `pending` | A secção de propriedade ainda não foi obtida do registo. Nada é faturado, e `registry_tier_delivered` é `null` até que isso aconteça. | `not_held` e `unavailable` são ambos entregues e faturados como Lite, mas não são o mesmo resultado: `not_held` significa que a fonte de propriedade não cobre a empresa, uma lacuna de cobertura, enquanto `unavailable` significa que os dados não foram fornecidos, seja por uma falha ou por uma secção que o registo deixou vazia. `registry_data.ownership_error` indica o motivo. As seleções que antes reportavam `unavailable` porque o registo de propriedade não incluía a empresa passam agora a reportar `not_held`. Se a sua lógica depende do estado, trate ambos como a mesma entrega Lite. Dois dos seus valores têm significados diferentes e não devem ser lidos como o mesmo resultado: | `ownership_error` | Significado | | - | - | | `no_owners_on_record` | O registo respondeu à secção de propriedade e não indica nenhum proprietário. A empresa não tem tabela de capital registada nesse registo. | | `ownership_section_unavailable` | O registo não devolveu a secção de propriedade, por isso não foi entregue nada para ela. A lista está em falta, não vazia, e não diz nada sobre quem é dono da empresa. | Uma secção que o registo não devolveu também fica registada de forma estruturada, em `registry_data.section_errors`, identificada pela secção (`officers`, `shareholders`, `group_structure`) com o estado devolvido pelo registo: ```json theme={null} { "section_errors": { "shareholders": { "status_code": 404 } } } ``` `section_errors` descreve a resposta que tem em mãos, não o histórico que a antecedeu. Uma secção que não foi devolvida no primeiro pedido e é entregue numa passagem posterior (ver a obtenção assíncrona abaixo) perde a sua entrada. Assim, `registry_ownership_status`, `ownership_error` e `section_errors` estão sempre em concordância: uma secção `delivered` nunca tem entrada, e `no_owners_on_record` nunca vem acompanhado de uma entrada para `shareholders`. Além disso, uma secção nunca é entregue parcialmente: se o registo fornecer a primeira página de uma lista e falhar ao fornecer uma página seguinte, a obtenção não é concluída nessa tentativa. Uma obtenção `pending` é repetida na passagem seguinte, e um novo pedido recebe o erro de registo indisponível. Por isso, uma lista `officers` ou de acionistas entregue é sempre a lista completa que o registo detém. Trate uma secção listada em `section_errors` como dados que nunca foram entregues, e não como um resultado vazio. Uma lista `officers` ou de acionistas vazia ao lado de uma entrada em `section_errors` para essa secção não diz nada sobre a empresa. ### Propriedade obtida de forma assíncrona Alguns registos são consultados sob pedido: o primeiro pedido para uma empresa sobre a qual a fonte nunca foi consultada não devolve nenhuma secção de propriedade enquanto ela é obtida, e os dados chegam em cerca de dois minutos. Reportar isso como "sem propriedade registada" subestimaria uma empresa que de facto tem acionistas, por isso o pedido é devolvido como `pending`. Enquanto a obtenção estiver `pending`, `fetch_status` também está `pending` e o estado da resposta é `202 Accepted`. A Didit repete a consulta da secção por conta própria e conclui a obtenção sem qualquer nova chamada da sua parte: * assim que os dados de propriedade chegarem, os acionistas e os beneficiários efetivos aparecem na verificação guardada, `registry_tier_delivered` passa a ser o nível que foi fornecido, e a utilização é cobrada a esse nível; * se a secção continuar vazia quando a janela de nova tentativa fechar, o estado passa a `unavailable`, e o pedido é entregue e faturado como Lite. Guarde o `request_id` e consulte `GET /v3/session/{request_id}/decision/` até que `registry_checks[0].company.fetch_status` seja `resolved`. Não repita o pedido de obtenção enquanto estiver `pending`: cada novo `POST` é um pedido separado, faturado separadamente. Use `POST /v3/kyb/search/` para encontrar empresas candidatas. A pesquisa não cria uma verificação guardada. O parâmetro `tier` da pesquisa escolhe a cadeia que é pesquisada, ver [nível de pesquisa](https://docs.didit.me/pt/standalone-apis/kyb-registry-search.md#nível-de-pesquisa). As pesquisas em registos podem demorar cerca de 90 segundos. Envie `webhook_url` quando quiser que a Didit devolva a resposta de imediato e notifique o seu URL assim que os candidatos estiverem prontos. A notificação de retorno da pesquisa não é assinada de propósito, por isso não precisa de configurar um segredo partilhado para esta notificação simples. Use `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/` com o `kyb_response_id` devolvido para obter o perfil no nível de que precisa. A obtenção é faturável e guarda o resultado como Manual Check na Business Console. ## Fluxo típico 1. Pesquise pelo nome da empresa, número de registo e país, no `tier` que pretende comprar (`basic` é a cadeia Lite predefinida; `shareholders` e `ubo` pesquisam a cadeia desse nível). 2. Se `search_resolved=false`, aguarde pela notificação opcional em `webhook_url` em vez de fazer polling. 3. Mostre os candidatos devolvidos ao seu operador ou cliente. 4. Obtenha o `kyb_response_id` correspondente no nível de que precisa (select para Lite, shareholders ou ubo). 5. Guarde o `request_id` devolvido e use-o para obter o resultado guardado da verificação de empresas. ## Callback da pesquisa Quando o fornecedor informa a Didit de que a pesquisa foi resolvida, a Didit envia um único `POST` para o seu `webhook_url`: ```json theme={null} { "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91", "event_type": "kyb.registry_search.resolved", "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85", "vendor_data": "business-123", "metadata": { "source": "onboarding" }, "search_status": "resolved", "search_resolved": true, "kyb_registry": { "companies": [ { "kyb_response_id": "kyb_resp_123", "name": "TESCO PLC", "registration_number": "00445790", "status": "active", "type": "Public Limited Company", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA", "risk_level": null, "fetch_status": "pending" } ], "pagination": { "total": 1, "page": 1, "per_page": 25 }, "search_status": "resolved", "search_resolved": true }, "timestamp": 1767225600, "created_at": 1767225600 } ``` Trate o callback como uma notificação de entrega. Use o `kyb_response_id` devolvido com `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/` para executar a obtenção do perfil do registo, que é faturável. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.