Skip to main content
PATCH
/
entities
/
by-external-id
/
:externalId
Actualizar una entidad por ID externo
curl --request PATCH \
  --url http://api.gu1.ai/entities/by-external-id/:externalId \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "email": {},
  "phone": {},
  "nationality": {},
  "status": "<string>",
  "reason": "<string>",
  "changeStatusManual": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "entityData": {},
  "attributes": {},
  "metadata": {}
}
'
{
  "entity": {},
  "evaluation": {},
  "previousEntity": {},
  "404 Not Found": {},
  "400 Bad Request": {}
}

​
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

​
externalId
string
required
Tu identificador externo único para la entidad

​
Cuerpo de la Solicitud

​
name
string
Nombre de la entidad (nombre completo de persona o nombre de empresa)
​
taxId
string
Número de identificación fiscal (SSN, EIN, VAT, RFC, etc.)
​
email
string | null
Correo de contacto en la raíz de la entidad. Omite para no cambiar; null lo borra.
​
phone
string | null
Teléfono de contacto en la raíz de la entidad. Omite para no cambiar; null lo borra.
​
nationality
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.
​
status
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.
​
reason
string
Requerido al cambiar el estado a blocked, suspended o rejected. Proporciona un registro de auditoría para el cambio de estado.
​
changeStatusManual
boolean
default:"false"
Misma semántica que Actualizar entidad por ID. Con true, reglas de matriz y automatizaciones no pueden cambiar status.
​
riskMatrixId
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.
​
riskMatrixIds
string[]
Forma preferida para varias matrices: lista ordenada de UUIDs de tu organización. Enviá [] para desasignar todas.
​
entityData
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
​
attributes
object
Atributos personalizados clave-valor para almacenamiento flexible de datos
​
metadata
object
Metadatos del sistema (generalmente establecidos por el sistema, pero pueden actualizarse)

​
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.
​
entity
object
El objeto de entidad actualizado con todos los valores actuales
​
evaluation
object | null
Objeto de evaluación (actualmente null - función de re-evaluación temporalmente deshabilitada)
​
previousEntity
object
El estado de la entidad antes de la actualización (para auditoría)

​
Ejemplo de Solicitud

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

{
  "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: 
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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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 
{
  "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: 
GET /entity-events?entityId=:entityId&eventType=ATTRIBUTE_CHANGED

​
Respuestas de Error

​
404 Not Found
error
Entidad con el externalId especificado no encontrada en tu organización
{
  "error": "Entity not found"
}
​
400 Bad Request
error
Datos de solicitud inválidos o error de validación
{
  "error": "Changing status to 'blocked' requires a reason for audit purposes."
}
​
400 Bad Request
error
Intentando cambiar campos inmutables
{
  "error": "Field 'type' cannot be changed after entity creation"
}

​
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