Crear una persona automáticamente con enriquecimiento

curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

automatic

Crear una persona automáticamente con enriquecimiento

curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

Resumen

El endpoint de creación automática de persona te permite crear personas proporcionando información mínima (ID fiscal y país). El sistema automáticamente:

Obtiene datos de la persona de registros oficiales
Enriquece la persona con información adicional
Ejecuta enriquecimientos automáticamente

Esto es ideal para procesos KYC (Conoce a tu Cliente) donde deseas incorporar clientes con información completa automáticamente.

Endpoint

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

Autenticación

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

Authorization: Bearer YOUR_API_KEY

Cuerpo de la Solicitud

taxId

string

required

Número de identificación fiscal de la persona (ej., CPF para Brasil, CURP para México, CUIT para Argentina)

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

country

string

required

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

type

string

required

Debe establecerse en person

externalId

string

Tu identificador único para esta persona (opcional, se generará automáticamente si no se proporciona)

isClient

boolean

default:"false"

Marca esta persona como cliente para fines de seguimiento

riskMatrixId

string | string[]

Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Tras la creación se ejecutan reglas activas de esas matrices (salvo skipRulesExecution: true).

riskMatrixIds

string[]

Preferido para varias matrices: lista ordenada de UUIDs. Tiene precedencia sobre riskMatrixId cuando viene informada y no vacía.

skipRulesExecution

boolean

default:"false"

Omitir la ejecución automática de reglas después de crear la persona

status

string

default:"under_review"

Estado inicial de la persona

operationalHours

object | null

Horario operativo opcional de la entidad principal (timezone + weekly). Se persiste en creación automática igual que en creación manual de entidades. No se aplica a accionistas/relaciones creadas por depth.

depth

number

default:"0"

Profundidad de extracción de relaciones (0-5). Controla cuántos niveles de relaciones se obtienen y crean automáticamente.

0: Sin relaciones (solo entidad principal)
1: Solo relaciones directas
2: Relaciones + sus relaciones
3-5: Niveles adicionales (usar con precaución - puede crear muchas entidades)

autoExecuteIntegrations

object

Configurar la ejecución automática de integraciones para la entidad de persona principal. Ver Referencia de Códigos de Proveedor para códigos disponibles.Tipo: object (opcional)Propiedades:

executeAllActiveEnrichments (boolean, opcional, predeterminado: false) - Ejecutar todas las integraciones de enriquecimiento activas
enrichments (array, opcional, predeterminado: []) - Array de códigos específicos de proveedor de enriquecimiento a ejecutar
enrichmentGroupRefs (array de strings, opcional) - Slugs de grupos de enriquecimiento del Marketplace (solo enriquecimientos). Con executeAllActiveEnrichments: false, se resuelven los grupos y se fusionan con enrichments explícitos. Con executeAllActiveEnrichments: true, los refs de grupo no se usan; los enrichments explícitos pueden seguir añadiendo códigos tras el conjunto activo.

{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
  enrichmentGroupRefs?: string[];
}

Ejemplo:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_bdc_basic_data_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"],
}

autoExecuteIntegrationsShareholders

object

Configurar la ejecución automática de integraciones para relaciones descubiertas. Útil al usar depth > 0. Ver Referencia de Códigos de Proveedor para códigos disponibles.Tipo: object (opcional)Propiedades:

executeAllActiveEnrichments (boolean, opcional, predeterminado: false) - Ejecutar todos los enriquecimientos activos en entidades relacionadas
enrichments (object, opcional) - Enriquecimientos específicos por tipo de entidad
- company (array, predeterminado: []) - Enriquecimientos para relaciones de empresa
- person (array, predeterminado: []) - Enriquecimientos para relaciones de persona
enrichmentGroupRefs (array de strings, opcional) - Mismos slugs que en el objeto principal; con executeAllActiveEnrichments: false se aplican tanto a company como a person. Con executeAllActiveEnrichments: true en este objeto, los refs de grupo no se usan; los enrichments explícitos por tipo pueden seguir añadiendo códigos tras el activo de cada lado.

{
  executeAllActiveEnrichments?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  enrichmentGroupRefs?: string[];
}

Ejemplo:

{
  "enrichments": {
    "person": ["br_cpfcnpj_complete_person_enrichment"],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  },
  "enrichmentGroupRefs": ["related_entities_group_slug"]
}

Códigos de Enrichment Obligatorios por País

Al usar códigos de enrichment específicos (no executeAllActiveEnrichments: true), ciertos enrichments son obligatorios para que la creación automática funcione. Sin ellos, el sistema no puede obtener los datos básicos de la persona de los registros oficiales y la solicitud fallará.

Brasil (BR)

Escenario	Código(s) de Enrichment Obligatorio(s)	Descripción
Entidad principal	`br_bdc_basic_data_enrichment`	Obtiene datos de la persona vía BDC/CPF (nombre completo, fecha de nacimiento, dirección, etc.)
Relacionados (`depth > 0`)	`br_bdc_related_companies_enrichment` Y `br_bdc_related_persons_enrichment`	Ambos obligatorios en `autoExecuteIntegrations.enrichments`. Obtiene empresas y personas relacionadas con el individuo

Los enrichments de relaciones deben incluirse en el array autoExecuteIntegrations.enrichments de la entidad principal (no en autoExecuteIntegrationsShareholders), porque el sistema necesita ejecutarlos sobre la persona principal para descubrir las relaciones. El campo autoExecuteIntegrationsShareholders controla qué enrichments ejecutar sobre cada entidad relacionada después de ser creada.

Argentina (AR)

Escenario	Código de Enrichment Obligatorio	Descripción
Entidad principal	`ar_nosis_extended_verification_enrichment`	Obtiene datos de la persona de Nosis

Argentina no soporta la creación automática de relaciones aún. El parámetro depth debe ser 0.

customData

object

Opcional — Datos del cliente para la persona principal que no deben ser reemplazados por enrichments. Detalle completo (tabla root vs entityData): Creación automática de entidades.Campos: name, email, phone, birthDate → entityData.person.dateOfBirth, address → entityData.person.address, gender (enum: M | F | male | female | other | unknown — usar other para no binario; ver Crear entidad).Ejemplo:

{
  "taxId": "23450679909",
  "country": "AR",
  "type": "person",
  "customData": {
    "name": "LEDESMA BRUNO EZEQUIEL",
    "email": "cliente@empresa.com",
    "phone": "+541112345678",
    "birthDate": "1990-05-15",
    "address": "Av. Corrientes 1234, CABA"
  }
}

attributes

object

Opcional - Atributos personalizados como pares clave-valor para la entidad creada.Se aplican solo a la entidad principal (la persona creada), no a relaciones/accionistas. Útil para segmentos de negocio, etiquetas, IDs internos o cualquier metadato que quieras asociar desde el momento de la creación.Estructura: objeto con claves string y valores de cualquier tipo (string, number, boolean, array, etc.).Ejemplo:

{
  "businessSegments": ["retail", "fintech"],
  "source": "onboarding_web",
  "tags": ["vip", "high_volume"]
}

Respuesta

success

boolean

Indica si la persona fue creada exitosamente

data

object

Información completa sobre la creación:

entity (object) - La persona creada con todos los datos
summary (object) - Resumen de creación
errors (object, opcional) - Detalles de cualquier error

rulesResult

object

Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es false y hay matriz configurada vía riskMatrixId o riskMatrixIds), o null. Cuando está presente, incluye:

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 y se ejecutó la matriz de riesgo). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron. Estructura completa y ejemplo: Resumen de Ejecución de Reglas.

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.

Ejemplos

Crear Persona con Todas las Integraciones Activas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "person",
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
    }
  }'

Crear Persona con Integraciones Específicas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "person",
    "externalId": "customer_12345",
    "autoExecuteIntegrations": {
      "enrichments": ["br_bdc_basic_data_enrichment"]
    }
  }'

Ejemplo de Respuesta

{
  "success": true,
  "data": {
    "entity": {
      "id": "person_uuid",
      "organizationId": "org_uuid",
      "type": "person",
      "name": "João Silva",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "person": {
          "firstName": "João",
          "lastName": "Silva",
          "dateOfBirth": "1985-05-15",
          "nationality": "BR"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Respuestas de Error

400 Bad Request - Tax ID Inválido

{
  "success": false,
  "error": "Invalid CPF format for Brazil"
}

404 Not Found - Persona No Encontrada en Registro

{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

409 Conflict - Persona Ya Existe

{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "123.456.789-00"
  }
}

Mejores Prácticas

Manejo de errores: Siempre verifica el campo success en la respuesta
Límite de tasa: Ten en cuenta los límites de tasa al crear múltiples personas
Selección de integración: Elige integraciones específicas para un mejor control sobre costo y rendimiento

Próximos Pasos

Obtener Persona - Recuperar detalles de persona
Crear Persona Manualmente - Crear personas con tus propios datos
Crear Validación KYC - Iniciar verificación de identidad

Crear una entidad persona Obtener una persona por ID

⌘I

​Resumen

​Endpoint

​Autenticación

​Cuerpo de la Solicitud

​Códigos de Enrichment Obligatorios por País

​Brasil (BR)

​Argentina (AR)

​Respuesta

​Ejemplos

​Crear Persona con Todas las Integraciones Activas

​Crear Persona con Integraciones Específicas

​Ejemplo de Respuesta

​Respuestas de Error

​400 Bad Request - Tax ID Inválido

​404 Not Found - Persona No Encontrada en Registro

​409 Conflict - Persona Ya Existe

​Mejores Prácticas

​Próximos Pasos

Resumen

Endpoint

Autenticación

Cuerpo de la Solicitud

Códigos de Enrichment Obligatorios por País

Brasil (BR)

Argentina (AR)

Respuesta

Ejemplos

Crear Persona con Todas las Integraciones Activas

Crear Persona con Integraciones Específicas

Ejemplo de Respuesta

Respuestas de Error

400 Bad Request - Tax ID Inválido

404 Not Found - Persona No Encontrada en Registro

409 Conflict - Persona Ya Existe

Mejores Prácticas

Próximos Pasos