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-carteira

Escopos necessários

  • grupo_carteira:read - listagem, listagem do responsável, responsáveis com carteira e detalhamento
  • grupo_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âmetroTipoLocalObrigatórioDescrição
grupo_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
grupo_idintpathsimID 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âmetroTipoLocalObrigatórioDescrição
grupo_idintpathsimID 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

CampoTipoObrigatórioObservações
nomestrsimNome do grupo de carteiras.
id_responsavelintsimID do usuário responsável pela carteira. Sem permissão adicional, é substituído pelo ID do próprio usuário.
statusintnãoSituação do grupo. Default 1 (ativo).

GrupoCarteiraUpdate

Todos os campos são opcionais; apenas os enviados são atualizados.

CampoTipoObservações
nomestrNovo nome do grupo.
statusintNova situação.
id_responsavelintReatribui o grupo a outro responsável. Exige permissão adicional.

GrupoCarteiraRead

CampoTipoNotas
idintIdentificador do grupo.
nomestrNome do grupo.
statusintSituação (1 = ativo).
id_responsavelintUsuá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 } no 422 de validação) com o status HTTP correspondente.
  • meus e responsaveis são rotas estáticas e não devem ser usadas como grupo_id.
  • Relaciona-se com Carteiras de Cliente, que associa clientes individuais a carteiras.