Skip to content

Visão Geral

🔐 Perfis de acesso

Perfis de acesso são configurações que determinam o que cada usuário pode ou não fazer dentro do sistema.

Cada perfil agrupa escopos de permissões bem definidos. Entre os mais comuns estão:

  • Visualização, que permite acesso a endpoints de listagem e busca
  • Escrita, responsável por ações como criar, editar ou excluir informações

    • Essas permissões regulam o acesso a módulos, rotas e funcionalidades, garantindo que cada usuário interaja apenas com áreas compatíveis com sua função.

    Como resultado, o sistema mantém segurança, organização e rastreabilidade das ações, pontos essenciais para o controle operacional e para a observabilidade 🔎.

    Escopos de permissão

    Os escopos de permissão funcionam como o mecanismo central de controle de acesso da API.

    Cada escopo representa uma permissão específica e é validado por meio de middlewares, responsáveis por interpretar os códigos de escopo associados ao perfil do usuário.

    Ao tentar acessar um módulo ou uma rota, o middleware verifica se o usuário possui o escopo necessário. Caso contrário, a ação é automaticamente bloqueada.

    Por isso, é fundamental que cada perfil tenha seus escopos corretamente vinculados ⚠️.

    Sem essa associação, o usuário não terá autorização para executar operações dentro do painel, mesmo que esteja autenticado.

    🔁 Perfil → Escopos → Middleware → Acesso à rota

    Políticas comerciais

    A política comercial é uma estrutura que define como produtos e canais de venda se comportam dentro da plataforma.

    Cada política pode conter informações próprias, como descrição, preço, URL e associações com lojas ou canais específicos.

    Isso permite que um mesmo produto exista em versões diferentes, de acordo com a política aplicada.

    No contexto de perfis de acesso, as políticas comerciais também atuam como um limitador de visibilidade e operação 🔐.

    Um perfil pode ter acesso a todas as políticas ou ser restrito a apenas algumas delas.

    Com isso, o usuário passa a visualizar e gerenciar somente os dados vinculados às políticas permitidas pelo seu perfil, garantindo controle, organização e segurança dentro do painel 🔎.

    Notas e Considerações

  • Se atente a limitação de dados sensíveis, ativar o campo possibilita que o usuário possa solicitar a visualização de informações
  • Se atente também a políticas comerciais, caso nenhuma seja informada o usuário terá total acesso a todas as políticas

Detalhes de perfil de usuário

GET /auth/profile/{profileId}

Busca os detalhes de um perfil de usuário por id

Descrição

Retorna os detalhes de um perfil de acesso a partir do ID do perfil.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação do usuário

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
profileIdintegerSimID do perfil do usuário

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/profile/{profileId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 3,
5    "storeId": 1,
6    "name": "OperadorTeste2",
7    "sensitiveDataPermission": true,
8    "tradePolicyLimitation": true,
9    "tradePolicies": [
10      1,
11      2,
12      4
13    ],
14    "createdAt": "2024-07-19 13:23:24",
15    "updatedAt": "2024-08-27 18:35:30",
16    "scopes": [
17      "DASHBOARD_READ"
18    ]
19  }
20}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_AUTH_PROFILE_NOT_FOUND404O perfil solicitado não existe
```

Listagem de mapeamento de perfis de usuário

GET /auth/profile/all

Listagem de mapeamento de perfis de usuário

Descrição

Listagem simples para mapear perfis de usuário, geralmente utilizada para facilitar lógicas no frontend.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/admin/auth/profile/all \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

Esta rota retorna dados no padrão chave-valor, utilizando o ID do perfil como índice e o nome como valor.

1{
2  "status": true,
3  "data": {
4    "1": "admin master",
5    "2": "admin",
6    "3": "operador"
7  }
8}

Listagem de Perfis de usuários

Endpoint

GET /auth/profile

Lista todos os perfis de acesso dos usuários da loja

Descrição

Lista todos os perfis de acesso dos usuários da loja, utilizada para controle e associação de permissões.

Parâmetros de Query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do usuário

Campos de Condição Disponíveis

CampoTipoDescrição
namestringBuscar por nome do perfil de usuário
createdAtstringFiltrar por data de cadastro do perfil
updatedAtstringFiltrar por data de atualização do perfil
sensitiveDataPermissionboolFiltrar por usuários com visualização a dados sensíveis permitida
tradePolicyIdintFiltrar por id de política comercial

Campos de Ordenação Disponíveis

CampoDescrição
idID do perfil
nameNome do perfil
createdAtData de criação do perfil
updatedAtData de atualização do perfil

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/auth/profile \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "name": "Operador1",
8        "sensitiveDataPermission": true,
9        "tradePolicyLimitation": true,
10        "tradePolicies": [],
11        "createdAt": "2024-07-19 13:23:24",
12        "updatedAt": "2024-08-27 18:35:30",
13        "scopes": []
14      },
15      {
16        "id": 2,
17        "name": "Operador2",
18        "sensitiveDataPermission": true,
19        "tradePolicyLimitation": true,
20        "tradePolicies": [
21          1,
22          2,
23          3
24        ],
25        "createdAt": "2024-08-23 19:44:28",
26        "updatedAt": "2024-08-27 18:25:05",
27        "scopes": []
28      },
29      {
30        "id": 3,
31        "name": "Operador3",
32        "sensitiveDataPermission": true,
33        "tradePolicyLimitation": true,
34        "tradePolicies": [],
35        "createdAt": "2024-08-27 18:38:10",
36        "updatedAt": "2024-08-27 18:38:10",
37        "scopes": []
38      }
39    ],
40    "pagination": {
41      "limit": 10,
42      "offset": 0,
43      "pages": 3,
44      "registers": 23
45    }
46  }
47}

Cadastro de Perfil de Usuário

POST /auth/profile

Cria/Atualiza um novo perfil de usuário

Descrição

Endpoint responsável por cadastrar ou atualizar um perfil de acesso.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typeapplication/jsonTipo de conteúdo
AuthorizationBearer {token}Token de autenticação de usuário

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
idint❌Identificador do perfil, só deve ser informado para atualização
namestring✅Nome do perfil (max 50 caracteres)
sensitiveDataPermissionbool✅Determina se o usuário poderá solicita visualização de dados sensíveis de uma página
tradePolicyLimitationbool✅Determina se o usuário poderá ver/alterar itens de todas as políticas comerciais. Caso haja limitação, deve ser informado quais políticas são permitidas no array de tradePolicies
tradePoliciesarray❔Políticas comerciais que devem ser vinculadas/desvinculadas, se torna obrigatório quando há tradePolicyLimitation ativo, caso contrário não deve ser informado
tradePolicies.*.{tradePolicyId}bool✅Tem como índice o id da política comercial e o valor booleano determina se deve vincular ou desvincular

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/auth/profile/ \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "id": 123,
6    "name":"Operador",
7    "sensitiveDataPermission":true,
8    "tradePolicyLimitation":true,
9    "tradePolicies": {
10      "1":true,
11      "2":true,
12      "3":true
13    }
14  }'

✅ Resposta de Sucesso

1{
2  "id": 123,
3  "storeId": 123,
4  "name": "Operador",
5  "sensitiveDataPermission": true,
6  "tradePolicyLimitation": true,
7  "tradePolicies": [
8    1,
9    2,
10    3
11  ],
12  "createdAt": "2025-11-28 20:18:07",
13  "updatedAt": "2025-11-28 20:18:07",
14  "scopes": []
15}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_CORE_INVALID_TRADE_POLICY_ID403Os ids de política comercial não são permitidos.
UAPPI_AUTH_PROFILE_NOT_FOUND404O perfil solicitado não foi encontrado

Exclui Perfil de Usuário

DELETE /auth/profile/{profileId}

Remove um perfil de usuário

Descrição

Endpoint responsável por excluir um perfil de acesso da loja a partir do seu ID.

O perfil não poderá ser removido caso esteja em uso.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação de usuário

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
profileIdintegerSimID do perfil de usuário

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/auth/profile/{profileId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "id": 123,
3  "name": "Operador",
4  "createdAt": "2024-07-19 13:26:00",
5  "updatedAt": "2024-07-19 13:26:00"
6}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código InternoCódigo HttpDescrição
UAPPI_AUTH_PROFILE_IN_USE403O perfil solicitado está em uso
UAPPI_AUTH_PROFILE_NOT_FOUND404O perfil solicitado não existe

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;