Visão Geral de Enriquecimento

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

Selecionar Entidade: Escolha a entidade que deseja enriquecer (por ID interno ou seu ID externo)
Escolher Provedores: Selecione um ou mais códigos de integração de enriquecimento
Executar: o gu1 chama os provedores externos em paralelo e normaliza as respostas
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.

Fallbacks do Marketplace

Alguns enriquecimentos do catálogo definem uma cadeia de fallback: enriquecimentos substitutos, em ordem, que a Gu1 pode tentar somente depois que o primário falhar.

Não precisam estar ativos no Marketplace

Na maior parte do catálogo, fallback_requires_activation é false. Nesse caso o fallback não precisa estar ligado no Marketplace para ser elegível. A Gu1 pode executá-lo quando o primário falha mesmo que esse card esteja desabilitado para a organização. Mantenha desabilitado se quiser usá-lo só como rede de segurança. Ativá-lo no Marketplace (ou listá-lo em autoExecuteIntegrations.enrichments / executeAllActiveEnrichments: true) o transforma em um enriquecimento regular: roda em toda criação automática correspondente e consome créditos mesmo quando o primário já teve sucesso. Se o card do primário indicar que os fallbacks devem estar habilitados antes (fallback_requires_activation: true), então cada substituto da cadeia precisa estar ativo na organização para poder rodar.

Quando rodam

Os fallbacks rodam em pipelines automáticos, por exemplo:

Criação automática de entidade — depois das novas tentativas de dados básicos, a cadeia efetiva da org do primário é tentada em ordem até um sucesso (ou a cadeia ficar vazia).
Enriquecimentos adicionais dessa mesma criação automática (depois dos dados básicos) — se um código listado falhar, a Gu1 pode tentar a cadeia de catálogo desse enriquecimento.
Importação em massa de entidades — a mesma ideia para dados básicos automáticos (por exemplo Argentina: Nosis se estiver habilitado; senão, ARCA só se esse card também estiver habilitado).

Não rodam na execução manual do Marketplace: Executar por ID e Executar por ID externo só executam os códigos enviados. Esses códigos precisam estar habilitados para a organização. A criação automática exige pelo menos um código dessa cadeia habilitado no Marketplace: o primário, ou um substituto. Se o primário está ativo, roda primeiro e os substitutos só são tentados se ele falhar. Se o primário está desligado, o primeiro substituto habilitado é a fonte. Se nenhum está habilitado, a resposta é HTTP 422 (error.code BASIC_DATA_ENRICHMENT_REQUIRED) e errors.creationFailed[].error traz a frase em inglês que lista os códigos (Activate one of: …). Essa frase é a que o integrador recebe; não é trocada por um erro genérico. Veja Criação automática de entidade.

Como configurar a cadeia

Abra o enriquecimento primário no Marketplace (/marketplace). A seção Cadeia de fallback permite:

Manter os padrões do catálogo Gu1 (o típico: os substitutos ficam desligados como produto e só rodam se o primário falhar).
Reordenar, adicionar ou remover candidatos do catálogo (não é possível inventar códigos).
Salvar uma cadeia vazia para que, se o primário falhar, nada mais seja tentado.
Restaurar o padrão Gu1.

Os créditos são cobrados por cada tentativa de fallback que de fato executa, não por deixar o card desabilitado. Se a criação automática identificar um menor e a organização tiver habilitada a criação com nome provisório, a Gu1 omite de propósito novas tentativas, fallbacks e enriquecimentos extras. Em criações automáticas que falham, enrichmentFailedDetails lista cada tentativa (primário + fallbacks do catálogo) quando a entidade não foi criada.

Endpoints Disponíveis

Executar por ID Interno

Execute enriquecimentos usando o UUID interno da entidade no gu1

Executar por ID Externo

Execute enriquecimentos usando seu próprio identificador de entidade

Obter enrichment normalizado

Lê o dossiê canônico persistido da Gu1 (normalizedData)

Obter dados atuais de enrichment

Lê o último mapped e raw por código de integração

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 para a lista completa.

Casos de Uso

Onboarding KYC/KYB

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

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:

const result = await enrichEntity(customerId, [
  'ar_bcra_enrichment',
  'ar_nosis_enrichment'
]);

Screening de Compliance

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

const result = await enrichEntity(entityId, [
  'global_worldcheck_enrichment',
  'global_dowjones_enrichment'
]);

Monitoramento Contínuo

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

// 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:

// 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:

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:

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:

// 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:

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

{
  "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:

{
  "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:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite de taxa do provedor excedido",
    "retryAfter": 3600
  }
}

Próximos Passos

Explore Executar por ID para enriquecimento baseado em UUID interno
Aprenda sobre Executar por ID Externo para integração simplificada
Leia Fallbacks do Marketplace — substitutos em pipelines automáticos, não no execute manual
Leia o dossiê normalizado persistido ou os dados atuais mapped/raw
Navegue Códigos de Provedores para ver todos os enriquecimentos disponíveis
Configure Regras para automatizar ações após o enriquecimento

​O que é Enriquecimento?

​Como Funciona

​Recursos Principais

​Execução em Lote

​Transparência de Custos

​Métricas de Qualidade

​Trilha de Auditoria Automática

​Integração com Motor de Regras

​Fallbacks do Marketplace

​Não precisam estar ativos no Marketplace

​Quando rodam

​Como configurar a cadeia

​Endpoints Disponíveis

Executar por ID Interno

Executar por ID Externo

Obter enrichment normalizado

Obter dados atuais de enrichment

​Códigos de Integração Comuns

​Argentina

​Brasil

​Global

​Casos de Uso

​Onboarding KYC/KYB

​Avaliação de Crédito

​Screening de Compliance

​Monitoramento Contínuo

​Melhores Práticas

​1. Agrupe Enriquecimentos Relacionados

​2. Trate Falhas Parciais

​3. Rastreie Custos

​4. Use IDs Externos para Conveniência

​5. Aproveite as Métricas de Qualidade

​Tratamento de Erros

​Entidade Não Encontrada

​Erros de Provedor

​Limite de Taxa

​Próximos Passos