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-clienteEscopos necessários
carteira_cliente:read- listagem, clientes por responsável e detalhamentocarteira_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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
grupo_id | int | path | sim | ID do grupo de carteiras |
customer_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
user_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
carteira_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
carteira_id | int | path | sim | ID 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âmetro | Tipo | Local | Obrigatório | Descrição |
|---|---|---|---|---|
carteira_id | int | path | sim | ID 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.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id_cliente | int | sim | ID do cliente vinculado à carteira. |
id_grupo | int | sim | ID do grupo de carteiras. |
CarteiraClienteUpdate
Todos os campos são opcionais; apenas os enviados são atualizados.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id | int | não | Identificador da carteira de cliente. |
id_cliente | int | não | Reatribui a carteira a outro cliente. |
id_grupo | int | não | Move a carteira para outro grupo. |
CarteiraClienteRead
Herda de CarteiraClienteBase, acrescentando o id.
| Campo | Tipo | Obrigatório | Observações |
|---|---|---|---|
id | int | sim | Identificador da carteira de cliente. |
id_cliente | int | sim | ID do cliente vinculado. |
id_grupo | int | sim | ID 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 }no422de validação) com o status HTTP correspondente. -
O
POST /carteira-cliente/{grupo_id}/create/{customer_id}retorna200 OK(e não201 Created), mesmo criando um novo vínculo. -
Relaciona-se com Grupo de Carteiras (o
id_gruporeferencia um grupo) e com Customers (oid_clientereferencia um cliente).