Descripción General de Enriquecimiento

¿Qué es el Enriquecimiento?

El enriquecimiento es el proceso de mejorar los datos de entidades mediante la recopilación de información adicional de proveedores de datos externos. gu1 se integra con docenas de registros gubernamentales oficiales, burós de crédito, servicios de verificación de identidad y otras fuentes de datos confiables para proporcionar perfiles completos de entidades.

Cómo Funciona

Seleccionar Entidad: Elige la entidad que deseas enriquecer (por ID interno o tu ID externo)
Elegir Proveedores: Selecciona uno o más códigos de integración de enriquecimiento
Ejecutar: gu1 llama a los proveedores externos en paralelo y normaliza las respuestas
Resultados: Obtén datos de enriquecimiento estandarizados, métricas de calidad y costos

Características Clave

Ejecución por Lotes

Ejecuta múltiples enriquecimientos en una sola llamada API para mejor rendimiento y conveniencia.

Transparencia de Costos

Cada enriquecimiento devuelve su costo individual en centavos, y obtienes un total para el lote.

Métricas de Calidad

Cada enriquecimiento incluye:

Completitud: Cuánta de la información solicitada se encontró (0-1)
Confianza: Confianza del proveedor en la precisión de los datos (0-1)

Registro de Auditoría Automático

Todos los enriquecimientos se registran automáticamente con:

Marca de tiempo
Proveedor utilizado
Campos enriquecidos
Tiempo de ejecución
Costo

Integración con Motor de Reglas

Los enriquecimientos exitosos activan automáticamente el motor de reglas con el evento enrichment_completed, permitiéndote crear flujos de trabajo automatizados.

Fallbacks del Marketplace

Algunos enriquecimientos del catálogo definen una cadena de fallback: enriquecimientos sustitutos, en orden, que Gu1 puede intentar solo después de que falle el primario.

No hace falta activarlos en Marketplace

En la mayoría del catálogo, fallback_requires_activation es false. Entonces el fallback no tiene que estar prendido en Marketplace para ser elegible. Gu1 puede ejecutarlo si falla el primario aunque esa tarjeta esté deshabilitada para tu organización. Dejalo deshabilitado si solo lo querés como red de seguridad. Activarlo en Marketplace (o listarlo en autoExecuteIntegrations.enrichments / executeAllActiveEnrichments: true) lo convierte en un enriquecimiento regular: corre en cada creación automática coincidente y consume créditos aunque el primario ya haya funcionado. Si la tarjeta del primario indica que los fallbacks deben estar habilitados primero (fallback_requires_activation: true), entonces cada sustituto de la cadena sí tiene que estar activo en la organización para poder correr.

Cuándo corren

Los fallbacks corren en pipelines automáticos, por ejemplo:

Creación automática de entidad — tras los reintentos de datos básicos, se prueba la cadena efectiva de la org del primario, en orden, hasta que uno tenga éxito (o la cadena esté vacía).
Enriquecimientos adicionales de esa misma creación automática (después de datos básicos) — si falla un código listado, Gu1 puede intentar la cadena de catálogo de ese enriquecimiento.
Importación masiva de entidades — la misma idea para datos básicos automáticos (por ejemplo Argentina: Nosis si está habilitado; si no, ARCA solo si esa tarjeta también está habilitada).

No corren en la ejecución manual de Marketplace: Ejecutar por ID y Ejecutar por ID externo solo ejecutan los códigos que enviás. Esos códigos deben estar habilitados para la organización. La creación automática exige al menos un código de esa cadena habilitado en Marketplace: el primario, o un sustituto. Si el primario está activo, corre primero y los sustitutos solo se intentan si falla. Si el primario está apagado, el primer sustituto habilitado es la fuente. Si ninguno está habilitado, la respuesta es HTTP 422 (error.code BASIC_DATA_ENRICHMENT_REQUIRED) y errors.creationFailed[].error trae la frase en inglés que lista los códigos (Activate one of: …). Esa frase es la que recibe el integrador; no se reemplaza por un error genérico. Ver Creación automática de entidad.

Cómo configurar la cadena

Abrí el enriquecimiento primario en Marketplace (/marketplace). La sección Cadena de fallback permite:

Conservar los defaults del catálogo Gu1 (lo típico: los sustitutos quedan apagados como producto y solo corren si falla el primario).
Reordenar, agregar o quitar candidatos del catálogo (no se pueden inventar códigos).
Guardar una cadena vacía para que, si falla el primario, no se intente nada más.
Restaurar el default Gu1.

Los créditos se cobran por cada intento de fallback que realmente se ejecuta, no por dejar la tarjeta deshabilitada. Si la creación automática identifica a un menor y tu organización tiene habilitada la creación con nombre provisorio, Gu1 omite a propósito reintentos, fallbacks y enriquecimientos extra. En creaciones automáticas fallidas, enrichmentFailedDetails lista cada intento (primario + fallbacks de catálogo) cuando la entidad no se creó.

Endpoints Disponibles

Ejecutar por ID Interno

Ejecuta enriquecimientos usando el UUID interno de la entidad en gu1

Ejecutar por ID Externo

Ejecuta enriquecimientos usando tu propio identificador de entidad

Obtener enrichment normalizado

Lee el dossier canónico persistido de Gu1 (normalizedData)

Obtener datos actuales de enrichment

Lee el último mapped y raw por código de integración

Códigos de Integración Comunes

Argentina

ar_repet_enrichment - Datos oficiales de personas de REPET
ar_renaper_enrichment - Registro nacional de identidad
ar_bcra_enrichment - Datos financieros del banco central
ar_bcra_deudas_enrichment - Información de deudas del banco central
ar_afip_enrichment - Datos de la autoridad fiscal
ar_nosis_enrichment - Reporte del buró de crédito

Brasil

br_serasa_enrichment - Datos de crédito Serasa
br_spc_enrichment - Buró de crédito SPC
br_receita_federal_enrichment - Datos de la receita federal
br_cpf_enrichment - Validación y datos de CPF
br_cnpj_enrichment - Datos de empresa CNPJ

Global

global_worldcheck_enrichment - Screening de sanciones y PEP
global_dowjones_enrichment - Datos de riesgo y compliance

Consulta Códigos de Proveedores de Integración para la lista completa.

Casos de Uso

Onboarding KYC/KYB

Obtén datos oficiales de identidad y empresa durante el onboarding de clientes:

const result = await enrichEntity(customerId, [
  'ar_repet_enrichment',
  'ar_renaper_enrichment'
]);

Evaluación de Crédito

Obtén datos financieros y de crédito para evaluación de riesgo:

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

Screening de Compliance

Screening de sanciones, status PEP y medios adversos:

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

Monitoreo Continuo

Actualiza periódicamente los datos de entidades para monitoreo continuo:

// Ejecutar mensualmente
const result = await enrichEntity(entityId, [
  'ar_bcra_deudas_enrichment',
  'ar_afip_enrichment'
]);

Mejores Prácticas

1. Agrupa Enriquecimientos Relacionados

Ejecuta enriquecimientos relacionados juntos para mejor rendimiento:

// Bueno - agrupa enriquecimientos relacionados
await enrichEntity(id, [
  'ar_repet_enrichment',
  'ar_renaper_enrichment',
  'ar_bcra_enrichment'
]);

// Menos óptimo - llamadas separadas
await enrichEntity(id, ['ar_repet_enrichment']);
await enrichEntity(id, ['ar_renaper_enrichment']);
await enrichEntity(id, ['ar_bcra_enrichment']);

2. Maneja Fallos Parciales

Verifica resultados individuales ya que algunos proveedores pueden fallar mientras otros tienen éxito:

const result = await enrichEntity(id, providers);

result.results.forEach(r => {
  if (r.success) {
    // Procesar enriquecimiento exitoso
    console.log(`✓ ${r.integrationName}`);
  } else {
    // Registrar enriquecimiento fallido
    console.warn(`✗ ${r.integrationName}: ${r.error.message}`);
  }
});

3. Rastrea Costos

Monitorea los costos de enriquecimiento para optimizar el uso de tus integraciones:

const result = await enrichEntity(id, providers);

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

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

4. Usa IDs Externos para Conveniencia

Si trabajas con tus propios identificadores, usa el endpoint de ID externo:

// Más simple - usa tu ID
await enrichEntityByExternalId('customer_12345', providers);

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

5. Aprovecha las Métricas de Calidad

Usa los puntajes de completitud y confianza para evaluar la calidad de los datos:

result.results.forEach(r => {
  if (r.success) {
    const quality = r.result.dataQuality;

    if (quality.completeness < 0.5) {
      console.warn('Baja completitud de datos');
    }

    if (quality.confidence < 0.8) {
      console.warn('Baja confianza - se recomienda revisión manual');
    }
  }
});

Manejo de Errores

Los enriquecimientos pueden fallar por varias razones:

Entidad No Encontrada

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entidad no encontrada"
  }
}

Errores de Proveedor

Los fallos individuales de proveedores no fallan todo el lote:

{
  "success": true,
  "results": [
    {
      "success": false,
      "error": {
        "code": "NO_DATA_FOUND",
        "message": "No se encontraron datos para esta entidad"
      }
    }
  ]
}

Límite de Tasa

Algunos proveedores tienen límites de tasa - los fallos incluyen información de reintento:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Límite de tasa del proveedor excedido",
    "retryAfter": 3600
  }
}

Próximos Pasos

Explora Ejecutar por ID para enriquecimiento basado en UUID interno
Aprende sobre Ejecutar por ID Externo para integración simplificada
Leé Fallbacks del Marketplace — sustitutos en pipelines automáticos, no en execute manual
Leé el dossier normalizado persistido o los datos actuales mapped/raw
Navega Códigos de Proveedores para ver todos los enriquecimientos disponibles
Configura Reglas para automatizar acciones después del enriquecimiento

​¿Qué es el Enriquecimiento?

​Cómo Funciona

​Características Clave

​Ejecución por Lotes

​Transparencia de Costos

​Métricas de Calidad

​Registro de Auditoría Automático

​Integración con Motor de Reglas

​Fallbacks del Marketplace

​No hace falta activarlos en Marketplace

​Cuándo corren

​Cómo configurar la cadena

​Endpoints Disponibles

Ejecutar por ID Interno

Ejecutar por ID Externo

Obtener enrichment normalizado

Obtener datos actuales de enrichment

​Códigos de Integración Comunes

​Argentina

​Brasil

​Global

​Casos de Uso

​Onboarding KYC/KYB

​Evaluación de Crédito

​Screening de Compliance

​Monitoreo Continuo

​Mejores Prácticas

​1. Agrupa Enriquecimientos Relacionados

​2. Maneja Fallos Parciales

​3. Rastrea Costos

​4. Usa IDs Externos para Conveniencia

​5. Aprovecha las Métricas de Calidad

​Manejo de Errores

​Entidad No Encontrada

​Errores de Proveedor

​Límite de Tasa

​Próximos Pasos