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 y filas de eventos por import: Filas de entidades por import CSV usan la misma tabla de plan y después un techo duro de 20.000 (Growth/Enterprise/usage_based quedan en 20.000). El número efectivo en runtime: GET /individual-organization/batch-upload-enabled → maxBulkEntityItemsPerImport. 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.

​

Concurrencia (transacciones y entidades)

Los pools entre organizaciones son separados: lotes de transacciones y de entidades no comparten el cupo de 2 orgs. Dentro de una organización, solo uno de esos tipos puede correr a la vez, y como máximo un job puede esperar (queued). Los jobs de transacciones siguen running hasta que termina la evaluación de reglas encolada (si executeRules es true). Si executeRules es false, el job se completa al terminar los inserts. Las importaciones de eventos de usuario no usan este mutex ni el pool de cupos.

​

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.