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

> Actualizar una entidad usando tu identificador externo en lugar del UUID interno — para entidades de empresa en la plataforma de riesgo y compliance gu1.

## Descripción general

Este endpoint te permite actualizar una entidad usando tu propio identificador externo en lugar de nuestro UUID interno. Esto 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="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`: La entidad está activa y operativa
  * `inactive`: La entidad está inactiva
  * `blocked`: La entidad está bloqueada (requiere `reason`)
  * `suspended`: La entidad está suspendida (requiere `reason`)
  * `rejected`: La entidad fue rechazada durante la incorporación (requiere `reason`)

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

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

<ParamField body="riskMatrixId" type="string (uuid)">
  ID de matriz de riesgo para asignar a esta entidad. La matriz de riesgo determina qué reglas se ejecutarán para la evaluación de riesgo.
</ParamField>

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

  **Campos de persona**:

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

  **Campos de empresa**:

  * `legalName`: Nombre legal de la empresa
  * `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 de entidad
</ParamField>

<ParamField body="metadata" type="object">
  Metadatos del sistema (generalmente establecidos por el sistema, pero se pueden actualizar)
</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 fines de auditoría)
</ResponseField>

## Ejemplo de solicitud

```bash theme={null}
curl -X PATCH https://api.gueno.ai/entities/by-external-id/customer-12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Michael Doe",
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "John",
        "middleName": "Michael",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1-555-0123"
      }
    },
    "riskMatrixId": "matrix-uuid-here"
  }'
```

## Ejemplo de respuesta

```json theme={null}
{
  "entity": {
    "id": "entity-uuid",
    "organizationId": "org-uuid",
    "externalId": "customer-12345",
    "type": "person",
    "name": "John Michael Doe",
    "taxId": "123-45-6789",
    "countryCode": "US",
    "nationality": "US",
    "status": "active",
    "riskScore": "35.00",
    "riskMatrixId": "matrix-uuid-here",
    "entityData": {
      "person": {
        "firstName": "John",
        "middleName": "Michael",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "phone": "+1-555-0123"
      }
    },
    "createdAt": "2025-12-20T10:00:00Z",
    "updatedAt": "2025-12-24T15:30:00Z"
  },
  "evaluation": null,
  "previousEntity": {
    "id": "entity-uuid",
    "name": "John Doe",
    "status": "pending",
    ...
  }
}
```

## Cambio de estado con razón

Al cambiar el estado a `blocked`, `suspended` o `rejected`, **debes** proporcionar una razón:

```bash theme={null}
curl -X PATCH https://api.gueno.ai/entities/by-external-id/customer-12345 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "blocked",
    "reason": "Failed sanctions screening - OFAC match detected"
  }'
```

## 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": "Jane Smith-Johnson",
  "entityData": {
    "person": {
      "lastName": "Smith-Johnson",
      "email": "jane.smithjohnson@example.com",
      "address": {
        "street": "456 New St",
        "city": "Seattle",
        "state": "WA",
        "country": "US",
        "postalCode": "98101"
      }
    }
  }
}
```

### 2. Asignar matriz de riesgo

Asignar o cambiar la matriz de riesgo para una entidad:

```json theme={null}
{
  "riskMatrixId": "high-risk-matrix-uuid"
}
```

Después de actualizar la matriz de riesgo, debes activar un nuevo 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": "Investigation revealed connections to sanctioned entities"
}
```

### 4. Sincronizar datos de la empresa

Actualizar información de la empresa desde el registro mercantil:

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

## Eventos y Webhooks

### Eventos en tiempo real

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

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

### Activadores de Webhook

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

**Evento**: `entity.status_changed`

```json theme={null}
{
  "event": "entity.status_changed",
  "entityId": "entity-uuid",
  "externalId": "customer-12345",
  "oldStatus": "active",
  "newStatus": "blocked",
  "reason": "Failed sanctions screening",
  "changedBy": "user-uuid",
  "timestamp": "2025-12-24T15:30:00Z"
}
```

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

## Pista de auditoría

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

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

Consultar pista 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">
  Intento de cambiar campos inmutables

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

## Mejores prácticas

1. **Establece siempre ID externo en la creación**: Establece `externalId` al crear entidades a través de `POST /entities` para habilitar actualizaciones por ID externo.

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

3. **Proporciona razones para cambios de estado**: Siempre incluye razones significativas al bloquear, suspender o rechazar entidades para la pista de auditoría de cumplimiento.

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

5. **Maneja 404 con elegancia**: Si la entidad no se encuentra por ID externo, es posible que debas crearla primero usando `POST /entities`.

6. **Actualizaciones por lotes**: Para actualizar múltiples entidades, llama a este endpoint de forma concurrente con diferentes IDs externos para un 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) - Recuperar detalles de entidad
* [Analizar entidad](/en/api-reference/entities/analyze) - Activar análisis de riesgo