Crear - gu1

Resumen

Crea una nueva entidad de persona con los atributos especificados. Las entidades de persona representan clientes individuales que deseas analizar para riesgo y cumplimiento (KYC).

Endpoint

POST http://api.gu1.ai/entities

Autenticación

Requiere una clave API válida en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Cuerpo de la Solicitud

type

string

required

Debe ser person para crear una entidad de persona

externalId

string

required

Tu identificador único para esta persona en tu sistema

name

string

required

Nombre para mostrar de la persona

countryCode

string

required

Código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)

taxId

string

Número de identificación fiscal (validado según el país)

📋 Ver Formatos de Tax ID por País para formatos aceptados y reglas de validación para cada país.

attributes

object

Opcional - Atributos personalizados como pares clave-valor para metadatos flexiblesÚsalo para campos personalizados que no encajan en el esquema estándar (ej: IDs internos, etiquetas, banderas)

entityData

object

Opcional - Estructura de datos específica de persona (ver más abajo)

¿Cuándo usar entityData?

Opcional para creación básica de entidad - Puedes crear una persona con solo type, name, taxId y countryCode
Requerido para enriquecimiento y análisis de riesgo - Si quieres ejecutar verificaciones de cumplimiento, necesitarás proporcionar campos relevantes
Puede ser completado después - Puedes crear una persona mínima primero, luego actualizarla con datos completos antes de ejecutar análisis de riesgo

Ejemplo Mínimo:

{
  "type": "person",
  "name": "Juan Pérez",
  "taxId": "12345678",
  "countryCode": "ES"
  // No se necesita entityData para creación básica
}

Ejemplo Completo (con datos KYC):

{
  "type": "person",
  "name": "Juan Pérez",
  "taxId": "12345678",
  "countryCode": "ES",
  "entityData": {
    "person": {
      "firstName": "Juan",
      "lastName": "Pérez",
      "dateOfBirth": "1980-01-15",
      "email": "juan@example.com",
      "phone": "+34612345678"
    }
  }
}

registrationDate

string

Fecha de registro de la persona en formato ISO 8601 datetime (ej., “2024-01-15T10:30:00Z”)

isClient

boolean

default:"false"

Marca esta persona como cliente para fines de seguimiento

riskMatrixId

string

UUID de la matriz de riesgo para ejecutar reglas automáticamente. Ver sección Ejecución de Matriz de Riesgo abajo para más detalles.

skipRulesExecution

boolean

default:"false"

Omitir la ejecución automática de reglas después de crear la persona. Use esto para crear la entidad primero y activar las reglas manualmente más tarde.

status

string

default:"under_review"

Estado inicial de la persona. Opciones:

active - Persona activa
inactive - Persona inactiva
blocked - Persona bloqueada
under_review - Persona en revisión (predeterminado)
suspended - Persona suspendida
expired - Registro de persona expirado
deleted - Eliminación lógica
rejected - Persona rechazada

autoExecuteIntegrations

object

Configurar la ejecución automática de integraciones (enriquecimientos y verificaciones) al crear la persona.Estructura:

{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": [
    "ar_renaper_data_enrichment",
    "ar_repet_person_enrichment"
  ],
  "checks": [
    "ar_repet_person_check",
    "global_complyadvantage_person_search_check",
    "global_gueno_sanctions_check"
  ]
}

Propiedades:

executeAllActiveEnrichments (boolean) - Ejecutar todas las integraciones de enriquecimiento activas configuradas en su organización
executeAllActiveChecks (boolean) - Ejecutar todas las integraciones de verificación activas configuradas en su organización
enrichments (string[]) - Array de códigos específicos de proveedores de enriquecimiento a ejecutar
checks (string[]) - Array de códigos específicos de proveedores de verificación a ejecutar

Ejemplos de códigos válidos (persona AR — deben coincidir con ValidProviderCodesEnum):

ar_renaper_data_enrichment — datos RENAPER
ar_repet_person_enrichment — REPET / contexto persona
ar_repet_person_check — verificación REPET persona
global_complyadvantage_person_search_check — búsqueda ComplyAdvantage (persona)
global_complyadvantage_pep_check — PEP ComplyAdvantage
global_gueno_sanctions_check — sanciones Güeno (si está configurado)

Ver Códigos de proveedores y provider-codes.

monitoring

object

Opcional. Si el enriquecimiento de sanciones globales Gueno se ejecuta vía autoExecuteIntegrations, enviá monitoring.main["global_gueno_sanctions_enrichment"]: true para pedir modo lista vigilada (suscripción al screening diario). Hoy es la única clave de monitoreo soportada. Tiene que ir el mismo código en autoExecuteIntegrations.enrichments (o activo vía execute-all) y el monitoreo habilitado en Marketplace. Ejemplos completos: Crear entidad — ejemplo Gueno.

Monitoreo de sanciones Gueno (persona)

{
  "type": "person",
  "externalId": "cust_screening_001",
  "name": "María González",
  "countryCode": "AR",
  "taxId": "27-12345678-1",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "executeAllActiveChecks": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
    "checks": []
  }
}

Estructura de Datos de Entidad de Persona

El objeto entityData.person debe contener:

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number,
    "incomeCurrency": "string",
    "address": "string | object (ver nota de Formato de Dirección)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string",
    "email": "string",
    "phone": "string",
    "alternativePhone": "string",
    "idType": "national_id | passport | drivers_license | tax_id | other",
    "idNumber": "string",
    "isPep": boolean,
    "pepPosition": "string",
    "pepCountry": "string"
  }
}

Formato de Dirección: El campo address admite ambos formatos:

Formato de cadena (simple): "Av. Paulista, 1000, São Paulo, SP, Brazil"

Formato de objeto (estructurado):

{
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

Ejecución de Matriz de Riesgo

Puede ejecutar automáticamente una matriz de riesgo (reglas de cumplimiento KYC) al crear una persona proporcionando el parámetro riskMatrixId.

Cómo funciona

Obtenga su ID de Matriz de Riesgo desde el panel de gu1 (formato: UUID)
Incluya riskMatrixId en su solicitud de creación
El sistema automáticamente:
- Crea la entidad persona
- Ejecuta todas las reglas KYC en la matriz
- Calcula el puntaje de riesgo
- Genera alertas de cumplimiento si es necesario
- Actualiza el estado de la persona según los resultados

Ejemplo con Matriz de Riesgo

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "occupation": "Software Engineer"
    }
  }
}

Combinado con Enriquecimientos

Para mejores resultados, combine la ejecución de matriz con enriquecimientos automáticos:

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": [
      "ar_renaper_data_enrichment",
      "ar_repet_person_enrichment"
    ],
    "checks": [
      "ar_repet_person_check",
      "global_complyadvantage_person_search_check"
    ]
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}

Flujo de Ejecución:

Se crea la entidad persona
Se ejecutan los enriquecimientos indicados (p. ej. ar_renaper_data_enrichment, ar_repet_person_enrichment)
Se ejecutan los checks indicados (p. ej. ar_repet_person_check, global_complyadvantage_person_search_check)
Las reglas de la matriz de riesgo evalúan los datos recopilados
Se calcula el puntaje de riesgo final
Se generan alertas de cumplimiento si las reglas se activan

Respuesta

success

boolean

Indica si la persona fue creada exitosamente

entity

object

El objeto de persona creado incluyendo:

id - ID interno de gu1
externalId - Tu ID externo
organizationId - Tu ID de organización
type - Siempre “person”
name - Nombre de la persona
riskScore - Puntuación de riesgo inicial (0-100)
status - Estado de la persona
entityData - Datos específicos de la persona
attributes - Atributos personalizados
createdAt - Marca de tiempo de creación
updatedAt - Marca de tiempo de última actualización

rulesResult

object

Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es false y hay matriz de riesgo configurada), incluyendo:

success (boolean) - Si las reglas se ejecutaron correctamente
rulesTriggered (number) - Número de reglas disparadas
alerts (array) - Alertas generadas por las reglas
riskScore (number) - Puntuación de riesgo final
decision (string) - Decisión final (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
rulesExecutionSummary (object) - Presente cuando se ejecutaron reglas. Ver abajo la estructura.

rulesExecutionSummary

object

En la raíz de la respuesta (igual que la API de transacciones). Mismo valor que rulesResult.rulesExecutionSummary. Solo presente cuando se ejecutaron reglas (p. ej. skipRulesExecution es false). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron.

rulesHit (array) - Reglas cuyas condiciones se cumplieron. Cada ítem: name, description, score, priority, category, status (p. ej. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
rulesNoHit (array) - Reglas evaluadas pero cuyas condiciones no se cumplieron. Misma estructura que rulesHit (incluye acciones configuradas, no ejecutadas).
actionsExecuted (object) - Acciones ejecutadas agregadas de todas las reglas que hicieron hit: alerts, suggestion (BLOCK | SUSPEND | FLAG, mayor peso), status (estado aplicado a la entidad, si hay), assignedUser ({ userId }, si hay), customKeys (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match; para integraciones/workflows.
totalScore (number) - Suma del score de todas las reglas que hicieron hit y no están en estado shadow.

Ejemplo de Solicitud

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "externalId": "customer_12345",
    "name": "María González",
    "countryCode": "AR",
    "taxId": "20-12345678-9",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    }
  }'

Ejemplo de Respuesta

{
  "success": true,
  "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": 25,
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  }
}

Respuestas de Error

400 Bad Request - Tax ID Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid CUIT format. Please check the format and try again.",
    "details": {
      "field": "taxId",
      "taxIdName": "CUIT",
      "providedValue": "20-12345678-9"
    }
  },
  "entity": null
}

400 Bad Request - Faltan Campos Requeridos

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for person creation",
    "details": {
      "missingFields": ["firstName", "lastName"],
      "requiredFields": ["firstName", "lastName", "dateOfBirth"],
      "countryCode": "AR"
    }
  },
  "entity": null
}

409 Conflict - Entidad Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "customer_12345",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

Próximos Pasos

Después de crear una persona, puedes:

Obtener Detalles de Persona - Recuperar información completa de la persona
Listar Personas - Consultar tus personas
Actualizar Persona - Modificar datos de la persona
Crear Validación KYC - Iniciar proceso de verificación KYC

Comenzando

Casos de Uso

Webhooks

Workflows

Monitoreo (entidades)

Persona

Mensajería

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

Documentation Index

​Resumen

​Endpoint

​Autenticación

​Cuerpo de la Solicitud

​Monitoreo de sanciones Gueno (persona)

​Estructura de Datos de Entidad de Persona

​Ejecución de Matriz de Riesgo

​Cómo funciona

​Ejemplo con Matriz de Riesgo

​Combinado con Enriquecimientos

​Respuesta

​Ejemplo de Solicitud

​Ejemplo de Respuesta

​Respuestas de Error

​400 Bad Request - Tax ID Inválido

​400 Bad Request - Faltan Campos Requeridos

​409 Conflict - Entidad Duplicada

​401 Unauthorized

​Próximos Pasos

Resumen

Endpoint

Autenticación

Cuerpo de la Solicitud

Monitoreo de sanciones Gueno (persona)

Estructura de Datos de Entidad de Persona

Ejecución de Matriz de Riesgo

Cómo funciona

Ejemplo con Matriz de Riesgo

Combinado con Enriquecimientos

Respuesta

Ejemplo de Solicitud

Ejemplo de Respuesta

Respuestas de Error

400 Bad Request - Tax ID Inválido

400 Bad Request - Faltan Campos Requeridos

409 Conflict - Entidad Duplicada

401 Unauthorized

Próximos Pasos