Testando o Módulo Usuario

Guia completo para testar todas as rotas do módulo no Insomnia, Postman, HTTPie e Thunder Client.

Pré-requisito

Certifique-se de ter rodado php vupi migrate --seed e que o servidor está no ar em http://localhost:3005 (ou a URL do seu servidor). Substitua BASE_URL pela sua URL base em todos os exemplos.

Ferramentas de teste

Escolha a ferramenta de sua preferência. Todos os exemplos abaixo funcionam em qualquer uma delas:

Ferramenta	Tipo	Download
Insomnia	Desktop / Web	`insomnia.rest`
Postman	Desktop / Web	`postman.com`
Thunder Client	Extensão VS Code	Marketplace do VS Code
HTTPie	Terminal	`httpie.io`
curl	Terminal	Já instalado no Linux/macOS

Como configurar o token nas ferramentas

Após fazer login e obter o access_token, configure em todas as requisições autenticadas:
Insomnia/Postman/Thunder Client: Aba Auth → Bearer Token → cole o token.
HTTPie: adicione Authorization:"Bearer SEU_TOKEN" ao comando.
curl: adicione -H "Authorization: Bearer SEU_TOKEN".

Middlewares de segurança nas rotas

O módulo Usuario usa três níveis de proteção. Entender isso é essencial para saber qual token usar em cada teste:

Middleware	O que faz	Quando usar
`AuthHybridMiddleware`	Valida o JWT e injeta o usuário autenticado na requisição	Qualquer rota que exige login
`AdminOnlyMiddleware`	Exige `nivel_acesso = admin_system` no token	Rotas de gerenciamento admin
`RateLimitMiddleware`	Limita requisições por janela de tempo (ex: 5/min no registro)	Automático — não precisa configurar
`CircuitBreakerMiddleware`	Protege o banco de dados em caso de falhas em cascata	Automático — não precisa configurar

Dois tipos de token

Rotas admin exigem um token gerado com JWT_API_SECRET (token de admin_system). Rotas de perfil aceitam qualquer token de usuário autenticado. Se receber 403 Acesso restrito, você está usando o token errado.

Passo 1 — Obter o token de admin

Antes de testar rotas protegidas, faça login com o usuário admin criado pelo seeder. Veja também a seção Middlewares → Como gerar o token JWT_API_SECRET para entender os diferentes tipos de token.

curl / HTTPie

bash

# curl
curl -X POST http://localhost:3005/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","senha":"admin123"}'

# HTTPie
http POST http://localhost:3005/api/auth/login \
  [email protected] senha=admin123

Insomnia / Postman / Thunder Client

json

// Método: POST
// URL: http://localhost:3005/api/auth/login
// Body (JSON):
{
  "email": "[email protected]",
  "senha": "admin123"
}

Resposta esperada (200):

json

{
  "access_token": "eyJ...",   // ← copie este valor para usar nas próximas requisições
  "token_type": "Bearer",
  "expires_in": 900
}

Dica: variável de ambiente nas ferramentas

No Insomnia e Postman, crie uma variável de ambiente TOKEN e salve o access_token nela. Assim você usa {{TOKEN}} em todas as requisições sem precisar colar o token manualmente toda vez.

Registrar novo usuário (POST — público)

Rota: POST /api/registrar — sem autenticação, com rate limit de 5 req/min.

bash

# curl
curl -X POST http://localhost:3005/api/registrar \
  -H "Content-Type: application/json" \
  -d '{"nome_completo":"João Silva","username":"joao.silva","email":"[email protected]","senha":"Senha@123"}'

# HTTPie
http POST http://localhost:3005/api/registrar \
  nome_completo="João Silva" username=joao.silva \
  [email protected] senha=Senha@123

json

// Método: POST  |  URL: http://localhost:3005/api/registrar
// Body (JSON):
{
  "nome_completo": "João Silva",
  "username": "joao.silva",
  "email": "[email protected]",
  "senha": "Senha@123"
}
// Resposta esperada: 201 Created
// {
//   "status": "success",
//   "message": "Usuário criado com sucesso...",
//   "usuario": { "uuid": "...", "nome_completo": "João Silva", ... }
// }

Listar usuários (GET — admin)

Rota: GET /api/usuarios — requer token admin.

bash

# curl
curl http://localhost:3005/api/usuarios \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

# Com paginação e filtro
curl "http://localhost:3005/api/usuarios?pagina=1&por_pagina=10&q=joao" \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

# HTTPie
http GET http://localhost:3005/api/usuarios \
  Authorization:"Bearer SEU_TOKEN_ADMIN"

json

// Método: GET  |  URL: http://localhost:3005/api/usuarios
// Headers: Authorization: Bearer SEU_TOKEN_ADMIN
// Query params opcionais: pagina=1 | por_pagina=20 | q=busca | nivel=admin
// Resposta esperada: 200 OK
// { "status": "success", "usuarios": [...], "total": 2, "total_paginas": 1 }

Buscar usuário por UUID (GET — admin)

Rota: GET /api/usuario/{uuid}

bash

# curl — substitua o UUID pelo retornado no registro
curl http://localhost:3005/api/usuario/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

json

// Método: GET
// URL: http://localhost:3005/api/usuario/550e8400-e29b-41d4-a716-446655440000
// Headers: Authorization: Bearer SEU_TOKEN_ADMIN
// Resposta esperada: 200 OK  |  404 se não encontrado

Atualizar usuário (PUT — admin)

Rota: PUT /api/usuario/atualizar/{uuid}

bash

# curl
curl -X PUT http://localhost:3005/api/usuario/atualizar/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN" \
  -d '{"nome_completo":"João da Silva","nivel_acesso":"admin"}'

json

// Método: PUT
// URL: http://localhost:3005/api/usuario/atualizar/550e8400-e29b-41d4-a716-446655440000
// Headers: Authorization: Bearer SEU_TOKEN_ADMIN
// Body (JSON) — envie apenas os campos que deseja alterar:
{
  "nome_completo": "João da Silva",
  "nivel_acesso": "admin"
}

Desativar / Ativar usuário (PATCH — admin)

Rotas: PATCH /api/usuario/{uuid}/desativar e PATCH /api/usuario/{uuid}/ativar

bash

# Desativar
curl -X PATCH http://localhost:3005/api/usuario/550e8400-e29b-41d4-a716-446655440000/desativar \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

# Ativar novamente
curl -X PATCH http://localhost:3005/api/usuario/550e8400-e29b-41d4-a716-446655440000/ativar \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

json

// Método: PATCH  |  Sem body
// URL desativar: http://localhost:3005/api/usuario/UUID/desativar
// URL ativar:    http://localhost:3005/api/usuario/UUID/ativar
// Headers: Authorization: Bearer SEU_TOKEN_ADMIN
// Resposta esperada: 200 OK  |  { "status": "success", "message": "Usuário desativado." }

Ver perfil próprio (GET — usuário autenticado)

Rota: GET /api/perfil — qualquer usuário logado pode ver seu próprio perfil.

bash

# curl — use o token do usuário (não precisa ser admin)
curl http://localhost:3005/api/perfil \
  -H "Authorization: Bearer SEU_TOKEN_USUARIO"

Atualizar perfil próprio (PUT — usuário autenticado)

Rota: PUT /api/perfil

bash

# curl
curl -X PUT http://localhost:3005/api/perfil \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_USUARIO" \
  -d '{"nome_completo":"João Atualizado","biografia":"Dev PHP"}'

json

// Método: PUT  |  URL: http://localhost:3005/api/perfil
// Headers: Authorization: Bearer SEU_TOKEN_USUARIO
// Body (JSON):
{
  "nome_completo": "João Atualizado",
  "biografia": "Dev PHP"
}

Alterar senha (PUT — usuário autenticado)

Rota: PUT /api/perfil/senha

bash

# curl
curl -X PUT http://localhost:3005/api/perfil/senha \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer SEU_TOKEN_USUARIO" \
  -d '{"senha_atual":"Senha@123","nova_senha":"NovaSenha@456"}'

json

// Método: PUT  |  URL: http://localhost:3005/api/perfil/senha
// Body (JSON):
{
  "senha_atual": "Senha@123",
  "nova_senha": "NovaSenha@456"
}
// Resposta esperada: 200  |  403 se senha_atual incorreta

Perfil público por username (GET — público)

Rota: GET /api/perfil/{username} — sem autenticação.

bash

# curl
curl http://localhost:3005/api/perfil/joao.silva

# HTTPie
http GET http://localhost:3005/api/perfil/joao.silva

Deletar usuário (DELETE — admin)

Rota: DELETE /api/usuario/deletar/{uuid}

bash

# curl
curl -X DELETE http://localhost:3005/api/usuario/deletar/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer SEU_TOKEN_ADMIN"

json

// Método: DELETE
// URL: http://localhost:3005/api/usuario/deletar/550e8400-e29b-41d4-a716-446655440000
// Headers: Authorization: Bearer SEU_TOKEN_ADMIN
// Resposta esperada: 200  |  { "status": "success", "message": "Usuário removido." }

Respostas de erro comuns

Código	Causa	Solução
`401`	Token ausente ou expirado	Faça login novamente e use o novo token
`403`	Token de usuário comum em rota admin	Use o token do admin_system
`404`	UUID não encontrado	Verifique o UUID na listagem
`409`	E-mail ou username já cadastrado	Use dados diferentes no registro
`422`	Dados inválidos (senha fraca, e-mail inválido)	Verifique os campos obrigatórios
`429`	Rate limit atingido (5 registros/min)	Aguarde 1 minuto e tente novamente

Fluxo completo de teste em ordem

text

1. POST /api/auth/login          → obtém token admin
2. POST /api/registrar           → cria usuário de teste (anote o UUID)
3. GET  /api/usuarios            → confirma que aparece na listagem
4. GET  /api/usuario/{uuid}      → busca o usuário criado
5. PUT  /api/usuario/atualizar/{uuid} → atualiza nome
6. PATCH /api/usuario/{uuid}/desativar → desativa
7. PATCH /api/usuario/{uuid}/ativar   → reativa
8. POST /api/auth/login (usuário) → obtém token do usuário comum
9. GET  /api/perfil              → vê o próprio perfil
10. PUT /api/perfil              → atualiza o perfil
11. DELETE /api/usuario/deletar/{uuid} → remove (com token admin)