> ## 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.

# Visão Geral de Enriquecimento

> Execute integrações de enriquecimento do marketplace para obter dados adicionais de entidades de provedores externos — usando provedores marketplace da gu1.

## O que é Enriquecimento?

Enriquecimento é o processo de melhorar os dados de entidades coletando informações adicionais de provedores de dados externos. O gu1 se integra com dezenas de registros governamentais oficiais, bureaus de crédito, serviços de verificação de identidade e outras fontes de dados confiáveis para fornecer perfis completos de entidades.

## Como Funciona

1. **Selecionar Entidade**: Escolha a entidade que deseja enriquecer (por ID interno ou seu ID externo)
2. **Escolher Provedores**: Selecione um ou mais códigos de integração de enriquecimento
3. **Executar**: o gu1 chama os provedores externos em paralelo e normaliza as respostas
4. **Resultados**: Obtenha dados de enriquecimento padronizados, métricas de qualidade e custos

## Recursos Principais

### Execução em Lote

Execute múltiplos enriquecimentos em uma única chamada de API para melhor desempenho e conveniência.

### Transparência de Custos

Cada enriquecimento retorna seu custo individual em centavos, e você obtém um total para o lote.

### Métricas de Qualidade

Cada enriquecimento inclui:

* **Completude**: Quanto das informações solicitadas foi encontrado (0-1)
* **Confiança**: Confiança do provedor na precisão dos dados (0-1)

### Trilha de Auditoria Automática

Todos os enriquecimentos são registrados automaticamente com:

* Timestamp
* Provedor utilizado
* Campos enriquecidos
* Tempo de execução
* Custo

### Integração com Motor de Regras

Enriquecimentos bem-sucedidos acionam automaticamente o motor de regras com o evento `enrichment_completed`, permitindo criar fluxos de trabalho automatizados.

## Endpoints Disponíveis

<Card title="Executar por ID Interno" icon="database" href="/pt/api-reference/enrichment/execute-by-id">
  Execute enriquecimentos usando o UUID interno da entidade no gu1
</Card>

<Card title="Executar por ID Externo" icon="id-card" href="/pt/api-reference/enrichment/execute-by-external-id">
  Execute enriquecimentos usando seu próprio identificador de entidade
</Card>

## Códigos de Integração Comuns

### Argentina

* `ar_repet_enrichment` - Dados oficiais de pessoas do REPET
* `ar_renaper_enrichment` - Registro nacional de identidade
* `ar_bcra_enrichment` - Dados financeiros do banco central
* `ar_bcra_deudas_enrichment` - Informações de dívidas do banco central
* `ar_afip_enrichment` - Dados da autoridade fiscal
* `ar_nosis_enrichment` - Relatório do bureau de crédito

### Brasil

* `br_serasa_enrichment` - Dados de crédito Serasa
* `br_spc_enrichment` - Bureau de crédito SPC
* `br_receita_federal_enrichment` - Dados da receita federal
* `br_cpf_enrichment` - Validação e dados de CPF
* `br_cnpj_enrichment` - Dados de empresa CNPJ

### Global

* `global_worldcheck_enrichment` - Screening de sanções e PEP
* `global_dowjones_enrichment` - Dados de risco e compliance

Consulte [Códigos de Provedores de Integração](/pt/api-reference/integrations/provider-codes) para a lista completa.

## Casos de Uso

### Onboarding KYC/KYB

Obtenha dados oficiais de identidade e empresa durante o onboarding de clientes:

```javascript theme={null}
const result = await enrichEntity(customerId, [
  'ar_repet_enrichment',
  'ar_renaper_enrichment'
]);
```

### Avaliação de Crédito

Obtenha dados financeiros e de crédito para avaliação de risco:

```javascript theme={null}
const result = await enrichEntity(customerId, [
  'ar_bcra_enrichment',
  'ar_nosis_enrichment'
]);
```

### Screening de Compliance

Screening de sanções, status PEP e mídia adversa:

```javascript theme={null}
const result = await enrichEntity(entityId, [
  'global_worldcheck_enrichment',
  'global_dowjones_enrichment'
]);
```

### Monitoramento Contínuo

Atualize periodicamente os dados de entidades para monitoramento contínuo:

```javascript theme={null}
// Executar mensalmente
const result = await enrichEntity(entityId, [
  'ar_bcra_deudas_enrichment',
  'ar_afip_enrichment'
]);
```

## Melhores Práticas

### 1. Agrupe Enriquecimentos Relacionados

Execute enriquecimentos relacionados juntos para melhor desempenho:

```javascript theme={null}
// Bom - agrupe enriquecimentos relacionados
await enrichEntity(id, [
  'ar_repet_enrichment',
  'ar_renaper_enrichment',
  'ar_bcra_enrichment'
]);

// Menos ótimo - chamadas separadas
await enrichEntity(id, ['ar_repet_enrichment']);
await enrichEntity(id, ['ar_renaper_enrichment']);
await enrichEntity(id, ['ar_bcra_enrichment']);
```

### 2. Trate Falhas Parciais

Verifique resultados individuais, pois alguns provedores podem falhar enquanto outros têm sucesso:

```javascript theme={null}
const result = await enrichEntity(id, providers);

result.results.forEach(r => {
  if (r.success) {
    // Processar enriquecimento bem-sucedido
    console.log(`✓ ${r.integrationName}`);
  } else {
    // Registrar enriquecimento falhado
    console.warn(`✗ ${r.integrationName}: ${r.error.message}`);
  }
});
```

### 3. Rastreie Custos

Monitore os custos de enriquecimento para otimizar o uso de suas integrações:

```javascript theme={null}
const result = await enrichEntity(id, providers);

console.log(`Custo total: $${result.totalCostCents / 100}`);

// Rastreie custos por provedor
result.results.forEach(r => {
  if (r.costCents > 0) {
    console.log(`${r.integrationName}: $${r.costCents / 100}`);
  }
});
```

### 4. Use IDs Externos para Conveniência

Se você trabalha com seus próprios identificadores, use o endpoint de ID externo:

```javascript theme={null}
// Mais simples - use seu ID
await enrichEntityByExternalId('customer_12345', providers);

// vs armazenar/buscar UUID
const uuid = await getEntityUUID('customer_12345');
await enrichEntity(uuid, providers);
```

### 5. Aproveite as Métricas de Qualidade

Use as pontuações de completude e confiança para avaliar a qualidade dos dados:

```javascript theme={null}
result.results.forEach(r => {
  if (r.success) {
    const quality = r.result.dataQuality;

    if (quality.completeness < 0.5) {
      console.warn('Baixa completude de dados');
    }

    if (quality.confidence < 0.8) {
      console.warn('Baixa confiança - revisão manual recomendada');
    }
  }
});
```

## Tratamento de Erros

Os enriquecimentos podem falhar por várias razões:

### Entidade Não Encontrada

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entidade não encontrada"
  }
}
```

### Erros de Provedor

Falhas individuais de provedores não falham todo o lote:

```json theme={null}
{
  "success": true,
  "results": [
    {
      "success": false,
      "error": {
        "code": "NO_DATA_FOUND",
        "message": "Nenhum dado encontrado para esta entidade"
      }
    }
  ]
}
```

### Limite de Taxa

Alguns provedores têm limites de taxa - as falhas incluem informações de nova tentativa:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de taxa do provedor excedido",
    "retryAfter": 3600
  }
}
```

## Próximos Passos

* Explore [Executar por ID](/pt/api-reference/enrichment/execute-by-id) para enriquecimento baseado em UUID interno
* Aprenda sobre [Executar por ID Externo](/pt/api-reference/enrichment/execute-by-external-id) para integração simplificada
* Navegue [Códigos de Provedores](/pt/api-reference/integrations/provider-codes) para ver todos os enriquecimentos disponíveis
* Configure [Regras](/pt/api-reference/rules/create) para automatizar ações após o enriquecimento