# Importação de alunos

> Como importar alunos por planilha XLSX: as colunas que a Cademí lê, a análise antes do processamento, duplicados, linhas com erro e assinaturas.

A importação traz muitos alunos de uma vez, por uma planilha. Ela serve para quem vem de outra plataforma ou para uma turma inteira de uma empresa. Cada linha cria o aluno, se ele não existe, e dá a ele uma entrega. Você envia o arquivo em **Alunos > Importações**, confere a análise e só depois processa.

**A regra mais importante:** a entrega precisa existir antes. Cada linha aponta para uma entrega pelo código de produto dela. Sem entrega para o código, a linha fica com erro.

## Como funciona

- Cada linha da planilha é **um aluno e uma entrega**.
- Se o aluno deve receber várias entregas, ele aparece em várias linhas.
- A entrega é encontrada pelo código de produto configurado nela, o mesmo que uma venda do gateway traria. Veja [Entregas](https://help.cademi.cloud/pt/vendas/entregas.md).

O acesso é uma matrícula manual, igual à de **Adicionar entrega** no perfil. Ela aparece em **Compras** como **Entrega avulsa**, e a conta controla essa matrícula. A duração é a da entrega, contada do início da matrícula.

A importação não traz progresso de aulas, tentativas de prova nem certificados da plataforma antiga.

### As colunas

A primeira linha da planilha é o cabeçalho, com estes nomes. A Cademí descarta linhas vazias. Uma célula com só "0" conta como vazia.

| Coluna | Obrigatória | O que a Cademí lê |
|---|---|---|
| `status` | Sim | Se a linha dá ou desliga o acesso. Veja abaixo |
| `produto_id` | Sim | O código de produto configurado na entrega. Sem entrega para o código, a linha fica com erro |
| `cliente_email` | Sim | O e-mail do aluno. Por ele a Cademí decide se cria um cadastro ou usa o que existe |
| `cliente_nome`, `cliente_celular`, `cliente_doc` | Não | Nome, celular e documento. Nome e celular só entram quando a linha cria o aluno. O documento entra sempre que a linha dá acesso |
| `cliente_endereco`, `cliente_endereco_n`, `cliente_endereco_comp`, `cliente_endereco_bairro`, `cliente_endereco_cidade`, `cliente_endereco_estado`, `cliente_endereco_cep` | Não | Endereço. Só entra num aluno que a linha cria |
| `comecou_em` | Não | Quando o acesso começou, no formato `AAAA-MM-DD HH:MM:SS`. Em branco, o acesso começa quando a linha é processada |
| `tags` | Não | Nomes de tags separados por ponto e vírgula. Se um nome não existe, a Cademí cria a tag na análise |
| `codigo` | Não | O código do pedido na plataforma antiga, para você reconhecer a linha depois |
| `cliente_senha` | Não | Uma senha inicial. Só vale se a linha cria o aluno |
| `recorrencia_id`, `recorrencia_status` | Não | O código e o status da assinatura, quando a linha é uma assinatura. Veja abaixo |

**O `status`** aceita o que as pessoas costumam escrever, em português ou inglês:

- "Aprovado", "pago", "completo" e "concluído" dão o acesso.
- "Cancelado" desliga o acesso que o aluno já tinha àquela entrega.
- "Reembolso", "estorno", "chargeback" e "disputa" também desligam.
- Qualquer outra palavra deixa a linha com erro.

**A `recorrencia_status`** decide no lugar do `status` quando a linha tem `recorrencia_id`. "Ativo" e "trial" dão o acesso. "Cancelado" e "em atraso" desligam.

Não há coluna de duração nem de "dias restantes": o tempo é o da entrega. A planilha não preenche os campos personalizados da conta.

### Data de início e assinaturas numa migração

- **Deixe `comecou_em` em branco** quando todos devem começar hoje. Por exemplo: uma turma nova, ou uma migração em que você dá um período novo.
- **Use a data da compra original** quando o tempo da entrega deve continuar desde a plataforma antiga. Numa entrega de um ano, quem comprou há dez meses fica com cerca de dois meses. Quem já tinha vencido lá continua vencido aqui.
- **As regras "N dias após a compra"** também contam dessa data. O aluno chega com aberto o que ele já tinha alcançado.
- **Assinaturas** precisam do `recorrencia_id`. É por ele que a Cademí reconhece a mesma assinatura quando o gateway, depois de conectado, avisa a renovação ou o cancelamento.
- **Uma compra depois da importação**, da mesma entrega e pelo mesmo e-mail, fica com a matrícula importada. Daí em diante, o gateway controla essa matrícula.

**Atenção: é aqui que mais acontece erro.** O Rafa pagou até 30 de junho na plataforma antiga. Você importa a linha dele com "cancelado", achando que quer dizer "pago até". Resultado: o acesso do Rafa fecha na hora. Para encerrar no dia certo, importe com "aprovado" e programe o encerramento depois, na aba **Compras**. Veja [Matrículas e acessos](https://help.cademi.cloud/pt/alunos/matriculas-e-acessos.md).

## Passo a passo

1. Abra **Alunos > Importações**.
2. Clique em **Nova importação**.
3. Escolha o arquivo: um XLSX de até 20 MB e 5.000 registros, com as colunas `status`, `produto_id` e `cliente_email`.
4. Clique em **Enviar arquivo**.
5. Confira a tela **Análise da Importação**. A análise roda sozinha e põe cada linha em **Prontos**, **Com erro** ou **Ignorados**. O **Total** mostra tudo.
6. Se há linhas **Com erro**, corrija a causa (veja abaixo).
7. Sem linhas com erro, clique em **Processar**.

As linhas prontas vão para a fila e a importação fica **Processado**. Use a busca da análise para achar uma linha pelo nome, pelo e-mail ou pelo código.

Como corrigir uma linha com erro:

- **A entrega não existia:** crie a entrega e clique em **Reprocessar análise**. A Cademí lê a mesma planilha de novo.
- **O erro está na planilha**, como um e-mail ou uma data errada: envie o arquivo corrigido como uma importação nova.

**A primeira importação da conta** precisa da liberação do time da Cademí. A análise roda, mas, ao processar, a tela pede que você chame o suporte. As importações seguintes processam direto.

O caminho de uma importação, do envio ao processamento:

```mermaid
flowchart TD
    accTitle: As etapas de uma importação
    accDescr: Você envia o arquivo e a análise roda sozinha. Se alguma linha ficou com erro, corrija a causa e reprocesse a análise, ou envie um arquivo corrigido. Sem erros, a primeira importação da conta espera a liberação do suporte. Depois você processa: as linhas prontas vão para a fila e os alunos e as matrículas são aplicados em segundo plano. Linhas ignoradas não bloqueiam.
    enviar["Enviar arquivo"]
    analise["Análise da Importação"]
    erro{"Alguma linha Com erro?"}
    corrigir["Corrija e Reprocessar análise"]
    primeira{"Primeira importação da conta?"}
    suporte["O suporte libera"]
    processar["Processar"]
    fila["Alunos e matrículas em segundo plano"]
    enviar --> analise
    analise --> erro
    erro -->|Sim| corrigir
    corrigir --> analise
    erro -->|Não| primeira
    primeira -->|Sim| suporte
    primeira -->|Não| processar
    suporte --> processar
    processar --> fila
    classDef destaque stroke:#ff005c,stroke-width:2px
    class processar destaque
```

Linhas **Ignorados** não contam como erro: elas não travam e não dão nada.

Processar quer dizer que a Cademí aceitou as linhas. Não quer dizer que todo aluno já entra: cadastros, matrículas e e-mails acontecem em segundo plano. Os botões **Baixar arquivo original** e **Baixar JSON da análise** ficam na tela, para você guardar o que enviou e o resultado.

## Duplicados e linhas ignoradas

A análise decide pelo e-mail e pela entrega. Uma linha ignorada não é um defeito: ela não trava o processamento e não dá nada.

| Situação | O que acontece |
|---|---|
| E-mail novo | Cria o aluno e a matrícula |
| E-mail existe e ele não tem essa entrega ativa | O mesmo aluno recebe a entrega. Nome, senha e perfil ficam como estão |
| E-mail existe e ele já tem essa entrega ativa | Linha ignorada: **Já possui acesso ativo** |
| Mesmo e-mail e mesma entrega duas vezes no arquivo | A primeira linha vale. A repetição é ignorada: **Repetida nesta planilha** |
| Outra importação já pôs esse e-mail na fila para essa entrega | Linha ignorada: **Já está na fila para processamento** |
| Mesmo e-mail, entregas diferentes | Cada linha vale sozinha |
| O aluno está na lixeira, ou a matrícula não está mais ativa | Não conta como "já tem acesso". A linha dá o acesso de novo |

A importação nunca muda o nome, o celular ou a senha de um aluno que já existe. Para corrigir esses dados, edite o aluno no perfil.

## Linhas com erro

| Falha | O que fazer |
|---|---|
| A linha ficou **Com erro** na análise: status desconhecido, data ilegível ou `produto_id` sem entrega | Uma linha com erro trava a importação inteira. Crie a entrega e use **Reprocessar análise**, ou envie um arquivo corrigido como importação nova |
| O arquivo inteiro foi recusado: ilegível, sem linhas, sem uma coluna obrigatória ou com mais de 5.000 registros | Corrija o arquivo e envie de novo. Para mais linhas, divida em arquivos ou fale com o suporte |
| A linha foi processada e falhou depois. Por exemplo: a conta chegou ao limite de alunos | Libere vagas e envie essas pessoas numa importação nova. Quem já existia recebe a entrega mesmo com a cota cheia. Só os alunos novos falham |
| A tela diz que as importações estão bloqueadas | O suporte da Cademí desligou as importações da conta. Peça para tirar o bloqueio |

## O e-mail de boas-vindas

- **Alunos novos** recebem o e-mail de importação da conta, com o login e a senha. Isso acontece quando esse modelo está ligado em **Configurações > E-mails**.
- **Quem já existia** e só ganhou uma entrega não recebe esse e-mail nem senha nova.
- **Com o modelo desligado**, a Cademí cria o aluno com uma senha, mas ele não sabe qual é. Para entrar, ele usa "esqueci minha senha".

Antes de uma importação grande, envie um teste para você.

## Bom saber

- **Cota de alunos.** Cada aluno novo ocupa uma vaga do plano. Confira as vagas antes de uma migração.
- **Excluir uma importação.** Só dá antes de processar, e não desfaz o que já foi para a fila. A importação excluída vai para a **Lixeira** da tela e pode ser restaurada.
- **Importação processada.** Ela não pode ser excluída. Para desfazer o acesso, exclua ou inative as matrículas no perfil de cada aluno.
- **Tags criadas na análise.** Elas ficam mesmo se a importação é excluída ou a linha é ignorada.
- **Uma planilha por entrega.** Fica mais fácil achar e corrigir erros, e você evita cadastro duplicado.
- **Sem modelo de planilha.** A tela não tem modelo para baixar. Monte o arquivo com os nomes de coluna da tabela acima, sem mudar o cabeçalho.

## Perguntas frequentes

**"Não existe nenhuma entrega configurada para o ID".** O valor em `produto_id` não bate com o código de produto de nenhuma entrega da conta. Confira o código na entrega, ou crie a entrega. Depois clique em **Reprocessar análise**.

**Importei e os alunos não receberam o e-mail.** Veja se a importação está **Processado** e se o modelo de e-mail de importação está ligado. Quem já existia não recebe. A primeira importação da conta espera a liberação do suporte.

**Quero manter o tempo que restava a cada aluno.** Use a data da compra original em `comecou_em` e uma entrega com a mesma duração da oferta antiga. A data de hoje daria o período inteiro de novo.

**Importei com "cancelado" e o aluno perdeu o acesso.** "Cancelado" desliga o acesso na hora; não quer dizer "pago até". Na aba **Compras** do aluno, clique no status da linha para ativar. Depois programe o encerramento no dia certo.