Skip to content

Usuários

Visão Geral

👨🏻‍🦰 Usuários Humanos

Usuários humanos, no contexto do Uappi, representam tanto administradores do painel quanto lojistas vinculados à plataforma.

Esses usuários são responsáveis pelo gerenciamento operacional da loja, incluindo atividades como:

  • Cadastro e manutenção de produtos;
  • Configuração de informações da loja;
  • Acompanhamento de pedidos;
  • Interação com as demais funcionalidades disponibilizadas pelo sistema.

Cada usuário possui um perfil de acesso específico, que determina suas permissões dentro do painel.

Essas permissões controlam quais módulos, ações e rotas podem ser acessados, garantindo segurança e uma gestão adequada das responsabilidades de cada papel dentro da plataforma.

🤖 Usuários de Integração

Usuários de integração são contas destinadas exclusivamente à comunicação automatizada com o Uappi por meio da API.

Esse tipo de usuário é normalmente utilizado por integrações externas de terceiros, como ERPs, CRMs, hubs e automações em geral, permitindo que sistemas externos executem operações programáticas mediante autenticação via token.

Suas permissões também são determinadas por escopos, porém geralmente limitadas ao necessário para os processos de integração, como sincronização de dados, importação ou exportação de informações.

Notas e Considerações

Para facilitar a comunicação relacionada a este módulo, é importante ter em mente que, ao mencionar “Usuário”, estamos nos referindo ao lojista ou ao administrador do painel.

Listagem de Usuários

GET /auth/users

Endpoint responsável por listar os usuários admins da loja

Descrição

Retorna lista de todos os usuários administradores cadastrados na loja.

Parâmetros de Query

Headers Obrigatórios

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

Campos de Condição Disponíveis

CampoTipoDescrição
idintegerFiltrar por id do usuário
namestringBuscar por nome do usuário
emailstringFiltrar por email
profileIdintegerFiltrar usuários por perfil
activebooleanFiltrar por status
userTypestringTipo do usuário (integração ou humano)

Campos de Ordenação Disponíveis

CampoDescrição
idOrdenar lista por id do usuário
emailOrdenar lista por email
createdAtOrdenar lista por data de criação

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 123,
7        "profileId": 123,
8        "name": "Uappi",
9        "email": "abc123@uappi.store",
10        "userType": "integration",
11        "phone": "+193529252",
12        "image": "",
13        "gender": "undefined",
14        "active": true,
15        "createdAt": "2025-06-06 20:40:34",
16        "lastLoginAt": ""
17      },
18      {
19        "id": 124,
20        "profileId": 124,
21        "name": "João",
22        "email": "joão@uappi.com",
23        "userType": "human",
24        "phone": "+12123451234",
25        "image": "",
26        "gender": "male",
27        "active": true,
28        "createdAt": "2024-07-17 20:38:05",
29        "lastLoginAt": ""
30      },
31    ],
32    "pagination": {
33      "limit": 10,
34      "offset": 0,
35      "pages": 16,
36      "registers": 156
37    }
38  }
39}

Obter Usuário por Id

GET /auth/users/{userId}

Obtém informações completas de um usuário buscando por id

Descrição

Endpoint responsável por buscar um usuário por id e retornar suas informações completas, incluindo:

  • Dados pessoais;
  • Perfil de acesso
  • Escopos de permissão;
  • Integrações configuradas;
  • Histórico de login.

Parâmetros de Query

Headers Obrigatórios

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

Parâmetros da URL

ParâmetroTipoObrigatórioDescrição
userIdintegerSimID único do usuário

Exemplo de Requisição

1curl --request GET \
2  --url {{ MAIN_URL }}/auth/users/{userId} \
3  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "user": {
5      "id": 123,
6      "profileId": 1,
7      "name": "João da Silva",
8      "email": "joao@exemplo.com",
9      "userType": "human",
10      "phone": "+5511999999999",
11      "image": "https://sualoja.com.br/storage/users/123/avatar.jpg",
12      "gender": "masculino",
13      "active": true,
14      "createdAt": "2024-01-15 10:30:00",
15      "lastLoginAt": "2024-08-14 08:45:30"
16    },
17    "profile": {
18      "id": 1,
19      "storeId": 0,
20      "name": "Administrador",
21      "sensitiveDataPermission": false,
22      "tradePolicyLimitation": true,
23      "tradePolicies": [
24        1,
25        2,
26        3,
27        4
28      ],
29      "scopes": [],
30      "createdAt": "2024-01-15 10:30:00",
31      "updatedAt": "2024-01-15 10:30:00"
32    },
33    "scopes": [
34      "USER_READ",
35      "USER_WRITE",
36      "PRODUCT_READ",
37      "PRODUCT_WRITE",
38      "ORDER_READ",
39      "DASHBOARD_ACCESS"
40    ],
41    "integrations": [
42      {
43        "userId": 1,
44        "type": "produto",
45        "integrationMethod": "fila",
46        "active":true,
47        "webhookUrl":"https://sualoja.com.br/webhooks/pagamento/confirmado"
48      }
49    ],
50    "loginHistory": [
51      {
52        "login": "2024-08-14 08:45:30",
53        "status": "sucess"
54      },
55      {
56        "login": "2024-08-13 15:20:15",
57        "status": "sucess"
58      },
59      {
60        "login": "2024-08-12 09:10:45",
61        "status": "error"
62      }
63    ],
64    "documents": [
65      {
66        "hash": "20231017-termos-de-uso-uappi",
67        "html": "https://doc.com.br/termos-de-uso/pt-BR/uappi.html",
68        "htmlContent": "",
69        "pdf": "https://doc.com.br/termos-de-uso/pt-BR/uappi.pdf",
70        "title": "Termos de Uso",
71        "subtitle": "Para utilizar a plataforma Uappi é necessário concordar com nossos termos de uso.",
72        "acceptanceText": "Concordo",
73        "postponementLimit": 3,
74        "date": "2023-10-17",
75        "sign": true
76      }
77    ]
78  }
79}

⚠️ 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_USER_NOT_FOUND404O usuário solicitado não foi encontrado.

Obter Usuário Atual

GET /auth/users/current

Obtém informações completas do usuário autenticado

Descrição

Endpoint responsável por retornar informações completas do usuário atualmente autenticado, incluindo:

  • Dados pessoais;
  • Perfil de acesso;
  • Escopos de permissão;
  • Integrações configuradas;
  • Histórico de login.

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 }}/auth/users/current \
3  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "user": {
5      "id": 123,
6      "profileId": 1,
7      "name": "João da Silva",
8      "email": "joao@exemplo.com",
9      "userType": "human",
10      "phone": "+5511999999999",
11      "image": "https://sualoja.com.br/storage/users/123/avatar.jpg",
12      "gender": "masculino",
13      "active": true,
14      "createdAt": "2024-01-15 10:30:00",
15      "lastLoginAt": "2024-08-14 08:45:30"
16    },
17    "profile": {
18      "id": 1,
19      "storeId": 0,
20      "name": "Administrador",
21      "sensitiveDataPermission": false,
22      "tradePolicyLimitation": true,
23      "tradePolicies": [
24        1,
25        2,
26        3,
27        4
28      ],
29      "scopes": [],
30      "createdAt": "2024-01-15 10:30:00",
31      "updatedAt": "2024-01-15 10:30:00"
32    },
33    "scopes": [
34      "USER_READ",
35      "USER_WRITE",
36      "PRODUCT_READ",
37      "PRODUCT_WRITE",
38      "ORDER_READ",
39      "DASHBOARD_ACCESS"
40    ],
41    "integrations": [
42      {
43        "userId": 1,
44        "type": "produto",
45        "integrationMethod": "fila",
46        "active":true,
47        "webhookUrl":"https://sualoja.com.br/webhooks/pagamento/confirmado"
48      }
49    ],
50    "loginHistory": [
51      {
52        "login": "2024-08-14 08:45:30",
53        "status": "sucess"
54      },
55      {
56        "login": "2024-08-13 15:20:15",
57        "status": "sucess"
58      },
59      {
60        "login": "2024-08-12 09:10:45",
61        "status": "error"
62      }
63    ],
64    "documents": [
65      {
66        "hash": "20231017-termos-de-uso-uappi",
67        "html": "https://doc.com.br/termos-de-uso/pt-BR/uappi.html",
68        "htmlContent": "",
69        "pdf": "https://doc.com.br/termos-de-uso/pt-BR/uappi.pdf",
70        "title": "Termos de Uso",
71        "subtitle": "Para utilizar a plataforma Uappi é necessário concordar com nossos termos de uso.",
72        "acceptanceText": "Concordo",
73        "postponementLimit": 3,
74        "date": "2023-10-17",
75        "sign": true
76      }
77    ]
78  }
79}

Cadastro/Atualização de Usuário

POST /auth/users

Cadastro/Atualização informações completas do usuário autenticado

Descrição

Endpoint responsável por atualizar ou cadastrar as informações completas de um usuário.

Este endpoint possui um comportamento híbrido, servindo tanto para cadastrar quanto para atualizar usuários humanos e de integração.

Importante observar que, para cadastrar um usuário, o campo "id" NÃO DEVE estar presente na requisição.

Por outro lado, caso o objetivo seja atualizar um usuário existente, o campo "id" DEVE estar presente.

Na atualização, envie todos os dados do usuário. Os campos opcionais que não forem enviados ficam vazios.

Usuários Humanos

Usuários humanos são administradores da plataforma, responsáveis pela gestão do sistema por meio do painel administrativo.

O processo de criação segue o fluxo comum, com nome, e-mail e demais informações básicas. No entanto, por motivos de segurança, o administrador responsável pelo cadastro não pode definir a senha do novo usuário.

Após a criação, o sistema envia automaticamente um e-mail de convite ao usuário recém-cadastrado, com um botão, o link e o código para que ele defina sua própria senha. O convite é válido por 60 minutos.

Somente após essa etapa o usuário poderá acessar a plataforma.

Usuários de Integração

Usuários de integração são entidades utilizadas para autenticação e comunicação entre a plataforma e APIs externas.

O processo de cadastro é semelhante ao dos usuários humanos, porém a senha não pode ser informada manualmente.

O e-mail é opcional e, quando informado, é o login da API da integração. Quando não é informado, o sistema gera um e-mail não funcional para esse login.

A senha é gerada pelo sistema e retornada no momento do cadastro, e pode ser visualizada apenas uma única vez.

É essencial armazená-la com segurança. Caso seja perdida, é possível definir uma nova senha pela recuperação de senha, desde que a integração tenha um e-mail válido.

Parâmetros de Query

Headers Obrigatórios

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

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
idintegerSimID do usuário. Apenas para o cenário de atualização
profileIdintegerSimID do perfil de acesso do usuário
userTypestringSimDefine se o usuário é integration ou um usuário admin human. Apenas no cadastro
namestringSimNome completo do usuário (máx. 255 caracteres)
emailstringCondicionalEmail do usuário. Obrigatório para usuários humanos e opcional para integrações (máx. 255 caracteres)
phonestringNãoTelefone do usuário no formato válido
genderstringNãoGênero: male, female, undefined. Se não informado, é gravado undefined
activebooleanSimSe o usuário deve estar ativo
⚠️ IMPORTANTE: o campo userType é proibido em operações de atualização, a fim de preservar a integridade do tipo de usuário.

Exemplo de Requisição

1curl --request POST \
2  --url {{ MAIN_URL }}/auth/users \
3  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...' \
4  --data '{
5    "profileId": 1,
6    "userType": "human",
7    "name": "João da Silva",
8    "email": "joao.silva@exemplo.com",
9    "phone": "+5511999999999",
10    "gender": "male",
11    "active": true
12  }'

✅ Resposta de Sucesso

Response para Usuários Humanos

1{
2  "status": true,
3  "data": {
4    "id": 123,
5    "profileId": 1,
6    "code": "USER001",
7    "name": "João da Silva",
8    "email": "joao.silva@exemplo.com",
9    "userType": "human",
10    "phone": "+5511999999999",
11    "image": null,
12    "gender": "male",
13    "active": true,
14    "createdAt": "2024-01-15 10:30:00",
15    "lastLoginAt": "2024-08-14 08:45:30"
16  }
17}

Response para Usuários de Integração

1{
2  "status": true,
3  "data": {
4    "id": 123,
5    "profileId": 1,
6    "code": "USER001",
7    "name": "João da Silva",
8    "email": "b8437b2@exemplo.com",
9    "userType": "integration",
10    "phone": "+5511999999999",
11    "password": "8gh38g3",
12    "image": null,
13    "gender": "male",
14    "active": true,
15    "createdAt": "2024-01-15 10:30:00",
16    "lastLoginAt": "2024-08-14 08:45:30"
17  }
18}

⚠️ 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_INVALID_PROFILE404O perfil solicitado não foi encontrado.
UAPPI_AUTH_DUPLICATED_EMAIL400O e-mail informado já existe.

Cadastro/Atualização da imagem do usuário

POST /auth/users/{userId}/image

Endpoint responsável por cadastrar ou atualizar a foto de perfil do usuário

Descrição

Endpoint responsável por cadastrar ou atualizar a foto de perfil do usuário.

Parâmetros de query

Headers Obrigatórios

HeaderValorDescrição
Content-Typemultipart/form-dataTipo de conteúdo
AuthorizationBearer {token}Token de autenticação

Parâmetros da URL

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

Parâmetros do Corpo

ParâmetroTipoObrigatórioDescrição
imageimage✅Foto de perfil do usuário (formato: png, jpg, jpeg) (max: 2mb)

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/auth/users/{userId}/image \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --form "file=@filepath"

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": true
4}

⚠️ 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_USER_NOT_FOUND404O usuário solicitado não foi encontrado.

Exclusão da imagem do usuário

DELETE /auth/users/{userId}/image

Endpoint responsável por remover a foto de perfil do usuário

Descrição

Endpoint responsável por remover a foto de perfil do usuário.

Parâmetros de query

Headers Obrigatórios

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

Parâmetros da URL

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

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2	"status": true,
3	"data": true
4}

⚠️ 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_USER_NOT_FOUND404O usuário solicitado não foi encontrado.

Exclusão de usuário

DELETE /auth/users/{userId}

Endpoint responsável pela exclusão de usuários por id

Descrição

Endpoint responsável pela exclusão de um usuário por id.

Parâmetros de query

Headers Obrigatórios

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

Parâmetros da URL

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

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/auth/users/{userId} \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 123,
5    "profileId": 123,
6    "name": "Uappi User",
7    "email": "example.address@uappi.com.br",
8    "userType": "human",
9    "phone": "000000000",
10    "image": "",
11    "gender": "undefined",
12    "active": true,
13    "createdAt": "2025-04-30 16:32:45",
14    "lastLoginAt": ""
15  }
16}

⚠️ 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_USER_NOT_FOUND404O usuário solicitado não foi encontrado.

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

Institucional

;