Skip to main content

​
Descripción General

Actualiza los atributos y datos de una entidad existente. Este endpoint desencadena automáticamente una re-evaluación de la puntuación de riesgo de la entidad 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

​
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
​
externalId
string
Actualizar tu identificador externo
​
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 los atributos existentes)
​
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
​
evaluation
object
Evaluación recién creada desencadenada 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 entidad antes de la actualización (para auditoría/comparación)

​
Comportamiento

Cuando actualizas una entidad, el sistema automáticamente:
  1. Registra el cambio en el registro de eventos de la entidad con una instantánea del antes/después
  2. Desencadena re-evaluación para recalcular la puntuación de riesgo basada en los nuevos datos
  3. Emite evento en tiempo real para notificar a los clientes conectados sobre la actualización
  4. 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": "[email protected]",
      "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