> ## 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 empresa
> Crear una nueva empresa con datos personalizados — para entidades de empresa en la plataforma de riesgo y compliance gu1, con ejemplos para create.
## Descripción general
Crea una nueva entidad de empresa con los atributos especificados. Las entidades de empresa representan organizaciones comerciales que deseas analizar en términos de riesgo y cumplimiento (KYB).
## Endpoint
```
POST http://api.gu1.ai/entities
```
## Autenticación
Requiere una clave API válida en el encabezado Authorization:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Cuerpo de la solicitud
Debe ser `company` para crear una entidad de empresa
Tu identificador único para esta empresa en tu sistema
Nombre para mostrar de la empresa
Código de país ISO 3166-1 alpha-2 (ej., "US", "BR", "AR")
Número de identificación fiscal (validado según el país)
📋 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.
Horario operativo opcional en **raíz** para reglas KYT. Misma forma que en [Crear entidad](/es/api-reference/entities/create): `timezone` + `weekly`.
Atributos personalizados como pares clave-valor
Estructura de datos específica de la empresa (ver abajo)
Fecha de registro de la empresa en formato ISO 8601 datetime (ej., "2024-01-15T10:30:00Z")
Marcar esta empresa como cliente para fines de seguimiento
Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Si se envían, tras la creación el sistema evalúa la empresa **solo** contra reglas activas de esas matrices (salvo `skipRulesExecution: true`). Misma semántica que `riskMatrixIds` cuando enviás un único id como string. Ver [Ejecución de Matriz de Riesgo](#ejecución-de-matriz-de-riesgo) abajo.
Forma preferida para **varias** matrices: lista ordenada de UUIDs de tu organización. Si viene informada y no vacía, tiene precedencia sobre `riskMatrixId`.
Omitir la ejecución automática de reglas después de la creación de la empresa. Use esto para crear la entidad primero y activar las reglas manualmente más tarde.
Estado inicial de la empresa. Opciones:
* `active` - Empresa activa
* `inactive` - Empresa inactiva
* `blocked` - Empresa bloqueada
* `under_review` - Empresa bajo revisión (predeterminado)
* `suspended` - Empresa suspendida
* `expired` - Registro de empresa expirado
* `deleted` - Eliminación lógica
* `rejected` - Empresa rechazada
Configurar la ejecución automática de enriquecimientos al crear la empresa.
**Estructura:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_nosis_extended_verification_enrichment",
"ar_bcra_deudas_enrichment",
"global_gueno_sanctions_enrichment"
],
"excludeEnrichments": []
}
```
**Propiedades:**
* `executeAllActiveEnrichments` (boolean) - Ejecutar todas las integraciones de enriquecimiento activas configuradas en su organización
* `enrichments` (string\[]) - Array de códigos específicos de proveedores de enriquecimiento a ejecutar
**Ejemplos de códigos válidos (empresa AR — deben coincidir con los valores string de `ValidProviderCodesEnum`):**
* `ar_nosis_extended_verification_enrichment` — enriquecimiento NOSIS extendido
* `ar_bcra_deudas_enrichment` — deudas BCRA
* `ar_repet_entity_enrichment` — REPET / listas (empresa)
* `global_complyadvantage_sanctions_enrichment` — ComplyAdvantage sanciones
* `global_gueno_sanctions_enrichment` — sanciones Gu1 (si está configurado)
Ver [Códigos de proveedores](/es/api-reference/integrations/company-provider-codes) y la referencia completa en [provider-codes](/es/api-reference/integrations/provider-codes).
Opcional. Igual que en [Crear entidad](/es/api-reference/entities/create): usá `monitoring.main` con `global_gueno_sanctions_enrichment: true` para **lista vigilada** cuando ese enriquecimiento corre desde `autoExecuteIntegrations`. **Solo está soportado ese código hoy.** Requiere monitoreo habilitado en Marketplace. Ejemplos: [Crear entidad — ejemplo Gu1](/es/api-reference/entities/create#ejemplo-monitoreo-de-sanciones-gu1-al-crear).
## Monitoreo de sanciones Gu1 (empresa)
```json theme={null}
{
"type": "company",
"externalId": "co_screening_001",
"name": "Tech Solutions S.A.",
"countryCode": "AR",
"taxId": "30-71000001-2",
"entityData": {
"company": {
"legalName": "Tech Solutions S.A.",
"tradeName": "Tech Solutions",
"industry": "Software"
}
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": true
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": ["global_gueno_sanctions_enrichment"],
}
}
```
## Estructura de datos de la entidad empresa
El objeto `entityData.company` debe contener:
```json theme={null}
{
"company": {
"legalName": "string",
"tradeName": "string",
"incorporationDate": "YYYY-MM-DD",
"companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other",
"industry": "string",
"websiteUrl": "string",
"employeeCount": number,
"revenue": number,
"revenueCurrency": "string",
"contactInfo": {
"email": "string",
"phone": "string",
"alternativePhone": "string"
},
"address": "string | object (ver nota de Formato de dirección)",
"city": "string",
"state": "string",
"country": "string",
"postalCode": "string"
}
}
```
**Formato de dirección**: El campo `address` admite ambos formatos:
* **Formato de cadena** (simple): `"Av. Paulista, 1000, São Paulo, SP, Brazil"`
* **Formato de objeto** (estructurado):
```json theme={null}
{
"street": "Av. Paulista",
"number": "1000",
"complement": "Suite 200",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "Brazil",
"postalCode": "01310-100"
}
```
***
## Ejecución de Matriz de Riesgo
Puede ejecutar automáticamente una o más matrices de riesgo (reglas de cumplimiento KYB) al crear una empresa proporcionando `riskMatrixId` o `riskMatrixIds`.
### Cómo funciona
1. **Obtenga su(s) ID(s) de Matriz de Riesgo** desde el panel de gu1 (formato: UUID)
2. **Incluya `riskMatrixId` o `riskMatrixIds` en su solicitud de creación**
3. El sistema automáticamente:
* Crea la entidad empresa
* Ejecuta todas las reglas KYB en la matriz
* Calcula el puntaje de riesgo
* Genera alertas de cumplimiento si es necesario
* Actualiza el estado de la empresa según los resultados
### Ejemplo con Matriz de Riesgo
```json theme={null}
{
"type": "company",
"name": "Tech Solutions S.A.",
"taxId": "30-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"entityData": {
"company": {
"legalName": "Tech Solutions S.A.",
"industry": "fintech",
"revenue": 5000000
}
}
}
```
### Ejemplo con varias matrices de riesgo
```json theme={null}
{
"type": "company",
"name": "Tech Solutions S.A.",
"taxId": "30-12345678-9",
"countryCode": "AR",
"riskMatrixIds": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
],
"entityData": {
"company": {
"legalName": "Tech Solutions S.A.",
"industry": "fintech"
}
}
}
```
### Combinado con enriquecimientos y monitoreo Gu1
```json theme={null}
{
"type": "company",
"name": "Tech Solutions S.A.",
"taxId": "30-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_nosis_extended_verification_enrichment",
"ar_bcra_deudas_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
},
"entityData": {
"company": {
"legalName": "Tech Solutions S.A.",
"industry": "fintech"
}
}
}
```
Ver el detalle de `monitoring` en [Crear entidad](/es/api-reference/entities/create#ejemplo-monitoreo-de-sanciones-gu1-al-crear).
***
## Respuesta
Indica si la empresa se creó exitosamente
El objeto de empresa creado incluyendo:
* `id` - ID interno de gu1
* `externalId` - Tu ID externo
* `organizationId` - ID de tu organización
* `type` - Siempre "company"
* `name` - Nombre de la empresa
* `riskScore` - Puntuación de riesgo inicial (0-100)
* `status` - Estado de la empresa
* `entityData` - Datos específicos de la empresa
* `attributes` - Atributos personalizados
* `createdAt` - Marca de tiempo de creación
* `updatedAt` - Marca de tiempo de última actualización
Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando **skipRulesExecution** es `false` y hay matriz de riesgo configurada), incluyendo:
* **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).** Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron.
* **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`.
## Ejemplo de solicitud
```bash cURL theme={null}
curl -X POST http://api.gu1.ai/entities \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "company",
"externalId": "company_789",
"name": "Tech Solutions S.A.",
"countryCode": "BR",
"taxId": "12.345.678/0001-90",
"entityData": {
"company": {
"legalName": "Tech Solutions Sociedade Anônima",
"tradeName": "Tech Solutions",
"incorporationDate": "2020-06-15",
"industry": "Software Development",
"employeeCount": 50,
"revenue": 5000000,
"revenueCurrency": "BRL",
"contactInfo": {
"email": "contact@techsolutions.com.br",
"phone": "+55 11 3456-7890"
},
"address": "Av. Paulista, 1000",
"city": "São Paulo",
"state": "SP",
"country": "Brazil",
"postalCode": "01310-100"
}
},
"attributes": {
"website": "https://techsolutions.com.br",
"partnershipTier": "gold"
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('http://api.gu1.ai/entities', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
type: 'company',
externalId: 'company_789',
name: 'Tech Solutions S.A.',
countryCode: 'BR',
taxId: '12.345.678/0001-90',
entityData: {
company: {
legalName: 'Tech Solutions Sociedade Anônima',
tradeName: 'Tech Solutions',
incorporationDate: '2020-06-15',
industry: 'Software Development',
employeeCount: 50,
revenue: 5000000,
revenueCurrency: 'BRL',
contactInfo: {
email: 'contact@techsolutions.com.br',
phone: '+55 11 3456-7890'
},
address: 'Av. Paulista, 1000',
city: 'São Paulo',
state: 'SP',
country: 'Brazil',
postalCode: '01310-100'
}
},
attributes: {
website: 'https://techsolutions.com.br',
partnershipTier: 'gold'
}
})
});
const data = await response.json();
console.log(data.entity);
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'type': 'company',
'externalId': 'company_789',
'name': 'Tech Solutions S.A.',
'countryCode': 'BR',
'taxId': '12.345.678/0001-90',
'entityData': {
'company': {
'legalName': 'Tech Solutions Sociedade Anônima',
'tradeName': 'Tech Solutions',
'incorporationDate': '2020-06-15',
'industry': 'Software Development',
'employeeCount': 50,
'revenue': 5000000,
'revenueCurrency': 'BRL',
'contactInfo': {
'email': 'contact@techsolutions.com.br',
'phone': '+55 11 3456-7890'
},
'address': 'Av. Paulista, 1000',
'city': 'São Paulo',
'state': 'SP',
'country': 'Brazil',
'postalCode': '01310-100'
}
},
'attributes': {
'website': 'https://techsolutions.com.br',
'partnershipTier': 'gold'
}
}
)
entity = response.json()['entity']
print(entity)
```
## Ejemplo de respuesta
```json theme={null}
{
"success": true,
"entity": {
"id": "660e9511-f39c-52e5-b827-557766551111",
"externalId": "company_789",
"organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
"type": "company",
"name": "Tech Solutions S.A.",
"taxId": "12.345.678/0001-90",
"countryCode": "BR",
"riskScore": 35,
"status": "active",
"entityData": {
"company": {
"legalName": "Tech Solutions Sociedade Anônima",
"tradeName": "Tech Solutions",
"incorporationDate": "2020-06-15",
"industry": "Software Development",
"employeeCount": 50,
"revenue": 5000000,
"revenueCurrency": "BRL"
}
},
"attributes": {
"website": "https://techsolutions.com.br",
"partnershipTier": "gold"
},
"createdAt": "2024-10-03T15:00:00.000Z",
"updatedAt": "2024-10-03T15:00:00.000Z"
}
}
```
## Respuestas de error
### 400 Bad Request - Tax ID inválido
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid CNPJ format. Please check the format and try again.",
"details": {
"field": "taxId",
"taxIdName": "CNPJ",
"providedValue": "12.345.678/0001-90"
}
},
"entity": null
}
```
### 400 Bad Request - Campos requeridos faltantes
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Missing required fields for company creation",
"details": {
"missingFields": ["legalName", "industry"],
"requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
"countryCode": "BR"
}
},
"entity": null
}
```
### 409 Conflict - Entidad duplicada
```json theme={null}
{
"success": false,
"error": {
"code": "DUPLICATE_ENTITY",
"message": "Entity with this external_id already exists",
"details": {
"field": "external_id",
"value": "company_789",
"constraint": "entities_organization_external_id_unique"
}
},
"entity": null
}
```
### 401 Unauthorized
```json theme={null}
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
```
## Próximos pasos
Después de crear una empresa, puedes:
1. [Obtener detalles de empresa](/es/api-reference/company/get) - Recuperar información completa de la empresa
2. [Listar empresas](/es/api-reference/company/list) - Consultar tus empresas
3. [Actualizar empresa](/es/api-reference/company/update) - Modificar datos de la empresa
4. [Crear validación KYB](/es/use-cases/kyb/overview) - Iniciar proceso de verificación KYB