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.
Não há um único parâmetro type: custom | platform. O comportamento depende da rota e se você envia mapeamento:
| Cenário | Como funciona |
|---|
| Transações — formato nativo | POST /transactions/batch/upload sem mappingId nem columnMapping: o servidor faz parse de CSV / Excel / JSON com o parser nativo. Ver Criar transações em lote. |
| Transações — mapeamento salvo | O mesmo endpoint de upload com mappingId, ou columnMapping como string JSON (apenas CSV). Também disponível como POST /batch-import/import/transactions. |
| Entidades — aba Entidades do hub | POST /batch-import/import/entities (CSV multipart; mesmo wizard do hub). |
| Entidades — CSV multipart (API) | POST /batch-import/import/entities (padrão manual). |
| Entidades — colunas CSV arbitrárias | POST /batch-import/import/entities com file + mappingId. |
| Eventos de usuário | POST /batch-import/import/user-events com file + mappingId (target user_event). |
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.
| Tipo | Endpoint(s) | Arquivos por request | Máx. linhas por arquivo / request |
|---|
| Transações | POST /transactions/batch/upload, POST /batch-import/import/transactions | Até 5 | Conforme plano (teto 100.000 linhas/arquivo) |
| Entidades (CSV / hub) | POST /batch-import/import/entities | 1 | Conforme plano; teto opcional via BULK_AUTOMATIC_ENTITY_MAX_ITEMS |
| Eventos de usuário | POST /batch-import/import/user-events | 1 | Conforme plano; teto opcional via USER_EVENT_BATCH_IMPORT_MAX_ROWS |
Limites por plano
Vale para linhas de transação por arquivo, linhas de entidade por import CSV e linhas de evento por import:
| Plano | Máx. linhas por arquivo / import |
|---|
| Freemium | 4.000 |
| Startup | 12.000 |
| Growth | 30.000 |
| Enterprise | 100.000 |
| Usage based | 100.000 |
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).
| Manual (manual) | Automático (automatic) |
|---|
| Dados básicos por tax ID | Não | Sim |
| Nome | suggested_name / suggestedName obrigatório | Recomendado |
| País (ISO2) | Obrigatório — country do lote e/ou country_code por linha (linha prevalece) | Igual (automático: só AR, BR, CL) |
| Enrichments | Opcionais | Padrão todos ativos |
depth acionistas | Não | Sim (0–5) |
| Países | Qualquer ISO2 válido | AR, BR, CL |
| Default API | POST /batch-import/import/entities | POST /batch-import/import/entities com entityImportMode=automatic |
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.
| Recurso | CSV | JSON |
|---|
| Transações | 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 (inclui skips[] para taxId duplicado) |
completed / failed → buscar endpoint de falhas 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.
