Saltar para o conteúdo principal

​
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): 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".
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.
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: 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: 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:
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. 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:
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.
Última modificação em 7 de novembro de 2026