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

# Ejecutar Enriquecimiento por ID de Entidad

> Ejecuta integraciones de enriquecimiento del marketplace en una entidad usando su ID interno — usando proveedores marketplace de gu1 para KYC, KYB y datos PEP.

## Descripción General

Ejecuta una o más integraciones de enriquecimiento del marketplace en una entidad específica para recopilar datos adicionales de proveedores externos. Este endpoint acepta el UUID interno de la entidad y soporta la ejecución en lote de múltiples enriquecimientos en una sola solicitud.

**Nota:** `enrichmentGroupRefs` aplica solo a esta API de ejecución del marketplace (y a `POST .../enrichment-by-external-id`). Los flujos de **creación de entidades** (manual o automática) siguen aceptando solo códigos de enriquecimiento explícitos, no slugs de grupo.

## Endpoint

```
POST http://api.gu1.ai/integration-execution/marketplace/enrichment
```

## Autenticación

Requiere una clave API válida en el encabezado de autorización:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Cuerpo de la Solicitud

<ParamField body="entityId" type="string" required>
  El UUID de la entidad a enriquecer
</ParamField>

<ParamField body="integrationCodes" type="array<string>">
  Lista explícita de códigos de integración de enriquecimiento a ejecutar (misma semántica que antes). Ver [Códigos de Proveedores de Integración](/es/api-reference/integrations/provider-codes).

  Podés enviar **solo `integrationCodes`**, **solo `enrichmentGroupRefs`** o **ambos**. Si enviás ambos, la API expande los grupos a códigos, concatena `integrationCodes` y **deduplica** manteniendo el orden de primera aparición. Al menos uno de `integrationCodes` o `enrichmentGroupRefs` debe ser no vacío.
</ParamField>

<ParamField body="enrichmentGroupRefs" type="array<string>">
  Referencias a **grupos de enriquecimiento** definidos para tu organización en el Marketplace (lista guardada de códigos de integración). Cada valor es el **slug del grupo** o el **UUID del grupo**.

  Se respeta el orden: por cada referencia se agregan los códigos del grupo en el orden guardado; luego se fusionan los `integrationCodes`. Expandir grupos **no** saltea el catálogo ni las reglas de org: cada código resultante sigue siendo evaluado por el orquestador (p. ej. debe estar habilitado para la organización salvo rutas de fallback específicas), igual que si pasaras los códigos directamente.
</ParamField>

<ParamField body="parameters" type="object">
  Parámetros adicionales opcionales para pasar a las integraciones
</ParamField>

## Respuesta

<ResponseField name="success" type="boolean">
  Si la operación de enriquecimiento en lote se completó exitosamente
</ResponseField>

<ResponseField name="entityId" type="string">
  El UUID de la entidad enriquecida
</ResponseField>

<ResponseField name="results" type="array">
  Array de resultados de enriquecimiento, uno por cada código de integración

  Cada resultado contiene:

  * `success` (boolean) - Si este enriquecimiento específico tuvo éxito
  * `enrichmentId` (string) - UUID del registro de ejecución del enriquecimiento
  * `integrationCode` (string) - El código de integración que fue ejecutado
  * `integrationName` (string) - Nombre legible de la integración
  * `result` (object) - Datos de enriquecimiento (solo si fue exitoso)
    * `fieldsEnriched` (array) - Lista de campos de entidad que fueron enriquecidos
    * `dataQuality` (object) - Métricas de calidad
      * `completeness` (number) - Puntuación de completitud de datos (0-1)
      * `confidence` (number) - Puntuación de confianza (0-1)
    * `summary` (string) - Resumen legible
    * `enrichmentData` (object) - Los datos de enriquecimiento reales
  * `executionTime` (number) - Tiempo de ejecución en milisegundos
  * `costCents` (number) - Costo de este enriquecimiento en centavos
  * `error` (object) - Detalles del error (solo si falló)
    * `code` (string) - Código de error
    * `message` (string) - Mensaje de error
</ResponseField>

<ResponseField name="totalCostCents" type="number">
  Costo total de todos los enriquecimientos en centavos
</ResponseField>

<ResponseField name="totalExecutionTime" type="number">
  Tiempo total de ejecución para todos los enriquecimientos en milisegundos
</ResponseField>

## Ejemplos

### Ejecutar un Solo Enriquecimiento

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST http://api.gu1.ai/integration-execution/marketplace/enrichment \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "integrationCodes": ["ar_repet_enrichment"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'http://api.gu1.ai/integration-execution/marketplace/enrichment',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        entityId: '550e8400-e29b-41d4-a716-446655440000',
        integrationCodes: ['ar_repet_enrichment']
      })
    }
  );

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'http://api.gu1.ai/integration-execution/marketplace/enrichment',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'entityId': '550e8400-e29b-41d4-a716-446655440000',
          'integrationCodes': ['ar_repet_enrichment']
      }
  )

  result = response.json()
  print(result)
  ```
</CodeGroup>

### Ejecutar Múltiples Enriquecimientos (Lote)

```bash theme={null}
curl -X POST http://api.gu1.ai/integration-execution/marketplace/enrichment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationCodes": [
      "ar_repet_enrichment",
      "ar_bcra_enrichment",
      "ar_nosis_enrichment"
    ]
  }'
```

### Ejemplo de Respuesta - Enriquecimiento Exitoso

```json theme={null}
{
  "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "success": true,
      "enrichmentId": "enr_abc123def456",
      "integrationCode": "ar_repet_enrichment",
      "integrationName": "Argentina REPET Person Data",
      "result": {
        "fieldsEnriched": [
          "name",
          "taxId",
          "address",
          "legalStatus"
        ],
        "dataQuality": {
          "completeness": 0.95,
          "confidence": 0.92
        },
        "summary": "Successfully enriched person data from REPET",
        "enrichmentData": {
          "name": "María González",
          "taxId": "20-12345678-9",
          "address": {
            "street": "Av. Corrientes 1234",
            "city": "Buenos Aires",
            "province": "CABA",
            "country": "AR"
          },
          "legalStatus": "active"
        }
      },
      "executionTime": 1250,
      "costCents": 50
    }
  ],
  "totalCostCents": 50,
  "totalExecutionTime": 1250
}
```

### Ejemplo de Respuesta - Lote con Resultados Mixtos

```json theme={null}
{
  "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "success": true,
      "enrichmentId": "enr_abc123",
      "integrationCode": "ar_repet_enrichment",
      "integrationName": "Argentina REPET Person Data",
      "result": {
        "fieldsEnriched": ["name", "taxId"],
        "dataQuality": {
          "completeness": 0.85,
          "confidence": 0.90
        },
        "summary": "Data enriched successfully",
        "enrichmentData": {
          "name": "María González",
          "taxId": "20-12345678-9"
        }
      },
      "executionTime": 1200,
      "costCents": 50
    },
    {
      "success": false,
      "integrationCode": "ar_bcra_enrichment",
      "integrationName": "Argentina BCRA Financial Data",
      "executionTime": 800,
      "costCents": 0,
      "error": {
        "code": "NO_DATA_FOUND",
        "message": "No financial data found for this entity"
      }
    },
    {
      "success": true,
      "enrichmentId": "enr_xyz789",
      "integrationCode": "ar_nosis_enrichment",
      "integrationName": "Argentina Nosis Credit Report",
      "result": {
        "fieldsEnriched": ["creditScore", "riskLevel"],
        "dataQuality": {
          "completeness": 1.0,
          "confidence": 0.95
        },
        "summary": "Credit report retrieved",
        "enrichmentData": {
          "creditScore": 720,
          "riskLevel": "low"
        }
      },
      "executionTime": 1500,
      "costCents": 75
    }
  ],
  "totalCostCents": 125,
  "totalExecutionTime": 3500
}
```

## Respuestas de Error

### 404 Entidad No Encontrada

```json theme={null}
{
  "success": false,
  "results": [],
  "totalCostCents": 0,
  "totalExecutionTime": 0,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found"
  }
}
```

### 401 No Autorizado

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_ORGANIZATION",
    "message": "Organization ID is required"
  }
}
```

### 400 Solicitud Incorrecta

```json theme={null}
{
  "success": false,
  "results": [],
  "totalCostCents": 0,
  "totalExecutionTime": 0,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one integration code is required"
  }
}
```

## Casos de Uso

### Enriquecimiento de Datos KYC

Enriquecer una entidad de persona con datos oficiales del gobierno:

```javascript theme={null}
const enrichmentResult = await fetch(
  'http://api.gu1.ai/integration-execution/marketplace/enrichment',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityId: customerId,
      integrationCodes: [
        'ar_repet_enrichment',  // Official identity data
        'ar_renaper_enrichment' // National registry
      ]
    })
  }
).then(res => res.json());

if (enrichmentResult.success) {
  console.log('Customer data enriched');
  console.log('Total cost:', enrichmentResult.totalCostCents / 100, 'USD');

  // Check each enrichment result
  enrichmentResult.results.forEach(result => {
    if (result.success) {
      console.log(`✓ ${result.integrationName} completed`);
    } else {
      console.log(`✗ ${result.integrationName} failed: ${result.error?.message}`);
    }
  });
}
```

### Debida Diligencia de Empresa

Recopilar datos completos de empresa desde múltiples fuentes:

```python theme={null}
enrichment_data = requests.post(
    'http://api.gu1.ai/integration-execution/marketplace/enrichment',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'entityId': company_id,
        'integrationCodes': [
            'ar_afip_enrichment',      # Tax authority data
            'ar_bcra_enrichment',      # Central bank data
            'ar_commercial_registry'    # Commercial registry
        ]
    }
).json()

# Process successful enrichments
successful = [r for r in enrichment_data['results'] if r['success']]
failed = [r for r in enrichment_data['results'] if not r['success']]

print(f"Completed: {len(successful)}/{len(enrichment_data['results'])}")
print(f"Total cost: ${enrichment_data['totalCostCents'] / 100:.2f}")
```

## Notas Importantes

* **Ejecución en Lote**: Múltiples enriquecimientos se ejecutan en paralelo para mejor rendimiento
* **Seguimiento de Costos**: El costo de cada enriquecimiento se rastrea individualmente y se suma en `totalCostCents`
* **Éxito Parcial**: El lote puede tener éxito incluso si algunos enriquecimientos individuales fallan
* **Auditoría Automática**: Todos los enriquecimientos se registran automáticamente en el registro de auditoría
* **Activación de Reglas**: Los enriquecimientos exitosos activan el motor de reglas con el evento `enrichment_completed`
* **Idempotencia**: Ejecutar el mismo enriquecimiento múltiples veces puede devolver resultados en caché a menos que se use `forceRefresh`

## Endpoints Relacionados

* [Ejecutar Enriquecimiento por ID Externo](/es/api-reference/enrichment/execute-by-external-id) - Usa tu propio identificador de entidad
* [Obtener Entidad](/es/api-reference/entities/get) - Ver datos de entidad enriquecida
* [Listar Proveedores de Integración](/es/api-reference/integrations/provider-codes) - Códigos de enriquecimiento disponibles