> ## 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 KYB: busca e seleção de empresas > A API KYB Registry da Didit pesquisa registros de empresas e retorna a empresa no nível escolhido: Lite, Shareholders ou UBOs, com preço por país. ## Endpoints e faturamento Buscas avulsas bem-sucedidas que usam uma fonte paga de dados de empresas custam **\$0.50 por requisição**, independentemente do número de empresas candidatas. Resultados vazios, buscas com falha e resultados fornecidos apenas por outras fontes não são cobrados. A obtenção posterior de um perfil é faturada à parte. A obtenção de dados é vendida em três níveis, cada um com seu endpoint e com preço por país ([preços por país](https://docs.didit.me/pt-br/getting-started/kyb-registry-pricing.md)): | Endpoint | O que você recebe | Preço | | - | - | - | | [`POST /v3/kyb/search/`](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-search) | Empresas candidatas: nome, número de registro, status, tipo | \$0.50 quando são retornados resultados de fontes pagas | | [`POST /v3/kyb/select/`](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-select) | **Lite**: o perfil da empresa (identificadores, status, forma jurídica, data de constituição, endereço registrado, atividade, dados de contato) e os administradores | Preço Lite: \$2.00-\$3.00 conforme o país | | [`POST /v3/kyb/shareholders/`](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-shareholders) | Lite mais os acionistas diretos com suas faixas de propriedade | Preço Shareholders: \$5.00-\$22.00 conforme o país | | [`POST /v3/kyb/ubo/`](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-ubo) | Shareholders mais os beneficiários finais identificados ao longo da cadeia de propriedade | Preço UBO: \$9.00-\$96.00 conforme o país | `select` é o nível Lite: é o que um fluxo de verificação (workflow) KYB hospedado cobra por uma consulta ao registro no nível Lite, e ele mantém o mesmo contrato de sempre. Europa significa o EEE, o Reino Unido e a Suíça. Uma busca Shareholders ou UBO consulta a fonte de dados de propriedade que atende ao nível. Quando essa fonte responde que não possui dados sobre a empresa, a busca consulta também as outras fontes de registro do país, de modo que uma empresa que a fonte de propriedade não lista ainda é oferecida como candidata, em vez de terminar em entrada manual. As candidatas encontradas dessa forma mantêm o nível solicitado: ao recuperar seus perfis, a fonte de propriedade é consultada novamente e, se ainda não possuir dados sobre ela, o perfil Lite é entregue e faturado, com `registry_ownership_status: "not_held"`. > [!NOTE] > > **Você paga pelo nível entregue.** Toda resposta traz `registry_tier_requested` e `registry_tier_delivered`. Quando os registros do país não têm dados de propriedade, ou o registro não tem informações de propriedade da empresa selecionada, uma requisição de propriedade é entregue e faturada no nível mais alto disponível (geralmente Lite), e `registry_ownership_status` indica o motivo. Uma requisição UBO cujo relatório final não aponta nenhuma pessoa física como beneficiário final é entregue e faturada como Shareholders. > [!NOTE] > > **Versionamento.** Os endpoints Shareholders e UBO estão disponíveis apenas em `/v3/`. A tarifa de busca avulsa também se aplica a `/v2/kyb/search/`; a obtenção do perfil é faturada à parte. ## Status da propriedade `registry_ownership_status` indica o que aconteceu com a parte de propriedade de uma requisição Shareholders ou UBO: | Valor | Significado | | - | - | | `not_requested` | A chamada foi uma consulta Lite, portanto nenhum dado de propriedade foi solicitado. | | `delivered` | O registro forneceu os dados de propriedade, e o nível em `registry_tier_delivered` é o que você paga. | | `not_held` | O registro de propriedade respondeu e não lista esta empresa, então não tem nenhum registro de propriedade para fornecer. A empresa foi encontrada por outra das fontes de registro do país. Em vez disso, o perfil Lite é entregue e faturado, com `registry_data.ownership_error: "company_not_found"`. | | `unavailable` | Os dados de propriedade não foram fornecidos por qualquer outro motivo: o registro mantido pelo órgão não indica nenhum proprietário, o registro não retornou a seção de propriedade ou não foi possível consultá-lo. `registry_data.ownership_error` indica qual foi o caso. Em vez disso, o perfil Lite é entregue e faturado. | | `pending` | A seção de propriedade ainda não foi obtida do registro. Nada é faturado e `registry_tier_delivered` permanece `null` até que isso aconteça. | `not_held` e `unavailable` são ambos entregues e faturados como Lite, mas não representam a mesma constatação. `not_held` significa que a fonte de propriedade não cobre a empresa, ou seja, uma lacuna de cobertura. Já `unavailable` significa que os dados não foram fornecidos, seja por uma indisponibilidade, seja por uma seção que o registro deixou vazia. `registry_data.ownership_error` indica o motivo. Seleções que antes informavam `unavailable` porque o registro de propriedade não listava a empresa agora informam `not_held`. Se a sua lógica se ramifica com base no status, trate ambos como a mesma entrega Lite. Dois dos valores desse campo têm significados diferentes e não devem ser interpretados como a mesma constatação: | `ownership_error` | Significado | | - | - | | `no_owners_on_record` | O registro respondeu à seção de propriedade e ela não indica nenhum proprietário. A empresa não tem quadro societário arquivado nesse registro. | | `ownership_section_unavailable` | O registro não retornou a seção de propriedade, portanto nada foi entregue para ela. A lista está ausente, não vazia: ela não diz nada sobre quem é o proprietário da empresa. | Uma seção que o registro não retornou também fica registrada de forma estruturada em `registry_data.section_errors`, com chaves por seção (`officers`, `shareholders`, `group_structure`), com o status com que o registro respondeu: ```json theme={null} { "section_errors": { "shareholders": { "status_code": 404 } } } ``` `section_errors` descreve a resposta que você tem em mãos, não o histórico por trás dela. Uma seção que não foi retornada na primeira requisição e é fornecida em uma tentativa posterior (veja a obtenção assíncrona abaixo) perde sua entrada. Assim, `registry_ownership_status`, `ownership_error` e `section_errors` estão sempre de acordo: uma seção `delivered` nunca tem entrada, e `no_owners_on_record` nunca vem acompanhado de uma entrada para `shareholders`. Uma seção também nunca é entregue pela metade: se o registro fornece a primeira página de uma lista e depois falha ao fornecer uma página seguinte, a obtenção não é concluída nessa tentativa. Uma obtenção `pending` é tentada novamente na próxima tentativa, e uma nova requisição recebe como resposta o erro de registro indisponível. Por isso, uma lista de `officers` ou de acionistas entregue é sempre a lista completa mantida pelo registro. Trate uma seção listada em `section_errors` como dados que nunca foram entregues, e nunca como um resultado vazio: uma lista de `officers` ou de acionistas vazia ao lado de uma entrada em `section_errors` para ela não diz nada sobre a empresa. ### Propriedade obtida de forma assíncrona Alguns registros são consultados sob demanda: a primeira requisição sobre uma empresa que nunca foi consultada nessa fonte não retorna a seção de propriedade enquanto ela é buscada, e os dados chegam em poucos minutos. Informar isso como "nenhuma propriedade registrada" subestimaria uma empresa que de fato tem acionistas, por isso a requisição retorna `pending`. Enquanto uma obtenção está `pending`, `fetch_status` também fica `pending` e o status da resposta é `202 Accepted`. A Didit tenta obter a seção novamente por conta própria e conclui a obtenção sem nenhuma outra chamada da sua parte: * assim que os dados de propriedade chegam, os acionistas e beneficiários finais aparecem na verificação salva, `registry_tier_delivered` passa a ser o nível fornecido e o uso é cobrado nesse nível; * se a seção ainda estiver vazia quando a janela de novas tentativas terminar, o status passa a ser `unavailable` e a requisição é entregue e faturada como Lite. Guarde o `request_id` e consulte `GET /v3/session/{request_id}/decision/` periodicamente até que `registry_checks[0].company.fetch_status` seja `resolved`. Não repita a requisição de obtenção enquanto ela estiver `pending`: cada novo `POST` é uma requisição separada, faturada separadamente. Use `POST /v3/kyb/search/` para encontrar empresas candidatas. A busca não cria uma verificação salva. O parâmetro `tier` da busca define a cadeia em que ela pesquisa. Veja [nível de busca](https://docs.didit.me/pt-br/standalone-apis/kyb-registry-search.md#nível-de-busca). As buscas no registro podem levar cerca de 90 segundos. Envie `webhook_url` quando quiser que a Didit responda imediatamente e notifique sua URL assim que os candidatos estiverem prontos. O callback de busca não é assinado de propósito, então você não precisa configurar um segredo compartilhado para essa notificação simples. Use `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/` com o `kyb_response_id` retornado para obter o perfil no nível de que você precisa. A obtenção é faturável e salva o resultado como um Manual Check no Business Console. ## Fluxo típico 1. Busque pelo nome da empresa, número de registro e país, no `tier` que você pretende comprar (`basic` é a cadeia Lite padrão; `shareholders` e `ubo` pesquisam a cadeia desse nível). 2. Se `search_resolved=false`, aguarde o callback opcional de `webhook_url` em vez de fazer consultas periódicas. 3. Mostre os candidatos retornados ao seu operador ou cliente. 4. Obtenha o `kyb_response_id` correspondente no nível de que você precisa (selecione Lite, shareholders ou ubo). 5. Armazene o `request_id` retornado e use-o para obter o resultado salvo da verificação de empresa. ## Callback de pesquisa Quando o provedor informa à Didit que a pesquisa foi concluída, a Didit envia um único `POST` para a sua `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` retornado com `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` ou `POST /v3/kyb/ubo/` para executar a consulta faturável do perfil no registro de empresas. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.