> ## 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. # Importaciones masivas > Importaciones batch por CSV con mapeos de columnas guardados (transacciones, entidades, eventos de usuario). Consulta el esquema del request, códigos. ## Descripción general Las importaciones masivas permiten subir archivos **CSV** mapeados a campos Gu1 mediante **mapeos guardados** (`mappingId`). El hub del dashboard (**Importaciones masivas**) usa las mismas rutas que las integraciones por API. **Prefijo base:** todas las rutas indicadas más abajo van bajo `/batch-import` (por ejemplo `GET https://api.gu1.ai/batch-import/mappings`). ### Autenticación Usá la misma **API key Bearer** o sesión que en el resto de la API. Las peticiones están **acotadas a la organización**; los valores `mappingId` pertenecen solo a la organización actual. ### Nombre del campo: `mappingId` (no `mapperId`) Las importaciones multipart esperan el campo de formulario **`mappingId`**, el UUID que devuelve listar o crear mapeos (`GET` / `POST /batch-import/mappings`). No existe el campo `mapperId`. ### “Plataforma” vs CSV personalizado No hay un único parámetro `type: custom | platform`. El comportamiento depende de la ruta y de si enviás mapeo: | Escenario | Cómo funciona | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Transacciones — formato nativo de archivo** | `POST /transactions/batch/upload` **sin** `mappingId` ni `columnMapping`: el servidor parsea CSV / Excel / JSON con el parser integrado. Ver [Crear transacciones batch](/es/api-reference/transactions/create-batch). | | **Transacciones — mapeo guardado** | El mismo endpoint de upload **con** `mappingId`, o `columnMapping` como string JSON (solo CSV). También disponible como `POST /batch-import/import/transactions`. | | **Entidades — pestaña Entidades del hub** | [POST /batch-import/import/entities](/es/api-reference/bulk-imports/import-entities) (CSV multipart; mismo wizard del hub). | | **Entidades — CSV multipart (API)** | [POST /batch-import/import/entities](/es/api-reference/bulk-imports/import-entities) (default **manual**; automático explícito). | | **Entidades — columnas CSV arbitrarias** | `POST /batch-import/import/entities` con **`file` + `mappingId`**. | | **Eventos de usuario** | `POST /batch-import/import/user-events` con **`file` + `mappingId`** (`target` `user_event`). | ### Límites (todas las importaciones masivas) Por defecto, **un archivo CSV por request** en entidades y eventos de usuario. Transacciones: **hasta 5 archivos** por multipart. | Tipo | Endpoint(s) | Archivos por request | Máx. filas por archivo / request | | ------------------------- | --------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------- | | **Transacciones** | `POST /transactions/batch/upload`, `POST /batch-import/import/transactions` | **Hasta 5** | Según [plan](#límites-por-plan) (tope duro 100.000 filas/archivo) | | **Entidades (CSV / hub)** | `POST /batch-import/import/entities` | **1** | Según [plan](#límites-por-plan); tope opcional `BULK_AUTOMATIC_ENTITY_MAX_ITEMS` | | **Eventos de usuario** | `POST /batch-import/import/user-events` | **1** | Según [plan](#límites-por-plan); tope opcional vía `USER_EVENT_BATCH_IMPORT_MAX_ROWS` | #### Límites por plan Aplica a **filas de transacciones por archivo**, **filas de entidades por import CSV** y **filas de eventos por import** (mismos números): | Plan | Máx. filas por archivo / import | | ----------- | ------------------------------- | | Freemium | 4.000 | | Startup | 12.000 | | Growth | 30.000 | | Enterprise | 100.000 | | Usage based | 100.000 | Si se supera el límite: **`400`** con **`TOO_MANY_ITEMS`** (entidades, eventos) o mensaje de límite por plan (transacciones). **Consultar límites en runtime:** `GET /individual-organization/batch-upload-enabled` devuelve `plan`, `maxTransactionsPerFile`, `maxBulkEntityItemsPerImport`, `maxUserEventRowsPerFile` y mapas por plan. **Tamaño body JSON (batch transacciones):** máx. **50 MB** por request; **150 MB** multi-archivo. Ver [Crear transacciones batch](/es/api-reference/transactions/create-batch). ### Import entidades: manual vs automático Mismo job en cola; el modo se define con **`importMode`** (JSON) o **`entityImportMode`** (CSV multipart). | | **Manual** (`manual`) | **Automático** (`automatic`) | | ------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | Datos básicos por tax ID | **No** | **Sí** | | Nombre | **`suggested_name` / `suggestedName` 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 | | `depth` accionistas | **No** | Sí (0–5) | | Países | **Cualquier ISO2** válido | **AR**, **BR**, **CL** | | Default API | **`POST /batch-import/import/entities`** | **`POST /batch-import/import/entities`** con `entityImportMode=automatic` | Detalle: [Importar entidades (CSV)](/es/api-reference/bulk-imports/import-entities). ### Errores y fallos por fila Cada fila fallida incluye un **`code`** estable y un **`message`** legible. Descarga **CSV** o **JSON** por tipo de job. Catálogo completo: [Códigos de fallo batch](/es/api-reference/bulk-imports/batch-import-failure-codes). | Tipo | CSV | JSON | | ------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | | Transacciones | `GET /batch-import/transaction-jobs/{jobId}/failures.csv` | [GET …/failures](/es/api-reference/bulk-imports/get-transaction-batch-failures) | | Eventos | `GET /batch-import/user-event-jobs/{jobId}/failures.csv` | [GET …/failures](/es/api-reference/bulk-imports/get-user-event-batch-failures) | | Entidades | `GET /batch-import/entity-jobs/{jobId}/failures.csv` | [GET …/failures](/es/api-reference/bulk-imports/get-entity-batch-failures) (incluye `skips[]`) | **Flujo típico:** subir archivo → hacer polling a [Consultar estado de job batch](/es/api-reference/bulk-imports/get-batch-job-status) hasta que `status` sea terminal (`completed`, `failed`, `cancelled` o `interrupted`) → descargar fallos (CSV/JSON o `?include=failures`) si `failed > 0` o revisar `jobFailure` si el job entero abortó. **Breaking change CSV (2026-06-04):** los CSV de fallos incluyen columna **`code`**. Parsers con columnas fijas deben leer por nombre de header. ### Documentación relacionada * **[Índice de endpoints](/es/api-reference/bulk-imports/api-reference)** — tabla de rutas; cada operación tiene **página propia** con badge **GET/POST** en la barra lateral (igual que el resto de la referencia API). * [Crear transacciones batch](/es/api-reference/transactions/create-batch) — multipart y límites para archivos de transacciones.