Skip to main content
PATCH
Actualizar entidad por ID externo

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

string
required
Tu identificador externo único para la entidad

Cuerpo de la solicitud

string
Nombre de la entidad (nombre completo de persona o nombre de empresa)
string
Número de identificación fiscal (SSN, EIN, VAT, RFC, etc.)
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.
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.
string
Requerido al cambiar el estado a blocked, suspended o rejected. Proporciona una pista de auditoría para el cambio de estado.
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.
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
object
Atributos personalizados clave-valor para almacenamiento flexible de datos de entidad
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.
object
El objeto de entidad actualizado con todos los valores actuales
object | null
Objeto de evaluación (actualmente null - función de re-evaluación temporalmente deshabilitada)
object
El estado de la entidad antes de la actualización (para fines de auditoría)

Ejemplo de solicitud

Ejemplo de respuesta

Cambio de estado con razón

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

Casos de uso

1. Actualizar información del cliente

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

2. Asignar matriz de riesgo

Asignar o cambiar la matriz de riesgo para una entidad:
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:

4. Sincronizar datos de la empresa

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

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:

Activadores de Webhook

Si cambias solo el campo status (sin otros cambios de campo), se activa un webhook: Evento: entity.status_changed
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:

Respuestas de error

error
Entidad con el externalId especificado no encontrada en tu organización
error
Datos de solicitud inválidos o error de validación
error
Intento de cambiar campos inmutables

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