> ## 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 empresa automáticamente con enriquecimiento
> Crea empresas automáticamente con datos enriquecidos de registros oficiales — en la plataforma gu1 para procesos KYB de compliance y análisis de riesgo.
## Descripción general
El endpoint de creación automática de empresas te permite crear empresas proporcionando información mínima (Tax ID y país). El sistema automáticamente:
* Obtiene datos de la empresa de registros oficiales
* Enriquece la empresa con información adicional
* Ejecuta enriquecimientos automáticamente
Esto es ideal para procesos KYB (Know Your Business) donde deseas incorporar negocios 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 empresa (ej., CNPJ para Brasil, RFC para México, CUIT para Argentina)
📋 Ver [Formatos de Tax ID por País](/es/api-reference/entities/tax-id-formats) para formatos aceptados y reglas de validación para cada país.
Código de país ISO 3166-1 alpha-2 (ej., "BR", "MX", "AR", "CL")
Debe establecerse como `company`
Tu identificador único para esta empresa (opcional, se generará automáticamente si no se proporciona)
Marcar esta empresa como cliente/negocio para fines de seguimiento
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`).
Preferido para **varias** matrices: lista ordenada de UUIDs. Tiene precedencia sobre `riskMatrixId` cuando viene informada y no vacía.
Omitir la ejecución automática de reglas después de la creación de la empresa
Estado inicial de la empresa
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`.
Profundidad de extracción de relaciones (0-5). Controla cuántos niveles de accionistas/relaciones obtener y crear automáticamente.
* `0`: Sin relaciones (solo entidad principal)
* `1`: Solo accionistas directos
* `2`: Accionistas + sus accionistas
* `3-5`: Niveles adicionales (usar con precaución - puede crear muchas entidades)
Configurar la ejecución automática de integraciones para la entidad principal de la empresa. Ver [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 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.
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean; // predeterminado: false
enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
enrichmentGroupRefs?: string[];
}
```
**Ejemplo:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"],
}
```
Configurar la ejecución automática de integraciones para accionistas/relaciones descubiertos. Útil cuando se usa `depth > 0`. Ver [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 todos los enriquecimientos activos en accionistas
* `enrichments` (object, opcional) - Enriquecimientos específicos por tipo de entidad
* `company` (array, predeterminado: `[]`) - Enriquecimientos para accionistas empresa
* `person` (array, predeterminado: `[]`) - Enriquecimientos para accionistas 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.
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean;
enrichments?: {
company?: ValidProviderCodesEnum[];
person?: ValidProviderCodesEnum[];
};
enrichmentGroupRefs?: string[];
}
```
**Ejemplo:**
```json theme={null}
{
"enrichments": {
"person": [
"br_cpfcnpj_complete_person_enrichment",
"global_complyadvantage_person_search_enrichment"
],
"company": ["br_cpfcnpj_complete_company_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 empresa de los registros oficiales y la solicitud fallará.
### Brasil (BR)
| Escenario | Código(s) de Enrichment Obligatorio(s) | Descripción |
| ----------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Entidad principal** | `br_cpfcnpj_complete_company_enrichment` | Obtiene datos de la empresa de CNPJ/Receita Federal (razón social, nombre comercial, dirección, industria, etc.) |
| **Accionistas** (`depth > 0`) | `br_bdc_shareholders_enrichment` | Obligatorio en `autoExecuteIntegrations.enrichments`. Obtiene el QSA (Quadro Societário) para descubrir accionistas y directores |
El enrichment de accionistas debe incluirse en el array `autoExecuteIntegrations.enrichments` de la **entidad principal** (no en `autoExecuteIntegrationsShareholders`), porque el sistema necesita ejecutarlo sobre la empresa principal para descubrir el QSA. El campo `autoExecuteIntegrationsShareholders` controla qué enrichments ejecutar **sobre cada accionista** después de ser creado.
### Argentina (AR)
| Escenario | Código de Enrichment Obligatorio | Descripción |
| --------------------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Entidad principal** | `ar_nosis_extended_verification_enrichment` | Obtiene datos de la empresa de Nosis (razón social, estado CUIT, dirección, actividades, etc.) |
Argentina **no soporta** la creación automática de accionistas aún. El parámetro `depth` debe ser `0`. Si se proporciona `depth > 0`, la solicitud fallará con un error.
**Opcional** — Datos del cliente para la **empresa principal** que no deben ser reemplazados por enrichments. Detalle completo: [Creación automática de entidades](/es/api-reference/entities/create-automatic).
Campos: `name`, `email`, `phone`, `address` → `entityData.company.address` (`birthDate` no aplica a empresas).
**Ejemplo:**
```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 (la 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"]
}
```
## Respuesta
Indica si la empresa se creó exitosamente
Información completa sobre la creación:
* `entity` (object) - La empresa creada con todos los datos
* `summary` (object) - Resumen de creación
* `errors` (object, opcional) - Detalles de cualquier error
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**, **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 empresa con todas las integraciones activas
```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": "company",
"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: '123.456.789-00',
country: 'BR',
type: 'company',
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log('Company created:', data.data.entity);
```
```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': 'company',
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print('Company created:', data['data']['entity'])
```
### Crear empresa 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": "company",
"externalId": "business_12345",
"autoExecuteIntegrations": {
"enrichments": ["br_cpfcnpj_complete_company_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: 'company',
externalId: 'business_12345',
autoExecuteIntegrations: {
enrichments: ['br_cpfcnpj_complete_company_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': 'company',
'externalId': 'business_12345',
'autoExecuteIntegrations': {
'enrichments': ['br_cpfcnpj_complete_company_enrichment'],
}
}
)
data = response.json()
```
## Ejemplo de respuesta
```json theme={null}
{
"success": true,
"data": {
"entity": {
"id": "company_uuid",
"organizationId": "org_uuid",
"type": "company",
"name": "Tech Solutions LTDA",
"taxId": "12345678900",
"countryCode": "BR",
"status": "under_review",
"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"
},
"summary": {
"entitiesCreated": 1,
"relationshipsCreated": 0,
"errorsCount": 0
}
},
"rulesResult": null
}
```
## Respuestas de error
### 400 Bad Request - Tax ID inválido
```json theme={null}
{
"success": false,
"error": "Invalid CPF format for Brazil"
}
```
### 404 Not Found - Empresa no encontrada en el registro
```json theme={null}
{
"success": false,
"error": "Entity not found in official registry",
"details": {
"taxId": "123.456.789-00",
"country": "BR",
"registry": "Receita Federal"
}
}
```
### 409 Conflict - La empresa ya existe
```json theme={null}
{
"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 velocidad**: Ten en cuenta los límites de velocidad al crear múltiples empresas
3. **Selección de integración**: Elige integraciones específicas para un mejor control sobre el costo y el rendimiento
## Próximos pasos
* [Obtener empresa](/es/api-reference/company/get) - Recuperar detalles de la empresa
* [Crear empresa manualmente](/es/api-reference/company/create) - Crear empresas con tus propios datos
* [Crear validación KYB](/es/use-cases/kyc/create-validation) - Iniciar verificación de identidad