> ## 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 usuario (CSV)

> Subí un CSV y encolá una importación batch de eventos de usuario usando un mapeo de columnas guardado — mediante la API batch import de Gu1 para alto volumen.

## Endpoint

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

## Overview

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

**Permisos:** `events:create`.

## Autenticación

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

## Campos del formulario

| Campo                | Requerido | Descripción                                                                                  |
| -------------------- | --------- | -------------------------------------------------------------------------------------------- |
| `file`               | Sí        | Archivo CSV                                                                                  |
| `mappingId`          | Sí        | Mapeo con `target === user_event`                                                            |
| `executeRules`       | No        | `true` (default) o `false`                                                                   |
| `withAutoEntity`     | No        | `true` (default) o `false`                                                                   |
| `batchErrorHandling` | No        | Política de errores por fila — ver abajo. Default **`continue_collect_errors`** si se omite. |

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

| Valor                                   | Comportamiento                                                                                                                                                     |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **`continue_collect_errors`** (default) | Se encolan e importan filas válidas. Las que fallan validación de mapeo (p. ej. `eventType` sin mapear) quedan como fallos preflight en el CSV de errores del job. |
| **`rollback_all`**                      | Si **alguna** fila falla validación de mapeo, **`400`** y no se crea job.                                                                                          |
| **`stop_keep_success`**                 | Como continue en preflight; durante el procesamiento, el worker se detiene en el primer fallo runtime. Los eventos creados antes se conservan.                     |

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

## Límites

|                              | Valor                                                                                                  |
| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Archivos por request**     | **1** CSV                                                                                              |
| **Máx. filas por import**    | Según plan — [Overview bulk imports — Límites](/es/api-reference/bulk-imports/overview#limits-by-plan) |
| **Tope servidor (opcional)** | `USER_EVENT_BATCH_IMPORT_MAX_ROWS` puede reducir el límite del plan                                    |
| **Supera límite**            | **`400`** `TOO_MANY_ITEMS`                                                                             |

## Respuesta exitosa

**`202 Accepted`**

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

* **`totalItems`** — filas válidas encoladas + fallos preflight.
* **`preflightFailures`** — filas que fallaron mapeo antes del worker (descargá CSV de fallos desde [historial unificado](/es/api-reference/bulk-imports/list-unified-history)).

## Errores pre-job

| HTTP    | `error.code`       | Cuándo                                                                           |
| ------- | ------------------ | -------------------------------------------------------------------------------- |
| **400** | `VALIDATION_ERROR` | `rollback_all` y hay filas con error de mapeo (`details`: errores estructurados) |
| **400** | `NO_VALID_ROWS`    | Todas las filas fallaron mapeo con política continue                             |

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

Ver también: [Overview bulk imports](/es/api-reference/bulk-imports/overview).