VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Guia rápido

Grupos de usuários

Como funcionam os grupos de clientes, de sellers e de administradores, o status do grupo e do vínculo, os privilégios e o mapa das rotas.

Um grupo de usuários (usergroup) é uma lista nomeada de pessoas. A plataforma usa grupos para três coisas bem diferentes, e o type do grupo diz qual:

  • Segmentar clientes (C): "Atacado", "VIP", "Revendedores". A loja usa o grupo para decidir preços, formas de pagamento, promoções e campanhas por público.
  • Agrupar usuários de seller (V): permissões de quem opera o painel de um seller.
  • Dar permissão a administradores (A): o grupo carrega uma lista de privilégios (ver pedidos, gerenciar usuários...) e quem é membro ganha esses privilégios.

Esta seção documenta os grupos (/api/v1/admin/usergroups), o vínculo de um usuário a grupos e os privilégios de um grupo.

Pontos-chave
  • O type do grupo (C, V, A) não muda o que ele é por dentro, mas decide se ele pode ter privilégios: só grupos de administrador e de seller podem; um grupo de cliente recusa.
  • O grupo e o vínculo de cada usuário com ele têm status diferentes. Um membro pode estar pendente (P) num grupo que está ativo (A).
  • Tirar um usuário de um grupo apaga o vínculo. Para guardar o histórico, mude o status do vínculo em vez de apagar.
  • Apagar um grupo apaga também todos os vínculos dele, sem aviso.
  • Privilégio com nome que não existe é descartado em silêncio. Confira o resultado com GET .../privileges.

Como funciona

Tipos de grupo

typePara quêPode ter privilégios?
CSegmento de clientes (públicos, tabelas comerciais, campanhas). Padrão ao criar.Não. Tentar gravar privilégios devolve erro.
VGrupos de usuários de seller.Sim (privilégios de seller).
AGrupos de administradores da loja.Sim. Só o dono da loja pode alterar os privilégios.

Um tipo desconhecido, ao criar, vira C sem erro. Ao alterar, um tipo desconhecido é ignorado.

Status do grupo e do vínculo

O grupo tem um status próprio:

LetraPalavra aceitaSignificado
AactiveAtivo. Padrão ao criar.
HhiddenOculto.
DdisabledDesativado: ninguém novo pode ser vinculado e o grupo some da lista de grupos do usuário.

O vínculo entre um usuário e um grupo tem outro conjunto:

LetraSignificado
AMembro ativo. É o que vale para preços, pagamento e privilégios.
PPendente: pediu para entrar e ainda não foi aceito.
FDisponível: o usuário saiu, mas a linha foi guardada e ele pode voltar.
DRecusado.

Campos extras do grupo

  • vendor_manageable: se true, o seller pode colocar os próprios clientes neste grupo, pelo painel dele.
  • company_id: o seller para o qual o grupo foi liberado. null significa todos.
  • internal_code: código do grupo no seu ERP (texto livre). Útil para casar grupos entre sistemas.
  • members_count: quantos vínculos o grupo tem, de qualquer status.

Grupos cujo nome começa com CRM: são gerados pelas audiências de campanha e mantidos pela plataforma. Não os edite à mão: a próxima atualização da audiência desfaz a mudança.

Privilégios

Um privilégio é uma permissão com nome (view_orders, manage_users). Por convenção, view_* só lê e manage_* também escreve. Um administrador tem a soma dos privilégios dos grupos de que é membro ativo (A). O dono da loja (is_root) ignora os grupos e tem tudo. Administradores novos entram automaticamente no grupo de administradores padrão.

A lista de todos os privilégios existentes sai de GET /api/v1/admin/privileges (exige manage_usergroups): cada item tem privilege, section_id, group_id, is_view e module_slug.

Autenticação

Bearer de um administrador com o privilégio manage_usergroups (grupos e privilégios) ou manage_users (vincular usuários a grupos).

Endpoints

MétodoRotaO que fazAuthPágina
GET/api/v1/admin/usergroupsLista gruposAdminGrupos
GET/api/v1/admin/usergroups/{id}Consulta um grupo e os membrosAdminGrupos
POST/api/v1/admin/usergroupsCria grupoAdminGrupos
PUT/api/v1/admin/usergroups/{id}Altera grupoAdminGrupos
DELETE/api/v1/admin/usergroups/{id}Exclui grupoAdminGrupos
GET/api/v1/admin/users/{id}/usergroupsGrupos do usuárioAdminVínculo com grupos
POST/api/v1/admin/users/{id}/usergroupsVincula ou muda o vínculoAdminVínculo com grupos
DELETE/api/v1/admin/users/{id}/usergroups/{groupId}Remove o vínculoAdminVínculo com grupos
GET/api/v1/admin/usergroups/{id}/privilegesPrivilégios do grupoAdminPrivilégios
PUT/api/v1/admin/usergroups/{id}/privilegesTroca os privilégios do grupoAdminPrivilégios

Erros comuns

  1. Mandar um tipo escrito por extenso (customer). Só valem as letras C, V e A; outro valor, ao criar, vira C sem aviso.
  2. Gravar privilégios num grupo C. Devolve 500 com a explicação. Use grupo A ou V.
  3. Digitar errado um privilégio. O nome desconhecido é descartado e a resposta é 200. Releia o grupo para conferir.
  4. Excluir um grupo que ainda tem membros. Os vínculos somem junto, e o preço, o pagamento e as promoções amarrados ao grupo deixam de valer para essas pessoas.
  5. Esperar 404 ao tocar num grupo que não existe em todas as rotas. Excluir ou alterar o status de um grupo inexistente pode voltar 500. Veja os erros de cada página.

Próximos passos

Grupos
Crie, liste, altere e exclua grupos.
Vínculo com grupos
Coloque e tire usuários dos grupos.
Privilégios
Defina o que um grupo de administradores pode fazer.
Clientes
Cadastro, PF e PJ, endereços e crédito.
Anterior
WhatsApp
Próxima
Grupos
Nesta página
  • Como funciona
  • Tipos de grupo
  • Status do grupo e do vínculo
  • Campos extras do grupo
  • Privilégios
  • Autenticação
  • Endpoints
  • Erros comuns
  • Próximos passos