Importação CSV
Importação em lote de pessoas, alunos e atividades, com simulação antes de gravar.
Importa pessoas (equipe e alunos) por CSV
POST /instituicoes/{instituicaoId}/importacoes/pessoas
O CSV vai como texto no campo csv (máx. 500 linhas e 90 000 caracteres). Use modo: simular para ver o relatório antes de aplicar. A importação é idempotente: quem já existe volta como JA_EXISTE.
Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Limite: até 20 chamadas a cada 60 s por origem. Status de sucesso: 200.
Parâmetros de caminho
| Parâmetro | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
instituicaoId | string (uuid) | sim | Id da instituição. |
Corpo da requisição (ImportacaoEntrada)
| Campo | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
csv | string | sim | 1–90000 caracteres | |
modo | "simular" | "aplicar" | sim | simular só valida e mostra o que aconteceria; aplicar grava tudo ou nada (a menos que parcial). | |
parcial | boolean | não | Modo parcial (com travas): importa só as linhas válidas e devolve as ignoradas na resposta. simular com parcial devolve hashConteudo; aplicar com parcial exige o mesmo hashConteudo (ausente ou diferente = 409 CONFLICT). Ausente ou false = tudo ou nada. | |
hashConteudo | string | não | ^[0-9a-f]{64}$ | Hash devolvido pela simulação parcial do mesmo conteúdo (SHA-256 do conteúdo normalizado, 64 caracteres hexadecimais). |
Resposta
| Campo | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | sim | ||
modo | "simular" | "aplicar" | sim | ||
aplicado | boolean | sim | No aplicar: true = gravou; false = alguma linha com erro, nada foi gravado. No simular, sempre false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" ou nulo | sim | Erro do arquivo como um todo (vazio, grande demais, coluna obrigatória ausente). | |
colunaAusente | string ou nulo | sim | ||
resumo | object | sim | ||
linhas | lista de LinhaRelatorio | sim | ||
convites | integer ou nulo | sim | 0… | Convites que vão sair (contas novas). null = não informado (o simular não revela se o e-mail já tem conta). |
parcial | boolean | não | Só no modo parcial. true = o pedido foi parcial. | |
hashConteudo | string | não | Só no simular parcial: SHA-256 do conteúdo normalizado (tipo, destino e linhas lidas), que o aplicar parcial devolve. | |
contagens | object | não | Só no modo parcial: importadas = linhas válidas (CRIADA, INCLUIDA, REATIVADA ou JA_EXISTE, detalhadas em resumo); ignoradas = linhas com ERRO. Importadas + ignoradas = linhas lidas. No simular, é a previsão. | |
contagens.importadas | integer | sim | 0… | |
contagens.ignoradas | integer | sim | 0… | Só no aplicar parcial: as linhas que ficaram de fora (linha, campo e motivo). Existe apenas nesta resposta: não é gravado. |
ignoradas | lista de LinhaRelatorio | não | Só no aplicar parcial: as linhas que ficaram de fora (linha, campo e motivo). Existe apenas nesta resposta: não é gravado. |
Em caso de erro: modelo ErroApi.
Exemplo
bash
curl -X POST "$API/instituicoes/{instituicaoId}/importacoes/pessoas" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'Importa alunos da turma por CSV
POST /turmas/{turmaId}/importacoes/alunos
O CSV vai como texto no campo csv (máx. 500 linhas e 90 000 caracteres). Use modo: simular antes de aplicar. Repetir a importação não duplica matrículas.
Acesso: Exige a capacidade CADASTRAR sobre turma (params.turmaId). Limite: até 20 chamadas a cada 60 s por origem. Status de sucesso: 200.
Parâmetros de caminho
| Parâmetro | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
turmaId | string (uuid) | sim | Id da turma. |
Corpo da requisição (ImportacaoEntrada)
| Campo | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
csv | string | sim | 1–90000 caracteres | |
modo | "simular" | "aplicar" | sim | simular só valida e mostra o que aconteceria; aplicar grava tudo ou nada (a menos que parcial). | |
parcial | boolean | não | Modo parcial (com travas): importa só as linhas válidas e devolve as ignoradas na resposta. simular com parcial devolve hashConteudo; aplicar com parcial exige o mesmo hashConteudo (ausente ou diferente = 409 CONFLICT). Ausente ou false = tudo ou nada. | |
hashConteudo | string | não | ^[0-9a-f]{64}$ | Hash devolvido pela simulação parcial do mesmo conteúdo (SHA-256 do conteúdo normalizado, 64 caracteres hexadecimais). |
Resposta
| Campo | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | sim | ||
modo | "simular" | "aplicar" | sim | ||
aplicado | boolean | sim | No aplicar: true = gravou; false = alguma linha com erro, nada foi gravado. No simular, sempre false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" ou nulo | sim | Erro do arquivo como um todo (vazio, grande demais, coluna obrigatória ausente). | |
colunaAusente | string ou nulo | sim | ||
resumo | object | sim | ||
linhas | lista de LinhaRelatorio | sim | ||
convites | integer ou nulo | sim | 0… | Convites que vão sair (contas novas). null = não informado (o simular não revela se o e-mail já tem conta). |
parcial | boolean | não | Só no modo parcial. true = o pedido foi parcial. | |
hashConteudo | string | não | Só no simular parcial: SHA-256 do conteúdo normalizado (tipo, destino e linhas lidas), que o aplicar parcial devolve. | |
contagens | object | não | Só no modo parcial: importadas = linhas válidas (CRIADA, INCLUIDA, REATIVADA ou JA_EXISTE, detalhadas em resumo); ignoradas = linhas com ERRO. Importadas + ignoradas = linhas lidas. No simular, é a previsão. | |
contagens.importadas | integer | sim | 0… | |
contagens.ignoradas | integer | sim | 0… | Só no aplicar parcial: as linhas que ficaram de fora (linha, campo e motivo). Existe apenas nesta resposta: não é gravado. |
ignoradas | lista de LinhaRelatorio | não | Só no aplicar parcial: as linhas que ficaram de fora (linha, campo e motivo). Existe apenas nesta resposta: não é gravado. |
Em caso de erro: modelo ErroApi.
Exemplo
bash
curl -X POST "$API/turmas/{turmaId}/importacoes/alunos" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'Importa atividades da turma por CSV
POST /turmas/{turmaId}/importacoes/atividades
Uma atividade é reconhecida pela data, hora de início e descrição; a importação só cria, nunca altera nem apaga. Use modo: simular antes de aplicar.
Acesso: Exige a capacidade CADASTRAR sobre turma (params.turmaId). Limite: até 20 chamadas a cada 60 s por origem. Status de sucesso: 200.
Parâmetros de caminho
| Parâmetro | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
turmaId | string (uuid) | sim | Id da turma. |
Corpo da requisição (ImportacaoEntrada)
| Campo | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
csv | string | sim | 1–90000 caracteres | |
modo | "simular" | "aplicar" | sim | simular só valida e mostra o que aconteceria; aplicar grava tudo ou nada (a menos que parcial). | |
parcial | boolean | não | Modo parcial (com travas): importa só as linhas válidas e devolve as ignoradas na resposta. simular com parcial devolve hashConteudo; aplicar com parcial exige o mesmo hashConteudo (ausente ou diferente = 409 CONFLICT). Ausente ou false = tudo ou nada. | |
hashConteudo | string | não | ^[0-9a-f]{64}$ | Hash devolvido pela simulação parcial do mesmo conteúdo (SHA-256 do conteúdo normalizado, 64 caracteres hexadecimais). |
Resposta
| Campo | Tipo | Obrigatório | Restrições | Descrição |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | sim | ||
modo | "simular" | "aplicar" | sim | ||
aplicado | boolean | sim | No aplicar: true = gravou; false = alguma linha com erro, nada foi gravado. No simular, sempre false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" ou nulo | sim | Erro do arquivo como um todo (vazio, grande demais, coluna obrigatória ausente). | |
colunaAusente | string ou nulo | sim | ||
resumo | object | sim | ||
linhas | lista de LinhaRelatorio | sim | ||
convites | integer ou nulo | sim | 0… | Convites que vão sair (contas novas). null = não informado (o simular não revela se o e-mail já tem conta). |
parcial | boolean | não | Só no modo parcial. true = o pedido foi parcial. | |
hashConteudo | string | não | Só no simular parcial: SHA-256 do conteúdo normalizado (tipo, destino e linhas lidas), que o aplicar parcial devolve. | |
contagens | object | não | Só no modo parcial: importadas = linhas válidas (CRIADA, INCLUIDA, REATIVADA ou JA_EXISTE, detalhadas em resumo); ignoradas = linhas com ERRO. Importadas + ignoradas = linhas lidas. No simular, é a previsão. | |
contagens.importadas | integer | sim | 0… | |
contagens.ignoradas | integer | sim | 0… | Só no aplicar parcial: as linhas que ficaram de fora (linha, campo e motivo). Existe apenas nesta resposta: não é gravado. |
ignoradas | lista de LinhaRelatorio | não | Só no aplicar parcial: as linhas que ficaram de fora (linha, campo e motivo). Existe apenas nesta resposta: não é gravado. |
Em caso de erro: modelo ErroApi.
Exemplo
bash
curl -X POST "$API/turmas/{turmaId}/importacoes/atividades" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'