> ## 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.

# Importar eventos de usuário (CSV)

> Envie um CSV e enfileire uma importação batch de eventos de usuário usando um mapeamento de colunas salvo — pela API batch import da Gu1 para alto volume.

## Endpoint

```
POST https://api.gu1.ai/batch-import/import/user-events
```

## Overview

**Content-Type:** `multipart/form-data`.

**Permissões:** `events:create`.

## Autenticação

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Campos do formulário

| Campo                | Obrigatório | Descrição                                                                                  |
| -------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `file`               | Sim         | Arquivo CSV                                                                                |
| `mappingId`          | Sim         | Mapeamento com `target === user_event`                                                     |
| `executeRules`       | Não         | `true` (padrão) ou `false`                                                                 |
| `withAutoEntity`     | Não         | `true` (padrão) ou `false`                                                                 |
| `batchErrorHandling` | Não         | Política de erros por linha — ver abaixo. Padrão **`continue_collect_errors`** se omitido. |

### Política de erros (`batchErrorHandling`)

| Valor                                  | Comportamento                                                                                                                                                   |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`continue_collect_errors`** (padrão) | Linhas válidas são enfileiradas e importadas. Linhas com falha de mapeamento (ex.: `eventType` não mapeado) ficam como falhas preflight no CSV de erros do job. |
| **`rollback_all`**                     | Se **qualquer** linha falhar validação de mapeamento, **`400`** e nenhum job é criado.                                                                          |
| **`stop_keep_success`**                | Como continue no preflight; durante o processamento, o worker para no primeiro erro runtime. Eventos criados antes são mantidos.                                |

Alias legado: `stopOnFirstError=true` equivale a **`stop_keep_success`**.

## Limites

|                              | Valor                                                                                                      |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Arquivos por request**     | **1** CSV                                                                                                  |
| **Máx. linhas por import**   | Conforme plano — [Overview bulk imports — Limites](/pt/api-reference/bulk-imports/overview#limits-by-plan) |
| **Teto servidor (opcional)** | `USER_EVENT_BATCH_IMPORT_MAX_ROWS` pode reduzir o limite do plano                                          |
| **Acima do limite**          | **`400`** `TOO_MANY_ITEMS`                                                                                 |

## Resposta de sucesso

**`202 Accepted`**

```json theme={null}
{
  "success": true,
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "totalItems": 1200,
  "preflightFailures": 3,
  "message": "User event import queued"
}
```

* **`totalItems`** — linhas válidas enfileiradas + falhas preflight.
* **`preflightFailures`** — linhas que falharam mapeamento antes do worker (baixe CSV de falhas no [histórico unificado](/pt/api-reference/bulk-imports/list-unified-history)).

## Erros pre-job

| HTTP    | `error.code`       | Quando                                                                            |
| ------- | ------------------ | --------------------------------------------------------------------------------- |
| **400** | `VALIDATION_ERROR` | `rollback_all` e há linhas com erro de mapeamento (`details`: erros estruturados) |
| **400** | `NO_VALID_ROWS`    | Todas as linhas falharam mapeamento com política continue                         |

Ver [Códigos de falha batch import](/pt/api-reference/bulk-imports/batch-import-failure-codes).

Ver também: [Overview bulk imports](/pt/api-reference/bulk-imports/overview).