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

​
Descripción General

Actualiza los atributos y datos de una entidad existente. Si la entidad tiene alguna matriz asignada con trigger entity_updated, el motor de reglas puede ejecutarse tras la actualización (respetando watchFields opcionales en la matriz y skipRulesExecution). Siempre se registran auditoría y eventos 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

​
id
string
required
El ID gu1 de la entidad a actualizar

​
Cuerpo de la Solicitud

Todos los campos del esquema de creación están disponibles excepto type (el tipo de entidad no se puede cambiar). Todos los campos son opcionales - solo incluye los campos que deseas actualizar.
​
name
string
Actualizar el nombre visible de la entidad
El ID externo no se actualiza con este endpoint. Usa Cambiar ID externo (POST /entities/change-external-id) con un reason obligatorio (mín. 5 caracteres). Las rutas PATCH de actualización ignoran externalId en el cuerpo.
​
taxId
string
Actualizar número de identificación fiscal
​
email
string | null
Actualizar el correo de contacto en la raíz de la entidad. Omite el campo para no cambiar; envía null para borrarlo.
​
phone
string | null
Actualizar el teléfono de contacto en la raíz de la entidad. Omite el campo para no cambiar; envía null para borrarlo.
​
nationality
string | null
Nacionalidad en raíz (ISO 3166-1 alfa-2 al persistir). Omite para no cambiar; null la borra. Si actualizas nationality en entityData persona/empresa, la raíz puede recalcularse cuando vaya en el mismo request.
​
countryCode
string
Actualizar código de país ISO 3166-1 alpha-2
​
attributes
object
Actualizar atributos personalizados (se fusiona con los atributos existentes)
​
status
string
Estado del ciclo de vida (active, inactive, blocked, under_review, suspended, pending_verification, expired, rejected, deleted).Obligatorio con reason: cualquier cambio de estado debe incluir reason para auditoría.
​
reason
string
Motivo de la actualización (especialmente al cambiar el estado a blocked o rejected).Obligatorio cuando: se cambia el estado a blocked, rejected o suspended.
​
changeStatusManual
boolean
default:"false"
Con true, se desactivan las actualizaciones automáticas de status: las reglas de matrices de riesgo y acciones de automatización como set_entity_status no modifican el estado. Las actualizaciones manuales por este endpoint (o la UI) sí aplican.
  • Por defecto: false.
  • Enviar false explícitamente quita el bloqueo.
  • No desactiva el cálculo de riesgo ni otros efectos de reglas; solo escrituras de estado desde reglas/automatizaciones.
Obligatorio con reason: si cambia changeStatusManual (activar o desactivar), enviar reason en el mismo PATCH para auditoría.

​
Matrices de riesgo

Asignar o reemplazar las matrices de riesgo de la entidad. Misma semántica que Crear entidad (riskMatrixId / riskMatrixIds).
​
riskMatrixId
string | string[] | null
Legacy: un UUID, un array de UUIDs, o null para quitar todas las matrices asignadas. Si enviás riskMatrixIds no vacío, tiene precedencia sobre este campo.
​
riskMatrixIds
string[]
Forma preferida para varias matrices: lista ordenada de UUIDs de tu organización. Enviá [] (o riskMatrixId: null) para desasignar todas. Cada UUID debe existir en la org; si no, la API responde 400 con código INVALID_RISK_MATRIX.
​
skipRulesExecution
boolean
default:"false"
Con true, omite la evaluación automática de matrices en la actualización aunque haya matrices con trigger entity_updated.
Actualizar matrices solo persiste la asignación; la asignación sola no ejecuta reglas.Reglas en actualización: si la entidad tiene al menos una matriz asignada con trigger entity_updated y skipRulesExecution no es true, la API ejecuta el motor tras un cambio de campos. Las matrices pueden restringir con watchFields (solo si cambian paths listados, p. ej. email, attributes.clientTypes). El webhook entity.updated incluye rulesExecutionSummary cuando corrieron reglas o se omitieron con motivo.Los mismos campos aplican en Actualizar por ID externo y PATCH /entities/by-tax-id/{taxId}.
​
entityData
object
Actualizar datos específicos del tipo (se fusiona con entityData existente)

​
Respuesta

​
entity
object
El objeto de entidad actualizado con todos los valores actuales
​
previousEntity
object
El estado de la entidad antes de la actualización (para auditoría/comparación)
El cuerpo HTTP no incluye rulesExecutionSummary. Cuando se ejecutan u omiten reglas, el resumen va en el webhook entity.updated.

​
Comportamiento

Cuando actualizas una entidad, el sistema:
  1. Registra el cambio en auditoría con valores antes/después
  2. Ejecuta matrices de riesgo cuando hay matrices asignadas con entity_updated, skipRulesExecution no es true, y los watchFields opcionales coinciden con los campos cambiados
  3. Emite evento en tiempo real a clientes conectados
  4. Dispara webhook entity.updated con changes y opcional rulesExecutionSummary
  5. Mantiene registro de auditoría para cumplimiento y propósitos de revisión

​
Ejemplos

​
Actualizar Ingresos 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 Empresa

curl -X PATCH http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "company": {
        "employeeCount": 75,
        "revenue": 7500000
      }
    },
    "attributes": {
      "partnershipTier": "platinum",
      "monthlyVolume": 500000
    }
  }'

​
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 Transacción

curl -X PATCH http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "transaction": {
        "status": "reviewed",
        "flagged": false
      }
    }
  }'

​
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 No Encontrado

{
  "error": "Entity not found"
}

​
400 Solicitud Incorrecta - Datos Inválidos

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

​
401 No Autorizado

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

​
500 Error Interno del Servidor

{
  "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 entidad
const response = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  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 del cliente a medida que más información esté disponible
def update_customer_info(entity_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{entity_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()

​
Resolución de Transacción

// Marcar una transacción señalada como resuelta después de la investigación
async function resolveTransaction(txnId, resolution) {
  const response = await fetch(`http://api.gu1.ai/entities/${txnId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        transaction: {
          status: 'resolved',
          flagged: false
        }
      },
      attributes: {
        resolutionDate: new Date().toISOString(),
        resolutionNotes: resolution,
        reviewedBy: 'compliance_team'
      }
    })
  });

  return response.json();
}

​
Mejores Prácticas

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

​
Próximos Pasos