> ## 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.
# Importar entidades (CSV)
> Sube un CSV y encola import bulk de entidades — formato plataforma sin mappingId o columnas custom con mappingId. Default manual; automático explícito.
## Endpoint
```
POST https://api.gu1.ai/batch-import/import/entities
```
## Descripción
**Content-Type:** `multipart/form-data`.
Encola el mismo job bulk que el hub **Importaciones masivas**. Requiere **`entities:bulk_import`** y la flag org de **importación masiva automática**. Respuesta **`202`** con **`jobId`** e **`importMode`** efectivo.
## Autenticación
```bash theme={null}
Authorization: Bearer TU_API_KEY
```
## Modos de importación (`entityImportMode`)
| Modo | Cuándo | Comportamiento |
| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`manual`** | **Default** si omitís el campo | Entidad **mínima** con `taxId` + **`suggested_name`** (obligatorio). **Sin** pipeline de datos básicos (Nosis/CPF). **Enrichments opcionales** vía `autoExecuteIntegrations` en el form y/o columnas CSV por fila. **Sin** `depth` / accionistas. **País:** cualquier ISO2 válido de plataforma (prioridad `country_code` por fila). |
| **`automatic`** | Enviás `entityImportMode=automatic` | Datos básicos por tax ID (**AR**, **BR** o **CL**) + enrichments (default todos activos si omitís `autoExecuteIntegrations`) + `depth` / accionistas opcional. |
Los valores legacy `manual_no_enrichment` y `automatic_enriched` siguen aceptándose en el request y se normalizan a **`manual`** / **`automatic`**. La respuesta usa los nombres canónicos.
### Default si mandás solo el CSV
```bash theme={null}
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer TU_API_KEY' \
-F 'file=@bulk-entities-template.csv'
```
→ **`importMode`: `manual`** — entidad mínima, **sin enrichments** salvo que los agregues explícitamente.
### Manual con enrichments elegidos
Misma semántica que el modo **Manual** del hub:
```bash theme={null}
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer TU_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=manual' \
-F 'autoExecuteIntegrations={"executeAllActiveEnrichments":false,"enrichments":["nosis_enrichment"]}' \
-F 'riskMatrixCompanyId=UUID_DE_TU_MATRIZ'
```
Opcional: **`monitoring`** JSON (solo entidad principal en manual).
### Modo automático (explícito)
```bash theme={null}
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer TU_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=automatic'
```
Sin **`autoExecuteIntegrations`** en automático → todos los enrichments activos de la org.
Con **`depth` > 0** podés enviar **`autoExecuteIntegrationsShareholders`** (JSON) para accionistas.
### Manual sin reglas post-creación
```bash theme={null}
-F 'entityImportMode=manual' \
-F 'skipRulesExecution=true'
```
(Omití `entityImportMode` — ya es manual por default.)
## CSV formato plataforma (sin `mappingId`)
Cabeceras mínimas: **`tax_id`**, **`type`**. Recomendado: **`suggested_name`** (obligatorio en manual). Ver [País (ISO2)](#país-iso2--siempre-obligatorio) para **`country_code`**.
### País (ISO2) — siempre obligatorio
Cada fila necesita un país para crear la entidad (**manual y automático**). Podés indicarlo en **uno o ambos** lugares:
| Fuente | Cuándo usarla |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Campo del form** `country` | Paso 2 del hub o campo multipart en la API. **Obligatorio** en CSV simple (solo `tax_id` + `type`). **Obligatorio** en filas sin `country_code`. |
| **Columna CSV** `country_code` (alias `country`) | Por fila. **Pisa** el `country` del lote cuando está presente. |
**Prioridad:** `country_code` en la fila → `country` del lote.
**Si ninguno está definido en una fila**, el import falla con `missing country` antes de encolar el job.
| Modo | Países permitidos |
| ---------------------------- | ----------------------------------------------- |
| **Automático** (`automatic`) | **AR**, **BR**, **CL** (pipeline datos básicos) |
| **Manual** (`manual`) | Cualquier ISO2 válido de plataforma |
**Ejemplos:**
* CSV simple, todo AR → cabeceras `tax_id,type` + form `country=AR`.
* CSV avanzado, países mixtos → `country_code` en cada fila (`country` del lote opcional como respaldo).
* CSV avanzado, un solo país → todas las filas con `country_code=AR` **o** form `country=AR` sin la columna.
Plantillas de referencia — **descarga** (tax IDs de demo fijos; reemplazá antes de importar en producción) o generá IDs nuevos desde el hub del panel (**Entidades** → importación masiva):
* [**bulk-entities-template-automatic.csv**](/files/bulk-imports/bulk-entities-template-automatic.csv) — con **`entityImportMode=automatic`**. Filas demo AR/BR/CL, `depth`, enrichments.
* [**bulk-entities-template-manual.csv**](/files/bulk-imports/bulk-entities-template-manual.csv) — con **`entityImportMode=manual`** (default). Filas demo AR/MX/BR, **`suggested_name` obligatorio**, sin `depth`.
Fuente canónica (mantener alineada si cambian columnas): `apps/web/src/lib/bulk-automatic-entity-import-parse.ts`.
```csv theme={null}
tax_id,type,country_code,suggested_name,...,execute_all_active_enrichments,...,depth,status,segment_tag
20123456789,company,AR,Acme Argentina SA,...,true,...,0,under_review,retail
```
```csv theme={null}
tax_id,type,country_code,suggested_name,...,status,segment_tag
20123456789,company,AR,Empresa Manual AR SA,...,under_review,retail
XAXX010101000,company,MX,Empresa México Demo SA,...,active,latam
```
### Referencia de columnas (CSV plataforma)
Cabeceras **sin distinguir mayúsculas**; espacios → `_`. Alias entre paréntesis.
| Columna CSV | Alias | Campo API / entidad | Notas |
| ------------------------------------ | --------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`tax_id`** | `taxId` | `taxId` | **Obligatorio.** Se normaliza por país. |
| **`type`** | `tipo` | `type` | **Obligatorio.** `person` / `company` (`persona`, `empresa`, `pf`, `pj`). |
| **`country_code`** | `country` | `country` | ISO2 **por fila**. **Pisa** el `country` del form del lote. La columna es **opcional en el CSV** si enviás `country` en el lote (CSV simple) o si cada fila trae `country_code`. **El país siempre es obligatorio** — columna y/o campo del lote. |
| **`suggested_name`** | `name`, `nombre` | `suggestedName` | Nombre para mostrar. **Obligatorio en manual** en cada fila. |
| **`gender`** | — | `gender` | Dato de creación (`customData`). Enum: `M`, `F`, `male`, `female`, `other`, `unknown`. Usar **`other`** para no binario. Ver [Crear entidad — Persona](/es/api-reference/entities/create#entidad-persona). |
| **`external_id`** | `externalId` | `externalId` | ID externo de la entidad. |
| **`email`** | — | `email` | Email de contacto. |
| **`phone`** | — | `phone` | Teléfono de contacto. |
| **`registration_date`** | — | `registrationDate` | Fecha de registro (ISO). |
| **`risk_matrix_id`** | — | `riskMatrixId` | UUID de matriz **por fila**; vacío / `null` limpia. Pisa matrices del lote si viene informado. |
| **`execute_all_active_enrichments`** | — | `autoExecuteIntegrations.executeAllActiveEnrichments` | `true` / `false`. Aplica enrichments por fila si esta columna, **`enrichments`** o **`enrichment_group_refs`** están presentes. |
| **`enrichments`** | — | `autoExecuteIntegrations.enrichments` | Códigos de proveedor separados por `,` o `;`. |
| **`enrichment_group_refs`** | — | `autoExecuteIntegrations.enrichmentGroupRefs` | Slugs de grupos de enrichment. |
| **`omit_enrichments`** | `exclude_enrichments` | `autoExecuteIntegrations.excludeEnrichments` | Códigos a **omitir** del conjunto final. Funciona con **`execute_all_active_enrichments=true`** (todos los activos menos estos). Si es la única columna de enrichment en la fila, **se suma** a la config del lote (no la reemplaza). |
| **`create_relationships`** | — | `createRelationships` | Solo **modo automático** (ignorado en manual). |
| **`depth`** | — | `depth` | Entero **0–5**. Accionistas/relaciones. Solo **automático** (se elimina en manual). |
| **`related_tax_id`** | — | `relationships[].relatedTaxId` | Contraparte existente por tax ID. **Exactamente uno** de `related_tax_id` / `related_external_id` / `related_entity_id` por fila. |
| **`related_external_id`** | — | `relationships[].relatedExternalId` | Contraparte por `externalId`. |
| **`related_entity_id`** | — | `relationships[].relatedEntityId` | Contraparte por UUID. |
| **`relationship_type`** | — | `relationships[].relationshipType` | Default `shareholder` si hay contraparte. Enum del grafo. |
| **`relationship_role`** | — | `relationships[].role` | Rol en `metadata.roles` (ej. `SOCIO`). |
| **`relationship_as_source`** | — | `relationships[].asSource` | Default `true`: la fila creada es **source** y la contraparte (`related_*`) es **target**. Con `relationship_type=shareholder`, la fila es accionista/socio de esa contraparte. `false` invierte la dirección. |
| **`status`** | — | `status` | `active`, `under_review`, `blocked`, etc. |
| **`attributes.`** | — | **`attributes`** | Dato de negocio anidado (misma idea que transacciones con puntos). Ej.: `attributes.segment_tag`, `attributes.tags.tier`. |
| **`entityData.`** | — | **`entityData.{person\|company}`** | Perfil KYC/KYB. Sin `person`/`company` en la cabecera → usa el **`type`** de la fila (`person` → `entityData.person.*`, `company` → `entityData.company.*`). Ej.: `entityData.income`, `entityData.tradeName`. |
| **`entityData.person.`** | — | **`entityData.person`** | Explícito para persona (ignora mismatch con `type=company` en la misma fila). |
| **`entityData.company.`** | — | **`entityData.company`** | Explícito para empresa. |
| **`metadata.`** | — | **`attributes`** (legacy) | Deprecado; se fusiona en `attributes`. Preferí `attributes.*`. |
| **Columna sin prefijo** | — | **`attributes`** | Retrocompat: `segment_tag` → `attributes.segment_tag`. |
**Misma entidad, varios vínculos (CSV):** el CSV plataforma admite **una** relación por fila. Si la misma persona/empresa aparece en varias filas con distinto `related_*`, Gu1 **no recrea** la entidad (skip por `tax_id` duplicado) pero **sí aplica** el vínculo de esa fila. Si el edge (source → target + tipo) ya existe, se omite ese vínculo (idempotente). Alternativa en API/JSON: un solo create con hasta 10 ítems en `relationships[]`.
**Eliminado (2026-06-04):** las columnas CSV **`execute_all_active_checks`** y **`checks`** ya no forman parte del contrato de importación. Usá **`enrichments`**, **`enrichment_group_refs`** y **`execute_all_active_enrichments`**. Ver [Changelog](/es/changelog).
**Dot notation:** igual que el CSV nativo de transacciones — cabeceras con `.` generan objetos anidados. Enriquecimientos pueden sobrescribir `entityData`; los valores del CSV se re-aplican al final (el CSV gana en conflictos).
**Qué va a `attributes`:** columnas `attributes.*`, `metadata.*` (legacy) o sin prefijo. El form **`attributes`** (JSON) del lote se fusiona con los de fila (gana la fila en conflicto de clave).
**CSV simple** (solo `tax_id` + `type`): enviá **`country`** (ISO2) en el form del lote — obligatorio. No hace falta columna `country_code`.
**CSV custom:** requiere **`mappingId`** (mapeo guardado en el dashboard).
* Columnas de enrichment por fila aplican en **ambos** modos; **`depth`** / accionistas **solo** en **`automatic`**.
### Enrichments en relacionados por fila (CSV plataforma)
Opcional — solo modo **`automatic`**. Prefijo **`relationship_`** (alias plural **`relationships_`**).
| Columna | Descripción |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `relationship_execute_all_active_enrichments` | `true` = todos los activos en accionistas/relacionadas; `false` = solo datos básicos. **Reemplaza** la política del lote (`childEnrichmentPolicy`) para esa fila. |
| `relationship_enrichments_company` | Códigos de proveedor para hijos tipo empresa (separados por `,` o `;`) |
| `relationship_enrichments_person` | Códigos para hijos tipo persona |
| `relationship_enrichment_group_refs` | Grupos de marketplace (opcional) |
| `relationship_omit_enrichments` | Alias de `relationship_exclude_enrichments`. Códigos a omitir del conjunto final (también con `execute_all_active=true`). Si es la **única** columna `relationship_*` en la fila, **se fusiona** con la política del lote en lugar de reemplazarla. |
| `relationship_exclude_enrichments` | Igual que `relationship_omit_enrichments` (nombre legacy). |
**Paytime / lotes con `childEnrichmentPolicy` custom:** omití `relationship_execute_all_active_enrichments` del CSV si querés que aplique la política del formulario paso 2. Usá `relationship_omit_enrichments` por fila solo para excepciones puntuales.
Ejemplo omit en accionistas (all active del lote, menos sanciones globales en hijos):
```csv theme={null}
tax_id,type,country_code,depth,relationship_omit_enrichments
67250861000107,company,BR,1,global_gueno_sanctions_enrichment
```
## CSV custom
Columnas distintas al formato plataforma → **`mappingId`** obligatorio.
## Campos del formulario
| Campo | Obligatorio | Descripción |
| ------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file` | Sí | CSV |
| `mappingId` | Condicional | Custom; opcional con formato plataforma |
| `entityImportMode` | No | **`manual`** (default) o **`automatic`** |
| `country` | **Condicional (obligatorio en la práctica)** | ISO2 del lote. **Obligatorio** si el CSV no trae `country_code` en una fila (CSV simple típico). Respaldo opcional si todas las filas incluyen `country_code`. |
| `riskMatrixPersonId` | No | UUID — ambos modos |
| `riskMatrixCompanyId` | No | UUID — ambos modos |
| `skipRulesExecution` | No | `true` / `false` |
| `stopOnFirstError` | No | `true` / `false` |
| `autoExecuteIntegrations` | No | JSON — manual: enrichments opcionales; automático: default todos activos |
| `autoExecuteIntegrationsShareholders` | No | JSON a nivel lote — **solo automático** + `depth` > 0. Por fila: columnas `relationship_*` en CSV o campo en bulk JSON. |
| `childEnrichmentPolicy` | No | **`all_active`** (default), **`by_root_type`** o **`basic_only`** — ver [Enrichments en hijos y monitoreo](#enrichments-en-hijos-y-monitoreo). |
| `monitoringApplyToRelationships` | No | `true` / `false` — si `false`, `monitoring` solo en entidades principales. Default **`true`** con `depth` > 0 si se omite. |
| `depth` | No | 0–5 — **solo automático** |
| `monitoring` | No | JSON — ambos modos |
| `reportRecipientEmails` | No | JSON array |
| `emailLocale` | No | `en` / `es` / `pt` |
## Enrichments en hijos y monitoreo
Con **`entityImportMode=automatic`** y **`depth` > 0** se crean accionistas (raíz empresa) o entidades relacionadas (raíz persona). Dos campos del lote controlan enrichments y watchlist en esos hijos:
| `childEnrichmentPolicy` | Entidad principal | Empresa → accionistas | Persona → relacionadas |
| -------------------------- | ----------------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
| **`all_active`** (default) | Según config | Todos los enrichments activos del tipo del hijo | Igual |
| **`by_root_type`** | Según config | Todos los activos **excepto** `global_gueno_sanctions_enrichment` | **Solo datos básicos** del snapshot del proveedor de la raíz |
| **`basic_only`** | Según config | Solo datos básicos | Solo datos básicos |
**`monitoringApplyToRelationships`:** con **`false`**, el JSON `monitoring` aplica solo a la **entidad principal** (`monitoring.main`). Recomendado **`false`** con **`by_root_type`** cuando la raíz entra a monitoreo de sanciones pero los hijos no.
Ejemplo (CSV mixto, depth 1):
```bash theme={null}
-F 'entityImportMode=automatic' \
-F 'depth=1' \
-F 'childEnrichmentPolicy=by_root_type' \
-F 'monitoringApplyToRelationships=false' \
-F 'monitoring={"main":{"global_gueno_sanctions_enrichment":{"watchlist":true}}}'
```
Un **`autoExecuteIntegrationsShareholders`** por fila en bulk JSON **o columnas `relationship_*` en CSV** sigue pisando la política del lote para ese ítem.
## Manual vs automático
| | **Manual** | **Automático** |
| ----------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------- |
| Datos básicos Nosis/CPF | **No** | **Sí** |
| `suggested_name` | **Obligatorio** | Recomendado |
| **País (ISO2)** | **Obligatorio** — `country` del lote y/o `country_code` por fila (gana la fila) | Igual (automático: solo **AR**, **BR**, **CL**) |
| Enrichments | Opcionales | Default todos activos |
| Matrices de riesgo | Sí | Sí |
| `depth` accionistas | **No** | Sí (0–5) |
| Países | **Cualquier ISO2** válido | **AR**, **BR**, **CL** |
## Límites
| | Valor |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Archivos por request** | **1** CSV (campo `file`) |
| **Máx. filas por import** | Según plan de la org ([overview — Límites por plan](/es/api-reference/bulk-imports/overview#límites-por-plan)): Freemium **4.000** → Enterprise **100.000** |
| **Tope servidor (opcional)** | `BULK_AUTOMATIC_ENTITY_MAX_ITEMS` puede bajar el límite del plan en este endpoint |
| **Supera límite** | **`400`** `TOO_MANY_ITEMS` |
## Default si omitís modo
| Endpoint | Default |
| ---------------------------------------- | ------------ |
| **`POST /batch-import/import/entities`** | **`manual`** |
## Hub vs API
| Flujo | Endpoint | Default |
| ---------------------- | -------------------------------------------------------- | ---------------------------------------------- |
| Pantalla **Entidades** | **Este endpoint** (`POST /batch-import/import/entities`) | UI (automático → `entityImportMode=automatic`) |
| **API multipart** | `POST /batch-import/import/entities` | **Manual** |
| **Custom** | `POST /batch-import/import/entities` + **`mappingId`** | Selector UI |
Ver también: [Importaciones masivas](/es/api-reference/bulk-imports/overview).