Aparência
Gestão — Usuários da Conta
GET /access/manager/users
Lista os usuários vinculados à conta.
Query params:
| Parâmetro | Tipo | Descrição |
|---|---|---|
search | string | Busca por nome, e-mail ou documento |
status | string | Status do usuário |
role | string | Filtrar por papel (ex: admin, operator) |
per_page | integer | Padrão: 100 |
page | integer | Página atual |
Response 200: Lista paginada de usuários com roles e permissões.
POST /access/manager/users
Adiciona um novo usuário à conta.
Body:
json
{
"name": "Ana Silva",
"email": "ana@empresa.com",
"document": "11122233344",
"phone": "11988887777",
"password": "senha123",
"role": 2,
"permissions": [1, 3, 5]
}| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
name | string | Sim | máx. 30 caracteres |
email | string | Sim | único no sistema |
document | string | Sim | único no sistema |
password | string | Condicional | mín. 5 caracteres; obrigatório se não for role API |
role | integer | Sim | ID de role existente |
permissions | array | Não | IDs de permissões adicionais |
Response 200:
json
{
"data": {
"user": { "id": 10, "name": "Ana Silva", "email": "ana@empresa.com" },
"roles": [ { "id": 2, "name": "operator" } ],
"permissions": [ ... ]
},
"message": "Usuário criado com sucesso!"
}GET /access/manager/users/{id}
Retorna os detalhes de um usuário da conta.
Query params:
| Parâmetro | Tipo | Descrição |
|---|---|---|
include_boletos | boolean | Incluir boletos do usuário |
include_pixes | boolean | Incluir Pix do usuário |
include_charges | boolean | Incluir cobranças do usuário |
PUT /access/manager/users/{id}
Atualiza um usuário da conta. Todos os campos são opcionais; os ausentes mantêm o valor atual.
{id}é o id do vínculo usuário↔conta (data.idda listagem), o mesmo usado emGETeDELETE, não odata.user.id. Vínculo de outra conta:404.
json
{
"name": "Ana Costa",
"email": "ana.costa@empresa.com",
"document": "11122233344",
"phone": "11977776666",
"password": "nova-senha",
"role": 3,
"status": 1
}| Campo | Regras |
|---|---|
name | até 30 caracteres |
email, document | únicos entre os usuários; manter os do próprio usuário é aceito |
password | mín. 6 caracteres |
role | id de um papel existente (/access/manager/guard/roles) |
status | 1 ou 0 |
Corrigido em 03/10/2026: antes, o
updatebuscava o usuário pelo{id}como se fosseusers.id, e não o id do vínculo. A edição podia alterar outro usuário da mesma conta ou responder404. Além disso, qualquer edição respondia422:roleexigia ser o nome e um inteiro ao mesmo tempo, e a unicidade de e-mail e documento não ignorava o próprio usuário.
DELETE /access/manager/users/{id}
Remove um usuário da conta.
Erros:
| Código | Descrição |
|---|---|
| 422 | Usuário não pode remover a si mesmo |
| 404 | Usuário não encontrado na conta |
Papéis e permissões
Cada função tem a sua permissão (App\Enums\PortalPermission, 26 chaves) e a API recusa com 403 quem não tem a permissão da rota (middleware permission.any, que aceita qualquer uma das permissões listadas):
json
{ "message": "Seu usuário não tem permissão para esta ação. Peça ao administrador da conta.", "required_permissions": ["send_pix"] }| Grupo | Permissões |
|---|---|
| Saldo e extrato | view_balance, view_extract, generate_extract, view_transactions, view_reports |
| Pix | send_pix, receive_pix (QR Code), view_pix_history, view_pix_keys, manage_pix_keys |
| TED | send_ted, view_ted |
| Pagamento de boletos | pay_boleto, view_boleto_payments |
| Cobranças | view_charges, create_charges, edit_charges, delete_charges (cancelar/excluir) |
| Clientes | view_clients, manage_clients |
| Conta | view_profile, manage_config (dados, endereço e troca de contato da conta), manage_pin, manage_users, manage_api (tokens e webhooks) |
Sem permissão: GET /access/auth/me, GET /access/account, GET /access/accounts, o próprio perfil (/access/auth/edit), a verificação em duas etapas do usuário, notificações, listas fixas (/enums/*) e GET /consolidation/transaction-types.
Papéis por tipo de conta
Os papéis ficam em App\Enums\AccountRole. roles.label é o nome mostrado e roles.account_type diz onde o papel vale: pj (conta com CNPJ), pf (conta com CPF).
| Conta | Papel (name → label) | Permissões |
|---|---|---|
| PJ | pj_administrador → Administrador | todas |
| PJ | pj_financeiro → Financeiro | todas menos manage_users e manage_api |
| PJ | pj_operador_cobrancas → Operador de cobranças | cobranças, clientes, receive_pix, view_profile (não tira dinheiro da conta) |
| PJ | pj_consulta → Consulta | só ver: saldo, extrato, transações, relatórios, cobranças, clientes, Pix, TED e boletos |
| PJ | pj_integracao → Integração | manage_api, view_profile |
| PF | pf_titular → Titular | todas menos manage_users e manage_api |
| PF | pf_consulta → Consulta | view_balance, view_extract, view_transactions, view_charges, view_profile |
| — | API → Usuário de API (técnico) | operacionais (Pix, TED, boletos, cobranças, clientes, saldo, extrato), sem manage_users, manage_api, manage_config e manage_pin |
- Dono da conta: recebe
pj_administrador(CNPJ) oupf_titular(CPF) ao ser vinculado sem papel (inclusive na abertura de conta). - Atribuir papel (
POST/PUT /access/manager/users): só papéis do tipo da conta ativa; outro tipo, o papelAPIou papéis antigos →422. GET /access/auth/me:permissionstraz as permissões efetivas (papel + diretas);roletrazlabeleaccount_type.- Seeder (
php artisan db:seed --class=PermissionsSeeder): idempotente e aditivo. - Instalação nova: os papéis e as permissões são criados pelo
PermissionsSeeder(php artisan db:seed). A conversão dos papéis antigos (migration de 17/10/2026) saiu na consolidação das migrations de 17/11/2026.
GET /access/manager/guard/roles
Papéis que podem ser escolhidos na conta ativa (os do tipo da conta: PJ ou PF), com label, description e as permissões. Exige manage_users. Paginação padrão do Laravel.
GET /access/manager/guard/permissions
Catálogo de permissões do portal, com rótulo e grupo.
json
{
"code": 200,
"success": true,
"data": [
{ "id": 1, "name": "view_charges", "label": "Ver cobranças", "group": "Cobranças" },
{ "id": 2, "name": "create_charges", "label": "Criar cobranças", "group": "Cobranças" }
],
"message": "Permissões do portal"
}id vem null para uma permissão do catálogo que ainda não foi criada no banco (seeder não executado).