# Importación de alumnos

> Cómo importar alumnos con una planilla XLSX: las columnas que lee la Cademí, el análisis antes de procesar, duplicados, filas con error y suscripciones.

La importación trae muchos alumnos de una vez, con una planilla. Sirve para quien viene de otra plataforma o para un grupo completo de una empresa. Cada fila crea el alumno, si no existe, y le da una entrega. Envías el archivo en **Alumnos > Importaciones**, revisas el análisis y solo después procesas.

**La regla más importante:** la entrega tiene que existir antes. Cada fila apunta a una entrega por su código de producto. Sin entrega para el código, la fila queda con error.

## Cómo funciona

- Cada fila de la planilla es **un alumno y una entrega**.
- Si el alumno debe recibir varias entregas, aparece en varias filas.
- La entrega se encuentra por el código de producto configurado en ella, el mismo que traería una venta del gateway. Mira [Entregas](/es/vendas/entregas).

El acceso es una matrícula manual, igual a la de **Añadir entrega** en el perfil. Aparece en **Compras** como **Entrega suelta**, y la cuenta controla esa matrícula. La duración es la de la entrega, contada desde el inicio de la matrícula.

La importación no trae el progreso de las clases, los intentos de examen ni los certificados de la plataforma anterior.

### Las columnas

La primera fila de la planilla es el encabezado, con estos nombres. La Cademí descarta las filas vacías. Una celda con solo "0" cuenta como vacía.

| Columna | Obligatoria | Lo que lee la Cademí |
|---|---|---|
| `status` | Sí | Si la fila da o desactiva el acceso. Mira abajo |
| `produto_id` | Sí | El código de producto configurado en la entrega. Sin entrega para el código, la fila queda con error |
| `cliente_email` | Sí | El correo electrónico del alumno. Con él la Cademí decide si crea un registro o usa el que existe |
| `cliente_nome`, `cliente_celular`, `cliente_doc` | No | Nombre, celular y documento. El nombre y el celular solo entran cuando la fila crea el alumno. El documento entra siempre que la fila da acceso |
| `cliente_endereco`, `cliente_endereco_n`, `cliente_endereco_comp`, `cliente_endereco_bairro`, `cliente_endereco_cidade`, `cliente_endereco_estado`, `cliente_endereco_cep` | No | Dirección. Solo entra en un alumno que la fila crea |
| `comecou_em` | No | Cuándo empezó el acceso, en el formato `AAAA-MM-DD HH:MM:SS`. En blanco, el acceso empieza cuando se procesa la fila |
| `tags` | No | Nombres de etiquetas separados por punto y coma. Si un nombre no existe, la Cademí crea la etiqueta en el análisis |
| `codigo` | No | El código del pedido en la plataforma anterior, para que reconozcas la fila después |
| `cliente_senha` | No | Una contraseña inicial. Solo vale si la fila crea el alumno |
| `recorrencia_id`, `recorrencia_status` | No | El código y el estado de la suscripción, cuando la fila es una suscripción. Mira abajo |

**El `status`** acepta lo que la gente suele escribir, en portugués o en inglés:

- "Aprovado", "pago", "completo" y "concluído" dan el acceso.
- "Cancelado" desactiva el acceso que el alumno ya tenía a esa entrega.
- "Reembolso", "estorno", "chargeback" y "disputa" también lo desactivan.
- Cualquier otra palabra deja la fila con error.

**La `recorrencia_status`** decide en lugar del `status` cuando la fila tiene `recorrencia_id`. "Ativo" y "trial" dan el acceso. "Cancelado" y "em atraso" lo desactivan.

No hay columna de duración ni de "días restantes": el tiempo es el de la entrega. La planilla no completa los campos personalizados de la cuenta.

### Fecha de inicio y suscripciones en una migración

- **Deja `comecou_em` en blanco** cuando todos deben empezar hoy. Por ejemplo: un grupo nuevo, o una migración en la que das un período nuevo.
- **Usa la fecha de la compra original** cuando el tiempo de la entrega debe continuar desde la plataforma anterior. En una entrega de un año, quien compró hace diez meses queda con unos dos meses. Quien ya había vencido allá sigue vencido aquí.
- **Las reglas "N días después de la compra"** también cuentan desde esa fecha. El alumno llega con abierto lo que ya había alcanzado.
- **Las suscripciones** necesitan el `recorrencia_id`. Es con él que la Cademí reconoce la misma suscripción cuando el gateway, una vez conectado, avisa la renovación o la cancelación.
- **Una compra después de la importación**, de la misma entrega y con el mismo correo electrónico, se queda con la matrícula importada. Desde ese momento, el gateway controla esa matrícula.

**Atención: aquí es donde ocurren más errores.** Rafa pagó hasta el 30 de junio en la plataforma anterior. Importas su fila con "cancelado", pensando que quiere decir "pagado hasta". Resultado: el acceso de Rafa se cierra al momento. Para cerrarlo en el día correcto, importa con "aprovado" y programa la finalización después, en la pestaña **Compras**. Mira [Matrículas y accesos](/es/alunos/matriculas-e-acessos).

## Paso a paso

1. Abre **Alumnos > Importaciones**.
2. Haz clic en **Nueva importación**.
3. Elige el archivo: un XLSX de hasta 20 MB y 5.000 registros, con las columnas `status`, `produto_id` y `cliente_email`.
4. Haz clic en **Enviar archivo**.
5. Revisa la pantalla **Análisis de la importación**. El análisis se ejecuta solo y pone cada fila en **Listos**, **Con error** o **Ignorados**. El **Total** muestra todo.
6. Si hay filas **Con error**, corrige la causa (mira abajo).
7. Sin filas con error, haz clic en **Procesar**.

Las filas listas van a la cola y la importación queda **Procesado**. Usa la búsqueda del análisis para encontrar una fila por el nombre, por el correo electrónico o por el código.

Cómo corregir una fila con error:

- **La entrega no existía:** crea la entrega y haz clic en **Reprocesar análisis**. La Cademí lee la misma planilla de nuevo.
- **El error está en la planilla**, como un correo electrónico o una fecha mal escritos: envía el archivo corregido como una importación nueva.

**La primera importación de la cuenta** necesita la aprobación del equipo de la Cademí. El análisis se ejecuta, pero, al procesar, la pantalla te pide que contactes al soporte. Las importaciones siguientes se procesan directamente.

El camino de una importación, desde el envío hasta el procesamiento:

```mermaid
flowchart TD
    accTitle: Las etapas de una importación
    accDescr: Envías el archivo y el análisis se ejecuta solo. Si alguna fila quedó con error, corrige la causa y reprocesa el análisis, o envía un archivo corregido. Sin errores, la primera importación de la cuenta espera la aprobación del soporte. Después procesas: las filas listas van a la cola y los alumnos y las matrículas se aplican en segundo plano. Las filas ignoradas no bloquean.
    enviar["Enviar archivo"]
    analise["Análisis de la importación"]
    erro{"¿Alguna fila Con error?"}
    corrigir["Corrige y Reprocesar análisis"]
    primeira{"¿Primera importación de la cuenta?"}
    suporte["El soporte la aprueba"]
    processar["Procesar"]
    fila["Alumnos y matrículas en segundo plano"]
    enviar --> analise
    analise --> erro
    erro -->|Sí| corrigir
    corrigir --> analise
    erro -->|No| primeira
    primeira -->|Sí| suporte
    primeira -->|No| processar
    suporte --> processar
    processar --> fila
    classDef destaque stroke:#ff005c,stroke-width:2px
    class processar destaque
```

Las filas **Ignorados** no cuentan como error: no traban y no dan nada.

Procesar quiere decir que la Cademí aceptó las filas. No quiere decir que todo alumno ya entra: los registros, las matrículas y los correos electrónicos ocurren en segundo plano. Los botones **Descargar archivo original** y **Descargar JSON del análisis** quedan en la pantalla, para que guardes lo que enviaste y el resultado.

## Duplicados y filas ignoradas

El análisis decide por el correo electrónico y por la entrega. Una fila ignorada no es un defecto: no traba el procesamiento y no da nada.

| Situación | Lo que ocurre |
|---|---|
| Correo electrónico nuevo | Crea el alumno y la matrícula |
| El correo electrónico existe y no tiene esa entrega activa | El mismo alumno recibe la entrega. El nombre, la contraseña y el perfil quedan como están |
| El correo electrónico existe y ya tiene esa entrega activa | Fila ignorada: **Ya tiene acceso activo** |
| Mismo correo electrónico y misma entrega dos veces en el archivo | La primera fila vale. La repetición se ignora: **Repetida en esta planilla** |
| Otra importación ya puso ese correo electrónico en la cola para esa entrega | Fila ignorada: **Ya está en la cola de procesamiento** |
| Mismo correo electrónico, entregas diferentes | Cada fila vale por sí sola |
| El alumno está en la papelera, o la matrícula ya no está activa | No cuenta como "ya tiene acceso". La fila da el acceso de nuevo |

La importación nunca cambia el nombre, el celular ni la contraseña de un alumno que ya existe. Para corregir esos datos, edita el alumno en el perfil.

## Filas con error

| Falla | Qué hacer |
|---|---|
| La fila quedó **Con error** en el análisis: estado desconocido, fecha ilegible o `produto_id` sin entrega | Una fila con error traba toda la importación. Crea la entrega y usa **Reprocesar análisis**, o envía un archivo corregido como importación nueva |
| Se rechazó todo el archivo: ilegible, sin filas, sin una columna obligatoria o con más de 5.000 registros | Corrige el archivo y envíalo de nuevo. Para más filas, divídelo en archivos o habla con el soporte |
| La fila se procesó y falló después. Por ejemplo: la cuenta llegó al límite de alumnos | Libera cupos y envía a esas personas en una importación nueva. Quien ya existía recibe la entrega aunque el cupo esté lleno. Solo fallan los alumnos nuevos |
| La pantalla dice que las importaciones están bloqueadas | El soporte de la Cademí desactivó las importaciones de la cuenta. Pide que quiten el bloqueo |

## El correo de bienvenida

- **Los alumnos nuevos** reciben el correo de importación de la cuenta, con el usuario y la contraseña. Esto ocurre cuando esa plantilla está activada en **Configuraciones > Correos electrónicos**.
- **Quien ya existía** y solo recibió una entrega no recibe ese correo ni una contraseña nueva.
- **Con la plantilla desactivada**, la Cademí crea el alumno con una contraseña, pero él no sabe cuál es. Para entrar, usa "olvidé mi contraseña".

Antes de una importación grande, envía una prueba a ti mismo.

## Para tener en cuenta

- **Cupo de alumnos.** Cada alumno nuevo ocupa un cupo del plan. Revisa los cupos antes de una migración.
- **Eliminar una importación.** Solo se puede antes de procesar, y no deshace lo que ya fue a la cola. La importación eliminada va a la **Papelera** de la pantalla y se puede restaurar.
- **Importación procesada.** No se puede eliminar. Para deshacer el acceso, elimina o inactiva las matrículas en el perfil de cada alumno.
- **Etiquetas creadas en el análisis.** Se quedan aunque la importación se elimine o la fila se ignore.
- **Una planilla por entrega.** Es más fácil encontrar y corregir errores, y evitas registros duplicados.
- **Sin modelo de planilla.** La pantalla no tiene un modelo para descargar. Arma el archivo con los nombres de columna de la tabla de arriba, sin cambiar el encabezado.

## Preguntas frecuentes

**"No existe ninguna entrega configurada para el ID".** El valor en `produto_id` no coincide con el código de producto de ninguna entrega de la cuenta. Revisa el código en la entrega, o crea la entrega. Después haz clic en **Reprocesar análisis**.

**Importé y los alumnos no recibieron el correo.** Mira si la importación está **Procesado** y si la plantilla de correo de importación está activada. Quien ya existía no lo recibe. La primera importación de la cuenta espera la aprobación del soporte.

**Quiero mantener el tiempo que le quedaba a cada alumno.** Usa la fecha de la compra original en `comecou_em` y una entrega con la misma duración de la oferta anterior. La fecha de hoy daría el período completo de nuevo.

**Importé con "cancelado" y el alumno perdió el acceso.** "Cancelado" desactiva el acceso al momento; no quiere decir "pagado hasta". En la pestaña **Compras** del alumno, haz clic en el estado de la línea para activarla. Después programa la finalización en el día correcto.