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 chamarrequireno 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ície | Flag | Nota |
|---|---|---|
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.php | sessão | Sem flag de negócio |
backend/api/health.php | — | Healthcheck |
backend/api/v1/auth/login.php | token API v1 | Superfície externa pequena |
Catálogo canônico (o que a API deve pedir)
| Módulo | Flags | Onde costuma validar |
|---|---|---|
| Admin / permissões | admin.permissions, permissions.manage, permissions.edit | permissoes/* + Policy B |
| Usuários | users.view, users.view_all, users.create, users.edit, users.delete, users.approve, users.active, users.refer | usuarios/* |
| White Label | white_label.view, white_label.view_all, white_label.create, white_label.edit, white_label.delete, white_label.approve, white_label.manage_rates | white-label/* (CSRF nas mutações) |
| Dashboard | dashboard.view_all, dashboard.view_whitelabel, dashboard.view_own, dashboard.manage | dashboard/* (top10 usa user_can no endpoint) |
| Estabelecimentos | establishments.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_panel | estabelecimentos/* (trocar-representante e upload checam no endpoint) |
| Planos | plans.view, plans.view_all, plans.manage, plans.create, plans.edit, plans.delete, plans.link_establishment | planos/* |
| Gestão de taxas | management.view, management.rates, management.default_rates | gestao-taxas/* (default_rates é platform-only) |
| Terminais | terminals.view, terminals.view_all, terminals.manage, terminals.create, terminals.create_batch, terminals.edit, terminals.delete, terminals.link_establishment, terminals.link_other_user | terminais/* |
| Transações | transactions.view, transactions.view_all, transactions.payment_links, transactions.receivables, transactions.details, transactions.sync, transactions.export | transacoes/* (exportar-csv no endpoint) |
| Financeiro | finance.view, finance.view_all, finance.commissions, finance.commissions_read, finance.rentals | financeiro/* — aluguéis ainda parciais |
| Compliance | compliance.view, compliance.create, compliance.edit, compliance.delete, compliance.approve | compliance/* (screening/decidir/chat no service) |
| Documentos | documents.view, documents.create, documents.edit, documents.delete, documents.archive, documents.finished | menu + assinaturas |
| Propostas | proposals.view, proposals.view_all, proposals.create, proposals.edit, proposals.delete, proposals.manage, proposals.simulator, proposals.edit_base_rates | propostas/* |
| Simuladores | simulators.view, simulators.mdr_rate | simulador |
| Assinaturas | subscriptions.view, subscriptions.create, subscriptions.archive, subscriptions.delete, subscriptions.manage | assinaturas/* |
| Comercial | commercial.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 |
| Tarefas | família tasks.* (read/create/update/delete/assign/admin/block/change_status, steps/documents/flow/ai_summary) | tarefas/* + tenant_modules=tasks + CSRF |
| Storage | establishments.view (ou equivalente de leitura) | storage/drive-health.php usa user_can |
| Conta | sessão do próprio usuário | conta/* — 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:
| Endpoint | Como checa |
|---|---|
dashboard/top10-estabelecimentos-tpv-mes.php | backend_permission_user_can |
estabelecimentos/trocar-representante.php | backend_permission_user_can → establishments.change_representative |
estabelecimentos/usuarios-trocar-representante.php | backend_permission_user_can |
estabelecimentos/excluir.php, terminais.php, upload-documento.php | temPermissao |
estabelecimentos/atualizar-local.php, documento.php | assert no service |
comercial/places-search.php, places-import.php | leads.import + contexto plataforma |
compliance/processar-pendentes.php, processar-screening.php | assert no service |
transacoes/exportar-csv.php | transactions.export |
storage/drive-health.php | backend_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_anyno 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.