Crear Automáticamente

Descripción General

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

Obtiene datos de empresa/persona de registros oficiales
Enriquece la entidad con información adicional
Crea entidades relacionadas (accionistas, directores) según la profundidad especificada
Ejecuta integraciones (verificaciones y enriquecimientos) automáticamente

Esto es ideal para procesos KYB (Know Your Business) y KYC (Know Your Customer) donde desea incorporar entidades 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 entidad (ej: CNPJ para Brasil, RFC para México, CUIT para Argentina)Tipo: string (longitud mínima: 1)

country

string

required

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

type

string

required

Tipo de entidad a crear:

company - Entidad empresarial
person - Persona física

Tipo: enum - 'company' | 'person'

externalId

string

Su identificador único para esta entidad en su sistema (opcional, se generará automáticamente si no se proporciona)Tipo: string (opcional)

depth

number

default:"0"

Cuántos niveles de accionistas/relaciones crear automáticamente:

0 - Crear solo la entidad principal (sin relaciones)
1 - Crear accionistas/directores directos
2 - Crear accionistas y sus accionistas
Máximo: 5

Tipo: number (mín: 0, máx: 5, predeterminado: 0)

isClient

boolean

default:"false"

Marcar esta entidad como cliente para fines de seguimientoTipo: boolean (predeterminado: false)

riskMatrixId

string

UUID de la matriz de riesgo para ejecutar reglas automáticamenteTipo: string | null (opcional)

skipRulesExecution

boolean

default:"false"

Omitir ejecución automática de reglas después de la creación de la entidadTipo: boolean (opcional, predeterminado: false)

status

string

default:"under_review"

Estado inicial para la entidad. Opciones:

active
inactive
blocked
under_review (predeterminado)
suspended
pending_verification
expired
deleted
rejected

Tipo: enum -

'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'pending_verification' | 'expired' | 'deleted' | 'rejected'

(predeterminado: ‘under_review’)

autoExecuteIntegrations

object

Configurar ejecución automática de integraciones para la entidad principal. Vea Referencia de Códigos de Proveedores 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 proveedores de enriquecimiento para ejecutar
checks (array, opcional, predeterminado: []) - Array de códigos específicos de proveedores de verificación para ejecutar

{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  executeAllActiveChecks?: boolean; // predeterminado: false
  enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
  checks?: ValidProviderCodesEnum[]; // predeterminado: []
}

Ejemplo:

{
  "executeAllActiveEnrichments": true,
  "executeAllActiveChecks": false,
  "enrichments": ["serpro_cnpj", "receita_federal"],
  "checks": ["pep_check", "sanctions_check"]
}

autoExecuteIntegrationsShareholders

object

Configurar ejecución automática de integraciones para accionistas y entidades relacionadas creadas durante el recorrido de la jerarquía. Esto le permite especificar diferentes integraciones para empresas vs personas. Vea Referencia de Códigos de Proveedores para códigos disponibles.Tipo: object (opcional)Propiedades:

executeAllActiveEnrichments (boolean, opcional, predeterminado: false) - Ejecutar todas las integraciones de enriquecimiento activas para todos los accionistas
executeAllActiveChecks (boolean, opcional, predeterminado: false) - Ejecutar todas las integraciones de verificación activas para todos los accionistas
enrichments (object, opcional) - Códigos específicos de proveedores de enriquecimiento por tipo de entidad:
- company (array, opcional, predeterminado: []) - Enriquecimientos para accionistas empresas
- person (array, opcional, predeterminado: []) - Enriquecimientos para accionistas personas
checks (object, opcional) - Códigos específicos de proveedores de verificación por tipo de entidad:
- company (array, opcional, predeterminado: []) - Verificaciones para accionistas empresas
- person (array, opcional, predeterminado: []) - Verificaciones para accionistas personas

{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  executeAllActiveChecks?: boolean; // predeterminado: false
  enrichments?: {
    company?: ValidProviderCodesEnum[]; // predeterminado: []
    person?: ValidProviderCodesEnum[]; // predeterminado: []
  };
  checks?: {
    company?: ValidProviderCodesEnum[]; // predeterminado: []
    person?: ValidProviderCodesEnum[]; // predeterminado: []
  };
}

Ejemplo:

{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": {
    "company": ["serpro_cnpj", "receita_federal"],
    "person": ["serpro_cpf"]
  },
  "checks": {
    "company": ["sanctions_check"],
    "person": ["pep_check", "sanctions_check"]
  }
}

attributes

object

Opcional - Atributos personalizados como pares clave-valor para la entidad creada.Se aplican solo a la entidad principal (persona o empresa creada), no a accionistas/relaciones. Ú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"]
}

Parámetros de Query

refresh

boolean

default:"false"

Fuerza el re-enriquecimiento de la entidad principal incluso si ya existe en el sistema.Tipo: boolean (query string: "true" o "false")Comportamiento:

Cuando es true: Fuerza la búsqueda de datos actualizados de registros oficiales y proveedores de enriquecimiento
Cuando es false u omitido: Utiliza datos de enriquecimiento en caché si están disponibles
Sobreescribe la configuración de organización enrichmentsConfig.reEnrichExistingEntities

Casos de Uso:

Revisiones periódicas de cumplimiento que requieren información actualizada
Re-validar datos de entidad después de cambios regulatorios
Actualizar estructura empresarial después de cambios corporativos conocidos
Actualización manual activada por oficiales de cumplimiento

Ejemplo:

POST http://api.gu1.ai/entities/automatic?refresh=true

Nota de Costo: Puede incurrir en cargos adicionales de proveedores de datos terceros.

refreshShareholders

boolean

default:"false"

Fuerza el re-enriquecimiento de TODOS los accionistas y entidades relacionadas en la estructura corporativa.Tipo: boolean (query string: "true" o "false")Comportamiento:

Cuando es true: Fuerza la búsqueda de datos actualizados para la entidad principal Y todos los accionistas en todos los niveles (hasta depth)
Cuando es false u omitido: Solo actualiza la entidad principal si refresh=true, los accionistas usan datos en caché
Funciona en combinación con el parámetro depth para determinar qué tan profundo actualizar
Sobreescribe configuración de organización para todas las entidades relacionadas

Casos de Uso:

Auditoría completa de estructura corporativa
Due diligence que requiere cadena de propiedad actualizada
Revisiones anuales de cumplimiento de todo el árbol corporativo
Investigación de estructuras de propiedad complejas

Ejemplo - Actualizar estructura completa:

POST http://api.gu1.ai/entities/automatic?refreshShareholders=true&depth=3

Esto actualizará la empresa principal Y todos los accionistas hasta 3 niveles de profundidad.Nota de Rendimiento:

Establecer esto en true con valores altos de depth (4-5) puede tomar varios minutos
Puede resultar en costos significativos si la estructura corporativa es compleja
Considere usar selectivamente solo para entidades de alto riesgo

Mejor Práctica:

Use refresh=true solo para actualizaciones de entidad única
Use refreshShareholders=true solo cuando necesite validación completa de la cadena de propiedad

Respuesta

El endpoint se ejecuta síncronamente y retorna el resultado completo incluyendo la entidad principal y todas las entidades relacionadas creadas.

success

boolean

Indica si la entidad se creó correctamente

data

object

Información completa sobre la creación:

entity (object) - La entidad principal creada con todos sus datos
shareholders (array) - Array de entidades de accionistas creadas (para empresas)
relationships (array) - Array de entidades relacionadas creadas (para personas)
summary (object):
- entitiesCreated (number) - Número total de entidades creadas
- relationshipsCreated (number) - Número total de relaciones creadas
- errorsCount (number) - Número de errores encontrados
errors (object, opcional) - Detalles de cualquier error que ocurrió:
- creationFailed (array) - Creaciones de entidades que fallaron
- enrichmentFailed (array) - Ejecuciones de enriquecimiento que fallaron

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 (array de { name?, type?, severity?, description? }), 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.

Eventos WebSocket

El sistema emite eventos en tiempo real durante el proceso de creación:

`entity:creation-started`

Emitido cuando el proceso de creación comienza.

{
  "taxId": "12.345.678/0001-90",
  "type": "company",
  "userId": "user_id"
}

`entity:creation-completed`

Emitido cuando la entidad y todas las relaciones han sido creadas.

{
  "success": true,
  "mainEntity": {
    "id": "uuid",
    "name": "Nombre de la Empresa",
    "taxId": "12.345.678/0001-90"
  },
  "stats": {
    "totalEntitiesCreated": 15,
    "companiesCreated": 8,
    "peopleCreated": 7,
    "relationshipsCreated": 14
  }
}

`entity:creation-failed`

Emitido si el proceso de creación falla.

{
  "success": false,
  "error": "Mensaje de error",
  "taxId": "12.345.678/0001-90"
}

Ejemplos

Crear Empresa con Accionistas (Profundidad 1)

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "type": "company",
    "depth": 1,
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
      "executeAllActiveChecks": true
    }
  }'

Crear Persona (KYC) 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",
    "depth": 0,
    "autoExecuteIntegrations": {
      "enrichments": ["serpro_cpf", "bureau_credit"],
      "checks": ["pep_check", "sanctions_check"]
    }
  }'

Crear Empresa con Jerarquía Profunda e Integraciones Selectivas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "30-12345678-9",
    "country": "AR",
    "type": "company",
    "depth": 2,
    "isClient": true,
    "riskMatrixId": "risk_matrix_uuid",
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true
    },
    "autoExecuteIntegrationsShareholders": {
      "enrichments": {
        "company": ["afip_company"],
        "person": ["renaper_dni"]
      },
      "checks": {
        "company": [],
        "person": ["pep_check"]
      }
    }
  }'

Ejemplo de Respuesta

Creación Exitosa de Empresa con Accionistas

{
  "success": true,
  "data": {
    "entity": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions LTDA",
      "taxId": "12345678000190",
      "countryCode": "BR",
      "status": "under_review",
      "riskScore": null,
      "entityData": {
        "company": {
          "legalName": "Tech Solutions LTDA",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-01-15",
          "industry": "Technology"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "shareholders": [
      {
        "id": "shareholder_1_uuid",
        "type": "person",
        "name": "João Silva",
        "taxId": "12345678900",
        "countryCode": "BR",
        "entityData": {
          "person": {
            "firstName": "João",
            "lastName": "Silva"
          }
        },
        "shareholderInfo": {
          "percentage": 60.0,
          "role": "Sócio Administrador"
        }
      },
      {
        "id": "shareholder_2_uuid",
        "type": "person",
        "name": "Maria Santos",
        "taxId": "98765432100",
        "countryCode": "BR",
        "entityData": {
          "person": {
            "firstName": "Maria",
            "lastName": "Santos"
          }
        },
        "shareholderInfo": {
          "percentage": 40.0,
          "role": "Sócia"
        }
      }
    ],
    "summary": {
      "entitiesCreated": 3,
      "relationshipsCreated": 2,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Creación Exitosa de Persona

{
  "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"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "relationships": [],
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Respuestas de Error

400 Bad Request - ID Fiscal Inválido

{
  "success": false,
  "error": "Formato de CNPJ inválido para Brasil"
}

404 Not Found - Entidad No Encontrada en el Registro

{
  "success": false,
  "error": "Entidad no encontrada en el registro oficial",
  "details": {
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

409 Conflict - La Entidad Ya Existe

{
  "success": false,
  "error": "La entidad con este ID fiscal ya existe",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "12.345.678/0001-90"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": "Error al crear entidad automáticamente",
  "details": {
    "message": "Timeout de API externa"
  }
}

Mejores Prácticas

Use la profundidad sabiamente: Valores de profundidad más altos (3-5) pueden crear muchas entidades y tardar más en completarse. Comience con profundidad 0-1 para pruebas.
Monitoree eventos WebSocket: Aunque la API retorna síncronamente, los eventos WebSocket también se emiten para actualizaciones de UI en tiempo real (entity:creation-started, entity:creation-completed, entity:creation-failed).
Maneje timeouts: Para jerarquías complejas con alta profundidad, la solicitud puede tomar varios minutos. Configure valores de timeout HTTP apropiados en su cliente.
Manejo de errores: Siempre verifique el campo success y el objeto errors en la respuesta. Algunas entidades pueden crearse exitosamente mientras otras fallan.
Limitación de velocidad: Tenga cuidado con los límites de velocidad al crear múltiples entidades en rápida sucesión. El endpoint obtiene datos de APIs externas que pueden tener sus propios límites de velocidad.

Endpoints Relacionados

Crear Entidad Manualmente - Crear entidades con sus propios datos
Obtener Entidad - Recuperar detalles de la entidad
Listar Entidades - Consultar sus entidades

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Descripción General

​Endpoint

​Autenticación

​Cuerpo de la Solicitud

​Parámetros de Query

​Respuesta

​Eventos WebSocket

​entity:creation-started

​entity:creation-completed

​entity:creation-failed

​Ejemplos

​Crear Empresa con Accionistas (Profundidad 1)

​Crear Persona (KYC) con Integraciones Específicas

​Crear Empresa con Jerarquía Profunda e Integraciones Selectivas

​Ejemplo de Respuesta

​Creación Exitosa de Empresa con Accionistas

​Creación Exitosa de Persona

​Respuestas de Error

​400 Bad Request - ID Fiscal Inválido

​404 Not Found - Entidad No Encontrada en el Registro

​409 Conflict - La Entidad Ya Existe

​500 Internal Server Error

​Mejores Prácticas

​Endpoints Relacionados

Descripción General

Endpoint

Autenticación

Cuerpo de la Solicitud

Parámetros de Query

Respuesta

Eventos WebSocket

`entity:creation-started`

`entity:creation-completed`

`entity:creation-failed`

Ejemplos

Crear Empresa con Accionistas (Profundidad 1)

Crear Persona (KYC) con Integraciones Específicas

Crear Empresa con Jerarquía Profunda e Integraciones Selectivas

Ejemplo de Respuesta

Creación Exitosa de Empresa con Accionistas

Creación Exitosa de Persona

Respuestas de Error

400 Bad Request - ID Fiscal Inválido

404 Not Found - Entidad No Encontrada en el Registro

409 Conflict - La Entidad Ya Existe

500 Internal Server Error

Mejores Prácticas

Endpoints Relacionados