CSV import
Bulk import of people, students and activities, with a dry run before writing.
Import people (staff and students) by CSV
POST /instituicoes/{instituicaoId}/importacoes/pessoas
The CSV is sent as text in the csv field (max 500 rows and 90,000 characters). Use modo: simular to see the report before aplicar. Importing is idempotent: someone who already exists comes back as JA_EXISTE.
Access: Requires the capability ADMINISTRAR over institution (params.instituicaoId). Rate limit: up to 20 calls every 60 s per origin. Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
instituicaoId | string (uuid) | yes | Institution id. |
Request body (ImportacaoEntrada)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
csv | string | yes | 1–90000 characters | |
modo | "simular" | "aplicar" | yes | simular only validates and shows what would happen; aplicar writes all or nothing (unless parcial). | |
parcial | boolean | no | Partial mode (with safeguards): imports only valid rows and returns the skipped ones in the response. simular with parcial returns hashConteudo; aplicar with parcial requires the same hashConteudo (missing or different = 409 CONFLICT). Absent or false = all or nothing. | |
hashConteudo | string | no | ^[0-9a-f]{64}$ | Hash returned by the partial dry run of the same content (SHA-256 of the normalised content, 64 hex characters). |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | yes | ||
modo | "simular" | "aplicar" | yes | ||
aplicado | boolean | yes | On aplicar: true = written; false = some row had an error, nothing was written. On simular, always false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" or null | yes | Error of the file as a whole (empty, too large, required column missing). | |
colunaAusente | string or null | yes | ||
resumo | object | yes | ||
linhas | list of LinhaRelatorio | yes | ||
convites | integer or null | yes | 0… | Invitations that will be sent (new accounts). null = not reported (simular does not reveal whether an email already has an account). |
parcial | boolean | no | Partial mode only. true = the request was partial. | |
hashConteudo | string | no | Only on a partial simular: SHA-256 of the normalised content (type, target and rows read), which the partial aplicar sends back. | |
contagens | object | no | Partial mode only: importadas = valid rows (CRIADA, INCLUIDA, REATIVADA or JA_EXISTE, detailed in resumo); ignoradas = rows with ERRO. Imported + skipped = rows read. On simular, it is the forecast. | |
contagens.importadas | integer | yes | 0… | |
contagens.ignoradas | integer | yes | 0… | Only on a partial aplicar: the rows left out (row, field and reason). It exists only in this response: it is not stored. |
ignoradas | list of LinhaRelatorio | no | Only on a partial aplicar: the rows left out (row, field and reason). It exists only in this response: it is not stored. |
On error: ErroApi model.
Example
bash
curl -X POST "$API/instituicoes/{instituicaoId}/importacoes/pessoas" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'Import the class's students by CSV
POST /turmas/{turmaId}/importacoes/alunos
The CSV is sent as text in the csv field (max 500 rows and 90,000 characters). Use modo: simular before aplicar. Repeating the import does not duplicate enrollments.
Access: Requires the capability CADASTRAR over class (params.turmaId). Rate limit: up to 20 calls every 60 s per origin. Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
turmaId | string (uuid) | yes | Class id. |
Request body (ImportacaoEntrada)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
csv | string | yes | 1–90000 characters | |
modo | "simular" | "aplicar" | yes | simular only validates and shows what would happen; aplicar writes all or nothing (unless parcial). | |
parcial | boolean | no | Partial mode (with safeguards): imports only valid rows and returns the skipped ones in the response. simular with parcial returns hashConteudo; aplicar with parcial requires the same hashConteudo (missing or different = 409 CONFLICT). Absent or false = all or nothing. | |
hashConteudo | string | no | ^[0-9a-f]{64}$ | Hash returned by the partial dry run of the same content (SHA-256 of the normalised content, 64 hex characters). |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | yes | ||
modo | "simular" | "aplicar" | yes | ||
aplicado | boolean | yes | On aplicar: true = written; false = some row had an error, nothing was written. On simular, always false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" or null | yes | Error of the file as a whole (empty, too large, required column missing). | |
colunaAusente | string or null | yes | ||
resumo | object | yes | ||
linhas | list of LinhaRelatorio | yes | ||
convites | integer or null | yes | 0… | Invitations that will be sent (new accounts). null = not reported (simular does not reveal whether an email already has an account). |
parcial | boolean | no | Partial mode only. true = the request was partial. | |
hashConteudo | string | no | Only on a partial simular: SHA-256 of the normalised content (type, target and rows read), which the partial aplicar sends back. | |
contagens | object | no | Partial mode only: importadas = valid rows (CRIADA, INCLUIDA, REATIVADA or JA_EXISTE, detailed in resumo); ignoradas = rows with ERRO. Imported + skipped = rows read. On simular, it is the forecast. | |
contagens.importadas | integer | yes | 0… | |
contagens.ignoradas | integer | yes | 0… | Only on a partial aplicar: the rows left out (row, field and reason). It exists only in this response: it is not stored. |
ignoradas | list of LinhaRelatorio | no | Only on a partial aplicar: the rows left out (row, field and reason). It exists only in this response: it is not stored. |
On error: ErroApi model.
Example
bash
curl -X POST "$API/turmas/{turmaId}/importacoes/alunos" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'Import the class's activities by CSV
POST /turmas/{turmaId}/importacoes/atividades
An activity is recognised by date, start time and description; importing only creates, never changes or deletes. Use modo: simular before aplicar.
Access: Requires the capability CADASTRAR over class (params.turmaId). Rate limit: up to 20 calls every 60 s per origin. Success status: 200.
Path parameters
| Parameter | Type | Required | Constraints | Description |
|---|---|---|---|---|
turmaId | string (uuid) | yes | Class id. |
Request body (ImportacaoEntrada)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
csv | string | yes | 1–90000 characters | |
modo | "simular" | "aplicar" | yes | simular only validates and shows what would happen; aplicar writes all or nothing (unless parcial). | |
parcial | boolean | no | Partial mode (with safeguards): imports only valid rows and returns the skipped ones in the response. simular with parcial returns hashConteudo; aplicar with parcial requires the same hashConteudo (missing or different = 409 CONFLICT). Absent or false = all or nothing. | |
hashConteudo | string | no | ^[0-9a-f]{64}$ | Hash returned by the partial dry run of the same content (SHA-256 of the normalised content, 64 hex characters). |
Response
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
tipo | "pessoas" | "alunos" | "atividades" | yes | ||
modo | "simular" | "aplicar" | yes | ||
aplicado | boolean | yes | On aplicar: true = written; false = some row had an error, nothing was written. On simular, always false. | |
erroArquivo | "empty" | "too_many_lines" | "unterminated_quote" | "too_large" | "missing_column" or null | yes | Error of the file as a whole (empty, too large, required column missing). | |
colunaAusente | string or null | yes | ||
resumo | object | yes | ||
linhas | list of LinhaRelatorio | yes | ||
convites | integer or null | yes | 0… | Invitations that will be sent (new accounts). null = not reported (simular does not reveal whether an email already has an account). |
parcial | boolean | no | Partial mode only. true = the request was partial. | |
hashConteudo | string | no | Only on a partial simular: SHA-256 of the normalised content (type, target and rows read), which the partial aplicar sends back. | |
contagens | object | no | Partial mode only: importadas = valid rows (CRIADA, INCLUIDA, REATIVADA or JA_EXISTE, detailed in resumo); ignoradas = rows with ERRO. Imported + skipped = rows read. On simular, it is the forecast. | |
contagens.importadas | integer | yes | 0… | |
contagens.ignoradas | integer | yes | 0… | Only on a partial aplicar: the rows left out (row, field and reason). It exists only in this response: it is not stored. |
ignoradas | list of LinhaRelatorio | no | Only on a partial aplicar: the rows left out (row, field and reason). It exists only in this response: it is not stored. |
On error: ErroApi model.
Example
bash
curl -X POST "$API/turmas/{turmaId}/importacoes/atividades" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"csv":"texto","modo":"simular"}'