Empresa estrangeira

Empresa estrangeira

O módulo kyb_estrangeira 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.

// POST /v1/verification-sessions
{ "flow_id": "flow_...", "reference_id": "cliente-123",
  "foreign_entity": {
    "lei": "5493001KJTIIGC8Y1R12",            // ou "name" + "country" (ex.: "GB"), nunca os dois
    "beneficial_owners": [ { "name": "Nome da pessoa" } ] } }   // opcional, até 20 pessoas

// kyb_estrangeira no check_details
{ "module": "kyb_estrangeira", "passed": true, "outcome": "approved",
  "data": {
    "outcome": "encontrada",                  // ou "nao_encontrada_no_indice", "candidatos"
    "lookup_by": "lei",                       // ou "name"
    "index_published_at": "2026-09-26T00:00:00Z",   // data da publicação do índice que respondeu
    "reason": "foreign_entity_not_in_index",  // só quando vai para revisão
    "entity": { "lei": "...", "legal_name": "...", "country": "GB",
                "registration_status": "ISSUED", "entity_status": "ACTIVE",
                "parent_is_beneficial_owner": false,
                "direct_accounting_parent": { "kind": "entity", "lei": "...", "legal_name": "..." },
                "ultimate_accounting_parent": { "kind": "reporting_exception", "reason": "NATURAL_PERSONS" } },
    "candidates": [ { "lei": "...", "legal_name": "...", "country": "GB" } ],  // só na busca por nome
    "candidates_total": 3,                    // quantos o índice achou (a lista traz os primeiros)
    "declared_beneficial_owners_count": 1,
    "declared_beneficial_owners": { ... },    // a triagem nas listas, quando houve declaração
    "sanctions_coverage": { "consulted": [ ... ], "not_consulted": [ ... ] } } }

Como ler. encontrada 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. nao_encontrada_no_indice 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.