Skip to main content
POST
/
entities
/
automatic
Crear Automáticamente
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>",
  "skipRulesExecution": true,
  "status": "<string>",
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "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 integraciones (verificaciones y 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
UUID de la matriz de riesgo para ejecutar reglas automáticamente
​
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
​
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
  • executeAllActiveChecks (boolean, opcional, predeterminado: false) - Ejecutar todas las integraciones de verificación activas
  • enrichments (array, opcional, predeterminado: []) - Array de códigos específicos de proveedor de enriquecimiento a ejecutar
  • checks (array, opcional, predeterminado: []) - Array de códigos específicos de proveedor de verificación a ejecutar
{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  executeAllActiveChecks?: boolean; // predeterminado: false
  enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
  checks?: ValidProviderCodesEnum[]; // predeterminado: []
}
Ejemplo:
{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_bdc_basic_data_enrichment"],
  "checks": ["pep_check", "sanctions_check"]
}
​
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
  • executeAllActiveChecks (boolean, opcional, predeterminado: false) - Ejecutar todas las verificaciones activas 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
  • checks (object, opcional) - Verificaciones específicas por tipo de entidad
    • company (array, predeterminado: []) - Verificaciones para relaciones de empresa
    • person (array, predeterminado: []) - Verificaciones para relaciones de persona
{
  executeAllActiveEnrichments?: boolean;
  executeAllActiveChecks?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  checks?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
}
Ejemplo:
{
  "enrichments": {
    "person": ["br_cpfcnpj_complete_person_enrichment"],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  }
}

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

EscenarioCódigo(s) de Enrichment Obligatorio(s)Descripción
Entidad principalbr_bdc_basic_data_enrichmentObtiene 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_enrichmentAmbos 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)

EscenarioCódigo de Enrichment ObligatorioDescripción
Entidad principalar_nosis_extended_verification_enrichmentObtiene 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.
​
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 se proporcionó riskMatrixId), 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,
      "executeAllActiveChecks": 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

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

​
Próximos Pasos