Grupos de clientes do seller
Lista os grupos de clientes que o seller pode gerir, vê quais clientes dele estão em cada grupo e coloca ou tira clientes de um grupo.
Um grupo de clientes (usergroup) reúne clientes que recebem o mesmo tratamento na loja, por exemplo "Atacado" ou "Clientes VIP": preços específicos, condições de pagamento ou visibilidade de produtos. Quem cria o grupo e define suas regras é o administrador da loja. O seller só pode colocar e tirar os próprios clientes de grupos que o administrador marcou como "gerenciáveis pelo seller".
Estas rotas só existem quando a loja liga o módulo vendor-usergroups; sem ele, respondem 403 module_disabled. Também exigem um privilégio de configurações do seller (vendor_settings).
Regras que valem nas quatro rotas:
- O grupo precisa ser de clientes, estar ativo e ter sido marcado como gerenciável pelo seller. Caso contrário a resposta é
400com a razão emdetail. - Um cliente só entra num grupo se já comprou deste seller.
- O grupo pertence à loja, não ao seller: a entrada vale para o grupo como o administrador o definiu, e o seller só liga ou desliga clientes dele.
Listar os grupos
/api/v1/vendor/usergroupsSellerLista os grupos de clientes que o seller pode gerir
Devolve só os grupos ativos, de clientes e gerenciáveis pelo seller. Sem paginação.
{
"usergroups": [
{
"id": "b7a5e3c1-2d4f-4a6b-8c9d-0e1f2a3b4c5d",
"name": "Atacado",
"description": "Clientes com preço de atacado",
"type": "C",
"status": "A",
"members_count": 12,
"created_at": "2026-05-29T18:52:13Z",
"updated_at": "2026-09-15T19:00:17Z"
}
],
"total": 1
}Campos da resposta
usergroupsarray[]) quando o administrador não liberou nenhum.totalintegerusergroups[].iduuidusergroups[].namestringusergroups[].descriptionstringusergroups[].typestringC (clientes).usergroups[].statusstringA (ativo).usergroups[].members_countintegerusergroups[].created_atstringusergroups[].updated_atstringListar os membros
/api/v1/vendor/usergroups/{usergroupId}/membersSellerClientes do seller que estão num grupo
Devolve os membros do grupo que também são clientes deste seller (têm pelo menos um pedido com ele), em ordem alfabética. Membros ligados a outros sellers não aparecem, por isso a contagem pode ser menor que members_count.
Parâmetros de caminho
usergroupIduuidobrigatório{
"members": [
{
"user_id": "4f44f104-bbe0-4d2e-b497-c1afbe19d7c5",
"first_name": "Vinícius",
"last_name": "Nunes",
"email": "vinicius.nunes@example.com",
"usergroup_id": "b7a5e3c1-2d4f-4a6b-8c9d-0e1f2a3b4c5d",
"usergroup_name": "Atacado",
"status": "A",
"assigned_at": "2026-09-01T12:00:00Z"
}
],
"total": 1
}Campos da resposta
membersarraytotalintegermembers[].user_iduuidmembers[].first_namestringmembers[].last_namestringmembers[].emailstringmembers[].usergroup_iduuidmembers[].usergroup_namestringmembers[].statusstringAPFA ativo, P pendente, F disponível para adesão.members[].assigned_atstringColocar um cliente no grupo
/api/v1/vendor/usergroups/{usergroupId}/members/{customerId}SellerColoca um cliente do seller num grupo
Cria (ou reativa) o vínculo com status A. Sem corpo. Repetir não dá erro. O cliente precisa existir, ser do tipo cliente e ter pelo menos um pedido com este seller.
Parâmetros de caminho
usergroupIduuidobrigatóriocustomerIduuidobrigatório{ "message": "customer assigned to usergroup" }Tirar um cliente do grupo
/api/v1/vendor/usergroups/{usergroupId}/members/{customerId}SellerTira um cliente de um grupo
Remove o vínculo. Se o cliente já não estava no grupo, responde sucesso do mesmo jeito.
Parâmetros de caminho
usergroupIduuidobrigatóriocustomerIduuidobrigatório{ "message": "customer removed from usergroup" }Exemplo de requisição
GROUP=b7a5e3c1-2d4f-4a6b-8c9d-0e1f2a3b4c5d
CUSTOMER=4f44f104-bbe0-4d2e-b497-c1afbe19d7c5
# grupos que posso gerir
curl "$BASE_URL/api/v1/vendor/usergroups" -H "Authorization: Bearer $TOKEN"
# colocar o cliente no grupo
curl -X POST "$BASE_URL/api/v1/vendor/usergroups/$GROUP/members/$CUSTOMER" \
-H "Authorization: Bearer $TOKEN"
# tirar o cliente do grupo
curl -X DELETE "$BASE_URL/api/v1/vendor/usergroups/$GROUP/members/$CUSTOMER" \
-H "Authorization: Bearer $TOKEN"Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 400 | Grupo inexistente, inativo, que não é de clientes ou não liberado ao seller. | {"error":"VENDOR_USERGROUP_MEMBERS_FAILED","detail":"usergroup 0000... not found"} |
| 400 | Cliente inexistente, que não é do tipo cliente ou sem pedido neste seller (ao colocar). | {"error":"VENDOR_ASSIGN_CUSTOMER_FAILED","detail":"customer ... has no orders with vendor ..."} |
| 400 | usergroupId ou customerId que não é UUID. | {"error":"VENDOR_ASSIGN_CUSTOMER_FAILED","detail":"o valor \"abc\" não é um uuid válido. ..."} |
| 401 | Sem token. | {"error":"AUTH_REQUIRED"} |
| 403 | Módulo desligado. | {"error":"module_disabled","module":"vendor-usergroups"} |
| 403 | Falta o privilégio de configurações. | {"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","..."]} |
| 404 | O usuário não tem seller. | {"error":"VENDOR_NOT_FOUND"} |
O código de error muda conforme a rota (VENDOR_USERGROUP_MEMBERS_FAILED na leitura, VENDOR_ASSIGN_CUSTOMER_FAILED ao colocar, VENDOR_REMOVE_CUSTOMER_FAILED ao tirar); a causa está em detail, em inglês ou português.