Skip to content

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çãoResposta
Sem token, ou token inválido401
User sem o papel Backoffice403
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 papel403
User com o papel Backoffice, logado no painel (device_name: dashboard) ou com token do próprio Useracesso liberado

Corpo do 403:

json
{ "message": "Acesso restrito aos operadores do backoffice." }

Como funciona ​

  • Middleware: App\Http\Middleware\EnsureBackofficeOperator, com alias backoffice registrado em bootstrap/app.php. Ele se aplica a todo o grupo:

    php
    Route::middleware(['auth:api,sanctum', 'backoffice'])->group(function () { /* ... */ });
  • Login: o painel faz login com device_name: dashboard, e esse JWT é do UserAccount vinculado, não do User. O middleware resolve o User desse UserAccount ($userAccount->user) e confere o papel nele.

  • Papel: é um papel Spatie chamado Backoffice, no guard api. Ele é atribuído direto ao usuário (model_has_roles com model_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 roles e model_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 --remove

O 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.

ÁreaMétodo e rotaFunção
DashboardGET dashboardIndicadores gerais
CobrançasGET charges, GET charges/{id}, GET reports/chargesCobranças de todas as contas
UsuáriosGET users, GET users/{id}, GET reports/usersUsuários
ContasGET accounts, GET accounts/{id}, GET accounts/{id}/balance, GET accounts/{id}/balance-evolution, GET accounts/{id}/charges-report, PUT/PATCH accounts/{id}, GET reports/accountsContas, saldo, evolução e edição (status, telefone, endereço, taxas e limites)
ClientesGET clients, GET clients/{id}, GET reports/clientsClientes (pagadores)
TransaçõesGET transactions, GET transactions/{id}, PUT/PATCH transactions/{id}, DELETE transactions/{id}Extrato entre contas, edição e exclusão
Logs do portalGET logs, GET logs/{id}Auditoria, sistema e API, com dados mascarados
WebhooksGET webhooks, GET webhooks/{id}Webhooks recebidos dos bancos, só leitura, com o payload mascarado
Aberturas de contaGET 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-accountSolicitaçõ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/login com device_name: dashboard);
  • um token de UserAccount segue o papel do User dele;
  • o comando concede e remove o papel.

BackofficeWebhooksTest e BackofficeLogsTest cobrem as rotas de webhooks e de logs, usando um operador.