Actualizar una entidad persona

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>"
}
'

import requests

url = "http://api.gu1.ai/entities/{id}"

payload = {
    "name": "<string>",
    "taxId": "<string>",
    "countryCode": "<string>",
    "attributes": {},
    "entityData": {},
    "status": "<string>",
    "reason": "<string>",
    "riskMatrixId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    taxId: '<string>',
    countryCode: '<string>',
    attributes: {},
    entityData: {},
    status: '<string>',
    reason: '<string>',
    riskMatrixId: '<string>'
  })
};

fetch('http://api.gu1.ai/entities/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'taxId' => '<string>',
    'countryCode' => '<string>',
    'attributes' => [
        
    ],
    'entityData' => [
        
    ],
    'status' => '<string>',
    'reason' => '<string>',
    'riskMatrixId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("http://api.gu1.ai/entities/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

PATCH

entities

{id}

Actualizar una entidad persona

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>"
}
'

import requests

url = "http://api.gu1.ai/entities/{id}"

payload = {
    "name": "<string>",
    "taxId": "<string>",
    "countryCode": "<string>",
    "attributes": {},
    "entityData": {},
    "status": "<string>",
    "reason": "<string>",
    "riskMatrixId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    taxId: '<string>',
    countryCode: '<string>',
    attributes: {},
    entityData: {},
    status: '<string>',
    reason: '<string>',
    riskMatrixId: '<string>'
  })
};

fetch('http://api.gu1.ai/entities/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'taxId' => '<string>',
    'countryCode' => '<string>',
    'attributes' => [
        
    ],
    'entityData' => [
        
    ],
    'status' => '<string>',
    'reason' => '<string>',
    'riskMatrixId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("http://api.gu1.ai/entities/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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.

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).

string

Actualizar número de identificación fiscal

string

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

object

Actualizar atributos personalizados (se fusiona con atributos existentes)

object

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

string

Actualizar estado de la persona. Valores canónicos (ver Descripción general):

not_started - Creada; análisis aún no iniciado
under_review - En revisión (también el default al crear)
pending_verification - Esperando completar KYC/KYB
awaiting_information - Esperando datos del cliente (p. ej. documentos de onboarding pedidos por correo)
active - Verificada / operativa (“aprobada”)
inactive - Cerrada o inactiva
suspended - Suspensión temporal
blocked - Bloqueo permanente
rejected - Onboarding denegado
expired / deleted - Datos vencidos o baja lógica

Nota: Todo cambio de status requiere reason para auditoría. Las operaciones se bloquean en suspended, blocked y rejected.

string

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

string

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

Respuesta

object

El objeto de persona actualizado con todos los valores actuales

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”

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"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        person: {
          income: 95000,
          occupation: 'Senior Software Engineer'
        }
      }
    })
  }
);

const result = await response.json();
console.log('Updated person:', result.entity);
console.log('Re-evaluation triggered:', result.evaluation.id);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'person': {
                'income': 95000,
                'occupation': 'Senior Software Engineer'
            }
        }
    }
)

result = response.json()
print(f"Updated person: {result['entity']['name']}")
print(f"Re-evaluation ID: {result['evaluation']['id']}")

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"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        person: {
          email: 'new.email@example.com',
          phone: '+54 11 9876-5432',
          address: 'Av. Libertador 2500, Buenos Aires'
        }
      }
    })
  }
);

const result = await response.json();
console.log('Contact information updated');

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'person': {
                'email': 'new.email@example.com',
                'phone': '+54 11 9876-5432',
                'address': 'Av. Libertador 2500, Buenos Aires'
            }
        }
    }
)

result = response.json()
print("Contact information updated")

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"
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      attributes: {
        accountTier: 'premium',
        loyaltyPoints: 15000,
        lastLoginDate: '2024-10-03T14:00:00Z'
      }
    })
  }
);

const result = await response.json();
console.log('Attributes updated:', result.entity.attributes);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'attributes': {
            'accountTier': 'premium',
            'loyaltyPoints': 15000,
            'lastLoginDate': '2024-10-03T14:00:00Z'
        }
    }
)

result = response.json()
print(f"Attributes updated: {result['entity']['attributes']}")

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"
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'suspended',
      reason: 'Suspicious activity detected - pending investigation'
    })
  }
);

const result = await response.json();
console.log('Status updated to:', result.entity.status);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'status': 'suspended',
        'reason': 'Suspicious activity detected - pending investigation'
    }
)

result = response.json()
print(f"Status updated to: {result['entity']['status']}")

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

​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