Empresa estrangeira
O módulokyb_foreign verifica a empresa de fora do Brasil que não tem CNPJ. A empresa entra na criação da sessão pela API, no bloco foreign_entity: pelo identificador de entidade legal (LEI, o código de 20 caracteres da norma ISO 17442) ou, sem ele, pelo nome e pelo país. O país vem da mesma lista fechada do painel.
Erros do bloco. Flow com o módulo e sem o bloco responde 422 foreign_entity_required; o bloco num flow sem o módulo, 422 foreign_entity_not_supported; LEI com dígito de controle errado, 422 foreign_entity_lei_invalid; beneficiários acima do teto, 422 foreign_entity_too_many_owners. Chave desconhecida no bloco responde 400 unknown_foreign_entity_key, e num beneficiário, 400 unknown_beneficial_owner_key. O link hospedado não leva a empresa: o flow com este módulo só cria sessão pela API.
found com registro emitido e entidade ativa aprova. Registro vencido, candidatos por nome e beneficiário declarado com alerta vão para revisão humana com a evidência, e nunca reprovam sozinhos. not_found_in_index também vai para revisão: nem toda empresa tem LEI, e não constar no índice não quer dizer que a empresa não existe. Sem LEI, a sua equipe escolhe o candidato certo ou pede o identificador ao cliente. Quando o índice não responde, o módulo fica pendente, a verificação vai para revisão e o módulo não é cobrado.
O que o módulo não diz. As controladoras direta e final vêm da consolidação contábil que a própria empresa declara ao índice, e controladora contábil não é beneficiário final: quando o controle é de pessoas naturais, o índice registra uma exceção de reporte, não os nomes. Por isso os beneficiários finais pessoa natural entram pelo campo beneficial_owners, declarados por você, e passam pelas listas de sanções e de pessoas expostas politicamente. O bloco sanctions_coverage diz quais listas foram consultadas e quais não foram.