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

Grupos

Liste, consulte, crie, altere e exclua grupos de usuários no formato da Venddor 1.0.

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.

GET/api/v1.0/usergroupsAdmin

Listar grupos de usuários

Devolve todos os grupos que atendem ao filtro, sem paginação, ordenados pelo nome. O bloco params existe só por compatibilidade e traz page 1 e o total. Também responde em /api/usergroups.

Parâmetros de consulta

typestring

CVA

Só os grupos deste tipo.

statusstring

AHD

Só os grupos neste status (letra ou palavra).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/usergroups?type=C&status=A"

Resposta

200Grupos retornados

json

{
  "params": { "page": 1, "items_per_page": 2, "total_items": 2 },
  "usergroups": [
    {
      "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
      "usergroup": "Atacado",
      "status": "A",
      "type": "C",
      "description": "Compradores pessoa jurídica em maior volume, com condições comerciais diferenciadas.",
      "members_count": 0
    },
    {
      "usergroup_id": "bf61ec8f-8b6e-4fa3-871d-b6d4f63c7f38",
      "usergroup": "CRM: Audiência QA",
      "status": "A",
      "type": "C",
      "description": "Auto-managed by CRM audience 0e115df0-2332-43e2-9c4e-dbd57406ae2b",
      "members_count": 7104
    }
  ]
}

Campos da resposta

usergroups[].usergroup_idstring

Id do grupo (UUID; decimal em /api/usergroups).

usergroups[].usergroupstring

Nome do grupo.

usergroups[].statusstring

AHD

Status do grupo.

usergroups[].typestring

CVA

Tipo do grupo.

usergroups[].descriptionstring

Descrição livre.

usergroups[].members_countinteger

Vínculos do grupo, de qualquer status.

GET/api/v1.0/usergroups/{id}Admin

Consultar um grupo de usuários

Devolve o grupo no mesmo formato de um item da lista, sem os membros.

Parâmetros de caminho

idstringobrigatório

Id do grupo (UUID; na rota sem versão, o id decimal).

200Grupo encontrado

json

{
  "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
  "usergroup": "Atacado",
  "status": "A",
  "type": "C",
  "description": "Compradores pessoa jurídica em maior volume.",
  "members_count": 12
}

POST/api/v1.0/usergroupsAdmin

Criar um grupo de usuários

Cria um grupo. Nome, status e tipo são todos obrigatórios (a rota não assume padrões, para que um erro de digitação não crie um grupo diferente do que você queria).

Corpo da requisição

usergroupstringobrigatório

Nome do grupo.

statusstringobrigatório

AHD

Status inicial.

typestringobrigatório

CVA

Tipo do grupo.

descriptionstring

Descrição.

201Grupo criado

json

{ "usergroup_id": "adbe186e-01a5-47ea-8047-bd7defa2ba1d" }

PUT/api/v1.0/usergroups/{id}Admin

Atualizar um grupo de usuários

Altera os campos enviados. Responde {"message":"OK"} e o id do grupo.

Parâmetros de caminho

idstringobrigatório

Id do grupo.

Corpo da requisição

usergroupstring

Novo nome.

statusstring

AHD

Novo status.

typestring

CVA

Novo tipo. Valor desconhecido é ignorado.

descriptionstring

Nova descrição.

200Grupo alterado

json

{ "message": "OK", "usergroup_id": "adbe186e-01a5-47ea-8047-bd7defa2ba1d" }

DELETE/api/v1.0/usergroups/{id}Admin

Excluir um grupo de usuários

Exclui o grupo e todos os vínculos dele. Responde 204.

Parâmetros de caminho

idstringobrigatório

Id do grupo.

Erros

Status	Quando	Corpo
400	Falta `usergroup`, `status` ou `type` ao criar	`{"message":"Field 'usergroup' (name) is required","status":400}`, `{"message":"Required field: status","status":400}` ou `{"message":"Required field: type","status":400}`
400	Corpo que não é JSON	`{"message":"Invalid JSON","status":400}`
401	Sem credenciais ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Grupo inexistente em consultar e alterar	`{"message":"Usergroup not found","status":404}`
500	Excluir um grupo que não existe	`{"message":"usergroup ... not found","status":500}`
500	Id que não é UUID	`{"message":"query usergroup abc: pq: invalid input syntax for type uuid: \"abc\" (22P02)","status":500}`

Veja também

Grupos

Liste, consulte, crie, altere e exclua grupos de usuários no formato da Venddor 1.0.

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.

GET/api/v1.0/usergroupsAdmin

Listar grupos de usuários

Parâmetros de consulta

typestring

CVA

Só os grupos deste tipo.

statusstring

AHD

Só os grupos neste status (letra ou palavra).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/usergroups?type=C&status=A"

Resposta

200Grupos retornados

json

{
  "params": { "page": 1, "items_per_page": 2, "total_items": 2 },
  "usergroups": [
    {
      "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
      "usergroup": "Atacado",
      "status": "A",
      "type": "C",
      "description": "Compradores pessoa jurídica em maior volume, com condições comerciais diferenciadas.",
      "members_count": 0
    },
    {
      "usergroup_id": "bf61ec8f-8b6e-4fa3-871d-b6d4f63c7f38",
      "usergroup": "CRM: Audiência QA",
      "status": "A",
      "type": "C",
      "description": "Auto-managed by CRM audience 0e115df0-2332-43e2-9c4e-dbd57406ae2b",
      "members_count": 7104
    }
  ]
}

Campos da resposta

usergroups[].usergroup_idstring

Id do grupo (UUID; decimal em /api/usergroups).

usergroups[].usergroupstring

Nome do grupo.

usergroups[].statusstring

AHD

Status do grupo.

usergroups[].typestring

CVA

Tipo do grupo.

usergroups[].descriptionstring

Descrição livre.

usergroups[].members_countinteger

Vínculos do grupo, de qualquer status.

GET/api/v1.0/usergroups/{id}Admin

Consultar um grupo de usuários

Devolve o grupo no mesmo formato de um item da lista, sem os membros.

Parâmetros de caminho

idstringobrigatório

Id do grupo (UUID; na rota sem versão, o id decimal).

200Grupo encontrado

json

{
  "usergroup_id": "01569276-9514-44f3-bdca-897942fae7f0",
  "usergroup": "Atacado",
  "status": "A",
  "type": "C",
  "description": "Compradores pessoa jurídica em maior volume.",
  "members_count": 12
}

POST/api/v1.0/usergroupsAdmin

Criar um grupo de usuários

Cria um grupo. Nome, status e tipo são todos obrigatórios (a rota não assume padrões, para que um erro de digitação não crie um grupo diferente do que você queria).

Corpo da requisição

usergroupstringobrigatório

Nome do grupo.

statusstringobrigatório

AHD

Status inicial.

typestringobrigatório

CVA

Tipo do grupo.

descriptionstring

Descrição.

201Grupo criado

json

{ "usergroup_id": "adbe186e-01a5-47ea-8047-bd7defa2ba1d" }

PUT/api/v1.0/usergroups/{id}Admin

Atualizar um grupo de usuários

Altera os campos enviados. Responde {"message":"OK"} e o id do grupo.

Parâmetros de caminho

idstringobrigatório

Id do grupo.

Corpo da requisição

usergroupstring

Novo nome.

statusstring

AHD

Novo status.

typestring

CVA

Novo tipo. Valor desconhecido é ignorado.

descriptionstring

Nova descrição.

200Grupo alterado

json

{ "message": "OK", "usergroup_id": "adbe186e-01a5-47ea-8047-bd7defa2ba1d" }

DELETE/api/v1.0/usergroups/{id}Admin

Excluir um grupo de usuários

Exclui o grupo e todos os vínculos dele. Responde 204.

Parâmetros de caminho

idstringobrigatório

Id do grupo.

Erros

Status	Quando	Corpo
400	Falta `usergroup`, `status` ou `type` ao criar	`{"message":"Field 'usergroup' (name) is required","status":400}`, `{"message":"Required field: status","status":400}` ou `{"message":"Required field: type","status":400}`
400	Corpo que não é JSON	`{"message":"Invalid JSON","status":400}`
401	Sem credenciais ou token expirado	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Grupo inexistente em consultar e alterar	`{"message":"Usergroup not found","status":404}`
500	Excluir um grupo que não existe	`{"message":"usergroup ... not found","status":500}`
500	Id que não é UUID	`{"message":"query usergroup abc: pq: invalid input syntax for type uuid: \"abc\" (22P02)","status":500}`