> ## Documentation Index > Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt > Use this file to discover all available pages before exploring further. # Importações em lote > Importações batch por CSV com mapeamentos de colunas salvos para transações, entidades e eventos de usuário na API de importação em lote da gu1. ## 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: | 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](/pt/api-reference/transactions/create-batch). | | **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](/pt/api-reference/bulk-imports/import-entities) (CSV multipart; mesmo wizard do hub). | | **Entidades — CSV multipart (API)** | [POST /batch-import/import/entities](/pt/api-reference/bulk-imports/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](#limites-por-plano) (teto 100.000 linhas/arquivo) | | **Entidades (CSV / hub)** | `POST /batch-import/import/entities` | **1** | Conforme [plano](#limites-por-plano); teto opcional via `BULK_AUTOMATIC_ENTITY_MAX_ITEMS` | | **Eventos de usuário** | `POST /batch-import/import/user-events` | **1** | Conforme [plano](#limites-por-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 | 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](/pt/api-reference/transactions/create-batch). ### 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` | Detalhes: [Importar entidades (CSV)](/pt/api-reference/bulk-imports/import-entities). ### 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](/pt/api-reference/bulk-imports/batch-import-failure-codes). | Recurso | CSV | JSON | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Transações | `GET /batch-import/transaction-jobs/{jobId}/failures.csv` | [GET …/failures](/pt/api-reference/bulk-imports/get-transaction-batch-failures) | | Eventos | `GET /batch-import/user-event-jobs/{jobId}/failures.csv` | [GET …/failures](/pt/api-reference/bulk-imports/get-user-event-batch-failures) | | Entidades | `GET /batch-import/entity-jobs/{jobId}/failures.csv` | [GET …/failures](/pt/api-reference/bulk-imports/get-entity-batch-failures) (inclui `skips[]` para taxId duplicado) | **Fluxo típico:** upload → polling em [Consultar status do job batch](/pt/api-reference/bulk-imports/get-batch-job-status) 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](/pt/api-reference/bulk-imports/api-reference)** — 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](/pt/api-reference/transactions/create-batch) — multipart e limites para arquivos de transações.