Fila de KYC

A Fila de KYC é o painel de compliance do BackOffice onde o Compliance Officer revisa e decide o KYC composto do investidor: identidade (provedor de KYC ou selfie/documentoscopia Axia), Investidor Qualificado (evidência opcional que libera limites maiores) e, quando habilitado, o background-check do BaaS. A aprovação da conta é uma decisão manual — nenhum investidor é aprovado pelo webhook do provedor.

A única exceção é a pré-análise facial com aprovação automática habilitada: nesse caso, um veredito folgadamente positivo na comparação documento × selfie promove a conta sozinho, registrado como SYSTEM_FACE_MATCH. Nenhum veredito reprova conta automaticamente.

Pré-requisitos de acesso

• Permissão (módulo): viewKycQueue (ver fila e detalhes) e reviewKyc (aprovar / rejeitar / pedir reenvio)
• Licença/Feature: modo de aprovação do tenant em MANUAL (ver AUTO × MANUAL)
• Contêiner do menu: GERAL → Fila de KYC (/kyc-queue)

O que você pode fazer aqui

• Listar e buscar investidores em revisão, separados por abas Pendentes / Aprovados / Rejeitados / Todos, com busca por nome, CPF, CNPJ, passaporte ou e-mail.
• Revisar a identidade — payload do provedor (documento, imagens, liveness, AML) ou a nota da identidade verificada por selfie/documentoscopia Axia.
• Revisar a evidência de Investidor Qualificado (opcional) e decidi-la em escopo próprio.
• Consultar os documentos do usuário — todos os artefatos de KYC enviados, com a selfie AXIA_KYC em destaque para comparação facial.
• Ler a pré-análise facial — veredito automático da comparação entre o rosto do documento e o da selfie, quando habilitada para o tenant.
• Ver o background-check do BaaS e a documentoscopia (status, face match, OCR, link) quando o provedor bancário está habilitado.
• Analisar o Quadro Societário (QSA) do investidor pessoa jurídica, com CPF mascarado.
• Auditar o acesso — mapa de logins recentes geolocalizados e dispositivos registrados.
• Decidir — Aprovar conta, Rejeitar conta (com motivo) ou decidir o Investidor Qualificado, sempre com confirmação de segurança (step-up).

Fluxo de KYC composto

A identidade e o Investidor Qualificado são dois lados independentes:

• Conta — a aprovação da conta exige apenas que a identidade esteja verificada (provedor PASSED ou selfie/documentoscopia Axia). Aprovar seta user.status = 'APPROVED', que é a pré-condição já consumida pela provisão de identidade on-chain (ERC-3643).
• Investidor Qualificado (IQ) — é opcional e não bloqueia a conta. Aprovar o IQ marca o perfil como qualified (libera limites maiores). Ver Investidor Qualificado.

Significado dos status

Status	Valores	O que significa
Identidade	PENDING (Pendente) · PASSED (Aprovada) · FAILED (Reprovada)	Espelho do resultado do provedor de KYC. PASSED é pré-condição para aprovar a conta.
Inv. Qualificado	NOT_SUBMITTED (Não enviado) · SUBMITTED (Enviado) · PASSED (Aprovado) · FAILED (Reprovado)	Estado da evidência de patrimônio/accreditation. Independente da conta.
Status geral	PENDING (Pendente) · APPROVED (Aprovado) · REJECTED (Rejeitado)	Estado agregado da conta do investidor.

Motivos de rejeição (reason codes)

Toda rejeição de conta ou de IQ exige um motivo — é auditável e é o que o investidor vê para corrigir e reenviar.

Código	Rótulo	Quando usar
INSUFFICIENT_PC_EVIDENCE	Evidência de Investidor Qualificado insuficiente	Documento de patrimônio/accreditation não comprova a condição de qualificado.
AML_FAIL	Reprovado na checagem AML	Alerta de AML/sanções que impede a aprovação.
DOCUMENT_UNCLEAR	Documento ilegível ou incompleto	Imagem/arquivo ilegível, cortado ou incompleto.

Step-up obrigatório

Toda decisão (aprovar, rejeitar ou pedir reenvio) exige confirmação de segurança (step-up) — re-autenticação com senha + MFA, validada no servidor. É proteção de compliance de alto impacto: o reviewed_by da decisão vem sempre do administrador autenticado, nunca do corpo da requisição.

Clientes legados

Investidores antigos que já têm cadastro/documento mas nunca passaram pelo fluxo de verificação aparecem na aba Pendentes com o selo "Sem verificação iniciada". O estado é sintetizado (identidade PENDING, IQ NOT_SUBMITTED, status geral a partir do users.status).

Rejeitar um legado notifica o cliente

Rejeitar a conta de um cliente legado seta users.status = 'REJECTED' com o motivo e dispara notificação — é o mecanismo para o cliente ver o motivo e refazer o processo de verificação no hub de KYC.

Modo do tenant (AUTO × MANUAL)

O comportamento é controlado por tenant via approvalMode:

• AUTO (legado, padrão) — o webhook do provedor aprova a conta sozinho. A fila manual não governa esses tenants e não há regressão nos fluxos existentes.
• MANUAL — a fila governa: o webhook só atualiza a identidade; a conta só vira APPROVED por decisão explícita do Compliance Officer nesta tela.

Subseções

Página	O que cobre
Fila (lista)	Abas, busca, chips de status, selo de legado e paginação
Detalhe e decisão	Painéis do detalhe e as decisões de conta (aprovar/rejeitar/pedir reenvio)
Pré-análise facial	Comparação automática documento × selfie, leitura do veredito e aprovação automática
Investidor Qualificado	Evidência opcional e a decisão de IQ em escopo próprio