Grupos de usuários
Como funcionam os grupos de clientes, de sellers e de administradores na API da Venddor 1.0, o status do grupo e do vínculo 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): quem é membro do grupo ganha as permissões de painel que a loja configurou para ele.
Esta seção documenta os grupos (/api/v1.0/usergroups), o vínculo de um usuário a grupos e as rotas sem versão equivalentes. A autenticação é HTTP Basic com e-mail:chave_de_api de um administrador, ou Bearer; quem não é administrador recebe 403.
Como funciona
Tipos de grupo
type | Para quê |
|---|---|
C | Segmento de clientes (públicos, tabelas comerciais, campanhas). |
V | Grupos de usuários de seller. |
A | Grupos de administradores da loja. |
Ao alterar um grupo, um tipo desconhecido é ignorado. Ao criar, o tipo é obrigatório e só valem as letras C, V e A.
Status do grupo e do vínculo
O grupo tem um status próprio:
| Letra | Palavra aceita | Significado |
|---|---|---|
A | active | Ativo. |
H | hidden | Oculto. |
D | disabled | Desativado: 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:
| Letra | Significado |
|---|---|
A | Membro ativo. É o que vale para preços e pagamento. |
P | Pendente: pediu para entrar e ainda não foi aceito. |
F | Disponível: o usuário saiu, mas a linha foi guardada e ele pode voltar. |
D | Recusado. |
Campos do grupo
usergroup: o nome do grupo.description: texto livre.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.
Ids
Em /api/v1.0, os ids de grupo e de usuário são UUID em string. Nas rotas sem versão (/api/usergroups...), os ids são decimais dentro de string: veja Rotas sem versão.
Endpoints
| Método | Rota | O que faz | Auth | Página |
|---|---|---|---|---|
| GET | /api/v1.0/usergroups | Lista grupos | Admin | Grupos |
| GET | /api/v1.0/usergroups/{id} | Consulta um grupo | Admin | Grupos |
| POST | /api/v1.0/usergroups | Cria grupo | Admin | Grupos |
| PUT | /api/v1.0/usergroups/{id} | Altera grupo | Admin | Grupos |
| DELETE | /api/v1.0/usergroups/{id} | Exclui grupo | Admin | Grupos |
| GET | /api/v1.0/users/{user_id}/usergroups | Grupos do usuário | Admin | Vínculo com grupos |
| POST | /api/v1.0/users/{user_id}/usergroups | Vincula a um grupo (indisponível em lojas comuns) | Admin | Vínculo com grupos |
| PUT | /api/v1.0/users/{user_id}/usergroups/{group_id} | Muda o status do vínculo | Admin | Vínculo com grupos |
| DELETE | /api/v1.0/users/{user_id}/usergroups/{group_id} | Solta do grupo | Admin | Vínculo com grupos |
| GET | /api/v1.0/users/{user_id}/usergroups/{group_id} | Consulta o vínculo (só em modo específico) | Admin | Vínculo com grupos |
| PUT | /api/v1.0/internal_usergroups/{company_id} | Informa o grupo interno de um cliente | Admin | Grupos internos |
| GET, POST, PUT, DELETE | /api/v1.0/internal_usergroup... | Só em modo específico | Admin | Grupos internos |
As rotas sem versão (/api/usergroups...) estão em Rotas sem versão.
Erros comuns
- Criar um grupo sem
statusetype. A rota exige os dois, além do nome (usergroup). Sem eles a resposta é 400. - Mandar um tipo escrito por extenso (
customer). Só valem as letrasC,VeA. - Achar que
DELETEdo vínculo apaga a linha. Ele marcaF. O usuário deixa de contar como membro, mas pode voltar. - 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.
- 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.