> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Crear una entidad automáticamente con enriquecimiento
> Crea automáticamente con datos enriquecidos de registros oficiales — en el modelo universal de entidades gu1 para KYC, KYB y análisis de riesgo.
## 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 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:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Cuerpo de la Solicitud
Número de identificación fiscal de la entidad (ej: CNPJ para Brasil, RFC para México, CUIT para Argentina).
En una organización, un **`taxId`** activo (normalizado: solo letras y dígitos) puede pertenecer a **una sola** entidad — sea `person` o `company`. Si ya existe el mismo tipo, la API lo reutiliza (`alreadyExisted`). Si otro tipo ya tiene ese tax ID, la solicitud falla con **`409`** y código **`DUPLICATE_TAX_ID`**.
**Tipo**: `string` (longitud mínima: 1)
Código de país ISO 3166-1 alpha-2 (ej: "BR", "MX", "AR", "CL")
**Tipo**: `string` (longitud: 2)
Tipo de entidad a crear:
* `company` - Entidad empresarial
* `person` - Persona física
**Tipo**: `enum` - `'company' | 'person'`
Opcional. ISO 3166-1 alfa-2 o etiqueta mapeable; se guarda en la fila de la **entidad principal** (misma validación que [Crear entidad](/es/api-reference/entities/create)).
Opcional. Misma semántica que en [Crear entidad](/es/api-reference/entities/create#ejemplo-monitoreo-de-sanciones-gu1-al-crear), con dos mapas:
* **`main`**: watchlist para enrichments de la **entidad raíz** (taxId del request).
* **`relationships`**: watchlist para enrichments de **accionistas/relacionadas** creadas con `depth` > 0 (mismas claves de código que en `autoExecuteIntegrationsShareholders`).
**Hoy solo** `global_gueno_sanctions_enrichment`. Valor recomendado: `{ "watchlist": true }` o `{ "watchlist": true, "riskMatrixId": "" | null }` (también acepta `boolean` legacy).
Cada mapa solo afecta entidades que **reciben** ese enrichment en el job. Requiere el código en el arreglo de enrichments correspondiente y monitoreo ON en Marketplace.
Su identificador único para esta entidad en su sistema. **Opcional.**
Si se omite, `externalId` se establece con el **tax ID normalizado** a partir del **`taxId` obligatorio**: solo letras y dígitos, mayúsculas (sin puntos, guiones ni espacios). Ejemplo: `30-12345678-9` → `30123456789`.
El campo **`taxId`** se sigue guardando en el [formato de visualización del país](/es/api-reference/entities/tax-id-formats). Mismas reglas que [Crear una entidad (persona o empresa)](/es/api-reference/entities/create) cuando hay `taxId`.
**Tipo**: `string` (opcional)
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)
Marcar esta entidad como cliente para fines de seguimiento
**Tipo**: `boolean` (predeterminado: false)
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`).
**Tipo**: `string | string[] | null` (opcional)
Preferido para **varias** matrices: lista ordenada de UUIDs. Tiene precedencia sobre `riskMatrixId` cuando viene informada y no vacía.
**Tipo**: `string[]` (opcional)
Omitir ejecución automática de reglas después de la creación de la entidad
**Tipo**: `boolean` (opcional, predeterminado: false)
Estado inicial para la entidad. Opciones:
* `active`
* `inactive`
* `blocked`
* `under_review` (predeterminado)
* `suspended`
* `expired`
* `deleted`
* `rejected`
**Tipo**: `enum` - `'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected'` (predeterminado: 'under\_review')
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`.
Configurar ejecución automática de integraciones para la entidad principal. Vea [Referencia de Códigos de Proveedores](/es/api-reference/integrations/provider-codes) 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 proveedores de enriquecimiento para 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.
* `excludeEnrichments` (array, opcional, predeterminado: `[]`) - Códigos de proveedor que se omiten del conjunto final resuelto
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean; // predeterminado: false
enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // predeterminado: []
}
```
**Ejemplo:**
```json theme={null}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"]
}
```
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](/es/api-reference/integrations/provider-codes) para códigos disponibles.
**Tipo**: `object` (opcional)
**Propiedades:**
* `executeAllActiveEnrichments` (boolean, opcional, predeterminado: `false`) - Ejecutar todas las integraciones de enriquecimiento 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
* `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.
* `excludeEnrichments` (array, opcional, predeterminado: `[]`) - Códigos omitidos en las listas `company` y `person` tras el merge
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean; // predeterminado: false
enrichments?: {
company?: ValidProviderCodesEnum[]; // predeterminado: []
person?: ValidProviderCodesEnum[]; // predeterminado: []
};
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // predeterminado: []
}
```
**Ejemplo:**
```json theme={null}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["shareholder_pipeline_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 entidad de los registros oficiales y la solicitud fallará.
### Brasil (BR)
#### Entidad Principal
| Tipo de Entidad | Código de Enrichment Obligatorio | Descripción |
| --------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Company** | `br_cpfcnpj_complete_company_enrichment` | Obtiene datos de la empresa de CNPJ/Receita Federal (razón social, nombre comercial, dirección, industria, etc.) |
| **Person** | `br_bdc_basic_data_enrichment` | Obtiene datos de la persona vía BDC/CPF (nombre completo, fecha de nacimiento, dirección, etc.) |
#### Accionistas / Entidades Relacionadas (solo cuando `depth > 0`)
| Tipo de Entidad Principal | Código(s) de Enrichment Obligatorio(s) | Descripción |
| ------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Company** | `br_bdc_shareholders_enrichment` | Obtiene el QSA (Quadro Societário) para descubrir accionistas y directores de la empresa |
| **Person** | `br_bdc_related_companies_enrichment` **Y** `br_bdc_related_persons_enrichment` | Ambos son obligatorios. Obtiene empresas y personas relacionadas con el individuo |
Los enrichments de accionistas deben incluirse en el array `autoExecuteIntegrations.enrichments` de la **entidad principal** (no en `autoExecuteIntegrationsShareholders`), porque el sistema necesita ejecutarlos sobre la entidad principal para descubrir quiénes son los accionistas. El campo `autoExecuteIntegrationsShareholders` controla qué enrichments ejecutar **sobre cada accionista** después de ser creado.
### Argentina (AR)
#### Entidad Principal
| Tipo de Entidad | Código de Enrichment Obligatorio | Descripción |
| --------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Company** | `ar_nosis_extended_verification_enrichment` | Obtiene datos de la empresa de Nosis (razón social, estado CUIT, dirección, actividades, etc.) |
| **Person** | `ar_nosis_extended_verification_enrichment` | Mismo proveedor para ambos tipos de entidad |
#### Accionistas / Entidades Relacionadas
Argentina **no soporta** la creación automática de accionistas/relaciones aún. El parámetro `depth` debe ser `0`. Si se proporciona `depth > 0`, la solicitud fallará con un error.
**Opcional** — Datos que envía el cliente para la **entidad principal** y que **no** deben ser reemplazados por los enrichments del registro. No aplica a accionistas ni entidades relacionadas (`depth > 0`).
Tras los enrichments, la API **re-aplica** los valores enviados en `customData` para que no se pierdan (p. ej. sincronización automática de nombre).
**Dónde se persiste cada campo:**
| Campo en `customData` | Columna root (`entities`) | `entityData` | |
| --------------------- | ------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `name` | — | |
| `email` | `email` | `person.email` / `company.email` | |
| `phone` | `phone` | `person.phone` / `company.phone` | |
| `birthDate` | — | Solo `person.dateOfBirth` (personas) | |
| `address` | — | `person.address` o `company.address` | |
| `gender` | — | `person.gender` | Opcional. Enum cerrado: `M`, `F`, `male`, `female`, `other`, `unknown`. Usar **`other`** para identidad no binaria. Valores como `X` o `non_binary` se rechazan. En **AR**, solo `M`/`F` (o `male`/`female`) aplican a derivación CUIL y RENAPER. Ver [Crear entidad — Persona](/es/api-reference/entities/create#entidad-persona). |
**Propiedades documentadas:** `name`, `email`, `phone`, `birthDate` (persona), `address` (string o objeto con `fullAddress`, `street`, `city`, …), `gender` (enum opcional — `other` para no binario).
**Claves adicionales (solo API):** cualquier otra clave en `customData` se acepta y se guarda en `entityData.person` o `entityData.company` (misma protección contra enrichments). Ej.: `firstName`, `occupation`, `tradeName`. El dashboard solo envía los campos del formulario; integraciones vía API pueden ampliar el objeto.
**Ejemplo (persona):**
```json theme={null}
{
"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"
}
}
```
**Ejemplo (empresa):**
```json theme={null}
{
"taxId": "30712345678",
"country": "AR",
"type": "company",
"customData": {
"name": "Acme Argentina S.A. (nombre comercial)",
"email": "contacto@acme.com",
"phone": "+541140000000",
"address": {
"fullAddress": "Av. del Libertador 100, CABA",
"city": "Buenos Aires"
}
}
}
```
**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:**
```json theme={null}
{
"businessSegments": ["retail", "fintech"],
"source": "onboarding_web",
"tags": ["vip", "high_volume"]
}
```
## Parámetros de Query
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**:
```bash theme={null}
POST http://api.gu1.ai/entities/automatic?refresh=true
```
**Nota de Costo**: Puede incurrir en cargos adicionales de proveedores de datos terceros.
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**:
```bash theme={null}
POST http://api.gu1.ai/entities/automatic?reEnrichExistingChildEntities=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 `reEnrichExistingChildEntities=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.
Indica si la entidad se creó correctamente
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
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.
**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](/es/api-reference/rules-execution-summary).
* **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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"success": false,
"error": "Mensaje de error",
"taxId": "12.345.678/0001-90"
}
```
## Monitoreo de sanciones Gu1 en creación automática
En `POST /entities/automatic`:
| Campo | Aplica a |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `monitoring.main` | Entidad principal (`taxId` del body) cuando su enrichment corre desde `autoExecuteIntegrations`. |
| `monitoring.relationships` | Cada accionista/relacionada con `depth` > 0 cuando su enrichment corre desde `autoExecuteIntegrationsShareholders` (por `type` company/person). |
Hoy el único código con monitoreo vía body es **`global_gueno_sanctions_enrichment`**. Debe estar en el arreglo de enrichments del nivel que corresponda **y** en el mapa `main` o `relationships` con watchlist activo.
```json theme={null}
{
"taxId": "30-71000001-2",
"country": "AR",
"type": "company",
"depth": 1,
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
},
"relationships": {
"global_gueno_sanctions_enrichment": {
"watchlist": true,
"riskMatrixId": null
}
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_afip_registration_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"autoExecuteIntegrationsShareholders": {
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["global_gueno_sanctions_enrichment"],
"person": ["global_gueno_sanctions_enrichment"]
}
}
}
```
* **`main`**: la matriz Gu1 de la empresa matriz puede heredar `riskMatrixId` del body o usar matriz dedicada en el objeto.
* **`relationships`**: `riskMatrixId: null` hereda la matriz global de cada entidad hija; un UUID fija matriz solo para screening de monitoreo de esas hijas.
* Los enrichments de registro (p. ej. `ar_afip_registration_enrichment`) **no** usan `monitoring`; corren siempre como consulta normal.
Este cuerpo solo muestra **`monitoring`** y los códigos Gu1. Un request real debe incluir también los **enriquecimientos obligatorios de registro** para el `country` y `type` elegidos (ver **Códigos de enriquecimiento requeridos por país** más arriba); si no, la creación automática fallará.
## Ejemplos
### Crear Empresa con Accionistas (Profundidad 1)
```bash cURL theme={null}
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
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '12.345.678/0001-90',
country: 'BR',
type: 'company',
depth: 1,
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log(data);
// Escuchar eventos WebSocket
socket.on('entity:creation-completed', (result) => {
console.log('Entidad creada:', result.mainEntity);
console.log('Total de entidades creadas:', result.stats.totalEntitiesCreated);
});
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '12.345.678/0001-90',
'country': 'BR',
'type': 'company',
'depth': 1,
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print(data)
```
### Crear Persona (KYC) con Integraciones Específicas
```bash cURL theme={null}
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": ["br_bdc_basic_data_enrichment"]
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '123.456.789-00',
country: 'BR',
type: 'person',
externalId: 'customer_12345',
depth: 0,
autoExecuteIntegrations: {
enrichments: ['br_bdc_basic_data_enrichment']
}
})
});
const data = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '123.456.789-00',
'country': 'BR',
'type': 'person',
'externalId': 'customer_12345',
'depth': 0,
'autoExecuteIntegrations': {
'enrichments': ['br_bdc_basic_data_enrichment']
}
}
)
data = response.json()
```
### Crear Empresa Argentina (Sin Soporte de Accionistas)
```bash theme={null}
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": 0,
"isClient": true,
"riskMatrixId": "risk_matrix_uuid",
"autoExecuteIntegrations": {
"enrichments": ["ar_nosis_extended_verification_enrichment"]
}
}'
```
### Crear Empresa Brasileña con Accionistas e Integraciones Selectivas
```bash theme={null}
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": 2,
"isClient": true,
"riskMatrixId": "risk_matrix_uuid",
"autoExecuteIntegrations": {
"enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["main_entity_group_slug"]
},
"autoExecuteIntegrationsShareholders": {
"enrichments": {
"company": ["br_cpfcnpj_complete_company_enrichment"],
"person": ["br_bdc_basic_data_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
}
}'
```
## Ejemplo de Respuesta
### Creación Exitosa de Empresa con Accionistas
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"success": false,
"error": "Formato de CNPJ inválido para Brasil"
}
```
### 404 Not Found - Entidad No Encontrada en el Registro
```json theme={null}
{
"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
Se devuelve cuando el `taxId` normalizado ya está usado por una entidad **activa** de un **tipo distinto** en la misma organización (persona vs empresa). Los matches del mismo tipo se reutilizan en lugar de fallar.
```json theme={null}
{
"success": false,
"error": {
"code": "DUPLICATE_TAX_ID",
"message": "This tax ID is already registered for a company in this organization (Entity ID: uuid).",
"details": {
"existingEntityId": "uuid",
"existingEntityType": "company"
}
}
}
```
### 500 Internal Server Error
```json theme={null}
{
"success": false,
"error": "Error al crear entidad automáticamente",
"details": {
"message": "Timeout de API externa"
}
}
```
## Mejores Prácticas
1. **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.
2. **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`).
3. **Maneje timeouts**: Para jerarquías complejas con alta profundidad, la solicitud puede tomar varios minutos. Configure valores de timeout HTTP apropiados en su cliente.
4. **Manejo de errores**: Siempre verifique el campo `success` y el objeto `errors` en la respuesta. Algunas entidades pueden crearse exitosamente mientras otras fallan.
5. **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](/es/api-reference/entities/create) - Crear entidades con sus propios datos
* [Obtener Entidad](/es/api-reference/entities/get) - Recuperar detalles de la entidad
* [Listar Entidades](/es/api-reference/entities/list) - Consultar sus entidades