Saltar para o conteúdo principal
POST
curl
Use este endpoint primeiro para encontrar candidatos correspondentes no registo de empresas. A pesquisa não cria uma Verificação manual guardada. As pesquisas autónomas bem-sucedidas que usem uma fonte de dados de empresas paga custam $0.50 por pedido, independentemente do número de candidatos. Resultados vazios, pesquisas falhadas e resultados fornecidos apenas por outras fontes não são cobrados. A obtenção posterior de um perfil é faturada à parte. Para uma pesquisa que possa usar uma fonte paga, a Didit verifica e reserva o preço de pesquisa aplicável antes de contactar o registo. Um saldo insuficiente devolve 403 com code: "insufficient_credits". A faturação contratual segue a tarifa de pesquisa acordada; uma tarifa contratual não configurada é rejeitada antes da pesquisa. As pesquisas em sandbox são gratuitas. Cada pesquisa repetida bem-sucedida é um novo pedido faturável; a entrega do callback não acrescenta outra cobrança de pesquisa. Se enviar webhook_url, a Didit pode responder de imediato enquanto o fornecedor resolve a pesquisa e, depois, envia os candidatos para o seu URL de retorno quando estiverem prontos. O callback não é assinado por conceção, por isso não precisa de configurar um segredo do webhook para esta notificação de pesquisa. Consulte o exemplo de payload do callback da pesquisa. Depois de escolher o kyb_response_id correto, chame POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/ para obter o perfil faturável do registo no nível de que precisa.
O fetch_status de cada candidato é pending no momento da pesquisa e mantém-se pending até selecionar esse candidato. A pesquisa apenas lista candidatos, e a seleção é que obtém o perfil completo. Não faça polling à pesquisa à espera que isto se resolva.O kyb_response_id é um identificador opaco e efémero, limitado a um único pedido de pesquisa: devolva-o exatamente como o recebeu, nunca o interprete nem derive nada do seu conteúdo, e espere que repetir a mesma pesquisa devolva novos IDs. Selecione o candidato logo após a pesquisa e use registration_number quando precisar de um identificador estável para a própria empresa.

Nível de pesquisa

tier seleciona o nível do registo cuja cadeia de fornecedores a pesquisa usa: basic (o predefinido, a cadeia Lite), shareholders ou ubo. A lista de candidatos vem da cadeia desse nível, que nem sempre é a fonte que a pesquisa Lite consulta; por isso, uma pesquisa Lite vazia não prova que o registo não tem a empresa. Pesquise novamente no nível de que precisa. Quando o país não oferece o nível indicado, a pesquisa é executada no nível mais alto que ele oferece até esse. Um país sem qualquer dado de registo não é oferecido para verificações de registo; continue com a introdução manual da empresa. Pesquise no nível que pretende comprar e, depois, obtenha o candidato no endpoint que o vende:

search_type

search_type aceita apenas contains, que é também o predefinido. As fontes de registo por detrás da pesquisa procuram o nome da empresa por inclusão, por isso start_with e fuzzy são rejeitados com 400 ("start_with" is not a valid choice) em vez de serem tratados silenciosamente como contains. Envie registration_number para uma correspondência exata da empresa.

Pesquisa alojada e autónoma

POST /v1/kyb/search/ é a pesquisa que um fluxo de verificação alojado executa: é autenticada pela sessão de verificação, responde 403 a uma chave de API e não aceita tier, pois a configuração do registo KYB do fluxo escolhe a cadeia. As chamadas autónomas à API usam POST /v2/kyb/search/ ou POST /v3/kyb/search/ com o seu x-api-key; o parâmetro tier e os endpoints de seleção por nível são a forma de uma integração autónoma chegar aos mesmos candidatos, no nível de que precisa.

Tratar indisponibilidades do registo

Se o fornecedor do registo estiver temporariamente indisponível, o endpoint devolve 502 com um código estável e legível por máquina:
Quando receber este código, deixe o utilizador continuar com a introdução manual da empresa ou peça-lhe que tente novamente mais tarde. Mantenha os erros de validação separados: parâmetros de pesquisa inválidos devolvem 400 e não usam este código de indisponibilidade.

Tratar países não suportados e limites de pesquisa

Dois outros códigos estáveis indicam que deve parar de tentar novamente e continuar com a introdução manual da empresa: No fluxo alojado, cada passo de registo permite 3 pesquisas numa fonte de dados de empresas paga. Após a terceira, o requerente recebe a opção de introdução manual. Selecionar um candidato que é um registo de marca comercial e não uma empresa devolve 400 com code: "kyb_registry_entry_not_a_company". Escolha, em vez disso, uma empresa dos resultados da pesquisa.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json
country_code
string
obrigatório

Código ISO 3166-1 alpha-2 do país cujo registo de empresas deve ser pesquisado. Por exemplo, GB. Onde os registos de empresas operam a nível estadual ou provincial, anexe o código de subdivisão ISO 3166-2 como XX-YY: US-CA pesquisa o registo da Califórnia. As pesquisas nos Estados Unidos requerem sempre a subdivisão — um simples US é rejeitado. Insensível a maiúsculas e minúsculas; normalizado para maiúsculas.

Maximum string length: 10
Exemplo:

"GB"

name
string

Nome da empresa a pesquisar. É obrigatório indicar name ou registration_number.

Maximum string length: 255
Exemplo:

"Tesco"

registration_number
string

Número de registo a pesquisar. É obrigatório indicar name ou registration_number.

Maximum string length: 100
tier
enum<string>
padrão:basic

Nível do registo de empresas cuja cadeia de fornecedores executa esta pesquisa. basic (predefinição) pesquisa a cadeia Lite do país; shareholders e ubo pesquisam a cadeia de propriedade desse nível, que pode ser uma fonte diferente, pelo que uma pesquisa Lite vazia não prova que a empresa não conste do registo de empresas. Um país que não disponibilize o nível indicado é pesquisado no nível mais elevado disponível até esse. Obtenha o candidato a partir do endpoint que comercializa o nível pesquisado: POST /v3/kyb/select/ (Lite), POST /v3/kyb/shareholders/ ou POST /v3/kyb/ubo/.

Opções disponíveis:
basic,
shareholders,
ubo
Exemplo:

"basic"

search_type
enum<string>
padrão:contains

Estratégia de correspondência de nomes aplicada pela pesquisa no registo. contains é o único valor aceite: nenhuma fonte de registo por detrás da pesquisa disponibiliza um modo de prefixo ou aproximado (fuzzy), pelo que start_with e fuzzy são rejeitados com 400 (not a valid choice).

Opções disponíveis:
contains
vendor_data
string

O seu identificador para esta consulta; devolvido e incluído no callback do webhook.

metadata
object | null

JSON de formato livre; devolvido na resposta e incluído no callback do webhook.

webhook_url
string<uri>

Muda a pesquisa para o modo assíncrono: a API responde imediatamente e envia um callback POST não assinado kyb.registry_search.resolved para este URL quando a lista de candidatos estiver pronta.

Maximum string length: 500

Resposta

Pesquisa aceite. O modo síncrono devolve a lista final de candidatos; o modo webhook devolve imediatamente (frequentemente search_status: "pending") e entrega a lista final através do callback kyb.registry_search.resolved.

request_id
string<uuid>

Com webhook_url: o id persistido do pedido de pesquisa, devolvido como request_id no callback kyb.registry_search.resolved. Sem webhook_url: um UUID de correlação transitório (a pesquisa não é armazenada).

kyb_registry
object
vendor_data
string | null

Eco do vendor_data que enviou.

metadata
object | null

Eco do objeto metadata que enviou.

created_at
string<date-time>
Última modificação em 7 de novembro de 2026