API atual/Guia rápido/Grupos de usuários

Grupos

Liste, consulte, crie, altere e exclua grupos de usuários .

Use estas operações para manter o catálogo de grupos: um ERP que cria o grupo "Atacado Sul" quando abre uma nova tabela comercial, um painel que lista os grupos para o atendente escolher, uma rotina que remove grupos de campanhas antigas. Para colocar pessoas nos grupos, veja Vínculo com grupos.

Os conceitos (tipos C, V e A, status do grupo, campos extras) estão em Grupos de usuários. Um grupo novo nasce sem membros e sem privilégios.

GET/api/v1/admin/usergroupsAdmin

Lista os grupos de usuários

Exige manage_usergroups. Devolve todos os grupos que atendem ao filtro, ordenados pelo nome.

Query parameters

typestring

CVA

Só os grupos deste tipo.

statusstring

AHD

Só os grupos neste status (letra ou palavra active, hidden, disabled).

200Grupos retornados

json

{
  "usergroups": [
    {
      "id": "01569276-9514-44f3-bdca-897942fae7f0",
      "name": "Atacado",
      "description": "Compradores pessoa jurídica em maior volume.",
      "type": "C",
      "status": "A",
      "vendor_manageable": false,
      "members_count": 12,
      "internal_code": "ATAC",
      "created_at": "2026-07-31T21:15:27.511341Z",
      "updated_at": "2026-07-31T21:15:27.511341Z"
    }
  ],
  "total": 22
}

Campos da resposta

iduuid

Id do grupo.

namestring

Nome.

descriptionstring

Descrição.

typestring

CVA

Tipo.

statusstring

AHD

Status do grupo.

vendor_manageableboolean

Se o seller pode colocar clientes neste grupo.

members_countinteger

Vínculos, de qualquer status.

internal_codestring

Código do grupo no seu sistema. Pode ser vazio.

company_iduuid

Seller para o qual o grupo foi liberado. Ausente quando vale para todos.

legacy_idinteger

Id que o grupo tinha antes da migração da loja, em lojas migradas. Ausente nas demais.

totalinteger

Quantidade de grupos devolvidos.

GET/api/v1/admin/usergroups/{id}Admin

Consulta um grupo de usuários com seus membros

Devolve o grupo e a lista de membros, com o status de cada vínculo. Exige manage_usergroups. Grupos de audiência de campanha podem ter milhares de membros; prefira a lista quando só precisa do cabeçalho.

Path parameters

iduuidobrigatório

Id do grupo.

200Grupo e membros

json

{
  "id": "83dfbe9c-9ae4-49c9-a3f6-960ade0a0f52",
  "name": "Atacado Sul",
  "description": "Clientes de atacado da região Sul",
  "type": "C",
  "status": "A",
  "vendor_manageable": false,
  "company_id": null,
  "created_at": "2026-10-11T20:56:50.725639Z",
  "updated_at": "2026-10-11T20:56:50.725639Z",
  "members": [
    {
      "id": "a6ce359e-7dcb-462c-8342-bd0643f56a78",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "first_name": "Padaria Pão Doce Ltda",
      "last_name": "",
      "email": "contato@paodoce.example.com",
      "link_status": "A"
    }
  ],
  "members_count": 1
}

Campos da resposta

membersarray

Quem tem vínculo com o grupo (não inclui usuários excluídos).

members[].iduuid

Id do vínculo.

members[].user_iduuid

Id do usuário.

members[].link_statusstring

APFD

Status do vínculo.

members_countinteger

Quantidade de membros devolvidos.

Os demais campos são os da lista (internal_code não vem nesta resposta).

POST/api/v1/admin/usergroupsAdmin

Cria um grupo de usuários

Exige manage_usergroups. Só o nome é obrigatório; type e status assumem C e A quando faltam ou são desconhecidos.

Corpo da requisição

namestringobrigatório

Nome do grupo.

descriptionstring

Descrição.

typestringpadrão: C

CVA

Tipo. Valor desconhecido vira C.

statusstringpadrão: A

AHD

Status. Aceita a letra ou a palavra. Valor desconhecido vira A.

vendor_manageablebooleanpadrão: false

Deixa o seller colocar os próprios clientes neste grupo.

company_iduuid

Libera o grupo para um seller. Omitido, vale para todos.

internal_codestring

Código do grupo no seu ERP.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/usergroups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Atacado Sul", "description": "Clientes de atacado da região Sul", "type": "C", "internal_code": "ATAC-SUL"}'

Resposta

201Grupo criado

json

{
  "id": "83dfbe9c-9ae4-49c9-a3f6-960ade0a0f52",
  "name": "Atacado Sul",
  "description": "Clientes de atacado da região Sul",
  "type": "C",
  "status": "A",
  "vendor_manageable": false,
  "members_count": 0,
  "internal_code": "ATAC-SUL",
  "created_at": "2026-10-11T20:56:50.725639Z",
  "updated_at": "2026-10-11T20:56:50.725639Z"
}

PUT/api/v1/admin/usergroups/{id}Admin

Atualiza um grupo de usuários

Altera só os campos enviados e devolve o grupo atualizado. Exige manage_usergroups.

Path parameters

iduuidobrigatório

Id do grupo.

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição.

typestring

CVA

Novo tipo. Valor desconhecido é ignorado.

statusstring

AHD

Novo status. Valor desconhecido causa erro 500.

vendor_manageableboolean

Liga ou desliga a gestão pelo seller.

company_iduuid

Seller liberado. "" ou "0" volta a valer para todos.

internal_codestring

Código do ERP.

DELETE/api/v1/admin/usergroups/{id}Admin

Exclui um grupo de usuários

Exclui o grupo e todos os vínculos dele. Exige manage_usergroups.

Path parameters

iduuidobrigatório

Id do grupo.

200Grupo excluído

json

{ "message": "usergroup deleted" }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Falta `name` ao criar	`{"error":"name is required"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_usergroups`	`{"error":"insufficient privileges","required":"manage_usergroups"}`
404	Grupo inexistente em consultar e alterar	`{"error":"usergroup not found"}`
500	`status` inválido ao alterar	`{"error":"failed to update usergroup","detail":"invalid status: \"zz\" (must be A/H/D or active/hidden/disabled)"}`
500	Excluir um grupo que não existe	`{"error":"failed to delete usergroup","detail":"usergroup ... not found"}`

Veja também

Grupos

Liste, consulte, crie, altere e exclua grupos de usuários .

Os conceitos (tipos C, V e A, status do grupo, campos extras) estão em Grupos de usuários. Um grupo novo nasce sem membros e sem privilégios.

GET/api/v1/admin/usergroupsAdmin

Lista os grupos de usuários

Exige manage_usergroups. Devolve todos os grupos que atendem ao filtro, ordenados pelo nome.

Query parameters

typestring

CVA

Só os grupos deste tipo.

statusstring

AHD

Só os grupos neste status (letra ou palavra active, hidden, disabled).

200Grupos retornados

json

{
  "usergroups": [
    {
      "id": "01569276-9514-44f3-bdca-897942fae7f0",
      "name": "Atacado",
      "description": "Compradores pessoa jurídica em maior volume.",
      "type": "C",
      "status": "A",
      "vendor_manageable": false,
      "members_count": 12,
      "internal_code": "ATAC",
      "created_at": "2026-07-31T21:15:27.511341Z",
      "updated_at": "2026-07-31T21:15:27.511341Z"
    }
  ],
  "total": 22
}

Campos da resposta

iduuid

Id do grupo.

namestring

Nome.

descriptionstring

Descrição.

typestring

CVA

Tipo.

statusstring

AHD

Status do grupo.

vendor_manageableboolean

Se o seller pode colocar clientes neste grupo.

members_countinteger

Vínculos, de qualquer status.

internal_codestring

Código do grupo no seu sistema. Pode ser vazio.

company_iduuid

Seller para o qual o grupo foi liberado. Ausente quando vale para todos.

legacy_idinteger

Id que o grupo tinha antes da migração da loja, em lojas migradas. Ausente nas demais.

totalinteger

Quantidade de grupos devolvidos.

GET/api/v1/admin/usergroups/{id}Admin

Consulta um grupo de usuários com seus membros

Path parameters

iduuidobrigatório

Id do grupo.

200Grupo e membros

json

{
  "id": "83dfbe9c-9ae4-49c9-a3f6-960ade0a0f52",
  "name": "Atacado Sul",
  "description": "Clientes de atacado da região Sul",
  "type": "C",
  "status": "A",
  "vendor_manageable": false,
  "company_id": null,
  "created_at": "2026-10-11T20:56:50.725639Z",
  "updated_at": "2026-10-11T20:56:50.725639Z",
  "members": [
    {
      "id": "a6ce359e-7dcb-462c-8342-bd0643f56a78",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "first_name": "Padaria Pão Doce Ltda",
      "last_name": "",
      "email": "contato@paodoce.example.com",
      "link_status": "A"
    }
  ],
  "members_count": 1
}

Campos da resposta

membersarray

Quem tem vínculo com o grupo (não inclui usuários excluídos).

members[].iduuid

Id do vínculo.

members[].user_iduuid

Id do usuário.

members[].link_statusstring

APFD

Status do vínculo.

members_countinteger

Quantidade de membros devolvidos.

Os demais campos são os da lista (internal_code não vem nesta resposta).

POST/api/v1/admin/usergroupsAdmin

Cria um grupo de usuários

Exige manage_usergroups. Só o nome é obrigatório; type e status assumem C e A quando faltam ou são desconhecidos.

Corpo da requisição

namestringobrigatório

Nome do grupo.

descriptionstring

Descrição.

typestringpadrão: C

CVA

Tipo. Valor desconhecido vira C.

statusstringpadrão: A

AHD

Status. Aceita a letra ou a palavra. Valor desconhecido vira A.

vendor_manageablebooleanpadrão: false

Deixa o seller colocar os próprios clientes neste grupo.

company_iduuid

Libera o grupo para um seller. Omitido, vale para todos.

internal_codestring

Código do grupo no seu ERP.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/usergroups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Atacado Sul", "description": "Clientes de atacado da região Sul", "type": "C", "internal_code": "ATAC-SUL"}'

Resposta

201Grupo criado

json

{
  "id": "83dfbe9c-9ae4-49c9-a3f6-960ade0a0f52",
  "name": "Atacado Sul",
  "description": "Clientes de atacado da região Sul",
  "type": "C",
  "status": "A",
  "vendor_manageable": false,
  "members_count": 0,
  "internal_code": "ATAC-SUL",
  "created_at": "2026-10-11T20:56:50.725639Z",
  "updated_at": "2026-10-11T20:56:50.725639Z"
}

PUT/api/v1/admin/usergroups/{id}Admin

Atualiza um grupo de usuários

Altera só os campos enviados e devolve o grupo atualizado. Exige manage_usergroups.

Path parameters

iduuidobrigatório

Id do grupo.

Corpo da requisição

namestring

Novo nome.

descriptionstring

Nova descrição.

typestring

CVA

Novo tipo. Valor desconhecido é ignorado.

statusstring

AHD

Novo status. Valor desconhecido causa erro 500.

vendor_manageableboolean

Liga ou desliga a gestão pelo seller.

company_iduuid

Seller liberado. "" ou "0" volta a valer para todos.

internal_codestring

Código do ERP.

DELETE/api/v1/admin/usergroups/{id}Admin

Exclui um grupo de usuários

Exclui o grupo e todos os vínculos dele. Exige manage_usergroups.

Path parameters

iduuidobrigatório

Id do grupo.

200Grupo excluído

json

{ "message": "usergroup deleted" }

Erros

Status	Quando	Corpo
400	Corpo que não é JSON	`{"error":"invalid request body","detail":"..."}`
400	Falta `name` ao criar	`{"error":"name is required"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Falta `manage_usergroups`	`{"error":"insufficient privileges","required":"manage_usergroups"}`
404	Grupo inexistente em consultar e alterar	`{"error":"usergroup not found"}`
500	`status` inválido ao alterar	`{"error":"failed to update usergroup","detail":"invalid status: \"zz\" (must be A/H/D or active/hidden/disabled)"}`
500	Excluir um grupo que não existe	`{"error":"failed to delete usergroup","detail":"usergroup ... not found"}`