Usuários e vínculos

Pessoas e papéis de uma instituição: cadastro, convite e vínculos.

Lista as pessoas da instituição

GET /instituicoes/{instituicaoId}/usuarios

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). 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.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`busca`	`string`	não	a 100 caracteres	Texto para buscar (nome ou e-mail, conforme a rota).
`limite`	`integer`	não	1…200; padrão: `50`	Quantos itens por página (1 a 200; o padrão varia por rota, em geral 50).
`deslocamento`	`integer`	não	0…100000; padrão: `0`	Quantos itens pular, para paginar (até 100000).
`inativos`	`"true"` \| `"false"`	não	padrão: `"false"`	`true` inclui também os registros inativos.
`tipo`	`"equipe"` \| `"alunos"`	não		Filtra por tipo.
`papel`	`"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"` \| `"ALUNO"`	não		Filtra pelo papel (ex.: `PROFESSOR`).
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	não		Filtra pela situação.

Resposta

UsuarioLista

Campo	Tipo	Obrigatório	Restrições
`items`	lista de UsuarioDto	sim
`total`	`integer`	sim	0…
`contagens`	UsuarioContagens	não

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/instituicoes/{instituicaoId}/usuarios" -H "Authorization: Bearer $TOKEN"

Cria uma pessoa da equipe e dá o vínculo

POST /instituicoes/{instituicaoId}/usuarios

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Limite: até 120 chamadas a cada 60 s por origem. Status de sucesso: 201.

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 (EquipeCriar)

Campo	Tipo	Obrigatório	Restrições
`email`	Email	sim
`nome`	`string`	sim	1–200 caracteres
`nationality`	`string` ou `nulo`	não	2–2 caracteres; `^[A-Za-z]{2}$`
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` ou `nulo`	não
`papel`	`"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sim
`disciplinaId`	`string (uuid)` ou `nulo`	não
`turmaId`	`string (uuid)` ou `nulo`	não
`podeAvaliar`	`boolean`	não	padrão: `false`
`podeCadastrar`	`boolean`	não	padrão: `false`

Resposta

UsuarioDto

Campo	Tipo	Obrigatório	Descrição
`id`	`string (uuid)`	sim
`email`	`string`	sim
`nome`	`string`	sim
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	sim
`nationality`	`string` ou `nulo`	sim
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` ou `nulo`	sim
`compartilhado`	`boolean`	sim	Tem vínculo ou matrícula em outra instituição: só a plataforma altera nome e status.
`jaExistia`	`boolean`	não	Só na resposta de criar: o e-mail já tinha conta e a pessoa foi vinculada a ela.

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X POST "$API/instituicoes/{instituicaoId}/usuarios" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"email":"texto","nome":"texto","papel":"CURADOR"}'

Lê uma pessoa da instituição

GET /instituicoes/{instituicaoId}/usuarios/{usuarioId}

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`usuarioId`	`string (uuid)`	sim		Id da pessoa.
`instituicaoId`	`string (uuid)`	sim		Id da instituição.

Resposta

UsuarioDto

Campo	Tipo	Obrigatório	Descrição
`id`	`string (uuid)`	sim
`email`	`string`	sim
`nome`	`string`	sim
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	sim
`nationality`	`string` ou `nulo`	sim
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` ou `nulo`	sim
`compartilhado`	`boolean`	sim	Tem vínculo ou matrícula em outra instituição: só a plataforma altera nome e status.
`jaExistia`	`boolean`	não	Só na resposta de criar: o e-mail já tinha conta e a pessoa foi vinculada a ela.

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/instituicoes/{instituicaoId}/usuarios/{usuarioId}" -H "Authorization: Bearer $TOKEN"

Atualiza uma pessoa da instituição

PATCH /instituicoes/{instituicaoId}/usuarios/{usuarioId}

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`usuarioId`	`string (uuid)`	sim		Id da pessoa.
`instituicaoId`	`string (uuid)`	sim		Id da instituição.

Corpo da requisição (UsuarioAtualizar)

Campo	Tipo	Obrigatório	Restrições
`nome`	`string`	não	1–200 caracteres
`nationality`	`string` ou `nulo`	não	2–2 caracteres; `^[A-Za-z]{2}$`
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` ou `nulo`	não
`status`	`"ATIVO"` \| `"SUSPENSO"`	não

Resposta

UsuarioDto

Campo	Tipo	Obrigatório	Descrição
`id`	`string (uuid)`	sim
`email`	`string`	sim
`nome`	`string`	sim
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	sim
`nationality`	`string` ou `nulo`	sim
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` ou `nulo`	sim
`compartilhado`	`boolean`	sim	Tem vínculo ou matrícula em outra instituição: só a plataforma altera nome e status.
`jaExistia`	`boolean`	não	Só na resposta de criar: o e-mail já tinha conta e a pessoa foi vinculada a ela.

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X PATCH "$API/instituicoes/{instituicaoId}/usuarios/{usuarioId}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'

Reenvia o convite por e-mail

POST /instituicoes/{instituicaoId}/usuarios/{usuarioId}/convite

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Limite: até 30 chamadas a cada 60 s por origem. Status de sucesso: 204.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`usuarioId`	`string (uuid)`	sim		Id da pessoa.
`instituicaoId`	`string (uuid)`	sim		Id da instituição.

Resposta

Sem corpo na resposta.

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X POST "$API/instituicoes/{instituicaoId}/usuarios/{usuarioId}/convite" -H "Authorization: Bearer $TOKEN"

Lista os vínculos da instituição

GET /instituicoes/{instituicaoId}/vinculos

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). 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.

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`busca`	`string`	não	a 100 caracteres	Texto para buscar (nome ou e-mail, conforme a rota).
`limite`	`integer`	não	1…200; padrão: `50`	Quantos itens por página (1 a 200; o padrão varia por rota, em geral 50).
`deslocamento`	`integer`	não	0…100000; padrão: `0`	Quantos itens pular, para paginar (até 100000).
`inativos`	`"true"` \| `"false"`	não	padrão: `"false"`	`true` inclui também os registros inativos.
`usuarioId`	`string (uuid)`	não		Id da pessoa.

Resposta

lista de VinculoItem (+ total)

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`usuarioId`	`string (uuid)`	sim
`nome`	`string`	sim
`email`	`string`	sim
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sim
`instituicaoId`	`string (uuid)` ou `nulo`	sim
`disciplinaId`	`string (uuid)` ou `nulo`	sim
`turmaId`	`string (uuid)` ou `nulo`	sim
`podeAvaliar`	`boolean`	sim
`podeCadastrar`	`boolean`	sim
`ativo`	`boolean`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X GET "$API/instituicoes/{instituicaoId}/vinculos" -H "Authorization: Bearer $TOKEN"

Cria um vínculo (papel e escopo) para uma pessoa

POST /instituicoes/{instituicaoId}/vinculos

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Limite: até 120 chamadas a cada 60 s por origem. Status de sucesso: 201.

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 (VinculoCriar)

Campo	Tipo	Obrigatório	Restrições
`usuarioId`	`string (uuid)`	sim
`papel`	`"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sim
`disciplinaId`	`string (uuid)` ou `nulo`	não
`turmaId`	`string (uuid)` ou `nulo`	não
`podeAvaliar`	`boolean`	não	padrão: `false`
`podeCadastrar`	`boolean`	não	padrão: `false`

Resposta

VinculoItem

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`usuarioId`	`string (uuid)`	sim
`nome`	`string`	sim
`email`	`string`	sim
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sim
`instituicaoId`	`string (uuid)` ou `nulo`	sim
`disciplinaId`	`string (uuid)` ou `nulo`	sim
`turmaId`	`string (uuid)` ou `nulo`	sim
`podeAvaliar`	`boolean`	sim
`podeCadastrar`	`boolean`	sim
`ativo`	`boolean`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X POST "$API/instituicoes/{instituicaoId}/vinculos" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"usuarioId":"0198a000-0000-7000-8000-000000000001","papel":"CURADOR"}'

Atualiza um vínculo

PATCH /instituicoes/{instituicaoId}/vinculos/{vinculoId}

Acesso: Exige a capacidade ADMINISTRAR sobre instituição (params.instituicaoId). Status de sucesso: 200.

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Restrições	Descrição
`vinculoId`	`string (uuid)`	sim		Id do vínculo.
`instituicaoId`	`string (uuid)`	sim		Id da instituição.

Corpo da requisição (VinculoAtualizar)

Campo	Tipo	Obrigatório
`podeAvaliar`	`boolean`	não
`podeCadastrar`	`boolean`	não
`ativo`	`boolean`	não

Resposta

VinculoItem

Campo	Tipo	Obrigatório
`id`	`string (uuid)`	sim
`usuarioId`	`string (uuid)`	sim
`nome`	`string`	sim
`email`	`string`	sim
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sim
`instituicaoId`	`string (uuid)` ou `nulo`	sim
`disciplinaId`	`string (uuid)` ou `nulo`	sim
`turmaId`	`string (uuid)` ou `nulo`	sim
`podeAvaliar`	`boolean`	sim
`podeCadastrar`	`boolean`	sim
`ativo`	`boolean`	sim

Em caso de erro: modelo ErroApi.

Exemplo

bash

curl -X PATCH "$API/instituicoes/{instituicaoId}/vinculos/{vinculoId}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{}'

Usuários e vínculos ​

Lista as pessoas da instituição ​

Cria uma pessoa da equipe e dá o vínculo ​

Lê uma pessoa da instituição ​

Atualiza uma pessoa da instituição ​

Reenvia o convite por e-mail ​

Lista os vínculos da instituição ​

Cria um vínculo (papel e escopo) para uma pessoa ​

Atualiza um vínculo ​

Usuários e vínculos

Lista as pessoas da instituição

Cria uma pessoa da equipe e dá o vínculo

Lê uma pessoa da instituição

Atualiza uma pessoa da instituição

Reenvia o convite por e-mail

Lista os vínculos da instituição

Cria um vínculo (papel e escopo) para uma pessoa

Atualiza um vínculo