> ## 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 una entidad por ID externo

> Actualiza una entidad de gu1 usando tu identificador externo en lugar del UUID interno, cubriendo empresas, personas y transacciones en una sola llamada.

## Resumen

Este endpoint te permite actualizar una entidad usando tu propio identificador externo en lugar de nuestro UUID interno. Es útil cuando no almacenas nuestros UUIDs en tu sistema y solo rastreas tus propios IDs externos.

La funcionalidad es idéntica a `PATCH /entities/:id`, pero usa `externalId` como identificador.

## Parámetros de Ruta

<ParamField path="externalId" type="string" required>
  Tu identificador externo único para la entidad
</ParamField>

## Cuerpo de la Solicitud

<ParamField body="name" type="string">
  Nombre de la entidad (nombre completo de persona o nombre de empresa)
</ParamField>

<ParamField body="taxId" type="string">
  Número de identificación fiscal (SSN, EIN, VAT, RFC, etc.)
</ParamField>

<ParamField body="email" type="string | null">
  Correo de contacto en la raíz de la entidad. Omite para no cambiar; `null` lo borra.
</ParamField>

<ParamField body="phone" type="string | null">
  Teléfono de contacto en la raíz de la entidad. Omite para no cambiar; `null` lo borra.
</ParamField>

<ParamField body="nationality" type="string | null">
  Nacionalidad en la raíz (ISO 3166-1 alfa-2 al persistir). Omite para no cambiar; `null` la borra. Si actualizas `nationality` dentro de `entityData` en el mismo request, la raíz puede recalcularse.
</ParamField>

<ParamField body="status" type="string">
  Estado de la entidad. Valores posibles:

  * `active`: Entidad está activa y operativa
  * `inactive`: Entidad está inactiva
  * `blocked`: Entidad está bloqueada (requiere `reason`)
  * `suspended`: Entidad está suspendida (requiere `reason`)
  * `rejected`: Entidad fue rechazada durante el onboarding (requiere `reason`)

  **Nota**: Cambiar a `blocked`, `suspended` o `rejected` requiere proporcionar un `reason` para auditoría.
</ParamField>

<ParamField body="reason" type="string">
  Requerido al cambiar el estado a `blocked`, `suspended` o `rejected`. Proporciona un registro de auditoría para el cambio de estado.
</ParamField>

<ParamField body="changeStatusManual" type="boolean" default="false">
  Misma semántica que [Actualizar entidad por ID](/es/api-reference/entities/update#param-change-status-manual). Con `true`, reglas de matriz y automatizaciones no pueden cambiar `status`.
</ParamField>

<ParamField body="riskMatrixId" type="string | string[] | null">
  Legacy: un UUID, un array de UUIDs o `null` para quitar todas las matrices. Si `riskMatrixIds` viene no vacío, tiene precedencia. Ver [Actualizar entidad — Matrices de riesgo](/es/api-reference/entities/update#matrices-de-riesgo).
</ParamField>

<ParamField body="riskMatrixIds" type="string[]">
  Forma preferida para **varias** matrices: lista ordenada de UUIDs de tu organización. Enviá `[]` para desasignar todas.
</ParamField>

<ParamField body="entityData" type="object">
  Estructura de datos específica de la entidad. Para entidades de persona, usa `entityData.person`. Para entidades de empresa, usa `entityData.company`.

  **Campos de persona**:

  * `firstName`: Nombre
  * `lastName`: Apellido
  * `middleName`: Segundo nombre
  * `dateOfBirth`: Fecha de nacimiento (YYYY-MM-DD)
  * `nationality`: Nacionalidad (ISO 3166-1 alpha-2)
  * `email`: Correo electrónico
  * `phone`: Teléfono
  * `address`: Objeto de dirección (street, city, state, country, postalCode)

  **Campos de empresa**:

  * `legalName`: Razón social
  * `tradingNames`: Array de nombres comerciales
  * `registrationNumber`: Número de registro de la empresa
  * `incorporationDate`: Fecha de constitución (YYYY-MM-DD)
  * `industry`: Industria/sector
  * `employees`: Número de empleados
  * `website`: Sitio web de la empresa
  * `address`: Objeto de dirección
</ParamField>

<ParamField body="attributes" type="object">
  Atributos personalizados clave-valor para almacenamiento flexible de datos
</ParamField>

<ParamField body="metadata" type="object">
  Metadatos del sistema (generalmente establecidos por el sistema, pero pueden actualizarse)
</ParamField>

## Campos Inmutables

Los siguientes campos **no pueden** cambiarse después de la creación de la entidad:

* `type`: Tipo de entidad (person o company)
* `countryCode`: Código de país de la entidad (ISO 3166-1 alpha-2)

## Respuesta

Devuelve el objeto de entidad actualizado.

<ResponseField name="entity" type="object">
  El objeto de entidad actualizado con todos los valores actuales
</ResponseField>

<ResponseField name="evaluation" type="object | null">
  Objeto de evaluación (actualmente null - función de re-evaluación temporalmente deshabilitada)
</ResponseField>

<ResponseField name="previousEntity" type="object">
  El estado de la entidad antes de la actualización (para auditoría)
</ResponseField>

## Ejemplo de Solicitud

```bash theme={null}
curl -X PATCH https://api.gueno.ai/entities/by-external-id/cliente-12345 \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Miguel Pérez",
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "Juan",
        "middleName": "Miguel",
        "lastName": "Pérez",
        "email": "juan.perez@ejemplo.com",
        "phone": "+52-55-1234-5678"
      }
    },
    "riskMatrixIds": ["uuid-matriz-onboarding", "uuid-matriz-post-kyc"]
  }'
```

## Ejemplo de Respuesta

```json theme={null}
{
  "entity": {
    "id": "uuid-entidad",
    "organizationId": "uuid-org",
    "externalId": "cliente-12345",
    "type": "person",
    "name": "Juan Miguel Pérez",
    "taxId": "PERJ850315ABC",
    "countryCode": "MX",
    "nationality": "MX",
    "status": "active",
    "riskScore": "35.00",
    "riskMatrixIds": ["uuid-matriz-onboarding", "uuid-matriz-post-kyc"],
    "entityData": {
      "person": {
        "firstName": "Juan",
        "middleName": "Miguel",
        "lastName": "Pérez",
        "email": "juan.perez@ejemplo.com",
        "phone": "+52-55-1234-5678"
      }
    },
    "createdAt": "2025-12-20T10:00:00Z",
    "updatedAt": "2025-12-24T15:30:00Z"
  },
  "evaluation": null,
  "previousEntity": {
    "id": "uuid-entidad",
    "name": "Juan Pérez",
    "status": "pending",
    ...
  }
}
```

## Cambio de Estado con Motivo

Al cambiar el estado a `blocked`, `suspended` o `rejected`, **debes** proporcionar un motivo:

```bash theme={null}
curl -X PATCH https://api.gueno.ai/entities/by-external-id/cliente-12345 \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "blocked",
    "reason": "Falló el screening de sanciones - match detectado en lista OFAC"
  }'
```

## Casos de Uso

### 1. Actualizar Información del Cliente

Actualizar datos del cliente desde tu CRM o sistema de gestión de usuarios:

```json theme={null}
{
  "name": "María García López",
  "entityData": {
    "person": {
      "lastName": "García López",
      "email": "maria.garcialopez@ejemplo.com",
      "address": {
        "street": "Av. Reforma 456",
        "city": "Ciudad de México",
        "state": "CDMX",
        "country": "MX",
        "postalCode": "06600"
      }
    }
  }
}
```

### 2. Asignar Matriz de Riesgo

Asignar o cambiar la matriz de riesgo para una entidad:

```json theme={null}
{
  "riskMatrixIds": ["uuid-matriz-alto-riesgo"]
}
```

Después de actualizar la matriz de riesgo, debes activar un re-análisis usando `POST /entities/:entityId/analyze` para re-evaluar la entidad con las nuevas reglas.

### 3. Bloquear Entidad Después de Investigación

Bloquear una entidad después de una investigación de cumplimiento:

```json theme={null}
{
  "status": "blocked",
  "reason": "La investigación reveló conexiones con entidades sancionadas"
}
```

### 4. Sincronizar Datos de Empresa

Actualizar información de empresa desde el registro empresarial:

```json theme={null}
{
  "entityData": {
    "company": {
      "employees": 250,
      "revenue": 50000000,
      "website": "https://empresa-nuevo-dominio.com"
    }
  }
}
```

## Eventos y Webhooks

### Eventos en Tiempo Real

Después de una actualización exitosa, se emite el siguiente evento en tiempo real vía WebSocket:

```json theme={null}
{
  "event": "entity.updated",
  "entityId": "uuid-entidad",
  "externalId": "cliente-12345",
  "updatedFields": ["name", "entityData"],
  "previousValues": {...},
  "newValues": {...}
}
```

### Disparadores de Webhook

Si cambias **solo** el campo `status` (sin otros cambios de campo), se dispara un webhook:

**Evento**: `entity.status_changed`

```json theme={null}
{
  "event": "entity.status_changed",
  "entityId": "uuid-entidad",
  "externalId": "cliente-12345",
  "oldStatus": "active",
  "newStatus": "blocked",
  "reason": "Falló el screening de sanciones",
  "changedBy": "uuid-usuario",
  "timestamp": "2025-12-24T15:30:00Z"
}
```

**Nota**: Si actualizas el estado **junto con otros campos**, el webhook NO se dispara (asume edición masiva de entidad en lugar de cambio de estado independiente).

## Registro de Auditoría

Cada actualización de entidad crea un evento `ATTRIBUTE_CHANGED` en el registro de eventos de entidad con:

* Estado anterior (todos los campos cambiados)
* Estado posterior (todos los campos cambiados)
* Usuario que realizó el cambio
* Marca de tiempo
* Fuente (API, dashboard, etc.)

Consultar registro de auditoría:

```bash theme={null}
GET /entity-events?entityId=:entityId&eventType=ATTRIBUTE_CHANGED
```

## Respuestas de Error

<ResponseField name="404 Not Found" type="error">
  Entidad con el `externalId` especificado no encontrada en tu organización

  ```json theme={null}
  {
    "error": "Entity not found"
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Datos de solicitud inválidos o error de validación

  ```json theme={null}
  {
    "error": "Changing status to 'blocked' requires a reason for audit purposes."
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request" type="error">
  Intentando cambiar campos inmutables

  ```json theme={null}
  {
    "error": "Field 'type' cannot be changed after entity creation"
  }
  ```
</ResponseField>

## Mejores Prácticas

1. **Siempre Establece ID Externo en Creación**: Establece `externalId` al crear entidades vía `POST /entities` para habilitar actualizaciones por ID externo.

2. **Usa para Integración de Sistemas**: Este endpoint es ideal para integraciones donde sincronizas datos de sistemas externos (CRM, ERP, etc.) usando tus propios IDs.

3. **Proporciona Motivos para Cambios de Estado**: Siempre incluye motivos significativos al bloquear, suspender o rechazar entidades para el registro de auditoría de cumplimiento.

4. **Re-analiza Después de Cambiar Matriz de Riesgo**: Después de asignar una nueva matriz de riesgo, activa `POST /entities/:entityId/analyze` para re-evaluar con las nuevas reglas.

5. **Maneja 404 con Gracia**: Si la entidad no se encuentra por ID externo, puede que necesites crearla primero usando `POST /entities`.

6. **Actualizaciones en Lote**: Para actualizar múltiples entidades, llama este endpoint concurrentemente con diferentes IDs externos para mejor rendimiento.

## Endpoints Relacionados

* [Crear Entidad](/es/api-reference/entities/create) - Crear nueva entidad
* [Actualizar Entidad por UUID](/es/api-reference/entities/update) - Actualizar usando UUID interno
* [Obtener Entidad](/es/api-reference/entities/get) - Obtener detalles de entidad
* [Analizar Entidad](/en/api-reference/entities/analyze) - Activar análisis de riesgo