> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fluxo Completo de Pessoa (KYC)

> Guia completo para criar, enriquecer e analisar entidades de pessoa com validação KYC — na API KYC da gu1 para fluxos de verificação de identidade.

## Visão Geral

Este guia cobre o fluxo completo para gerenciamento de entidades de pessoa, desde a criação até o enriquecimento, validação KYC e análise de risco. O fluxo foi projetado para ser flexível, suportando processos automáticos e manuais em cada etapa.

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

<Note>
  **Resposta Rápida**: Use **Automático** para a maioria dos casos. Ele lida com tudo em uma chamada de API e é mais rápido de integrar.
</Note>

| Recurso                         | Criação Automática                       | Criação Manual                                                       |
| ------------------------------- | ---------------------------------------- | -------------------------------------------------------------------- |
| **Chamadas de API Necessárias** | 1 chamada (`POST /entities/automatic`)   | 2-3 chamadas (`POST /entities`, depois `POST /entities/:id/analyze`) |
| **Enriquecimento**              | Automático - executa em segundo plano    | Manual - você aciona separadamente                                   |
| **Análise de Risco**            | Automática - executa após enriquecimento | Manual - você aciona separadamente                                   |
| **Descoberta de Acionistas**    | Opcional - configurável na requisição    | Não disponível                                                       |
| **Complexidade de Integração**  | Simples - processo de uma etapa          | Complexo - orquestrar múltiplas etapas                               |
| **Dedução de Créditos**         | Automática                               | Automática (por operação)                                            |
| **Usar Quando**                 | Fluxos de onboarding padrão              | Precisa de controle granular do timing                               |
| **Melhor Para**                 | Apps de produção, processamento em lote  | Testes, debugging, fluxos personalizados                             |

**Quando usar Criação Manual:**

* 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

<Warning>
  **Quem Define a Matriz de Risco?** Você configura as regras da sua matriz de risco no dashboard da gu1 antes de usar a API.
</Warning>

### O que é uma Matriz de Risco?

Uma **Matriz de Risco** é uma coleção de regras que definem como as entidades são pontuadas por risco. Pense nisso como seu manual de conformidade - ela determina:

* 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](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

**Opção 1: Especificar na requisição da API** (recomendado para configurações multi-tenant):

```json theme={null}
{
  "riskMatrixId": "uuid-da-matriz-de-risco"
}
```

**Opção 2: Definir padrão da organização** no dashboard:

* 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

Para um passo a passo detalhado, consulte nossos guias:

* [Referência da API de Matriz de Risco](/en/api-reference/risk-matrix/execute-risk-matrix)
* [Onboarding de Pessoas com Matriz de Risco](/en/use-cases/onboarding/person-automatic-with-risk-matrix)
* [Onboarding de Empresas com Matriz de Risco](/en/use-cases/onboarding/company-automatic-with-risk-matrix)

## Diagrama de Fluxo

```mermaid theme={null}
graph TD
    A[Criar Pessoa] --> B{Criação Automática?}
    B -->|Sim| C[POST /entities/automatic]
    B -->|Não| D[POST /entities]

    C --> E[Enriquecimento Básico]
    E --> F[Entidade Criada com Dados]
    F --> G[Enriquecimentos Adicionais]

    D --> H[Entidade Criada - Apenas Informações Básicas]

    G --> I{Acionistas?}
    H --> J{Precisa de Enriquecimento?}

    I -->|Sim| K[Criação Recursiva de Acionistas]
    I -->|Não| L[Atribuição de Matriz de Risco]

    J -->|Sim| M[POST /entities/:id/analyze com enriquecimento]
    J -->|Não| N{Matriz de Risco Atribuída?}

    K --> L
    M --> N

    N -->|Sim| O[Análise de Risco Automática]
    N -->|Não| P[Análise de Risco Manual]

    O --> Q[Pontuação de Risco Calculada]
    P --> R[POST /entities/:id/analyze]
    R --> Q

    Q --> S{Precisa de KYC?}
    S -->|Sim| T[POST /kyc-validations]
    S -->|Não| U[Completo]

    T --> V[Usuário Completa KYC]
    V --> W[Webhook: Atualização de Status KYC]
    W --> X[Re-executar Análise de Risco]
    X --> U
```

## Passo 1: Criar Entidade de Pessoa

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

A criação automática gerencia enriquecimento, descoberta de acionistas e análise de risco em uma única operação.

**Endpoint**: `POST /entities/automatic`

**Requisição**:

```json theme={null}
{
  "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
}
```

**O que acontece automaticamente**:

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`)

<Info>
  **Nota sobre Acionistas (createShareholders)**: Este recurso é aplicável apenas para **entidades empresa (KYB)**, não entidades pessoa (KYC).

  Ao verificar uma **empresa**, você pode habilitar `createShareholders: true` para descobrir e criar automaticamente entidades para todos os beneficiários finais e acionistas corporativos.

  Para **entidades pessoa (KYC)**, este campo é ignorado, pois indivíduos não têm acionistas. Se você está implementando verificação de pessoas (KYC), pode omitir este campo completamente.
</Info>

**Resposta**:

```json theme={null}
{
  "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

Cria uma entidade de pessoa com apenas informações básicas, e depois enriquece e analisa separadamente.

**Endpoint**: `POST /entities`

**Requisição**:

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

**Resposta**:

```json theme={null}
{
  "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)

Se você criou a entidade manualmente, precisa enriquecê-la e executar a análise de risco.

**Endpoint**: `POST /entities/:entityId/analyze`

**Requisição**:

```json theme={null}
{
  "enrichIfNeeded": true,
  "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media"],
  "entityType": "person"
}
```

<Accordion title="Códigos de Fornecedor Disponíveis para KYC">
  **Códigos de Fornecedor Padrão** (mais usados):

  * `global_gueno_validation_kyc` - **Recomendado para KYC completo** - Verificação integral incluindo documento + liveness + face match
  * `world_check` - Screening PEP e sanções (Refinitiv WorldCheck)
  * `sanctions_api` - Screening de listas globais de sanções
  * `pep_database` - Detecção de Pessoas Politicamente Expostas
  * `adverse_media` - Monitoramento de notícias negativas
  * `legal_records` - Registros judiciais
  * `identity_verification` - Validação básica de identidade

  **Como Escolher Códigos:**

  1. **Para KYC Completo**:
     ```json theme={null}
     "providerCodes": ["global_gueno_validation_kyc"]
     ```

  2. **Apenas Screening AML**:
     ```json theme={null}
     "providerCodes": ["world_check", "sanctions_api", "pep_database"]
     ```

  3. **Due Diligence Reforçada**:
     ```json theme={null}
     "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media", "legal_records"]
     ```

  **Nota**: Fornecedores disponíveis dependem das assinaturas da sua organização.
</Accordion>

**O que acontece**:

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

**Resposta**:

```json theme={null}
{
  "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

O serviço **EnrichmentOrchestrator** gerencia todas as operações de 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

<Warning>
  **Importante**: Os créditos são deduzidos do saldo da sua organização quando os fornecedores de enriquecimento são executados com sucesso.
</Warning>

**Fluxo de Deduçã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

**Custos Típicos** (varia por plano de assinatura):

* `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

**Verifique Seu Saldo:**

```bash theme={null}
GET /api/billing/balance
```

**Monitore o Uso de Créditos:**

```bash theme={null}
GET /api/billing/transactions
```

**Adicionar Créditos:**

* Navegue até [Dashboard → Faturamento → Créditos](https://app.gu1.ai/billing/credits)
* Compre pacotes de créditos ou configure recarga automática

**Erro de Saldo Insuficiente:**

```json theme={null}
{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}
```

**Solução**: Adicione créditos à sua conta antes de executar operações de enriquecimento.

Para preços detalhados e gerenciamento de créditos, consulte seu [Dashboard → Faturamento → Créditos](https://app.gu1.ai/billing/credits).

### Estrutura de Resultado do Enriquecimento

```json theme={null}
{
  "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

O serviço **RulesExecutionService** gerencia todas as operações de 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

```json theme={null}
{
  "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)

Se as regras da sua matriz de risco exigirem campos de validação KYC (como `kyc.documentVerified`, `kyc.livenessCheck`), você precisa criar uma validação KYC.

### Criar Validação KYC

**Endpoint**: `POST /kyc-validations`

**Requisição**:

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

**Resposta**:

```json theme={null}
{
  "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

Quando o KYC é concluído, seu webhook recebe:

```json theme={null}
{
  "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

Uma vez que o KYC é concluído, re-execute a análise de risco para avaliar regras dependentes de KYC:

**Endpoint**: `POST /entities/:entityId/analyze`

**Requisição**:

```json theme={null}
{
  "enrichIfNeeded": false,
  "entityType": "person"
}
```

Agora as regras que verificam campos `kyc.*` serão avaliadas corretamente e a pontuação de risco final da entidade será calculada.

## Passo 6: Monitorar e Gerenciar

### Consultar Status da Entidade

**Endpoint**: `GET /entities/:entityId`

**A resposta inclui**:

* 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

**Endpoint**: `GET /risk-analysis-audits?entityId=:entityId`

**Retorna**:

* 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

**Endpoint**: `GET /investigations?entityId=:entityId`

**Retorna**:

* 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

**Saldo Insuficiente**:

```json theme={null}
{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}
```

**Solução**: Adicione créditos à conta de faturamento da organização.

**Cobertura Incompleta**:

```json theme={null}
{
  "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"]
  }
}
```

**Solução**: Execute os provedores recomendados ou crie validação KYC, e então re-analise.

**Sem Matriz de Risco**:

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

**Solução**: Atribua uma matriz de risco à entidade usando `PATCH /entities/:id`.

## Próximos Passos

* [Configurar Regras de Matriz de Risco](/pt/api-reference/risk-matrix/list)
* [Configurar Webhooks](/pt/use-cases/kyc/webhook-integration)
* [Gerenciar Integrações de Provedor](/pt/api-reference/integrations/provider-codes)
* Monitorar Uso de Créditos no seu [Dashboard → Faturamento](https://app.gu1.ai/billing/credits)