Skip to main content
POST
Importar entidades (CSV)

Endpoint

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

Modos de importación (entityImportMode)

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.

Si un enrichment falla (por fila)

Cada fila del CSV se procesa por separado. Default: la fila queda en failed y el job sigue con la siguiente. Con stopOnFirstError=true se corta en el primer fallo (las filas ya creadas se mantienen). En automatic, los enrichments extra (BCRA en Argentina, etc.) corren solo si datos básicos salieron bien. Un error de BCRA no aborta un alta cuyo paso de datos básicos ya fue exitoso.

Default si mandás solo el 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:
Opcional: monitoring JSON (solo entidad principal en manual).

Modo automático (explícito)

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

(Omití entityImportMode — ya es manual por default.)

Acción de matriz al finalizar

El campo multipart opcional postImportActions acepta un array JSON. La acción run_risk_matrix_filtered encola una ejecución masiva de matriz cuando el job termina en completed:
Con relatedEntitiesOfCreatedEntitiesOnly=true, Gu1 evalúa únicamente entidades vinculadas directamente —como origen o destino— con filas cuyo resultado en este archivo fue created. filters.type define si las relacionadas deben ser company o person, y se requiere la matriz correspondiente a ese tipo. No incluye filas skipped_existing ni failed. Sin el flag, filters se aplica al listado completo de entidades de la organización. Como alternativa, enviá sourceImportJobId con el ID de una importación de entidades anterior y completada. Gu1 ejecutará la matriz únicamente sobre las filas created de ese lote que coincidan con filters.type, incluso si no están relacionadas con las filas del archivo actual. sourceImportJobId y relatedEntitiesOfCreatedEntitiesOnly=true son mutuamente excluyentes. La importación anterior debe pertenecer a la misma organización y tener disponible su reporte completo. También podés enviar onlyWithoutRiskMatrixExecution=true para evaluar todas las entidades de filters.type que todavía no tengan ninguna auditoría de ejecución de matriz. Cuando una entidad se procesa correctamente, las cargas posteriores ya no vuelven a incluirla. Los tres alcances (sourceImportJobId, relacionados y sin ejecución previa) son mutuamente excluyentes.

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: 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. 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): Fuente canónica (mantener alineada si cambian columnas): apps/web/src/lib/bulk-automatic-entity-import-parse.ts.

Referencia de columnas (CSV plataforma)

Cabeceras sin distinguir mayúsculas; espacios → _. Alias entre paréntesis.
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.
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_). 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 custom

Columnas distintas al formato plataforma → mappingId obligatorio.

Campos del formulario

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

Límites

Default si omitís modo

Hub vs API

Ver también: Importaciones masivas.