Importaciones masivas

​

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:

​

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.

​

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

​

Import entidades: manual vs automático

Mismo job en cola; el modo se define con importMode (JSON) o entityImportMode (CSV multipart). Detalle: Importar entidades (CSV).

​

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. Flujo típico: subir archivo → hacer polling a Consultar estado de job batch 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ó.

​

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.