Importación CSV
Importación en lote de personas, alumnos y actividades, con simulación antes de grabar.
Importa personas (equipo y alumnos) por CSV
POST /instituicoes/{instituicaoId}/importacoes/pessoas
El CSV va como texto en el campo csv (máx. 500 filas y 90 000 caracteres). Use modo: simular para ver el informe antes de aplicar. La importación es idempotente: quien ya existe vuelve como JA_EXISTE.
Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Límite: hasta 20 llamadas cada 60 s por origen. Estado de éxito: 200.
Parámetros de ruta
| Parámetro | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
instituicaoId | string (uuid) | sí | Id de la institución. |
Cuerpo de la solicitud (ImportacaoEntrada)
| Campo | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
csv | string | sí | 1–90000 caracteres | |
modo | "simular" | "aplicar" | sí | simular solo valida y muestra lo que ocurriría; aplicar graba todo o nada (a menos que parcial). | |
parcial | boolean | no | Modo parcial (con trabas): importa solo las filas válidas y devuelve las ignoradas en la respuesta. simular con parcial devuelve hashConteudo; aplicar con parcial exige el mismo hashConteudo (ausente o distinto = 409 CONFLICT). Ausente o false = todo o nada. | |
hashConteudo | string | no | ^[0-9a-f]{64}$ | Hash devuelto por la simulación parcial del mismo contenido (SHA-256 del contenido normalizado, 64 caracteres hexadecimales). |
Respuesta
| Campo | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | sí | ||
modo | "simular" | "aplicar" | sí | ||
aplicado | boolean | sí | En aplicar: true = grabó; false = alguna fila con error, no se grabó nada. En simular, siempre false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" o nulo | sí | Error del archivo en su conjunto (vacío, demasiado grande, falta una columna obligatoria). | |
colunaAusente | string o nulo | sí | ||
resumo | object | sí | ||
linhas | lista de LinhaRelatorio | sí | ||
convites | integer o nulo | sí | 0… | Invitaciones que saldrán (cuentas nuevas). null = no informado (simular no revela si el correo ya tiene cuenta). |
parcial | boolean | no | Solo en el modo parcial. true = el pedido fue parcial. | |
hashConteudo | string | no | Solo en simular parcial: SHA-256 del contenido normalizado (tipo, destino y filas leídas), que aplicar parcial devuelve. | |
contagens | object | no | Solo en el modo parcial: importadas = filas válidas (CRIADA, INCLUIDA, REATIVADA o JA_EXISTE, detalladas en resumo); ignoradas = filas con ERRO. Importadas + ignoradas = filas leídas. En simular, es la previsión. | |
contagens.importadas | integer | sí | 0… | |
contagens.ignoradas | integer | sí | 0… | Solo en aplicar parcial: las filas que quedaron fuera (fila, campo y motivo). Existe solo en esta respuesta: no se graba. |
ignoradas | lista de LinhaRelatorio | no | Solo en aplicar parcial: las filas que quedaron fuera (fila, campo y motivo). Existe solo en esta respuesta: no se graba. |
En caso de error: modelo ErroApi.
Ejemplo
bash
curl -X POST "$API/instituicoes/{instituicaoId}/importacoes/pessoas" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'Importa alumnos del grupo por CSV
POST /turmas/{turmaId}/importacoes/alunos
El CSV va como texto en el campo csv (máx. 500 filas y 90 000 caracteres). Use modo: simular antes de aplicar. Repetir la importación no duplica matrículas.
Acceso: Exige la capacidad CADASTRAR sobre grupo (params.turmaId). Límite: hasta 20 llamadas cada 60 s por origen. Estado de éxito: 200.
Parámetros de ruta
| Parámetro | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
turmaId | string (uuid) | sí | Id del grupo. |
Cuerpo de la solicitud (ImportacaoEntrada)
| Campo | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
csv | string | sí | 1–90000 caracteres | |
modo | "simular" | "aplicar" | sí | simular solo valida y muestra lo que ocurriría; aplicar graba todo o nada (a menos que parcial). | |
parcial | boolean | no | Modo parcial (con trabas): importa solo las filas válidas y devuelve las ignoradas en la respuesta. simular con parcial devuelve hashConteudo; aplicar con parcial exige el mismo hashConteudo (ausente o distinto = 409 CONFLICT). Ausente o false = todo o nada. | |
hashConteudo | string | no | ^[0-9a-f]{64}$ | Hash devuelto por la simulación parcial del mismo contenido (SHA-256 del contenido normalizado, 64 caracteres hexadecimales). |
Respuesta
| Campo | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | sí | ||
modo | "simular" | "aplicar" | sí | ||
aplicado | boolean | sí | En aplicar: true = grabó; false = alguna fila con error, no se grabó nada. En simular, siempre false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" o nulo | sí | Error del archivo en su conjunto (vacío, demasiado grande, falta una columna obligatoria). | |
colunaAusente | string o nulo | sí | ||
resumo | object | sí | ||
linhas | lista de LinhaRelatorio | sí | ||
convites | integer o nulo | sí | 0… | Invitaciones que saldrán (cuentas nuevas). null = no informado (simular no revela si el correo ya tiene cuenta). |
parcial | boolean | no | Solo en el modo parcial. true = el pedido fue parcial. | |
hashConteudo | string | no | Solo en simular parcial: SHA-256 del contenido normalizado (tipo, destino y filas leídas), que aplicar parcial devuelve. | |
contagens | object | no | Solo en el modo parcial: importadas = filas válidas (CRIADA, INCLUIDA, REATIVADA o JA_EXISTE, detalladas en resumo); ignoradas = filas con ERRO. Importadas + ignoradas = filas leídas. En simular, es la previsión. | |
contagens.importadas | integer | sí | 0… | |
contagens.ignoradas | integer | sí | 0… | Solo en aplicar parcial: las filas que quedaron fuera (fila, campo y motivo). Existe solo en esta respuesta: no se graba. |
ignoradas | lista de LinhaRelatorio | no | Solo en aplicar parcial: las filas que quedaron fuera (fila, campo y motivo). Existe solo en esta respuesta: no se graba. |
En caso de error: modelo ErroApi.
Ejemplo
bash
curl -X POST "$API/turmas/{turmaId}/importacoes/alunos" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'Importa actividades del grupo por CSV
POST /turmas/{turmaId}/importacoes/atividades
Una actividad se reconoce por fecha, hora de inicio y descripción; la importación solo crea, nunca modifica ni borra. Use modo: simular antes de aplicar.
Acceso: Exige la capacidad CADASTRAR sobre grupo (params.turmaId). Límite: hasta 20 llamadas cada 60 s por origen. Estado de éxito: 200.
Parámetros de ruta
| Parámetro | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
turmaId | string (uuid) | sí | Id del grupo. |
Cuerpo de la solicitud (ImportacaoEntrada)
| Campo | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
csv | string | sí | 1–90000 caracteres | |
modo | "simular" | "aplicar" | sí | simular solo valida y muestra lo que ocurriría; aplicar graba todo o nada (a menos que parcial). | |
parcial | boolean | no | Modo parcial (con trabas): importa solo las filas válidas y devuelve las ignoradas en la respuesta. simular con parcial devuelve hashConteudo; aplicar con parcial exige el mismo hashConteudo (ausente o distinto = 409 CONFLICT). Ausente o false = todo o nada. | |
hashConteudo | string | no | ^[0-9a-f]{64}$ | Hash devuelto por la simulación parcial del mismo contenido (SHA-256 del contenido normalizado, 64 caracteres hexadecimales). |
Respuesta
| Campo | Tipo | Obligatorio | Restricciones | Descripción |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | sí | ||
modo | "simular" | "aplicar" | sí | ||
aplicado | boolean | sí | En aplicar: true = grabó; false = alguna fila con error, no se grabó nada. En simular, siempre false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" o nulo | sí | Error del archivo en su conjunto (vacío, demasiado grande, falta una columna obligatoria). | |
colunaAusente | string o nulo | sí | ||
resumo | object | sí | ||
linhas | lista de LinhaRelatorio | sí | ||
convites | integer o nulo | sí | 0… | Invitaciones que saldrán (cuentas nuevas). null = no informado (simular no revela si el correo ya tiene cuenta). |
parcial | boolean | no | Solo en el modo parcial. true = el pedido fue parcial. | |
hashConteudo | string | no | Solo en simular parcial: SHA-256 del contenido normalizado (tipo, destino y filas leídas), que aplicar parcial devuelve. | |
contagens | object | no | Solo en el modo parcial: importadas = filas válidas (CRIADA, INCLUIDA, REATIVADA o JA_EXISTE, detalladas en resumo); ignoradas = filas con ERRO. Importadas + ignoradas = filas leídas. En simular, es la previsión. | |
contagens.importadas | integer | sí | 0… | |
contagens.ignoradas | integer | sí | 0… | Solo en aplicar parcial: las filas que quedaron fuera (fila, campo y motivo). Existe solo en esta respuesta: no se graba. |
ignoradas | lista de LinhaRelatorio | no | Solo en aplicar parcial: las filas que quedaron fuera (fila, campo y motivo). Existe solo en esta respuesta: no se graba. |
En caso de error: modelo ErroApi.
Ejemplo
bash
curl -X POST "$API/turmas/{turmaId}/importacoes/atividades" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'