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

> Ejecuta integraciones de enriquecimiento del marketplace en una entidad usando su identificador externo. Consulta el esquema del request, códigos de respuesta.

## Descripción General

Ejecuta una o más integraciones de enriquecimiento del marketplace en una entidad específica usando su identificador externo. Este endpoint primero busca la entidad por su externalId, luego ejecuta los enriquecimientos. Es idéntico al endpoint por ID pero más conveniente cuando usa sus propios identificadores de entidad.

**Nota:** `enrichmentGroupRefs` aplica solo a esta API de ejecución del marketplace (y a `POST .../marketplace/enrichment` por UUID de entidad). La **creación de entidades** (manual o automática) sigue usando solo códigos explícitos, no slugs de grupo.

## Endpoint

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

## 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="externalId" type="string" required>
  Su identificador externo para la entidad (por ejemplo, su ID de cliente, ID de usuario, etc.)
</ParamField>

<ParamField body="integrationCodes" type="array<string>">
  Lista explícita de códigos de integración de enriquecimiento a ejecutar. 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** configurados para tu organización en el Marketplace. Cada valor es el **slug del grupo** o el **UUID del grupo**. El servidor reemplaza cada referencia por los códigos guardados en ese grupo (en orden) y luego fusiona los `integrationCodes`. Cada código sigue sujeto a las mismas reglas del orquestador que una solicitud directa (tipo de catálogo, habilitación en la org, bloqueos, etc.).
</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 interno resuelto de la entidad enriquecida
</ResponseField>

<ResponseField name="externalId" type="string">
  El ID externo que se usó para buscar la entidad
</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 '{
      "externalId": "customer_12345",
      "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({
        externalId: 'customer_12345',
        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={
          'externalId': 'customer_12345',
          '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 '{
    "externalId": "customer_12345",
    "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",
  "externalId": "customer_12345",
  "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",
  "externalId": "customer_12345",
  "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