Carteiras de Cliente

Endpoints da WebApiAlcance para gerenciar carteiras de cliente - o vínculo individual entre um cliente (id_cliente) e um grupo de carteiras (id_grupo). Enquanto o Grupo de Carteiras define o agrupamento e o responsável, a carteira de cliente representa cada associação concreta de um cliente a esse grupo. Cobrem a adição de um cliente a um grupo, listagem das carteiras do usuário logado, clientes da carteira de um responsável, 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/carteira-cliente

Escopos necessários

  • carteira_cliente:read - listagem, clientes por responsável e detalhamento
  • carteira_cliente:write - adição de cliente ao grupo, atualização e exclusão

O escopo é derivado da rota: o prefixo /carteira-cliente vira o recurso carteira_cliente (hífen → underscore), e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Quem administra a carteira

As escritas (adicionar, mover e remover cliente) exigem, além do escopo, ser o responsável pelo grupo da carteira ou ter permissão adicional. Quem não atende a nenhuma das duas condições recebe 403. Mover um cliente entre grupos exige ser responsável pelo grupo de origem e pelo de destino.

Endpoints

POST /carteira-cliente/{grupo_id}/create/{customer_id}

Adiciona um cliente a um grupo de carteiras existente, criando a associação (carteira de cliente). O id do grupo e o id do cliente vêm da rota - não há corpo de requisição.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
grupo_idintpathsimID do grupo de carteiras
customer_idintpathsimID do cliente a ser vinculado

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Carteira de cliente adicionada ao grupo com sucesso!",
  "data": {
    "id": 45,
    "id_cliente": 1234,
    "id_grupo": 12
  }
}

Quando não é possível criar o vínculo, retorna o envelope de erro com message: "Não foi possível adicionar o cliente ao grupo de clientes." e details: []. Sem permissão sobre o grupo, retorna 403; grupo inexistente, 404.

Escopo: carteira_cliente:write + ser responsável pelo grupo ou ter permissão adicional

GET /carteira-cliente/por-responsavel/{user_id}

Lista os IDs dos clientes (customer_id, sem repetição) na carteira de um responsável, somando todos os grupos dele. Qualquer usuário autenticado pode consultar a carteira de qualquer responsável. Lista vazia é um estado válido - retorna 200 OK com data: [].

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
user_idintpathsimID do usuário responsável

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Carteira do responsável encontrada com sucesso!",
  "data": [1234, 1235, 1240]
}

Escopo: carteira_cliente:read

GET /carteira-cliente/{carteira_id}

Detalha uma carteira de cliente pelo ID inteiro. Quando não encontrada, retorna 404 Not Found com detail: "Carteira de cliente não encontrada.".

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
carteira_idintpathsimID interno da carteira de cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Carteira de cliente encontrada com sucesso!",
  "data": {
    "id": 45,
    "id_cliente": 1234,
    "id_grupo": 12
  }
}

Escopo: carteira_cliente:read

GET /carteira-cliente/

Lista todas as carteiras de cliente do usuário logado. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma carteira de clientes encontrada!".

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": "Carteiras de clientes encontradas com sucesso!",
  "data": [
    { "id": 45, "id_cliente": 1234, "id_grupo": 12 },
    { "id": 46, "id_cliente": 1235, "id_grupo": 12 }
  ]
}

Escopo: carteira_cliente:read

PUT /carteira-cliente/{carteira_id}

Atualiza uma carteira de cliente existente. O corpo é um CarteiraClienteUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
carteira_idintpathsimID da carteira de cliente

Request (CarteiraClienteUpdate - todos os campos opcionais)

{
  "id_grupo": 13
}

Response 200 OK

{
  "status": "success",
  "message": "Dados da carteira de cliente atualizado com sucesso!",
  "data": {
    "id": 45,
    "id_cliente": 1234,
    "id_grupo": 13
  }
}

Quando não é possível atualizar, retorna o envelope de erro com message: "Não foi possível atualizar os dados da carteira de clientes!". Carteira inexistente retorna 404; sem permissão sobre o grupo de origem (e o de destino, ao mudar id_grupo), 403.

Escopo: carteira_cliente:write + ser responsável pelo(s) grupo(s) ou ter permissão adicional

DELETE /carteira-cliente/{carteira_id}

Remove uma carteira de cliente (o vínculo cliente/grupo) pelo ID.

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
carteira_idintpathsimID da carteira de cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "message": "Carteira de cliente removida com sucesso!",
  "data": null
}

Carteira inexistente retorna 404; sem permissão sobre o grupo da carteira, 403.

Escopo: carteira_cliente:write + ser responsável pelo grupo ou ter permissão adicional

Schemas

CarteiraClienteCreate

Herda de CarteiraClienteBase. Representa a associação a ser criada entre cliente e grupo.

CampoTipoObrigatórioObservações
id_clienteintsimID do cliente vinculado à carteira.
id_grupointsimID do grupo de carteiras.

CarteiraClienteUpdate

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

CampoTipoObrigatórioObservações
idintnãoIdentificador da carteira de cliente.
id_clienteintnãoReatribui a carteira a outro cliente.
id_grupointnãoMove a carteira para outro grupo.

CarteiraClienteRead

Herda de CarteiraClienteBase, acrescentando o id.

CampoTipoObrigatórioObservações
idintsimIdentificador da carteira de cliente.
id_clienteintsimID do cliente vinculado.
id_grupointsimID do grupo de carteiras.

Schema equivalente

Existe também o schema CarteiraClientesRead, com os mesmos campos (id, id_cliente, id_grupo) - é uma variante de leitura usada internamente pelo domínio.

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.

  • O POST /carteira-cliente/{grupo_id}/create/{customer_id} retorna 200 OK (e não 201 Created), mesmo criando um novo vínculo.

  • Relaciona-se com Grupo de Carteiras (o id_grupo referencia um grupo) e com Customers (o id_cliente referencia um cliente).