Skip to main content

​
Visão geral

As importações em lote permitem enviar arquivos CSV mapeados para campos Gu1 usando mapeamentos salvos (mappingId). O hub do dashboard (Importações em lote) usa as mesmas rotas da API. Prefixo base: todas as rotas abaixo ficam sob /batch-import (por exemplo GET https://api.gu1.ai/batch-import/mappings).

​
Autenticação

Use a mesma API key Bearer ou sessão do restante da API. As requisições são por organização; os mappingId pertencem apenas à organização atual.

​
Nome do campo: mappingId (não mapperId)

As importações multipart esperam o campo de formulário mappingId, o UUID retornado ao listar ou criar mapeamentos (GET / POST /batch-import/mappings). Não existe campo mapperId.

​
“Plataforma” vs CSV personalizado

Não há um único parâmetro type: custom | platform. O comportamento depende da rota e se você envia mapeamento:

​
Limites (todas as importações em lote)

Por padrão, um arquivo CSV por request em entidades e eventos de usuário. Transações: até 5 arquivos por multipart.

​
Limites por plano

Vale para linhas de transação por arquivo, linhas de entidade por import CSV e linhas de evento por import: Acima do limite: 400 com TOO_MANY_ITEMS (entidades, eventos) ou erro de limite por plano (transações). Descobrir limites em runtime: GET /individual-organization/batch-upload-enabled retorna plan, maxTransactionsPerFile, maxBulkEntityItemsPerImport, maxUserEventRowsPerFile e mapas por plano. Tamanho do body JSON (batch transações): máx. 50 MB por request; 150 MB multi-arquivo. Ver Criar transações em lote.

​
Import entidades: manual vs automático

Mesmo job em fila; modo via importMode (JSON) ou entityImportMode (CSV multipart). Detalhes: Importar entidades (CSV).

​
Falhas por linha e códigos estáveis

Cada linha com falha inclui code estável e message legível. Baixe CSV ou JSON por tipo de job. Catálogo: Códigos de falha batch. Fluxo típico: upload → polling em Consultar status do job batch até status terminal (completed, failed, cancelled ou interrupted) → buscar falhas (CSV/JSON ou ?include=failures) se failed > 0 ou inspecionar jobFailure quando o job inteiro abortou.
Breaking change CSV (2026-06-04): CSVs de falha agora incluem coluna code. Parsers que assumiam exatamente duas colunas devem ler pelo nome do header.

​
Documentação relacionada

  • Índice de endpoints — tabela de rotas; cada operação tem página própria com badge GET/POST na barra lateral (mesmo padrão do restante da API).
  • Criar transações em lote — multipart e limites para arquivos de transações.