Importar entidades (CSV)

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

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

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:

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)

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

  -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) 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 — con entityImportMode=automatic. Filas demo AR/BR/CL, depth, enrichments.
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.

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

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.
`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).
`status`	—	`status`	`active`, `under_review`, `blocked`, etc.
`attributes.<path>`	—	`attributes`	Dato de negocio anidado (misma idea que transacciones con puntos). Ej.: `attributes.segment_tag`, `attributes.tags.tier`.
`entityData.<path>`	—	`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.<path>`	—	`entityData.person`	Explícito para persona (ignora mismatch con `type=company` en la misma fila).
`entityData.company.<path>`	—	`entityData.company`	Explícito para empresa.
`metadata.<path>`	—	`attributes` (legacy)	Deprecado; se fusiona en `attributes`. Preferí `attributes.*`.
Columna sin prefijo	—	`attributes`	Retrocompat: `segment_tag` → `attributes.segment_tag`.

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.

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):

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.
`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):

-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): 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.

​Endpoint

​Descripción

​Autenticación

​Modos de importación (entityImportMode)

​Default si mandás solo el CSV

​Manual con enrichments elegidos

​Modo automático (explícito)

​Manual sin reglas post-creación

​CSV formato plataforma (sin mappingId)

​País (ISO2) — siempre obligatorio

​Referencia de columnas (CSV plataforma)

​Enrichments en relacionados por fila (CSV plataforma)

​CSV custom

​Campos del formulario

​Enrichments en hijos y monitoreo

​Manual vs automático

​Límites

​Default si omitís modo

​Hub vs API

Endpoint

Descripción

Autenticación

Modos de importación (`entityImportMode`)

Default si mandás solo el CSV

Manual con enrichments elegidos

Modo automático (explícito)

Manual sin reglas post-creación

CSV formato plataforma (sin `mappingId`)

País (ISO2) — siempre obligatorio

Referencia de columnas (CSV plataforma)

Enrichments en relacionados por fila (CSV plataforma)

CSV custom

Campos del formulario

Enrichments en hijos y monitoreo

Manual vs automático

Límites

Default si omitís modo

Hub vs API