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: type y, en automático, tax_id. En manual tax_id puede ir vacío. suggested_name es 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

Brasil + depth > 0 falla toda la fila si los enrichments de descubrimiento no están en el conjunto resuelto de la entidad principal. La fila no se crea sin relacionados.
  • Persona: br_bdc_related_companies_enrichment y br_bdc_related_persons_enrichment deben estar habilitados y no excluidos (omit_enrichments / excludeEnrichments). execute_all_active_enrichments=true no saltea esto si alguno está deshabilitado en el marketplace.
  • Empresa: br_bdc_shareholders_enrichment debe estar habilitado y no excluido.
childEnrichmentPolicy y las columnas relationship_* solo controlan enrichments en los hijos después de existir. No cumplen el chequeo de descubrimiento. Si no se pueden ejecutar esos códigos, enviá depth: 0.
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

Errores por fila

El CSV de fallos (solo filas failed) trae code y error_message. Si el alta automática se corta en los datos básicos, code queda en CREATION_FAILED y se agregan provider_code, provider_error_code y provider_error_message. En Argentina, provider_error_code = INVALID_DOCUMENT_FORMAT significa que el documento no es un CUIT/CUIL de 11 dígitos. Un comercio con prefijo de persona (20, 23, 24, 27) es válido. ARCA_BOTH_BRANCHES_FAILED es un rechazo de ARCA: el motivo está en provider_error_message. BASIC_DATA_ENRICHMENT_REQUIRED significa que no hay un enrichment de datos básicos habilitado para ese país y tipo. Ver también: Importaciones masivas.