Pular para o conteúdo principal

Matriz endpoint → flag

Última revisão contra o código: 19/09/2026.

Matriz viva da API interna (backend/api/**).

Regras:

  • Flag canônica em inglês (users.edit). Alias PT ainda funciona.
  • A UI (data-permission) só esconde controle. A API revalida no servidor.
  • Super-admin tem bypass em backend_permission_user_can().
  • Comercial e Tarefas também exigem tenant_modules (leads / tasks).
  • backend_permission_require() quase não é usado no arquivo do endpoint. A checagem está no service. Código novo deve chamar require no endpoint e no service.

Fonte das famílias: backend/src/services/core/permission_canonical.php.

Convenção​

modulo.acao
modulo.recurso.acao

Autenticação e sessão​

SuperfícieFlagNota
backend/api/auth/login.php, forgot-password.php, reset-password.php—Público + rate limit
backend/api/auth/logout.php, permissoes.php, csrf-token.php, white-label-id.phpsessãoSem flag de negócio
backend/api/health.php—Healthcheck
backend/api/v1/auth/login.phptoken API v1Superfície externa pequena

Catálogo canônico (o que a API deve pedir)​

MóduloFlagsOnde costuma validar
Admin / permissõesadmin.permissions, permissions.manage, permissions.editpermissoes/* + Policy B
Usuáriosusers.view, users.view_all, users.create, users.edit, users.delete, users.approve, users.active, users.referusuarios/*
White Labelwhite_label.view, white_label.view_all, white_label.create, white_label.edit, white_label.delete, white_label.approve, white_label.manage_rateswhite-label/* (CSRF nas mutações)
Dashboarddashboard.view_all, dashboard.view_whitelabel, dashboard.view_own, dashboard.managedashboard/* (top10 usa user_can no endpoint)
Estabelecimentosestablishments.view, establishments.view_all, establishments.create, establishments.edit, establishments.delete, establishments.approve, establishments.change_representative, establishments.link_terminal, establishments.unlink_terminal, establishments.link_plan, establishments.send_compliance, establishments.create_panelestabelecimentos/* (trocar-representante e upload checam no endpoint)
Planosplans.view, plans.view_all, plans.manage, plans.create, plans.edit, plans.delete, plans.link_establishmentplanos/*
Gestão de taxasmanagement.view, management.rates, management.default_ratesgestao-taxas/* (default_rates é platform-only)
Terminaisterminals.view, terminals.view_all, terminals.manage, terminals.create, terminals.create_batch, terminals.edit, terminals.delete, terminals.link_establishment, terminals.link_other_userterminais/*
Transaçõestransactions.view, transactions.view_all, transactions.payment_links, transactions.receivables, transactions.details, transactions.sync, transactions.exporttransacoes/* (exportar-csv no endpoint)
Financeirofinance.view, finance.view_all, finance.commissions, finance.commissions_read, finance.rentalsfinanceiro/* — aluguéis ainda parciais
Compliancecompliance.view, compliance.create, compliance.edit, compliance.delete, compliance.approvecompliance/* (screening/decidir/chat no service)
Documentosdocuments.view, documents.create, documents.edit, documents.delete, documents.archive, documents.finishedmenu + assinaturas
Propostasproposals.view, proposals.view_all, proposals.create, proposals.edit, proposals.delete, proposals.manage, proposals.simulator, proposals.edit_base_ratespropostas/*
Simuladoressimulators.view, simulators.mdr_ratesimulador
Assinaturassubscriptions.view, subscriptions.create, subscriptions.archive, subscriptions.delete, subscriptions.manageassinaturas/*
Comercialcommercial.read + família leads.* (read/create/update/delete/assign/convert/export/import/admin, activities, map, evolution, monitor, stage, visits, proposals, routes, field, funnel, sources, loss_reasons)comercial/* + tenant_modules=leads + CSRF nas mutações
Tarefasfamília tasks.* (read/create/update/delete/assign/admin/block/change_status, steps/documents/flow/ai_summary)tarefas/* + tenant_modules=tasks + CSRF
Storageestablishments.view (ou equivalente de leitura)storage/drive-health.php usa user_can
Contasessão do próprio usuárioconta/* — sem família conta.*

Aliases PT (usuarios.editar, estabelecimentos.trocar_representante, assinaturas.visualizar, …) continuam válidos via backend_permission_expand_keys().

Endpoints que já checam no próprio arquivo​

Poucos (14 de 224). Os demais delegam:

EndpointComo checa
dashboard/top10-estabelecimentos-tpv-mes.phpbackend_permission_user_can
estabelecimentos/trocar-representante.phpbackend_permission_user_can → establishments.change_representative
estabelecimentos/usuarios-trocar-representante.phpbackend_permission_user_can
estabelecimentos/excluir.php, terminais.php, upload-documento.phptemPermissao
estabelecimentos/atualizar-local.php, documento.phpassert no service
comercial/places-search.php, places-import.phpleads.import + contexto plataforma
compliance/processar-pendentes.php, processar-screening.phpassert no service
transacoes/exportar-csv.phptransactions.export
storage/drive-health.phpbackend_permission_user_can

Google Places está implementado (não é mais pendência). O item de menu “Importar Places” está comentado; a página e a API existem.

CSRF​

Cerca de 33/224 endpoints validam CSRF no arquivo (leads, tarefas, white-label, permissões, alguns uploads). Mutações antigas podem estar descobertas — tratar como dívida, não como desenho.

Pendências​

  • Chamar backend_permission_require / require_any no endpoint, não só no service.
  • Fechar CSRF nas mutações restantes.
  • Flag única e explícita para financeiro/alugueis/listar.php.
  • Testes role × flag × escopo × setor.
  • Flags extras de menu (setores.menu.todos, menu.{setor}.read) não estão no catálogo canônico — documentar ou promover.