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

Base path

/api/v1/carteira-cliente

Escopos necessários

• carteira_cliente:read - listagem 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).

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

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: carteira_cliente:write

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

Request

Sem corpo de requisição.

Response 200 OK

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

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

Request (CarteiraClienteUpdate - todos os campos opcionais)

{
  "id_grupo": 13
}

Response 200 OK

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

Escopo: carteira_cliente:write

DELETE /carteira-cliente/{carteira_id}

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

Parâmetros

Request

Sem corpo de requisição.

Response 200 OK

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

Quando não é possível deletar, retorna o envelope de erro com message: "Não foi possível deletar a carteira de clientes!" e details: [].

Escopo: carteira_cliente:write

Schemas

CarteiraClienteCreate

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

CarteiraClienteUpdate

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

CarteiraClienteRead

Herda de CarteiraClienteBase, acrescentando o id.

Notas

• Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
• 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).