Aparência
Backoffice
O grupo /backoffice (routes/groups/api_backoffice.php) alimenta o painel administrativo interno da FastGivr (fastgivr-backoffice). Ele dá uma visão entre contas: dashboard, contas, usuários, clientes, cobranças, transações, logs do portal, webhooks recebidos e aberturas de conta.
Acesso restrito a operadores
Desde 24/10/2026, todas as rotas /backoffice/* exigem o papel Backoffice. Um JWT válido de usuário do portal ou do app não basta. Até essa data, qualquer usuário autenticado acessava essas rotas.
Controle de acesso
| Situação | Resposta |
|---|---|
| Sem token, ou token inválido | 401 |
User sem o papel Backoffice | 403 |
User só com papel de conta (Administrador da Conta, Gestor da Conta…) | 403 |
Token de API (POST /access/account/get-token), cujo usuário de API não tem o papel | 403 |
User com o papel Backoffice, logado no painel (device_name: dashboard) ou com token do próprio User | acesso liberado |
Corpo do 403:
json
{ "message": "Acesso restrito aos operadores do backoffice." }Como funciona
Middleware:
App\Http\Middleware\EnsureBackofficeOperator, com aliasbackofficeregistrado embootstrap/app.php. Ele se aplica a todo o grupo:phpRoute::middleware(['auth:api,sanctum', 'backoffice'])->group(function () { /* ... */ });Login: o painel faz login com
device_name: dashboard, e esse JWT é doUserAccountvinculado, não doUser. O middleware resolve oUserdesseUserAccount($userAccount->user) e confere o papel nele.Papel: é um papel Spatie chamado
Backoffice, no guardapi. Ele é atribuído direto ao usuário (model_has_rolescommodel_type = App\Models\User), e não a um vínculo com conta (UserAccount). Por isso os papéis de conta não dão acesso.Banco: nenhuma migration é necessária. O papel usa as tabelas
rolesemodel_has_roles, que já existem, e é criado na primeira vez que o comando abaixo roda.
Gerenciar operadores
bash
# Conceder acesso (cria o papel se ainda não existir)
php artisan backoffice:operator operador@fastgivr.com.br
# Remover acesso
php artisan backoffice:operator operador@fastgivr.com.br --removeO comando falha (código de saída 1) se o e-mail não existir em users. O operador precisa de um usuário comum, e o login no backoffice continua sendo POST /access/auth/login.
Antes do deploy
Rode backoffice:operator para cada operador atual. Sem o papel, todos passam a receber 403 no painel.
Rollback: remova 'backoffice' do Route::middleware em routes/groups/api_backoffice.php.
Endpoints
Todos ficam sob /backoffice e exigem Authorization: Bearer {token} de um operador.
| Área | Método e rota | Função |
|---|---|---|
| Dashboard | GET dashboard | Indicadores gerais |
| Cobranças | GET charges, GET charges/{id}, GET reports/charges | Cobranças de todas as contas |
| Usuários | GET users, GET users/{id}, GET reports/users | Usuários |
| Contas | GET accounts, GET accounts/{id}, GET accounts/{id}/balance, GET accounts/{id}/balance-evolution, GET accounts/{id}/charges-report, PUT/PATCH accounts/{id}, GET reports/accounts | Contas, saldo, evolução e edição (status, telefone, endereço, taxas e limites) |
| Clientes | GET clients, GET clients/{id}, GET reports/clients | Clientes (pagadores) |
| Transações | GET transactions, GET transactions/{id}, PUT/PATCH transactions/{id}, DELETE transactions/{id} | Extrato entre contas, edição e exclusão |
| Logs do portal | GET logs, GET logs/{id} | Auditoria, sistema e API, com dados mascarados |
| Webhooks | GET webhooks, GET webhooks/{id} | Webhooks recebidos dos bancos, só leitura, com o payload mascarado |
| Aberturas de conta | GET registers, GET registers/{id}, PUT/PATCH registers/{id}/reject, PUT/PATCH registers/{id}/documents/{documentId}/reject, POST registers/{id}/phone-verification/resend, POST registers/{id}/approve, POST registers/{id}/fiducia, GET registers/{id}/account/status, POST registers/{id}/confirm-account | Solicitações feitas no fastgivr-register (ver Revisão e Aprovação) |
Testes
tests/Feature/Backoffice/BackofficeAccessTest.php verifica que:
- toda rota
backoffice/*tem o middleware; - usuário sem o papel e usuário com papel de conta recebem
403; - sem login a resposta é
401; - o operador tem acesso, inclusive logado como o painel (
POST /access/auth/logincomdevice_name: dashboard); - um token de
UserAccountsegue o papel doUserdele; - o comando concede e remove o papel.
BackofficeWebhooksTest e BackofficeLogsTest cobrem as rotas de webhooks e de logs, usando um operador.