Conta do administrador
Segundo fator, preferências, privilégios, menus ocultos e bloqueio de IPs do administrador da loja.
Esta seção reúne as rotas em que o administrador da loja cuida da própria conta e da segurança do painel: segundo fator de autenticação (2FA), preferências de tela, a lista de privilégios que ele tem, menus escondidos e o registro de IPs bloqueados. Todas ficam sob /api/v1/admin e só aceitam o token de um administrador.
O login, o refresh e o logout do administrador ficam em Autenticação. Aqui entra o que acontece depois de logado.
Como funciona
O painel decide o que mostrar chamando GET /api/v1/admin/me/privileges logo após o login. A resposta traz a lista de privilégios e dois indicadores:
| Situação do administrador | is_full_admin | is_root | privileges |
|---|---|---|---|
| Dono da loja (marcado como root) | true | true | todos |
| Sem grupo de administrador ativo | true | false | todos |
| Com um ou mais grupos de administrador ativos | false | false | a união dos privilégios dos grupos |
Cada rota administrativa exige um privilégio específico (por exemplo manage_usergroups para o catálogo de privilégios). Quando falta, a resposta é 403 e o corpo diz qual: {"error":"insufficient privileges","required":"manage_usergroups"}. Algumas rotas aceitam qualquer um de uma lista, e então o corpo traz privilege_required_any.
Conceitos importantes
Grupo de usuários e privilégio
Um grupo de usuários (usergroup) do tipo administrador agrupa privilégios. Quem participa de um grupo ativo desse tipo fica restrito a ele. Grupos de cliente e de seller não restringem o administrador.
Módulo
Um módulo é um recurso que a loja liga ou desliga. Rotas de 2FA (two-factor-auth) e de bloqueio de IP (security) respondem 403 com {"error":"module_disabled","module":"security"} quando o módulo está desligado. A leitura GET /api/v1/admin/2fa/status funciona mesmo assim.
Token e personificação
Todas as chamadas levam Authorization: Bearer $TOKEN. Veja Tokens para duração e revogação. Numa sessão de personificação (um administrador atuando como outro usuário), as rotas de 2FA respondem 403 com {"error":"impersonation_blocked","message":"Esta ação requer login direto do usuário."}; a mensagem vem em português do servidor.
Endpoints
| Método | Caminho | Para que serve | Autenticação |
|---|---|---|---|
| GET | /api/v1/admin/2fa/status | Diz se o segundo fator está ligado. | admin |
| POST | /api/v1/admin/2fa/setup | Gera o segredo e o QR code. | admin |
| POST | /api/v1/admin/2fa/confirm | Liga o segundo fator e devolve os códigos de recuperação. | admin |
| POST | /api/v1/admin/2fa/disable | Desliga o segundo fator. | admin |
| GET | /api/v1/admin/me/preferences | Lê as preferências de tela do administrador. | admin |
| PUT | /api/v1/admin/me/preferences | Grava preferências (mescla com as existentes). | admin |
| GET | /api/v1/admin/me/privileges | Lista os privilégios do próprio administrador. | admin |
| GET | /api/v1/admin/me/panel-menus | Lista os menus escondidos para o administrador. | admin |
| GET | /api/v1/admin/privileges | Catálogo de todos os privilégios da loja. | admin |
| POST | /api/v1/admin/privileges/seed-defaults | Completa o catálogo com os privilégios padrão. | admin |
| GET | /api/v1/admin/security/blocked-ips | Lista os IPs bloqueados. | admin |
| POST | /api/v1/admin/security/blocked-ips | Bloqueia um IP ou faixa. | admin |
| GET | /api/v1/admin/security/blocked-ips/{id} | Consulta um bloqueio. | admin |
| DELETE | /api/v1/admin/security/blocked-ips/{id} | Remove um bloqueio. | admin |
| GET | /api/v1/admin/security/check-ip | Pergunta se um IP está bloqueado agora. | admin |
| POST | /api/v1/admin/security/clean-expired | Apaga os bloqueios já vencidos. | admin |
Erros comuns
- Chamar
POST /api/v1/admin/2fa/setupcom o 2FA já ligado. O segredo é substituído e o 2FA fica desligado até você confirmar o novo código. Veja Segundo fator. - Guardar só o segredo do 2FA e perder os códigos de recuperação: eles aparecem uma única vez, na confirmação.
- Esperar que
PUT /api/v1/admin/me/preferencessubstitua tudo: ele mescla só as chaves enviadas. - Tratar um menu escondido como bloqueio de acesso. Quem tem o privilégio continua podendo chamar a rota.
- Enviar
GET /api/v1/admin/security/blocked-ips/abc: um id que não é UUID devolve 500, não 404. - Supor que o bloqueio de IP recusa as requisições sozinho. Veja o aviso em IPs bloqueados.