Autenticação
Status: EM REVISÃO (2026-05-04)
Contratos consolidados a partir de UC-001 — Login e Obtenção de Token. Login social via MIDDAG documentado em modo doc-first: o contrato abaixo descreve a resposta esperada; a entrega do
wstokenno payload do MIDDAG está em implementação (B-pend-1).
Termos: API REST HÉLICO, Método de Login, Permissão, Perfil do Sistema.
Visão geral
+------------------+
| Frontend NextJS |
+--------+---------+
| tipo de login?
+-----+-----+
| |
v v
email+senha social/SSO (Google, ...)
| |
v v
+----------------------------------+ +-------------------------------------+
| Cenário 1: Moodle nativo | | Cenário 2: MIDDAG (social/SSO) |
| POST /login/token.php | | POST /local/middag/api/auth/login |
| ?service=moodle_mobile_app | | JSON {provider, code|idtoken} |
| form: username, password | | |
+--------+-------------------------+ +-----------+-------------------------+
| |
v v
200 { token, privatetoken } 200 { token, user{id, fullname, email, ...} }
| |
+-----------------+-----------------------+
v
+------------------------------+
| Authorization: Bearer <token>|
| OR query: ?wstoken=<token> |
+--------------+---------------+
v
+-------------------------------+
| /local/helico/ajax.php/ |
| api/v1/platform/* |
| /local/middag/api/* |
+-------------------------------+A Plataforma HÉLICO suporta dois Métodos de Login complementares: o nativo
do Moodle (credenciais do usuário) e o do MIDDAG (provedores externos via SSO).
Ambos resultam num wstoken que carrega a sessão para chamadas subsequentes.
Cenário 1 — Login Email/Senha (Moodle nativo)
Usar quando o cliente coleta credenciais diretamente. Padrão para web app HÉLICO, mobile e qualquer integração que controle username + password.
Request
POST /login/token.php
Content-Type: application/x-www-form-urlencoded| Campo | Tipo | Obrigatório | Valor |
|---|---|---|---|
username |
string | Sim | Email ou username Moodle do usuário |
password |
string | Sim | Senha em texto puro (TLS obrigatório) |
service |
string | Sim | moodle_mobile_app |
Response 200
{
"token": "abc123def456...",
"privatetoken": "xyz789..."
}| Campo | Tipo | Descrição |
|---|---|---|
token |
string | wstoken para usar em chamadas subsequentes da API REST HÉLICO |
privatetoken |
string | Token de sessão privado Moodle (uso interno; Frontend pode ignorar) |
Não retorna informações do usuário. Para obter dados do usuário, chamar
GET /api/v1/platform/me em seguida (ver me.md).
Response 4xx
| HTTP | Código errorcode |
Causa | Ação Frontend |
|---|---|---|---|
| 200 | invalidlogin |
Credenciais erradas | Mostrar erro, permitir retry |
| 200 | usernotconfirmed |
Email não confirmado | Pedir confirmação por email |
| 200 | userdeleted |
Usuário removido | Mostrar suporte |
| 200 | usersuspended |
Conta suspensa | Mostrar suporte |
| 403 | webservicesdisabled |
Web services desativado no Moodle | Erro infra (ops) |
| 403 | webserviceusernotenabled |
Service moodle_mobile_app não habilitado |
Erro infra (ops) |
| 429 | ratelimited |
Muitas tentativas de login | Backoff exponencial |
Erros 200 com
errorcodeO Moodle retorna HTTP 200 mesmo em falhas de autenticação. O cliente DEVE inspecionar a presença de
errorcodeno payload — se presente, a requisição falhou independentemente do status HTTP.
Exemplo cURL
curl -X POST 'https://helico.com.br/login/token.php' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'username=aluno@exemplo.com&password=Senha%40123&service=moodle_mobile_app'Cenário 2 — Login Social (MIDDAG)
Usar para SSO (Google, Microsoft, …). Frontend não coleta credenciais; usa
fluxo OAuth2 do provedor e troca o code ou idtoken por um wstoken
HÉLICO via MIDDAG.
Doc-first (CQ3)
Este contrato descreve a resposta esperada do MIDDAG. A inclusão do
tokenno payload é a entrega de B-pend-1 (em desenvolvimento). Até sua conclusão, o Frontend pode precisar combinar o callback OAuth com uma chamada subsequente aPOST /login/token.phpou similar — o contrato vigente substituirá esse workaround tão logo a implementação suba.
Request
POST /local/middag/api/auth/login
Content-Type: application/json{
"provider": "google",
"code": "4/0AdQt8q...",
"redirect_uri": "https://helico.com.br/auth/callback"
}| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
provider |
string | Sim | Identificador do provedor SSO (google, microsoft, …) |
code |
string | Condicional | Authorization code OAuth2 (fluxo code flow). Mutex com idtoken. |
idtoken |
string | Condicional | ID Token JWT (fluxo implicit/PKCE). Mutex com code. |
redirect_uri |
string | Sim em code | URI registrada no provedor; necessária para validação |
Response 200
{
"token": "abc123def456...",
"user": {
"id": 42,
"fullname": "Maria Silva",
"email": "maria@exemplo.com",
"avatar_url": "https://helico.com.br/avatar/42.jpg"
}
}| Campo | Tipo | Descrição |
|---|---|---|
token |
string | wstoken HÉLICO (idêntico ao do Cenário 1) |
user.id |
integer | ID Moodle do usuário |
user.fullname |
string | Nome completo |
user.email |
string | Email primário |
user.avatar_url |
string | URL absoluta do avatar do usuário |
Diferente do Cenário 1, o MIDDAG retorna user info na resposta — Frontend
pode pular a chamada a /api/v1/platform/me no fluxo pós-login.
Response 4xx
| HTTP | error |
Causa |
|---|---|---|
| 400 | invalid_provider |
provider desconhecido |
| 400 | missing_credential |
Nem code nem idtoken informados |
| 401 | provider_token_invalid |
code/idtoken rejeitado pelo provedor SSO |
| 403 | email_not_authorized |
Email do provedor não tem usuário Moodle |
| 429 | ratelimited |
Muitas tentativas |
Exemplo cURL
curl -X POST 'https://helico.com.br/local/middag/api/auth/login' \
-H 'Content-Type: application/json' \
-d '{
"provider": "google",
"code": "4/0AdQt8q...",
"redirect_uri": "https://helico.com.br/auth/callback"
}'Uso do wstoken nas requisições
Após obter o wstoken, o cliente envia em todas as chamadas a
/api/v1/platform/* e /local/middag/api/*. As duas formas são
equivalentes do ponto de vista do backend; o cliente escolhe baseado em
contexto.
Forma 1 — Header Authorization: Bearer
GET /local/helico/ajax.php/api/v1/platform/me
Authorization: Bearer abc123def456...Padrão recomendado para chamadas XHR/fetch do Frontend. Não vaza em logs
de servidor, histórico de browser, header Referer.
Forma 2 — Query parameter ?wstoken=
GET /local/helico/ajax.php/api/v1/platform/me?wstoken=abc123def456...Útil quando o cliente não pode controlar headers — download direto via
<a href>, iframe legado, EventSource sem proxy, link compartilhado.
Tradeoffs de segurança
Token em query string aparece em access logs do servidor, no histórico do browser e potencialmente no header
Refererde navegação subsequente. Usar somente quando a Forma 1 for inviável e o canal estiver protegido por TLS.
Polling assíncrono pós-onboarding {#polling}
Após o cliente submeter o Onboarding (último step), o Plano do Aluno é
criado em background. A resposta de POST /api/v1/platform/onboarding/{enrolment_id}/submit
retorna student_plan = { id: null, status: "creating" }. O Frontend
polleia GET /api/v1/platform/enrolments até student_plan.id aparecer.
Contrato de polling (P1)
| Regra | Valor |
|---|---|
| Intervalo inicial | 2 segundos |
| Backoff | Exponencial (×1.5), até teto de 30 segundos |
| Tentativas máximas | 60 (~5–10 min totais) |
| Servidor: rate limit por usuário | 30 req/min em /api/v1/platform/enrolments |
Estados possíveis de student_plan:
status |
id |
Significado | Próxima ação Frontend |
|---|---|---|---|
creating |
null |
Handler async em execução | Continuar polling |
active |
integer | Plano criado com sucesso | Redirecionar para Roteiro |
failed |
null |
Handler async falhou (T3) | Mostrar erro + botão “Tentar de novo” |
Quando status="failed", o response inclui error_message: string com
uma mensagem segura para o usuário. O retry re-emite o onboarding_completed_signal
sem reapresentar o questionário.
Erros gerais (qualquer endpoint autenticado)
| HTTP | error |
Significado |
|---|---|---|
| 401 | unauthorized |
wstoken ausente, inválido ou expirado |
| 403 | forbidden |
Token válido mas sem permissão |
| 404 | not_found |
Recurso não existe ou não pertence ao user |
| 409 | (depende do recurso) | Conflito de estado |
| 422 | validation_error |
Payload inválido. Ver errors[] no body |
| 429 | ratelimited |
Limite de chamadas excedido |
| 500 | internal_error |
Falha não esperada |
Fluxo end-to-end
+------------------+
| 1. Login | -> wstoken
+--------+---------+
|
v
+----------------------------+
| 2. GET /me (se Cenário 1) | -> dados do usuário
+----------------------------+
|
v
+--------------------------------+
| 3. GET /enrolments?status=... |
+--------------------------------+
|
+-----+-----+--------------+--------------------+
| | | |
v v v v
sem inscrição onboarding onboarding completo student_plan.status=failed
(catálogo) pendente (Área do Aluno) (mostrar retry)
|
v
+----+----+
| 4. GET | -> steps do questionário
| /onboar |
| ding/.. |
+----+----+
|
v
+----+----+
| 5. POST | -> {phase_completed, student_plan: {id:null, status:"creating"}}
| /submit |
+----+----+
|
v (polling P1)
+----+----+
| 6. GET | -> aguarda student_plan.id
| /enrol |
| ments |
+---------+
|
v (id aparecer)
Área do Aluno (Roteiro)Pendências externas
| ID | Descrição | Status |
|---|---|---|
| B-pend-1 | MIDDAG /local/middag/api/auth/login retornar wstoken no payload |
Em desenvolvimento |
| B-pend-2 | Async student_plan creation: dead letter / retry / alerta operacional | Backlog |
| TODO-1 | Documentar precedência quando Bearer + ?wstoken= chegam simultâneos |
Backlog (edge case) |
Referências
- UC-001 — Login e Obtenção de Token
- ADR-90 — Domínio Platform: Gateway e Contratos de Tela
- OpenAPI —
openapi.yaml(gerado viacomposer build:openapi) - Postman collection{ :download=“helico-platform.postman_collection.json” } — testes manuais e exemplos
- Plano de melhoria de docs