Vínculo com grupos
Coloque um usuário num grupo, mude o status do vínculo, tire-o do grupo e veja a quais grupos ele pertence.
O vínculo liga um usuário a um grupo e tem um status próprio (A ativo, P pendente, F disponível, D recusado; veja Grupos de usuários). Só vínculos ativos (A) contam para preço, pagamento, promoções e privilégios.
Use estas operações para refletir no sistema as regras do seu ERP ("este cliente agora é Atacado"), ou para aprovar quem pediu para entrar num grupo.
Ao tirar alguém de um grupo, o DELETE apaga o vínculo de verdade. Se você quer guardar o histórico e permitir que o usuário volte, mude o status do vínculo (por exemplo para F, disponível) com o POST em vez de apagar.
/api/v1/admin/users/{id}/usergroupsAdminGrupos de usuários de um usuário
Exige view_users ou manage_users. Lista todos os vínculos do usuário, de qualquer status, exceto com grupos desativados.
Path parameters
iduuidobrigatório{
"groups": [
{
"id": "a6ce359e-7dcb-462c-8342-bd0643f56a78",
"user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
"usergroup_id": "83dfbe9c-9ae4-49c9-a3f6-960ade0a0f52",
"usergroup_name": "Atacado Sul",
"usergroup_type": "C",
"status": "A",
"created_at": "2026-10-11T20:56:55.719007Z",
"updated_at": "2026-10-11T20:56:55.719007Z"
}
],
"total": 1
}Campos da resposta
groupsarraynull (em vez de []) quando não há nenhum.groups[].iduuidgroups[].usergroup_iduuidgroups[].usergroup_namestringgroups[].usergroup_typestringCVAgroups[].statusstringAPFDtotalinteger/api/v1/admin/users/{id}/usergroupsAdminVincula um usuário a um grupo de usuários
Vincula o usuário ao grupo, ou muda o status se o vínculo já existe (não duplica). Exige manage_users.
Path parameters
iduuidobrigatórioCorpo da requisição
usergroup_iduuidobrigatóriostatusstringobrigatórioAPFD{ "message": "user assigned to usergroup" }Exemplo de requisição
curl -X POST "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/usergroups" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"usergroup_id": "83dfbe9c-9ae4-49c9-a3f6-960ade0a0f52", "status": "A"}'/api/v1/admin/users/{id}/usergroups/{groupId}AdminRemove um usuário de um grupo de usuários
Apaga o vínculo. Exige manage_users. Se o usuário não está no grupo, a resposta é 400.
Path parameters
iduuidobrigatóriogroupIduuidobrigatório{ "message": "user removed from usergroup" }Erros
| Status | Quando | Corpo |
|---|---|---|
| 400 | status ausente ou inválido | {"error":"invalid link status: (must be A, P, D, or F)"} |
| 400 | usergroup_id ausente | {"error":"usergroup_id is required"} |
| 400 | Grupo inexistente ou desativado | {"error":"usergroup 00000000-... not found"} ou {"error":"usergroup ... is disabled"} |
| 400 | Usuário fora do grupo, ao remover | {"error":"user ... is not in group ..."} |
| 401 | Sem credenciais ou token expirado | {"error":"invalid or expired token"} |
| 403 | Falta o privilégio manage_users | {"error":"insufficient privileges","required":"manage_users"} |