UC-001: Login e Obtenção de Token
Status: EM REVISÃO Data: 2026-04-29 Domínio: platform (auth) Ator: Aluno (ou qualquer Perfil do Sistema) Terms: API REST HÉLICO, Permissão, Perfil do Sistema
Contexto
O Frontend (NextJS) precisa de um wstoken para consumir a API REST HÉLICO. Existem duas opções de login:
Opção A: Login Nativo Moodle
Endpoint padrão do Moodle, usado pelo App Moodle e integrações nativas.
POST /login/token.php
Content-Type: application/x-www-form-urlencoded
username=aluno@email.com
&password=senha123
&service=moodle_mobile_appResposta (sucesso):
{
"token": "abc123def456...",
"privatetoken": "xyz789..."
}Resposta (erro):
{
"error": "Invalid login, please try again",
"errorcode": "invalidlogin"
}Notas:
servicedeve sermoodle_mobile_app(definido emplatform_extension.php)tokenretornado é owstokenusado em todas as chamadas subsequentes- Não retorna informações do usuário — Frontend precisa chamar
/platform/meem seguida
Opção B: Login via MIDDAG
Endpoint do framework MIDDAG. Retorna wstoken + dados básicos do usuário.
POST /local/middag/api/auth/login
Content-Type: application/json
{
"username": "aluno@email.com",
"password": "senha123"
}Resposta (sucesso):
{
"token": "abc123def456...",
"user": {
"id": 42,
"fullname": "Maria Silva",
"email": "aluno@email.com",
"avatar_url": "https://..."
}
}Notas:
- MIDDAG retorna
wstoken+ userinfo equivalente a/me - MIDDAG não retorna dados específicos da HÉLICO (inscrições, onboarding, etc.)
- Dados HÉLICO vêm de endpoints HÉLICO (ver UC-002: Inscrições do Aluno)
Uso do token nas chamadas seguintes
Após obter o wstoken, o Frontend o envia em todas as requisições:
Authorization: Bearer {wstoken}Ou via query parameter (alternativa):
GET /local/middag/helico/api/v1/platform/enrolments?wstoken={token}Fluxo pós-login
Login (A ou B)
│
├── Token obtido
│
├── Se Opção A: GET /platform/me (obter dados do usuário)
│ Se Opção B: user já veio na resposta
│
└── GET /platform/enrolments?status=active (ver UC-002: Inscrições do Aluno)
│
├── Sem inscrições → tela de catálogo/aguardando
├── Com inscrição, onboarding pendente → fluxo de Onboarding (ver UC-003)
└── Com inscrição, onboarding completo → Área do AlunoErros esperados
| HTTP | Código | Situação |
|---|---|---|
| 401 | invalidlogin |
Credenciais inválidas |
| 403 | api_disabled |
API desabilitada em configuração |
| 429 | ratelimited |
Muitas tentativas de login |
Decisões
- D-01: Login Moodle nativo (A) continua como opção para compatibilidade com App Moodle
- D-02: Login MIDDAG (B) é a opção preferencial para o Frontend HÉLICO
- D-03: MIDDAG retorna wstoken + user info; dados de domínio HÉLICO ficam em endpoints HÉLICO
- D-04: O
servicepara web service Moodle émoodle_mobile_app