Skip to main content
PATCH
Actualizar una persona por ID externo

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

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: 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.
string
Requerido al cambiar el estado a blocked, suspended o rejected. Proporciona un registro de auditoría para el cambio de estado.
string (uuid)
ID de la matriz de riesgo a 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 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
object
Atributos personalizados clave-valor para almacenamiento flexible de datos
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.
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 auditoría)

Ejemplo de Solicitud

Ejemplo de Respuesta

Cambio de Estado con Motivo

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

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 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:

4. Sincronizar Datos de Empresa

Actualizar información de empresa desde el registro empresarial:

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:

Disparadores de Webhook

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

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
Intentando cambiar campos inmutables

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