Usuarios y vínculos

Personas y roles de una institución: alta, invitación y vínculos.

Lista las personas de la institución

GET /instituicoes/{instituicaoId}/usuarios

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Estado de éxito: 200.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`busca`	`string`	no	a 100 caracteres	Texto para buscar (nombre o correo, según la ruta).
`limite`	`integer`	no	1…200; por defecto: `50`	Cuántos elementos por página (1 a 200; el valor predeterminado varía por ruta, en general 50).
`deslocamento`	`integer`	no	0…100000; por defecto: `0`	Cuántos elementos saltar, para paginar (hasta 100000).
`inativos`	`"true"` \| `"false"`	no	por defecto: `"false"`	`true` incluye también los registros inactivos.
`tipo`	`"equipe"` \| `"alunos"`	no		Filtra por tipo.
`papel`	`"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"` \| `"ALUNO"`	no		Filtra por el rol (p. ej.: `PROFESSOR`).
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	no		Filtra por la situación.

Respuesta

UsuarioLista

Campo	Tipo	Obligatorio	Restricciones
`items`	lista de UsuarioDto	sí
`total`	`integer`	sí	0…
`contagens`	UsuarioContagens	no

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Crea una persona del equipo y le da el vínculo

POST /instituicoes/{instituicaoId}/usuarios

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Límite: hasta 120 llamadas cada 60 s por origen. Estado de éxito: 201.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Cuerpo de la solicitud (EquipeCriar)

Campo	Tipo	Obligatorio	Restricciones
`email`	Email	sí
`nome`	`string`	sí	1–200 caracteres
`nationality`	`string` o `nulo`	no	2–2 caracteres; `^[A-Za-z]{2}$`
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` o `nulo`	no
`papel`	`"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sí
`disciplinaId`	`string (uuid)` o `nulo`	no
`turmaId`	`string (uuid)` o `nulo`	no
`podeAvaliar`	`boolean`	no	por defecto: `false`
`podeCadastrar`	`boolean`	no	por defecto: `false`

Respuesta

UsuarioDto

Campo	Tipo	Obligatorio	Descripción
`id`	`string (uuid)`	sí
`email`	`string`	sí
`nome`	`string`	sí
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	sí
`nationality`	`string` o `nulo`	sí
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` o `nulo`	sí
`compartilhado`	`boolean`	sí	Tiene vínculo o matrícula en otra institución: solo la plataforma cambia nombre y estado.
`jaExistia`	`boolean`	no	Solo en la respuesta de crear: el correo ya tenía cuenta y la persona se vinculó a ella.

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Lee una persona de la institución

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

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Estado de éxito: 200.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`usuarioId`	`string (uuid)`	sí		Id de la persona.
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Respuesta

UsuarioDto

Campo	Tipo	Obligatorio	Descripción
`id`	`string (uuid)`	sí
`email`	`string`	sí
`nome`	`string`	sí
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	sí
`nationality`	`string` o `nulo`	sí
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` o `nulo`	sí
`compartilhado`	`boolean`	sí	Tiene vínculo o matrícula en otra institución: solo la plataforma cambia nombre y estado.
`jaExistia`	`boolean`	no	Solo en la respuesta de crear: el correo ya tenía cuenta y la persona se vinculó a ella.

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Actualiza una persona de la institución

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

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Estado de éxito: 200.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`usuarioId`	`string (uuid)`	sí		Id de la persona.
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Cuerpo de la solicitud (UsuarioAtualizar)

Campo	Tipo	Obligatorio	Restricciones
`nome`	`string`	no	1–200 caracteres
`nationality`	`string` o `nulo`	no	2–2 caracteres; `^[A-Za-z]{2}$`
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` o `nulo`	no
`status`	`"ATIVO"` \| `"SUSPENSO"`	no

Respuesta

UsuarioDto

Campo	Tipo	Obligatorio	Descripción
`id`	`string (uuid)`	sí
`email`	`string`	sí
`nome`	`string`	sí
`status`	`"CONVIDADO"` \| `"ATIVO"` \| `"SUSPENSO"`	sí
`nationality`	`string` o `nulo`	sí
`locale`	`"pt-BR"` \| `"es"` \| `"en-US"` o `nulo`	sí
`compartilhado`	`boolean`	sí	Tiene vínculo o matrícula en otra institución: solo la plataforma cambia nombre y estado.
`jaExistia`	`boolean`	no	Solo en la respuesta de crear: el correo ya tenía cuenta y la persona se vinculó a ella.

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Reenvía la invitación por correo

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

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Límite: hasta 30 llamadas cada 60 s por origen. Estado de éxito: 204.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`usuarioId`	`string (uuid)`	sí		Id de la persona.
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Respuesta

Sin cuerpo en la respuesta.

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Lista los vínculos de la institución

GET /instituicoes/{instituicaoId}/vinculos

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Estado de éxito: 200.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`busca`	`string`	no	a 100 caracteres	Texto para buscar (nombre o correo, según la ruta).
`limite`	`integer`	no	1…200; por defecto: `50`	Cuántos elementos por página (1 a 200; el valor predeterminado varía por ruta, en general 50).
`deslocamento`	`integer`	no	0…100000; por defecto: `0`	Cuántos elementos saltar, para paginar (hasta 100000).
`inativos`	`"true"` \| `"false"`	no	por defecto: `"false"`	`true` incluye también los registros inactivos.
`usuarioId`	`string (uuid)`	no		Id de la persona.

Respuesta

lista de VinculoItem (+ total)

Campo	Tipo	Obligatorio
`id`	`string (uuid)`	sí
`usuarioId`	`string (uuid)`	sí
`nome`	`string`	sí
`email`	`string`	sí
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sí
`instituicaoId`	`string (uuid)` o `nulo`	sí
`disciplinaId`	`string (uuid)` o `nulo`	sí
`turmaId`	`string (uuid)` o `nulo`	sí
`podeAvaliar`	`boolean`	sí
`podeCadastrar`	`boolean`	sí
`ativo`	`boolean`	sí

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Crea un vínculo (rol y ámbito) para una persona

POST /instituicoes/{instituicaoId}/vinculos

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Límite: hasta 120 llamadas cada 60 s por origen. Estado de éxito: 201.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Cuerpo de la solicitud (VinculoCriar)

Campo	Tipo	Obligatorio	Restricciones
`usuarioId`	`string (uuid)`	sí
`papel`	`"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sí
`disciplinaId`	`string (uuid)` o `nulo`	no
`turmaId`	`string (uuid)` o `nulo`	no
`podeAvaliar`	`boolean`	no	por defecto: `false`
`podeCadastrar`	`boolean`	no	por defecto: `false`

Respuesta

VinculoItem

Campo	Tipo	Obligatorio
`id`	`string (uuid)`	sí
`usuarioId`	`string (uuid)`	sí
`nome`	`string`	sí
`email`	`string`	sí
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sí
`instituicaoId`	`string (uuid)` o `nulo`	sí
`disciplinaId`	`string (uuid)` o `nulo`	sí
`turmaId`	`string (uuid)` o `nulo`	sí
`podeAvaliar`	`boolean`	sí
`podeCadastrar`	`boolean`	sí
`ativo`	`boolean`	sí

En caso de error: modelo ErroApi.

Ejemplo

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"}'

Actualiza un vínculo

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

Acceso: Exige la capacidad ADMINISTRAR sobre institución (params.instituicaoId). Estado de éxito: 200.

Parámetros de ruta

Parámetro	Tipo	Obligatorio	Restricciones	Descripción
`vinculoId`	`string (uuid)`	sí		Id del vínculo.
`instituicaoId`	`string (uuid)`	sí		Id de la institución.

Cuerpo de la solicitud (VinculoAtualizar)

Campo	Tipo	Obligatorio
`podeAvaliar`	`boolean`	no
`podeCadastrar`	`boolean`	no
`ativo`	`boolean`	no

Respuesta

VinculoItem

Campo	Tipo	Obligatorio
`id`	`string (uuid)`	sí
`usuarioId`	`string (uuid)`	sí
`nome`	`string`	sí
`email`	`string`	sí
`papel`	`"ADMIN_PLATAFORMA"` \| `"CURADOR"` \| `"PRECEPTOR"` \| `"COORDENADOR"` \| `"PROFESSOR"` \| `"AUXILIAR"`	sí
`instituicaoId`	`string (uuid)` o `nulo`	sí
`disciplinaId`	`string (uuid)` o `nulo`	sí
`turmaId`	`string (uuid)` o `nulo`	sí
`podeAvaliar`	`boolean`	sí
`podeCadastrar`	`boolean`	sí
`ativo`	`boolean`	sí

En caso de error: modelo ErroApi.

Ejemplo

bash

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

Usuarios y vínculos ​

Lista las personas de la institución ​

Crea una persona del equipo y le da el vínculo ​

Lee una persona de la institución ​

Actualiza una persona de la institución ​

Reenvía la invitación por correo ​

Lista los vínculos de la institución ​

Crea un vínculo (rol y ámbito) para una persona ​

Actualiza un vínculo ​

Usuarios y vínculos

Lista las personas de la institución

Crea una persona del equipo y le da el vínculo

Lee una persona de la institución

Actualiza una persona de la institución

Reenvía la invitación por correo

Lista los vínculos de la institución

Crea un vínculo (rol y ámbito) para una persona

Actualiza un vínculo