# Migração de Alunos

> Importe alunos e compras em massa por planilha XLSX ou CSV, com análise antes de processar.

Se você está trazendo alunos de outra plataforma, ou vendeu fora dos gateways integrados, pode cadastrá-los e liberar os acessos de uma vez por planilha. A importação fica em **Alunos › Importações** (`/dashboard/students/imports`) e funciona em duas etapas: primeiro você envia o arquivo e confere a análise, depois processa.

## Passo 1 - Tenha uma entrega pronta

A importação libera acesso por meio de uma **entrega**. Cada linha da planilha indica qual entrega o aluno recebe, e a entrega define os produtos, o tempo de acesso e as tags/turmas.

Se ainda não criou a entrega, veja [Entregas](/entregas/entregas-e-integracoes). Depois anote um destes dois valores, que vão na coluna `produto_id`:

- um dos **IDs de produto** cadastrados na entrega (o ID do produto no gateway); ou
- o **número da entrega**, que aparece como `#` na lista de **Vendas › Entregas**.

:::aviso
A entrega precisa ter pelo menos um produto marcado e não pode estar arquivada. Caso contrário, as linhas dela aparecem com erro na análise.
:::

## Passo 2 - Identifique o tipo de migração

### Lista de vendas

Exporte do seu gateway apenas as vendas **aprovadas** ou **completas**. Coloque o código da venda na coluna `codigo`: ele aparece depois em **Vendas** e facilita o suporte.

### Tempo de acesso retroativo

Use quando o produto tem prazo e parte dele já passou. Exemplo: um curso de 1 ano vendido há 3 meses deve terminar daqui a 9 meses, não daqui a 1 ano.

Preencha a coluna `comecou_em` com a data da compra original no formato **DD/MM/AAAA HH:MM:SS** (horário de Brasília). Datas no formato de data do próprio Excel também são aceitas. O prazo da entrega passa a contar a partir dessa data.

### Lista de assinantes

Exporte do gateway só os assinantes **ativos** e importe com o status `aprovado`.

:::embreve
As colunas `recorrencia_id` e `recorrencia_status` já são lidas da planilha, mas ainda não são usadas: o aluno importado não fica vinculado à assinatura do gateway. Renovações e cancelamentos futuros precisam chegar pelo postback com o mesmo e-mail ou CPF do aluno.
:::

## Passo 3 - Monte a planilha

A primeira linha da planilha deve ter os nomes das colunas, exatamente como na tabela abaixo (maiúsculas ou minúsculas tanto faz). Colunas com outros nomes são ignoradas, e a ordem não importa.

| Coluna | Obrigatória | O que colocar |
|---|---|---|
| `status` | Sim | `aprovado` libera o acesso. `cancelado` ou `disputa` encerram o acesso do aluno aos produtos da entrega |
| `produto_id` | Sim | ID de produto cadastrado na entrega, ou o número da entrega |
| `cliente_email` | Sim | E-mail do aluno |
| `cliente_nome` | Não | Nome do aluno. Em branco, a plataforma usa o início do e-mail |
| `codigo` | Não | ID da venda no gateway. Em branco, a plataforma gera um código da importação |
| `produto_nome` | Não | Nome do produto, só para referência |
| `cliente_celular` | Não | DDD + celular |
| `cliente_doc` | Não | CPF ou CNPJ |
| `comecou_em` | Não | Data de início do acesso, em DD/MM/AAAA HH:MM:SS |
| `tags` | Não | Tags extras para o aluno, separadas por barra vertical (veja o exemplo abaixo). Tags que não existem são criadas |
| `recorrencia_id` | Não | ID da assinatura no gateway (ainda sem efeito) |
| `recorrencia_status` | Não | `ativo` ou `cancelado` (ainda sem efeito) |

Exemplo de valor para a coluna `tags`, aplicando duas tags ao aluno: `Turma A|VIP`. As tags só são aplicadas nas linhas com status `aprovado`.

Regras do arquivo:

- formato **XLSX** ou **CSV** (separado por vírgula ou ponto e vírgula, em UTF-8 ou no padrão do Excel);
- no XLSX, só a **primeira aba** é lida;
- até **20MB** e **5.000 registros** por arquivo. Para listas maiores, divida em várias planilhas;
- evite células mescladas, fórmulas e hiperlinks nos dados.

:::info
Colunas de endereço (`cliente_endereco`, `cliente_endereco_cep` etc.) podem estar na planilha, mas são ignoradas.
:::

## Passo 4 - Envie e confira a análise

1. Em **Alunos › Importações**, clique em **Nova importação**.
2. Selecione o arquivo e clique em **Enviar arquivo**.
3. A tela da importação abre com a análise. **Nada foi criado ainda.**

A análise mostra quantos registros há, quantos estão prontos para processar, quantos alunos são novos e quantas linhas têm erro. A tabela lista linha a linha o e-mail, o nome, o status, o `produto_id`, a entrega encontrada, a data de início e o resultado:

- **Novo aluno**: o e-mail não existe na plataforma e será criado;
- **Atualiza aluno**: o e-mail já existe; o aluno recebe os acessos e tem os dados completados;
- uma etiqueta vermelha com o erro da linha.

Use a busca para procurar em qualquer coluna.

## Passo 5 - Processe

Quando a análise estiver como você quer:

1. Marque **Enviar e-mail de boas-vindas aos alunos novos** se quiser que os alunos criados recebam o link para definir a senha.
2. Clique em **Processar N registro(s)**.

Só as linhas sem erro são processadas. Para cada uma, a plataforma cria (ou atualiza) o aluno, registra a compra em **Vendas** com origem "Importação" e libera os produtos da entrega, com a duração e as tags/turmas configuradas nela. Ao final, a tela mostra quantos alunos foram criados e atualizados, quantos acessos foram liberados e a lista de linhas com erro.

:::aviso
Uma importação processada não pode ser desfeita nem processada de novo. Se algo saiu errado, corrija os alunos pela aba **Compras** do perfil ou envie uma nova planilha só com as linhas que faltaram.
:::

### Como os alunos existentes são tratados

- O aluno é identificado **somente pelo e-mail**.
- Se a planilha trouxer nome, ele substitui o nome atual. Celular e documento só são preenchidos quando o aluno ainda não tem esses dados.
- Um aluno que estava na lixeira volta para a lista de alunos.

:::aviso
Não use na planilha o e-mail de um administrador da plataforma. A importação não bloqueia esse caso, e o administrador passaria a receber acessos como se fosse aluno.
:::

:::embreve
A identificação por CPF (para não duplicar alunos que trocaram de e-mail) ainda não vale na importação, só nas vendas recebidas dos gateways. A importação também ainda não dispara o webhook de usuário criado.
:::

## Solucionando erros

| Mensagem | O que fazer |
|---|---|
| **As colunas obrigatórias são status, produto_id e cliente_email.** | Confira os nomes na primeira linha da planilha. Exclua a importação e envie de novo |
| **Arquivo inválido ou sem registros.** | O arquivo está vazio, protegido ou num formato que não é XLSX/CSV. Exclua e envie de novo |
| **E-mail inválido** | Corrija o e-mail na linha indicada |
| **Status inválido** | Use `aprovado`, `cancelado` ou `disputa` |
| **Entrega não encontrada** | O `produto_id` não está em nenhuma entrega ativa. Confira o Passo 1 |
| **Entrega sem acessos** | A entrega não tem produtos marcados. Edite a entrega e salve |
| **Data comecou_em inválida** | Use o formato DD/MM/AAAA HH:MM:SS |
| **Limite de alunos atingido** | O plano da plataforma chegou ao limite de alunos. Veja **Configurações › Limites do plano** |

Importações ainda não processadas podem ser excluídas pelo ícone de lixeira na lista. Em qualquer importação você pode baixar o arquivo original pelo botão **Baixar original**.