Skip to main content
PATCH
/
entities
/
by-external-id
/
:externalId
Actualizar 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>",
  "nationality": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": {},
  "entityData": {},
  "attributes": {},
  "metadata": {}
}
'
{
  "entity": {},
  "evaluation": {},
  "previousEntity": {},
  "404 Not Found": {},
  "400 Bad Request": {}
}

​
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

​
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.)
​
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: 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.
​
reason
string
Requerido al cambiar el estado a blocked, suspended o rejected. Proporciona una pista de auditoría para el cambio de estado.
​
riskMatrixId
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.
​
entityData
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
​
attributes
object
Atributos personalizados clave-valor para almacenamiento flexible de datos de entidad
​
metadata
object
Metadatos del sistema (generalmente establecidos por el sistema, pero se pueden actualizar)

​
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 fines de auditoría)

​
Ejemplo de solicitud

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

{
  "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: 
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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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 
{
  "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: 
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
Intento de cambiar campos inmutables
{
  "error": "Field 'type' cannot be changed after entity creation"
}

​
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