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.
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. |
| 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 (CSV multipart; mismo wizard del hub). |
| Entidades — CSV multipart (API) | POST /batch-import/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 (tope duro 100.000 filas/archivo) |
| Entidades (CSV / hub) | POST /batch-import/import/entities | 1 | Según plan; tope opcional BULK_AUTOMATIC_ENTITY_MAX_ITEMS |
| Eventos de usuario | POST /batch-import/import/user-events | 1 | Según 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 |
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.
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 |
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.
| Tipo | CSV | JSON |
|---|
| Transacciones | GET /batch-import/transaction-jobs/{jobId}/failures.csv | GET …/failures |
| Eventos | GET /batch-import/user-event-jobs/{jobId}/failures.csv | GET …/failures |
| Entidades | GET /batch-import/entity-jobs/{jobId}/failures.csv | GET …/failures (incluye skips[]) |
completed / failed → descargar fallos 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 — 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 — multipart y límites para archivos de transacciones.
