Fluxo Completo de Pessoa (KYC)

​

Visão Geral

​

Automático vs Manual: Qual Você Deve Usar?

• Você precisa coletar dados do usuário incrementalmente em múltiplas etapas
• Quer mostrar aos usuários um indicador de progresso entre etapas
• Está depurando e quer inspecionar dados entre operações
• Tem lógica de negócio personalizada entre criação de entidade e análise de risco

​

Configuração de Matriz de Risco

​

O que é uma Matriz de Risco?

• Quais pontos de dados verificar (status PEP, sanções, mídia adversa, etc.)
• Qual pontuação de risco atribuir quando as condições são atendidas
• Se aprovar, rejeitar ou sinalizar entidades para revisão
• Etiquetas de risco personalizadas (Baixo/Médio/Alto) com base em faixas de pontuação

​

Como Configurar sua Matriz de Risco

1. Faça login no Dashboard da gu1: https://app.gu1.ai
2. Navegue até Matrizes de Risco: Configurações → Matrizes de Risco
3. Crie uma Nova Matriz: Clique em “Nova Matriz de Risco”
4. Configure Regras: Adicione regras que correspondam aos seus requisitos de conformidade
   • Exemplo: “Se PEP detectado → adicionar 25 pontos à pontuação de risco”
   • Exemplo: “Se houver correspondência de sanções → rejeitar e criar alerta”
5. Defina Etiquetas Personalizadas: Defina faixas de pontuação (ex: 0-25: Baixo, 26-50: Médio, 51-100: Alto)
6. Salve e Copie o ID: Salve a matriz e copie o UUID - você usará isso em chamadas de API

​

Usar Matriz de Risco na API

{
  "riskMatrixId": "uuid-da-matriz-de-risco"
}

• Navegue até Configurações → Organização
• Defina “Matriz de Risco Padrão para Pessoas”
• Todas as entidades de pessoa usarão esta matriz, a menos que seja substituída

​

Tutorial: Configurando sua Primeira Matriz de Risco

• Referência da API de Matriz de Risco
• Onboarding de Pessoas com Matriz de Risco
• Onboarding de Empresas com Matriz de Risco

​

Diagrama de Fluxo

​

Passo 1: Criar Entidade de Pessoa

​

Opção A: Criação Automática (Recomendado)

{
  "entityType": "person",
  "data": {
    "taxId": "12345678",
    "name": "João Silva",
    "countryCode": "BR"
  },
  "enrichmentOptions": {
    "basic": ["identity_verification", "sanctions", "pep"],
    "additional": ["adverse_media", "legal_records"],
    "createShareholders": true,  // ⚠️ Apenas para entidades empresa (KYB), não pessoas (KYC)
    "maxShareholderDepth": 2     // ⚠️ Apenas para entidades empresa (KYB), não pessoas (KYC)
  },
  "skipRulesExecution": false,
  "riskMatrixId": "uuid-da-matriz-de-risco"  // Opcional - veja "Configuração de Matriz de Risco" acima
}

1. Enriquecimento de Dados Básicos: Executa provedores da lista basic
2. Criação de Entidade: Mapeia dados normalizados para a estrutura da entidade
3. Enriquecimento Adicional: Executa provedores da lista additional
4. Descoberta de Acionistas: Cria recursivamente entidades de acionistas (se habilitado) - ⚠️ Apenas empresas
5. Atribuição de Matriz de Risco: Atribui a matriz de risco fornecida (ou padrão)
6. Análise de Risco: Executa regras da matriz de risco automaticamente (a menos que skipRulesExecution: true)

{
  "entity": {
    "id": "uuid",
    "organizationId": "uuid",
    "type": "person",
    "name": "João Silva",
    "taxId": "12345678",
    "countryCode": "BR",
    "riskScore": "45.00",
    "riskFactors": {
      "reasons": ["Correspondência PEP encontrada", "Triagem de sanções aprovada"],
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Risco Médio",
        "color": "#f59e0b"
      }
    },
    "metadata": {
      "enrichment": {
        "hasData": true,
        "executedProviders": ["world_check", "sanctions_api", "pep_database"],
        "lastExecutedAt": "2025-12-24T10:30:00Z"
      }
    }
  },
  "enrichmentResult": {
    "success": true,
    "providers": ["world_check", "sanctions_api", "pep_database"],
    "dataQuality": 85,
    "confidence": 90
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "riskScore": 45
  },
  "shareholders": [
    {
      "id": "shareholder-uuid",
      "name": "Empresa ABC",
      "ownershipPercentage": 25
    }
  ]
}

​

Opção B: Criação Manual

{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678",
  "countryCode": "BR",
  "entityData": {
    "person": {
      "firstName": "João",
      "lastName": "Silva",
      "dateOfBirth": "1980-01-15",
      "nationality": "BR"
    }
  }
}

{
  "entity": {
    "id": "uuid",
    "organizationId": "uuid",
    "type": "person",
    "name": "João Silva",
    "taxId": "12345678",
    "countryCode": "BR",
    "status": "active",
    "riskScore": null,
    "metadata": {
      "enrichment": {
        "hasData": false
      }
    }
  }
}

​

Passo 2: Enriquecer e Analisar (Fluxo Manual)

{
  "enrichIfNeeded": true,
  "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media"],
  "entityType": "person"
}

1. Enriquecimento Opcional: Se enrichIfNeeded: true ou providerCodes fornecidos, executa enriquecimento primeiro
2. Análise de Risco: Executa regras da matriz de risco na entidade
3. Atualização de Pontuação: Atualiza pontuação de risco e status da entidade

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "uuid",
    "entityType": "person",
    "riskScore": 45,
    "overallConfidence": 0.9,
    "totalRules": 10,
    "successfulRules": 3,
    "flags": [
      {
        "type": "PEP",
        "severity": "warning",
        "reason": "Pessoa identificada como Pessoa Politicamente Exposta",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Risco Médio",
        "minScore": 25,
        "maxScore": 50,
        "color": "#f59e0b"
      }
    }
  },
  "rulesTriggered": 3,
  "executionTimeMs": 1250
}

​

Passo 3: Processo de Enriquecimento (Análise Detalhada)

​

Como Funciona o Enriquecimento

1. Seleção de Provedor:
   • Se providerCodes especificados: usa esses provedores específicos
   • Caso contrário: seleciona automaticamente com base nas assinaturas da organização e tipo de entidade
2. Validação de Saldo:
   • Calcula custo total de todos os provedores selecionados
   • Verifica saldo de créditos da organização
   • Lança InsufficientBalanceError se o saldo for muito baixo
3. Execução Paralela:
   • TODOS os provedores executam simultaneamente (até 15 simultâneos)
   • Cada provedor tem timeout individual (padrão: 7.5s, judicial: 15s)
   • Falhas em um provedor não afetam os outros
   • Tempo total de execução = provedor mais lento
4. Normalização de Dados:
   • Dados brutos do provedor normalizados para formato padrão
   • Resolução de conflitos em nível de campo (maior confiança, mais recente, maioria)
   • Mesclagem inteligente com dados de enriquecimento existentes
   • Pontuações de qualidade calculadas a partir de todos os resultados do provedor
5. Armazenamento de Dados:
   • Tabela normalized_enrichment: dados normalizados/mapeados
   • Tabela enrichment_data_current: snapshot de enriquecimento atual
   • Tabela audit_enrichment: auditoria de execução individual do provedor
   • entities.metadata.enrichment: cache de metadados de execução
6. Dedução de Crédito:
   • Saldo deduzido apenas APÓS execução bem-sucedida
   • Custos: varia por provedor (ex: WorldCheck: $0.50, Sanctions:$0.25)

​

Como Funciona a Gestão de Créditos

1. Pré-validação: Antes do enriquecimento começar, o sistema verifica se você tem saldo suficiente
2. Execução: Os fornecedores executam em paralelo (você é cobrado apenas por execuções bem-sucedidas)
3. Dedução: Os créditos são deduzidos APÓS a conclusão bem-sucedida (não antecipadamente)
4. Fornecedores falhados: Sem cobrança se um fornecedor falhar ou expirar

• global_gueno_validation_kyc: $2.00 por verificação
• world_check: $0.50 por verificação
• sanctions_api: $0.25 por screening
• pep_database: $0.25 por verificação
• adverse_media: $0.30 por busca
• legal_records: $0.40 por busca

GET /api/billing/balance

GET /api/billing/transactions

• Navegue até Dashboard → Faturamento → Créditos
• Compre pacotes de créditos ou configure recarga automática

{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}

​

Estrutura de Resultado do Enriquecimento

{
  "success": true,
  "entityId": "uuid",
  "normalized": {
    "entityType": "person",
    "normalized": {
      "fullName": "João Silva",
      "dateOfBirth": "1980-01-15",
      "nationality": "BR",
      "isPep": true,
      "sanctionsMatch": false,
      "adverseMedia": [
        {
          "title": "Investigação Empresarial",
          "date": "2023-05-10",
          "source": "Valor Econômico"
        }
      ]
    },
    "providers": ["world_check", "sanctions_api", "adverse_media"],
    "dataQuality": 85,
    "confidence": 90,
    "completeness": 78
  },
  "providers": ["world_check", "sanctions_api", "adverse_media"],
  "totalCostCents": 100,
  "executionTimeMs": 3500,
  "cacheHit": false,
  "metadata": {
    "providersAttempted": 3,
    "providersSucceeded": 3,
    "providersFailed": 0,
    "dataQuality": 85,
    "confidence": 90
  }
}

​

Passo 4: Análise de Risco (Análise Detalhada)

​

Como Funciona a Análise de Risco

1. Seleção de Estratégia:
   • Usa a matriz de risco atribuída à entidade
   • A matriz de risco define quais regras se aplicam e a estratégia de avaliação
2. Carregamento de Dados:
   • Carrega entidade com dados de enriquecimento
   • Carrega entidade com validação KYC (se existir)
   • Prepara contexto de execução
3. Validação de Cobertura (Apenas Pessoa/Empresa):
   • Extrai todos os campos exigidos pelas condições da regra
   • Valida que os provedores executados cobrem todos os campos de enriquecimento necessários
   • Valida que a validação KYC existe se campos KYC forem necessários
   • Retorna erro com campos ausentes e provedores recomendados se incompleto
4. Execução de Regras:
   • Filtra regras por evento de disparo (ex: “enrichment_completed”, “manual_evaluation”)
   • Executa regras em paralelo usando UniversalRulesEngine
   • Cada regra avalia condições e executa ações se correspondidas
5. Cálculo de Pontuação:
   • Acumula pontuações de regras correspondidas
   • Aplica estratégia de avaliação (score_based ou confidence_based)
   • Normaliza pontuação se rótulos personalizados configurados
   • Calcula rótulo personalizado com base na faixa de pontuação
6. Atualizações de Status:
   • Atualiza pontuação de risco e fatores de risco da entidade
   • Atualiza status da entidade se regras dispararam mudança de status
   • Envia notificação ENTITY_STATUS_CHANGED
7. Trilha de Auditoria:
   • Cria registro de avaliação
   • Registra evento de execução
   • Cria auditoria de análise de risco com detalhes completos de execução
   • Registra alertas criados por ações de regra
8. Consolidação de Alertas:
   • Após delay de 5 segundos, consolida alertas relacionados
   • Cria ou atualiza investigações
   • Envia notificações apropriadas

​

Estrutura de Resultado da Análise de Risco

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "uuid",
    "entityType": "person",
    "riskScore": 45,
    "overallConfidence": 0.9,
    "totalRules": 10,
    "successfulRules": 3,
    "failedRules": 0,
    "rulesExecuted": [
      {
        "ruleId": "rule-uuid",
        "ruleName": "Detecção de PEP",
        "executed": true,
        "conditionsMet": true,
        "confidence": 0.95,
        "executionTime": 50,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 25
          },
          {
            "type": "create_alert",
            "result": {
              "alertId": "alert-uuid"
            }
          }
        ]
      }
    ],
    "flags": [
      {
        "type": "PEP",
        "severity": "warning",
        "reason": "Pessoa identificada como Pessoa Politicamente Exposta",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "strategyType": "score_based",
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Risco Médio",
        "minScore": 25,
        "maxScore": 50,
        "color": "#f59e0b",
        "severity": "medium"
      },
      "displayRange": "25-50"
    }
  },
  "rulesTriggered": 3,
  "executionTimeMs": 1250,
  "auditId": "audit-uuid"
}

​

Passo 5: Validação KYC (Opcional)

​

Criar Validação KYC

{
  "entityId": "uuid",
  "provider": "persona",
  "templateId": "tmpl_ABC123",
  "requiredFields": ["government_id", "selfie"],
  "callbackUrl": "https://sua-app.com/webhooks/kyc"
}

{
  "validation": {
    "id": "kyc-uuid",
    "entityId": "entity-uuid",
    "provider": "persona",
    "status": "pending",
    "validationUrl": "https://kyc-provider.com/start?token=abc123",
    "expiresAt": "2025-12-31T23:59:59Z"
  }
}

​

Usuário Completa KYC

1. Envie o usuário para validationUrl
2. Usuário completa o fluxo KYC (envia documentos, tira selfie, etc.)
3. Provedor KYC envia webhook para sua callbackUrl

​

Webhook: Atualização de Status KYC

{
  "event": "kyc.completed",
  "validationId": "kyc-uuid",
  "entityId": "entity-uuid",
  "status": "approved",
  "data": {
    "documentVerified": true,
    "livenessCheck": true,
    "faceMatch": 98.5,
    "documentType": "passport",
    "documentNumber": "AB1234567",
    "verifiedAt": "2025-12-24T15:30:00Z"
  }
}

​

Re-executar Análise de Risco Após KYC

{
  "enrichIfNeeded": false,
  "entityType": "person"
}

​

Passo 6: Monitorar e Gerenciar

​

Consultar Status da Entidade

• Pontuação de risco atual (normalizada e original)
• Fatores de risco e sinalizadores
• Status de enriquecimento e provedores usados
• Status de validação KYC
• Timestamp da última avaliação de risco

​

Visualizar Histórico de Análise de Risco

• Todas as execuções de análise de risco
• Regras correspondidas em cada execução
• Mudanças de pontuação ao longo do tempo
• Dados de enriquecimento utilizados

​

Visualizar Alertas e Investigações

• Alertas consolidados relacionados à entidade
• Status e prioridade da investigação
• Analistas atribuídos e notas de resolução

​

Melhores Práticas

1. Use Criação Automática: Para a maioria dos casos, use POST /entities/automatic para gerenciar enriquecimento e análise de risco em uma operação.
2. Gerenciamento de Saldo: Sempre garanta créditos suficientes antes do enriquecimento. Monitore o saldo usando GET /billing/balance.
3. Seleção de Provedor: Use providerCodes específicos quando souber quais dados precisa. A seleção automática pode incluir provedores desnecessários.
4. Atribuição de Matriz de Risco: Sempre atribua uma matriz de risco ao criar entidades. Sem uma matriz de risco, a análise de risco não será executada para entidades pessoa/empresa.
5. Timing de KYC: Inicie a validação KYC no início do fluxo de onboarding. Algumas regras podem exigir dados KYC.
6. Validação de Cobertura: Se a análise de risco falhar devido à cobertura incompleta, verifique metadata.missingFields e execute os provedores recomendados.
7. Segurança de Webhook: Sempre valide assinaturas de webhook de provedores KYC para prevenir falsificação.
8. Monitoramento: Configure alertas para entidades de alto risco e enriquecimentos falhados.

​

Tratamento de Erros

​

Erros Comuns

{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}

{
  "success": false,
  "error": "Incomplete data coverage",
  "warnings": [
    "Campo 'sanctions.matches' requer provedor: world_check ou sanctions_api",
    "Campo 'kyc.documentVerified' requer validação KYC"
  ],
  "metadata": {
    "missingFields": [...],
    "recommendedProviders": ["world_check", "sanctions_api"]
  }
}

{
  "success": true,
  "executed": false,
  "error": "No risk matrix assigned to person entity. Please assign a Risk Matrix to enable rule execution."
}

​

Próximos Passos

• Configurar Regras de Matriz de Risco
• Configurar Webhooks
• Gerenciar Integrações de Provedor
• Monitorar Uso de Créditos no seu Dashboard → Faturamento