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

# Actualizar entidad (refresh)

> Re-ejecutar enrichments en una entidad existente con recursión opcional de socios y motor de reglas — scope unificado y flags preserve para nombre y ficha.

## Descripción

Re-ejecuta enrichments del marketplace para una **persona** o **empresa** existente, opcionalmente:

* Actualiza el **nombre** y/o **`entityData`** (solo si lo indicás con los nuevos flags)
* Crea o re-enriquece **socios** (empresas, `depth` > 0)
* Ejecuta el **motor de reglas** al finalizar

Equivalente programático al refresh completo del panel (Risk Matrix) o al refresh **solo datos básicos** del Entity Builder.

<Note>
  **Retrocompatibilidad:** Si omitís `refreshScope`, `preserveName` y `preserveEntityData`, el comportamiento es el de siempre: la selección de proveedores sigue `autoExecuteIntegrations` y el **nombre** se sincroniza desde `fullName` normalizado cuando cambia. **`entityData` no se modifica** salvo `refreshScope: "basic_data"` con `preserveEntityData`.
</Note>

## Endpoint

```
POST http://api.gu1.ai/entities/{entityId}/refresh
```

## Autenticación

Requiere permiso para ejecutar enrichments (igual que `POST /entities/{entityId}/enrich`).

## Parámetros de ruta

<ParamField path="entityId" type="string" required>
  UUID de la entidad a actualizar.
</ParamField>

## Cuerpo

<ParamField body="forceRefresh" type="boolean" default="true">
  Si es `true`, omite caché y vuelve a llamar a los proveedores.
</ParamField>

<ParamField body="skipRulesEngine" type="boolean" default="false">
  Si es `true`, no ejecuta reglas después del enrichment.
</ParamField>

<ParamField body="depth" type="integer" default="1">
  Profundidad de socios (**0–5**). Ignorado con `refreshScope: "basic_data"` (siempre **0**).
</ParamField>

<ParamField body="autoExecuteIntegrations" type="object">
  Selección **legacy** de proveedores (cuando `refreshScope` se omite). Misma forma que [`POST /entities/automatic`](/es/api-reference/entities/create-automatic).
</ParamField>

<ParamField body="autoExecuteIntegrationsShareholders" type="object">
  Pipeline de socios (empresas, `depth` > 0). Misma forma que creación automática.
</ParamField>

<ParamField body="refreshScope" type="string">
  Scope unificado opcional. Si está presente, **reemplaza** `autoExecuteIntegrations` en la entidad raíz:

  | Valor            | Comportamiento                                                           |
  | ---------------- | ------------------------------------------------------------------------ |
  | **`basic_data`** | Un solo proveedor de datos básicos del país (llamada fresh). Sin socios. |
  | **`all_active`** | Todos los enrichments activos para tipo y país.                          |
  | **`selected`**   | Lista explícita en `providerCodes` (obligatorio, no vacío).              |
</ParamField>

<ParamField body="providerCodes" type="array">
  Obligatorio cuando `refreshScope` es **`selected`**.
</ParamField>

<ParamField body="preserveName" type="boolean">
  * **`true`**: conservar el nombre actual.
  * **`false`**: sincronizar desde mapeo (`basic_data`) o `fullName` normalizado.
  * **Omitido (legacy)**: sincronizar nombre si `fullName` cambió (comportamiento anterior).
</ParamField>

<ParamField body="preserveEntityData" type="boolean">
  Solo con `refreshScope: "basic_data"` y enrichment exitoso:

  * **Omitido**: no tocar `entityData`.
  * **`true`**: completar solo campos vacíos (gap-fill).
  * **`false`**: reemplazar `entityData` desde datos básicos.

  Sin efecto en `all_active`, `selected` o bodies legacy sin `basic_data`.
</ParamField>

## Ejemplos

### Refresh legacy (sin cambios)

```bash theme={null}
curl -X POST http://api.gu1.ai/entities/{entityId}/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skipRulesEngine": false,
    "depth": 1,
    "forceRefresh": true,
    "autoExecuteIntegrations": { "executeAllActiveEnrichments": true },
    "autoExecuteIntegrationsShareholders": { "executeAllActiveEnrichments": true }
  }'
```

### Solo datos básicos (seguro)

```bash theme={null}
curl -X POST http://api.gu1.ai/entities/{entityId}/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refreshScope": "basic_data",
    "preserveName": true,
    "skipRulesEngine": true,
    "forceRefresh": true
  }'
```

## Respuesta

Incluye `data.entity`, `data.enrichmentResult`, contadores de socios y `errors`. Con `skipRulesEngine: false`, también **`rulesExecutionSummary`** en la raíz (igual que [Analyze](/es/api-reference/entities/analyze)).

## Eventos Socket.IO

`entity:refresh-started`, `entity:refreshed`, `entity:refresh-failed`.

## Endpoints relacionados

<CardGroup cols={2}>
  <Card title="Analyze" icon="chart-line" href="/es/api-reference/entities/analyze">
    Motor de reglas (enrichment opcional).
  </Card>

  <Card title="Materializar relaciones" icon="sitemap" href="/es/api-reference/entities/materialize-relationships">
    Cadena de socios desde normalized.
  </Card>
</CardGroup>