Actualizar una entidad persona

Actualizar

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

PATCH

entities

{id}

Actualizar

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

Resumen

Actualiza los atributos y datos de una persona existente. Este endpoint activa automáticamente una reevaluación de la puntuación de riesgo de la persona y emite eventos de actualización en tiempo real.

Endpoint

PATCH http://api.gu1.ai/entities/{id}

Autenticación

Requiere una clave API válida en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

string

required

El ID de gu1 de la persona a actualizar

Cuerpo de la Solicitud

Todos los campos son opcionales - solo incluye los campos que deseas actualizar.

name

string

Actualizar el nombre para mostrar de la persona

El ID externo no se actualiza con este endpoint. Usa Cambiar ID externo (POST /entities/change-external-id) con reason obligatorio (mín. 5 caracteres).

taxId

string

Actualizar número de identificación fiscal

countryCode

string

Actualizar código de país ISO 3166-1 alpha-2

attributes

object

Actualizar atributos personalizados (se fusiona con atributos existentes)

entityData

object

Actualizar datos específicos de la persona (se fusiona con entityData existente)

status

string

Actualizar estado de la persona. Estados disponibles:

pending - Estado inicial, esperando procesamiento
under_review - Bajo revisión manual
active - Aprobada y activa
suspended - Suspendida temporalmente (requiere reason)
blocked - Bloqueada permanentemente (requiere reason)
rejected - Rechazada durante onboarding (requiere reason)

Nota: Los cambios de estado a suspended, blocked o rejected requieren un campo reason para fines de auditoría.

reason

string

Requerido al cambiar el estado a suspended, blocked o rejected. Proporciona pista de auditoría para cambios de estado.

riskMatrixId

string

UUID de la matriz de riesgo a asociar con esta persona. Actualiza qué reglas se utilizan para la evaluación de riesgo.

Respuesta

entity

object

El objeto de persona actualizado con todos los valores actuales

evaluation

object

Evaluación recién creada activada por la actualización

id - ID de evaluación
entityId - ID de entidad
decision - “PENDING” (esperando procesamiento)
evaluationType - “SYSTEM”
reasons - Array con “Re-evaluation triggered by attribute change”

previousEntity

object

El estado de la persona antes de la actualización (para auditoría/comparación)

Este endpoint no devuelve rulesResult ni rulesExecutionSummary. El motor de reglas no se ejecuta en la actualización; esos campos solo se devuelven en endpoints que ejecutan reglas (crear, crear-automático, enriquecer, refrescar, analizar).

Comportamiento

Cuando actualizas una persona, el sistema automáticamente:

Registra el cambio en el registro de eventos de entidad con una instantánea de antes/después
Activa reevaluación para recalcular la puntuación de riesgo basada en nuevos datos
Emite evento en tiempo real para notificar a clientes conectados de la actualización
Mantiene pista de auditoría para cumplimiento y revisión

Ejemplos

Actualizar Ingresos y Ocupación de Persona

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "person": {
        "income": 95000,
        "occupation": "Senior Software Engineer"
      }
    }
  }'

Actualizar Información de Contacto

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "person": {
        "email": "new.email@example.com",
        "phone": "+54 11 9876-5432",
        "address": "Av. Libertador 2500, Buenos Aires"
      }
    }
  }'

Actualizar Solo Atributos Personalizados

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "accountTier": "premium",
      "loyaltyPoints": 15000,
      "lastLoginDate": "2024-10-03T14:00:00Z"
    }
  }'

Actualizar Estado de Persona

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended",
    "reason": "Suspicious activity detected - pending investigation"
  }'

Ejemplo de Respuesta

{
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "person",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Senior Software Engineer",
        "income": 95000
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "accountTier": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T16:45:00.000Z",
    "deletedAt": null
  },
  "evaluation": {
    "id": "eval_new_123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "decision": "PENDING",
    "evaluationType": "SYSTEM",
    "reasons": ["Re-evaluation triggered by attribute change"],
    "rules": [],
    "entitySnapshot": {...}
  },
  "previousEntity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityData": {
      "person": {
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "updatedAt": "2024-10-03T14:35:00.000Z"
  }
}

Respuestas de Error

404 Not Found

{
  "error": "Entity not found"
}

400 Bad Request - Datos Inválidos

{
  "error": "Validation failed",
  "details": ["Invalid country code format"]
}

400 Bad Request - Falta Razón para Cambio de Estado

{
  "error": "Changing status to 'suspended' requires a reason for audit purposes."
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to update entity"
}

Casos de Uso

Actualizar Después de Verificación KYC

// Después de completar la verificación KYC, actualizar la persona
const response = await fetch(`http://api.gu1.ai/entities/${personId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attributes: {
      kycVerified: true,
      kycVerificationDate: new Date().toISOString(),
      kycProvider: 'manual_review'
    }
  })
});

Enriquecimiento Progresivo de Perfil

# Enriquecer perfil de cliente a medida que más información esté disponible
def update_customer_info(person_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{person_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'person': new_data
            },
            'attributes': {
                'lastDataUpdate': datetime.now().isoformat(),
                'dataCompleteness': calculate_completeness(new_data)
            }
        }
    )
    return response.json()

Mejores Prácticas

Actualizaciones Parciales: Solo envía los campos que deseas cambiar - no es necesario enviar la persona completa
Monitorear Reevaluaciones: Verifica el ID de evaluación devuelto para rastrear el recálculo de puntuación de riesgo
Pista de Auditoría: Usa el previousEntity en la respuesta para mantener el historial de cambios
Sincronización en Tiempo Real: Las actualizaciones emiten eventos WebSocket para sincronización de UI en tiempo real
Idempotencia: Seguro para reintentar - actualizaciones con los mismos datos no crearán eventos duplicados

Próximos Pasos

Obtener Persona - Ver detalles de persona actualizados
Listar Personas - Consultar personas con filtros
Upsert Persona - Crear o actualizar en una operación

Listar personas Actualizar una persona por ID externo

⌘I

​Resumen

​Endpoint

​Autenticación

​Parámetros de Ruta

​Cuerpo de la Solicitud

​Respuesta

​Comportamiento

​Ejemplos

​Actualizar Ingresos y Ocupación de Persona

​Actualizar Información de Contacto

​Actualizar Solo Atributos Personalizados

​Actualizar Estado de Persona

​Ejemplo de Respuesta

​Respuestas de Error

​404 Not Found

​400 Bad Request - Datos Inválidos

​400 Bad Request - Falta Razón para Cambio de Estado

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Actualizar Después de Verificación KYC

​Enriquecimiento Progresivo de Perfil

​Mejores Prácticas

​Próximos Pasos

Resumen

Endpoint

Autenticación

Parámetros de Ruta

Cuerpo de la Solicitud

Respuesta

Comportamiento

Ejemplos

Actualizar Ingresos y Ocupación de Persona

Actualizar Información de Contacto

Actualizar Solo Atributos Personalizados

Actualizar Estado de Persona

Ejemplo de Respuesta

Respuestas de Error

404 Not Found

400 Bad Request - Datos Inválidos

400 Bad Request - Falta Razón para Cambio de Estado

401 Unauthorized

500 Internal Server Error

Casos de Uso

Actualizar Después de Verificación KYC

Enriquecimiento Progresivo de Perfil

Mejores Prácticas

Próximos Pasos