Actualizar una entidad empresa

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": {}
}

Descripción general

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

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 los atributos existentes)

entityData

object

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

status

string

Actualizar estado de la empresa. Estados disponibles:

pending - Estado inicial, esperando procesamiento
under_review - Bajo revisión manual
active - Aprobada y activa
suspended - Temporalmente suspendida (requiere reason)
blocked - Bloqueada permanentemente (requiere reason)
rejected - Rechazada durante la incorporación (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 una pista de auditoría para los cambios de estado.

riskMatrixId

string

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

Respuesta

entity

object

El objeto de empresa 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 empresa 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 empresa, el sistema automáticamente:

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

Ejemplos

Actualizar ingresos y ocupación de la empresa

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": {
      "company": {
        "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": {
      "company": {
        "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 la empresa

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": "business_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "company",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "company": {
        "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": {
      "company": {
        "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 KYB

// Después de completar la verificación KYB, actualizar la empresa
const response = await fetch(`http://api.gu1.ai/entities/${companyId}`, {
  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 del perfil

# Enriquecer perfil de negocio a medida que hay más información disponible
def update_business_info(company_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{company_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'company': 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 empresa completa
Monitorear re-evaluaciones: Verifica el ID de evaluación devuelto para rastrear el recálculo de la 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 - las actualizaciones con los mismos datos no crearán eventos duplicados

Próximos pasos

Obtener empresa - Ver detalles de empresa actualizados
Listar empresas - Consultar empresas con filtros
Upsert empresa - Crear o actualizar en una operación

Listar empresas Actualizar entidad por ID externo

⌘I

​Descripción general

​Endpoint

​Autenticación

​Parámetros de ruta

​Cuerpo de la solicitud

​Respuesta

​Comportamiento

​Ejemplos

​Actualizar ingresos y ocupación de la empresa

​Actualizar información de contacto

​Actualizar solo atributos personalizados

​Actualizar estado de la empresa

​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 KYB

​Enriquecimiento progresivo del perfil

​Mejores prácticas

​Próximos pasos

Descripción general

Endpoint

Autenticación

Parámetros de ruta

Cuerpo de la solicitud

Respuesta

Comportamiento

Ejemplos

Actualizar ingresos y ocupación de la empresa

Actualizar información de contacto

Actualizar solo atributos personalizados

Actualizar estado de la empresa

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 KYB

Enriquecimiento progresivo del perfil

Mejores prácticas

Próximos pasos