Grupo de Carteiras
Endpoints da WebApiAlcance para gerenciar grupos de carteiras - agrupamentos lógicos de clientes atribuídos a um usuário responsável (a "carteira" de um operador da contabilidade). Cobrem criação, listagem geral, listagem restrita ao responsável logado, lista de responsáveis com carteira, detalhamento por ID, atualização e exclusão.
Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key.
Base path
/api/v1/grupo-carteiraEscopos necessários
grupo_carteira:read- listagem, listagem do responsável, responsáveis com carteira e detalhamentogrupo_carteira:write- criação, atualização e exclusão
O escopo é derivado da rota: o prefixo /grupo-carteira vira o recurso grupo_carteira (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).
Quem pode o quê
Criar e editar grupo está liberado a qualquer usuário com o escopo write, com duas regras de campo sobre id_responsavel: sem permissão adicional, o grupo é sempre criado em nome de quem cria (o valor enviado é ignorado), e só quem tem permissão adicional reatribui o responsável de um grupo existente (403 caso contrário; reenviar o valor atual não conta). A exclusão é permitida ao responsável pelo grupo ou a quem tem permissão adicional; demais recebem 403.
Endpoints
POST /grupo-carteira/
Cria um novo grupo de carteiras. Sem permissão adicional, id_responsavel é forçado para o próprio usuário autenticado.
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (GrupoCarteiraCreate): nome (obrigatório), id_responsavel (obrigatório) e status (opcional, default 1).
Request
{
"nome": "Carteira Salvador - Centro",
"id_responsavel": 7,
"status": 1
}Response 201 Created
{
"status": "success",
"message": "Grupo de cliente criado com sucesso!",
"data": {
"id": 12,
"nome": "Carteira Salvador - Centro",
"status": 1,
"id_responsavel": 7
}
}Escopo: grupo_carteira:write
GET /grupo-carteira/meus
Lista os grupos em que o usuário logado é o responsável. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [].
Parâmetros
Este endpoint não recebe parâmetros de rota ou query - o responsável é derivado do usuário autenticado.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Grupos do usuário encontrados com sucesso!",
"data": [
{
"id": 12,
"nome": "Carteira Salvador - Centro",
"status": 1,
"id_responsavel": 7
}
]
}Escopo: grupo_carteira:read
GET /grupo-carteira/responsaveis
Lista os usuários que são responsáveis por ao menos um grupo de carteiras (sem repetição, ordenados por nome). Alimenta o filtro "Responsável" dos dashboards. Lista vazia é um estado válido - retorna 200 OK com data: [].
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Responsáveis encontrados com sucesso!",
"data": [
{ "id": 7, "nome": "Maria Souza" },
{ "id": 9, "nome": "João Lima" }
]
}Escopo: grupo_carteira:read
GET /grupo-carteira/{grupo_id}
Detalha um grupo pelo ID inteiro, incluindo os clientes vinculados em membros. Quando não encontrado, retorna 404 Not Found com { "message": "Grupo de cliente não encontrado." }.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
grupo_id | int | path | sim | ID interno do grupo |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Grupo de cliente encontrado com sucesso!",
"data": {
"id": 12,
"nome": "Carteira Salvador - Centro",
"status": 1,
"id_responsavel": 7,
"membros": []
}
}Escopo: grupo_carteira:read
GET /grupo-carteira/
Lista todos os grupos de carteiras cadastrados. Quando não há grupos, retorna 200 OK com data: [] e a mensagem "Nenhum grupo de clientes encontrado!".
Parâmetros
Este endpoint não recebe parâmetros de rota ou query.
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Grupos de clientes encontrados com sucesso!",
"data": [
{
"id": 12,
"nome": "Carteira Salvador - Centro",
"status": 1,
"id_responsavel": 7
},
{
"id": 13,
"nome": "Carteira Feira de Santana",
"status": 1,
"id_responsavel": 9
}
]
}Escopo: grupo_carteira:read
PUT /grupo-carteira/{grupo_id}
Atualiza um grupo existente. O body é um GrupoCarteiraUpdate com campos parciais - somente o que vier preenchido é alterado. Alterar id_responsavel exige permissão adicional (403 caso contrário); reenviar o valor atual é aceito. Grupo inexistente retorna 404.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
grupo_id | int | path | sim | ID do grupo |
Request (GrupoCarteiraUpdate - todos os campos opcionais)
{
"nome": "Carteira Salvador - Comércio",
"id_responsavel": 9
}Response 200 OK
{
"status": "success",
"message": "Dados do grupo de clientes atualizados com sucesso!",
"data": {
"id": 12,
"nome": "Carteira Salvador - Comércio",
"status": 1,
"id_responsavel": 9
}
}Escopo: grupo_carteira:write
DELETE /grupo-carteira/{grupo_id}
Remove um grupo de carteiras pelo ID, junto com os vínculos de clientes (carteira-cliente) do grupo. Permitido ao responsável pelo grupo ou a quem tem permissão adicional; grupo inexistente retorna 404 e demais usuários recebem 403.
Parâmetros
| Parâmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
grupo_id | int | path | sim | ID do grupo |
Request
Sem corpo de requisição.
Response 200 OK
{
"status": "success",
"message": "Grupo de clientes excluído com sucesso!",
"data": null
}Escopo: grupo_carteira:write + ser o responsável pelo grupo ou ter permissão adicional
Schemas
GrupoCarteiraCreate
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
nome | str | sim | Nome do grupo de carteiras. |
id_responsavel | int | sim | ID do usuário responsável pela carteira. Sem permissão adicional, é substituído pelo ID do próprio usuário. |
status | int | não | Situação do grupo. Default 1 (ativo). |
GrupoCarteiraUpdate
Todos os campos são opcionais; apenas os enviados são atualizados.
| Campo | Tipo | Observações |
|---|---|---|
nome | str | Novo nome do grupo. |
status | int | Nova situação. |
id_responsavel | int | Reatribui o grupo a outro responsável. Exige permissão adicional. |
GrupoCarteiraRead
| Campo | Tipo | Notas |
|---|---|---|
id | int | Identificador do grupo. |
nome | str | Nome do grupo. |
status | int | Situação (1 = ativo). |
id_responsavel | int | Usuário responsável pela carteira. |
Variante com membros
Existe também o schema GrupoCarteiraReadWithDetails, que estende o GrupoCarteiraRead com o array membros: List[CustomerReadWithDetails] - os clientes vinculados ao grupo. Consulte Customers para os campos de cada membro.
Notas
- Toda resposta de sucesso segue o envelope
{ status, message, data }. Erros usam{ message }(ou{ detail }no422de validação) com o status HTTP correspondente. meuseresponsaveissão rotas estáticas e não devem ser usadas comogrupo_id.- Relaciona-se com Carteiras de Cliente, que associa clientes individuais a carteiras.