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, detalhamento por ID, atualização e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/grupo-carteira

Escopos necessários

grupo_carteira:read - listagem, listagem do responsável 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).

Endpoints

`POST /grupo-carteira/`

Cria um novo grupo de carteiras.

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

{
  "success": true,
  "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

{
  "success": true,
  "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/{grupo_id}`

Detalha um grupo pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail: "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

{
  "success": true,
  "message": "Grupo de cliente encontrado com sucesso!",
  "data": {
    "id": 12,
    "nome": "Carteira Salvador - Centro",
    "status": 1,
    "id_responsavel": 7
  }
}

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

{
  "success": true,
  "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.

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

{
  "success": true,
  "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.

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

{
  "success": true,
  "message": "Grupo de clientes deletado com sucesso!",
  "data": {
    "id": 12,
    "nome": "Carteira Salvador - Comércio",
    "status": 1,
    "id_responsavel": 9
  }
}

Escopo: grupo_carteira:write

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.
`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.

`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 segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
GET /grupo-carteira/meus é declarado antes da rota dinâmica GET /grupo-carteira/{grupo_id}, então meus é resolvido como rota estática (e não interpretado como um grupo_id).
Relaciona-se com Carteiras de Cliente, que associa clientes individuais a carteiras.