Actualizar entidad por ID externo
curl --request PATCH \
--url http://api.gu1.ai/entities/by-external-id/:externalId \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
'import requests
url = "http://api.gu1.ai/entities/by-external-id/:externalId"
payload = {
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
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>',
nationality: {},
status: '<string>',
reason: '<string>',
riskMatrixId: {},
entityData: {},
attributes: {},
metadata: {}
})
};
fetch('http://api.gu1.ai/entities/by-external-id/:externalId', 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/by-external-id/:externalId",
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>',
'nationality' => [
],
'status' => '<string>',
'reason' => '<string>',
'riskMatrixId' => [
],
'entityData' => [
],
'attributes' => [
],
'metadata' => [
]
]),
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/by-external-id/:externalId"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\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/by-external-id/:externalId")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/by-external-id/:externalId")
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 \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"entity": {},
"evaluation": {},
"previousEntity": {},
"404 Not Found": {},
"400 Bad Request": {}
}Referencia API
Actualizar entidad por ID externo
Actualizar una entidad usando tu identificador externo en lugar del UUID interno — para entidades de empresa en la plataforma de riesgo y compliance gu1.
PATCH
/
entities
/
by-external-id
/
:externalId
Actualizar entidad por ID externo
curl --request PATCH \
--url http://api.gu1.ai/entities/by-external-id/:externalId \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
'import requests
url = "http://api.gu1.ai/entities/by-external-id/:externalId"
payload = {
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
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>',
nationality: {},
status: '<string>',
reason: '<string>',
riskMatrixId: {},
entityData: {},
attributes: {},
metadata: {}
})
};
fetch('http://api.gu1.ai/entities/by-external-id/:externalId', 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/by-external-id/:externalId",
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>',
'nationality' => [
],
'status' => '<string>',
'reason' => '<string>',
'riskMatrixId' => [
],
'entityData' => [
],
'attributes' => [
],
'metadata' => [
]
]),
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/by-external-id/:externalId"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\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/by-external-id/:externalId")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/by-external-id/:externalId")
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 \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"entity": {},
"evaluation": {},
"previousEntity": {},
"404 Not Found": {},
"400 Bad Request": {}
}Descripción general
Este endpoint te permite actualizar una entidad usando tu propio identificador externo en lugar de nuestro UUID interno. Esto es útil cuando no almacenas nuestros UUIDs en tu sistema y solo rastreas tus propios IDs externos. La funcionalidad es idéntica aPATCH /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: La entidad está activa y operativainactive: La entidad está inactivablocked: La entidad está bloqueada (requierereason)suspended: La entidad está suspendida (requierereason)rejected: La entidad fue rechazada durante la incorporación (requierereason)
blocked, suspended o rejected requiere proporcionar un reason para fines de auditoría.string
Requerido al cambiar el estado a
blocked, suspended o rejected. Proporciona una pista de auditoría para el cambio de estado.string (uuid)
ID de matriz de riesgo para 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 persona, usa
entityData.person. Para entidades empresa, usa entityData.company.Campos de persona:firstName: Primer nombrelastName: ApellidomiddleName: Segundo nombredateOfBirth: Fecha de nacimiento (YYYY-MM-DD)nationality: Nacionalidad (ISO 3166-1 alpha-2)email: Dirección de correo electrónicophone: Número de teléfonoaddress: Objeto de dirección (street, city, state, country, postalCode)
legalName: Nombre legal de la empresatradingNames: Array de nombres comercialesregistrationNumber: Número de registro de la empresaincorporationDate: Fecha de constitución (YYYY-MM-DD)industry: Industria/sectoremployees: Número de empleadoswebsite: Sitio web de la empresaaddress: Objeto de dirección
object
Atributos personalizados clave-valor para almacenamiento flexible de datos de entidad
object
Metadatos del sistema (generalmente establecidos por el sistema, pero se pueden actualizar)
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 fines de auditoría)
Ejemplo de solicitud
curl -X PATCH https://api.gueno.ai/entities/by-external-id/customer-12345 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "John Michael Doe",
"status": "active",
"entityData": {
"person": {
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"email": "john.doe@example.com",
"phone": "+1-555-0123"
}
},
"riskMatrixId": "matrix-uuid-here"
}'
Ejemplo de respuesta
{
"entity": {
"id": "entity-uuid",
"organizationId": "org-uuid",
"externalId": "customer-12345",
"type": "person",
"name": "John Michael Doe",
"taxId": "123-45-6789",
"countryCode": "US",
"nationality": "US",
"status": "active",
"riskScore": "35.00",
"riskMatrixId": "matrix-uuid-here",
"entityData": {
"person": {
"firstName": "John",
"middleName": "Michael",
"lastName": "Doe",
"email": "john.doe@example.com",
"phone": "+1-555-0123"
}
},
"createdAt": "2025-12-20T10:00:00Z",
"updatedAt": "2025-12-24T15:30:00Z"
},
"evaluation": null,
"previousEntity": {
"id": "entity-uuid",
"name": "John Doe",
"status": "pending",
...
}
}
Cambio de estado con razón
Al cambiar el estado ablocked, suspended o rejected, debes proporcionar una razón:
curl -X PATCH https://api.gueno.ai/entities/by-external-id/customer-12345 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "blocked",
"reason": "Failed sanctions screening - OFAC match detected"
}'
Casos de uso
1. Actualizar información del cliente
Actualizar datos del cliente desde tu CRM o sistema de gestión de usuarios:{
"name": "Jane Smith-Johnson",
"entityData": {
"person": {
"lastName": "Smith-Johnson",
"email": "jane.smithjohnson@example.com",
"address": {
"street": "456 New St",
"city": "Seattle",
"state": "WA",
"country": "US",
"postalCode": "98101"
}
}
}
}
2. Asignar matriz de riesgo
Asignar o cambiar la matriz de riesgo para una entidad:{
"riskMatrixId": "high-risk-matrix-uuid"
}
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:{
"status": "blocked",
"reason": "Investigation revealed connections to sanctioned entities"
}
4. Sincronizar datos de la empresa
Actualizar información de la empresa desde el registro mercantil:{
"entityData": {
"company": {
"employees": 250,
"revenue": 50000000,
"website": "https://company-new-domain.com"
}
}
}
Eventos y Webhooks
Eventos en tiempo real
Después de una actualización exitosa, se emite el siguiente evento en tiempo real a través de WebSocket:{
"event": "entity.updated",
"entityId": "entity-uuid",
"externalId": "customer-12345",
"updatedFields": ["name", "entityData"],
"previousValues": {...},
"newValues": {...}
}
Activadores de Webhook
Si cambias solo el campostatus (sin otros cambios de campo), se activa un webhook:
Evento: entity.status_changed
{
"event": "entity.status_changed",
"entityId": "entity-uuid",
"externalId": "customer-12345",
"oldStatus": "active",
"newStatus": "blocked",
"reason": "Failed sanctions screening",
"changedBy": "user-uuid",
"timestamp": "2025-12-24T15:30:00Z"
}
Pista de auditoría
Cada actualización de entidad crea un eventoATTRIBUTE_CHANGED en el registro de eventos de la entidad con:
- Estado anterior (todos los campos modificados)
- Estado posterior (todos los campos modificados)
- Usuario que realizó el cambio
- Marca de tiempo
- Fuente (API, panel de control, etc.)
GET /entity-events?entityId=:entityId&eventType=ATTRIBUTE_CHANGED
Respuestas de error
error
Entidad con el
externalId especificado no encontrada en tu organización{
"error": "Entity not found"
}
error
Datos de solicitud inválidos o error de validación
{
"error": "Changing status to 'blocked' requires a reason for audit purposes."
}
error
Intento de cambiar campos inmutables
{
"error": "Field 'type' cannot be changed after entity creation"
}
Mejores prácticas
-
Establece siempre ID externo en la creación: Establece
externalIdal crear entidades a través dePOST /entitiespara habilitar actualizaciones por ID externo. - Usa para integración del sistema: Este endpoint es ideal para integraciones donde sincronizas datos de sistemas externos (CRM, ERP, etc.) usando tus propios IDs.
- Proporciona razones para cambios de estado: Siempre incluye razones significativas al bloquear, suspender o rechazar entidades para la pista de auditoría de cumplimiento.
-
Re-analiza después del cambio de matriz de riesgo: Después de asignar una nueva matriz de riesgo, activa
POST /entities/:entityId/analyzepara re-evaluar con nuevas reglas. -
Maneja 404 con elegancia: Si la entidad no se encuentra por ID externo, es posible que debas crearla primero usando
POST /entities. - Actualizaciones por lotes: Para actualizar múltiples entidades, llama a este endpoint de forma concurrente con diferentes IDs externos para un mejor rendimiento.
Endpoints relacionados
- Crear entidad - Crear nueva entidad
- Actualizar entidad por UUID - Actualizar usando UUID interno
- Obtener entidad - Recuperar detalles de entidad
- Analizar entidad - Activar análisis de riesgo
Was this page helpful?