Gestão de Usuários e Responsáveis

A plataforma GDREdu possui dois tipos de pessoas:

• Staff (funcionários): Professores, coordenadores, administradores — vinculados a uma unidade com roles (permissões) específicas
• Responsáveis (guardians): Pais, mães ou responsáveis legais — vinculados a um estudante (não a uma unidade diretamente)

A mesma pessoa pode ser staff em uma unidade e responsável em outra. O parâmetro profile na listagem permite filtrar.

:::info
Branch-scoped
Os endpoints de staff operam no contexto de uma unidade. Os endpoints de responsáveis listam pessoas com filhos matriculados na unidade.
:::

:::warning[O que é o :id em /v1/users/:id?]
/v1/users/:id usa o userId (ID global da pessoa), NÃO o userHasBranchId. Diferente de /v1/students/:id, que usa o studentHasBranchId (vínculo com a unidade).

O userId é estável: a mesma pessoa é a mesma em qualquer unidade. Já o userHasBranchId muda entre unidades e entre contextos.

Se você está integrando e precisa mapear "esse cara que trabalha em 2 escolas", use sempre o userId.
:::

Endpoints

Endpoint de Ponto Eletrônico

GET /v1/users

Lista usuários (staff e/ou responsáveis) com paginação e filtros.

Parâmetros (query)

Roles disponíveis (accessRole)

Exemplo

curl "https://api.gdredu.com/v1/users?profile=staff&accessRole=DASH_ADMIN&page=1&limit=10" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Admin Escola Modelo",
      "email": "[email protected]",
      "cpf": null,
      "image": null,
      "isMasterAccount": true,
      "isAccessBlocked": false,
      "accessBlockedAt": null,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "profile": "staff",
      "accessRoles": ["DASH_ADMIN"],
      "shifts": ["MORNING"],
      "_count": { "students": 0 }
    }
  ],
  "pagination": { "page": 1, "limit": 10, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }
}

POST /v1/users

Cria um novo usuário. O endpoint serve tanto para staff quanto responsáveis.

Body (staff)

{
  "name": "Maria Souza",
  "email": "[email protected]",
  "cpf": "123.456.789-00",
  "number": "11988887777",
  "password": "senha-segura-123",
  "accessRoles": ["GRADES_TEACHER", "GRADES_ADMIN"],
  "shifts": ["MORNING", "AFTERNOON"],
  "branchIds": ["660e8400-e29b-41d4-a716-446655440000"],
  "disciplineIds": ["770e8400-e29b-41d4-a716-446655440000"]
}

:::info[Email é obrigatório]
Não é possível criar um usuário sem email — ele é necessário para o login. Para cadastro de responsáveis (que normalmente não acessam o painel), o email é gerado automaticamente se você não informar (use [email protected] como placeholder).
:::

Resposta (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Maria Souza",
  "email": "[email protected]"
}

Erros

GET /v1/users/:id

Retorna os detalhes de um usuário (incluindo vínculo com a branch, disciplinas, etc).

Resposta (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Maria Souza",
  "email": "[email protected]",
  "cpf": "123.456.789-00",
  "image": null,
  "isMasterAccount": false,
  "isAccessBlocked": false,
  "createdAt": "2026-01-15T10:00:00.000Z",
  "branch": {
    "userBranchId": "660e8400-e29b-41d4-a716-446655440000",
    "accessRoles": ["GRADES_TEACHER"],
    "shifts": ["MORNING"],
    "disciplines": [
      { "id": "...", "name": "Matemática" }
    ]
  }
}

Erros

PUT /v1/users/:id

Atualiza dados do usuário. Todos os campos são opcionais (PATCH semântico). Se email for enviado, deve ser válido e único (não pode colidir com outro usuário da mesma instituição).

Body

{
  "name": "Maria Souza Santos",
  "email": "[email protected]",
  "number": "11988886666",
  "accessRoles": ["GRADES_TEACHER", "GRADES_ADMIN"],
  "shifts": ["MORNING", "AFTERNOON"]
}

Resposta (200)

{ "id": "...", "message": "Usuário atualizado com sucesso." }

DELETE /v1/users/:id

Bloqueia o acesso do usuário. Pode ser revertido com POST /v1/users/:id/reactivate.

Resposta (204)

Sem corpo (No Content).

Erros

POST /v1/users/:id/reactivate

Desbloqueia o usuário.

Resposta (200)

{ "id": "...", "isAccessBlocked": false, "message": "Usuário desbloqueado com sucesso." }

Permissões de Acesso (Permissões e Turnos)

Define quais permissões e turnos o usuário tem na unidade. Permissões controlam acesso aos módulos do painel (Laboratório, Provas, Painel, Biblioteca). Turnos indicam a escala de trabalho (Manhã, Tarde, Noite).

PUT /v1/users/:id/access-roles

Atualiza permissões e/ou turnos. Para atualização em massa (junto com outros dados do usuário), use PUT /v1/users/:id.

Body

{
  "accessRoles": ["DASH_ADMIN", "GRADES_TEACHER"],
  "shifts": ["MORNING", "AFTERNOON"]
}

Resposta (200)

{
  "userId": "770e8400-e29b-41d4-a716-446655440000",
  "accessRoles": ["DASH_ADMIN", "GRADES_TEACHER"],
  "shifts": ["MORNING", "AFTERNOON"]
}

:::tip
Algumas permissões englobam outras: DASH_ADMIN abrange DASH_MANAGER e DASH_FINANCE; LAB_ADMIN abrange LAB; EXAMS_ADMIN abrange EXAMS_TEACHER; GRADES_ADMIN abrange GRADES_TEACHER. Garanta que o plano da instituição contempla as permissões antes de atribuí-las.
:::

Filiais com Acesso

Define quais filiais o usuário pode acessar. Administradores da instituição (isMasterAccount = true) não precisam desta configuração — têm acesso implícito a todas as filiais.

PUT /v1/users/:id/branches

Substitui a lista de filiais do usuário. Ao remover uma filial, configurações vinculadas a ela (horários de trabalho, disciplinas) também são removidas.

Body

{
  "branchIds": ["880e8400-e29b-41d4-a716-446655440001", "880e8400-e29b-41d4-a716-446655440002"]
}

Resposta (200)

{
  "userId": "770e8400-e29b-41d4-a716-446655440000",
  "branches": [
    { "branchId": "880e...001", "branchName": "Filial Centro", "accessRoles": ["GRADES_TEACHER"], "shifts": ["MORNING"] },
    { "branchId": "880e...002", "branchName": "Filial Norte", "accessRoles": [], "shifts": [] }
  ]
}

Horários de Trabalho

Define quando o usuário deve registrar ponto na unidade. A plataforma usa esses horários para classificar o ponto como dentro do horário, atrasado ou adiantado (tolerância padrão de 15 minutos).

GET /v1/users/:id/work-schedules

Lista os horários configurados.

Resposta (200)

{
  "userId": "770e8400-e29b-41d4-a716-446655440000",
  "workSchedules": [
    { "id": "...", "dayOfWeek": "Monday", "startTime": "08:00", "endTime": "12:00", "isUnavailable": false },
    { "id": "...", "dayOfWeek": "Monday", "startTime": "13:00", "endTime": "18:00", "isUnavailable": false }
  ]
}

PUT /v1/users/:id/work-schedules

Substitui todos os horários do usuário. Entradas duplicadas (mesmo dia + horário) são deduplicadas automaticamente.

Body

{
  "workSchedules": [
    { "dayOfWeek": "Monday", "startTime": "08:00", "endTime": "12:00", "isUnavailable": false },
    { "dayOfWeek": "Monday", "startTime": "13:00", "endTime": "18:00", "isUnavailable": false },
    { "dayOfWeek": "Tuesday", "startTime": "08:00", "endTime": "18:00", "isUnavailable": false },
    { "dayOfWeek": "Sunday", "startTime": "00:00", "endTime": "23:59", "isUnavailable": true }
  ]
}

Resposta (200) — lista atualizada (mesma forma do GET).

Disciplinas Lecionadas

Vincula o usuário (professor) a componentes curriculares. Use para o caso "professor X leciona a disciplina Y".

GET /v1/users/:id/disciplines

Lista as disciplinas vinculadas.

Resposta (200)

{
  "userId": "770e8400-e29b-41d4-a716-446655440000",
  "disciplines": [
    { "id": "...", "disciplineId": "aa0e8400-...", "name": "Matemática", "createdAt": "2026-01-15T..." }
  ]
}

PUT /v1/users/:id/disciplines

Substitui a lista de disciplinas. As disciplinas devem existir e pertencer à mesma instituição do usuário.

Body

{
  "disciplineIds": ["aa0e8400-e29b-41d4-a716-446655440000", "bb0e8400-e29b-41d4-a716-446655440000"]
}

Redefinição de Senha

Define a senha de login do usuário. Útil para: primeiro acesso, recuperação, migração de usuários, ou quando o fluxo de "esqueci minha senha" não é viável.

:::warning
Esta operação substitui a senha atual. A senha antiga deixa de funcionar imediatamente.
:::

POST /v1/users/:id/reset-password

Body

{
  "password": "NovaSenha@123"
}

Resposta (200)

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "message": "Senha redefinida com sucesso."
}

:::tip
Você também pode definir a senha ao criar (POST /v1/users) ou atualizar (PUT /v1/users/:id) o usuário incluindo o campo password no body.
:::

Acesso Físico (Catracas)

Bloqueia/desbloqueia o usuário nos dispositivos de acesso físico (catracas) da unidade. Verifique o campo hasControlIdEquipment em GET /v1/users/:id — quando false, os endpoints desta seção retornam 400.

POST /v1/users/:id/access-block

Body

{
  "blocked": true
}

Resposta (200)

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "isAccessBlocked": true,
  "accessBlockedAt": "2026-06-20T16:30:00.000Z",
  "devicesUpdated": 2
}

:::tip
Aviso: Diferença para DELETE /v1/users/:id:
POST /v1/users/:id/access-block é a forma reversível e controlada — pode ser desfeita com blocked: false. DELETE /v1/users/:id é o bloqueio total, sem reativação automática.
:::

POST /v1/users/:id/access-sync

Força a sincronização do estado de acesso do usuário com todos os dispositivos da unidade.

Resposta (200)

{
  "id": "770e8400-e29b-41d4-a716-446655440000",
  "devicesUpdated": 2
}

Conceitos importantes

Pessoa é global; o vínculo com a unidade é separado

O ID retornado em /v1/users é a pessoa (id global). O vínculo com a unidade contém as roles (permissões), turnos e disciplinas que a pessoa tem naquela unidade.

Uma mesma pessoa pode ser staff em uma unidade e responsável em outra. O isMasterAccount é uma flag global que indica se a pessoa é administradora da instituição inteira (acesso total).

Responsável não é um tipo especial de usuário

Um "responsável" é simplesmente uma pessoa referenciada como guardian de um estudante matriculado na unidade. A API não cria nem gerencia esse vínculo de forma isolada — isso é feito via POST /v1/students/:id/guardian ou implicitamente ao criar um estudante.

Bloqueio de acesso é global

O bloqueio afeta a pessoa em todas as unidades da plataforma. É uma medida de segurança drástica (LGPD, mau comportamento, etc).