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

Rotas sem versão

As rotas /api/usergroups e /api/users/{id}/usergroups, gêmeas das /api/v1.0, que usam ids decimais.

As rotas de grupos existem também sem o prefixo de versão: /api/usergroups no lugar de /api/v1.0/usergroups. A lógica, a autenticação (HTTP Basic com e-mail:chave_de_api de um administrador, ou Bearer) e os campos são os mesmos. A diferença está nos ids: a forma sem versão devolve e aceita ids decimais dentro de string ("418"), como a Venddor 1.0 fazia, em vez de UUID. O UUID também é aceito.

Use a forma sem versão só se o seu cliente já foi escrito para ela, e não misture as duas formas no mesmo cliente. Para tudo o que é novo, use as rotas com /v1.0 descritas em Grupos.

GET/api/usergroupsAdmin

Listar grupos de usuários (rota sem versão)

Igual a GET /api/v1.0/usergroups: Grupos.

POST/api/usergroupsAdmin

Criar um grupo de usuários (rota sem versão)

Igual a POST /api/v1.0/usergroups: Grupos.

GET/api/usergroups/{id}Admin

Consultar um grupo de usuários (rota sem versão)

Igual a GET /api/v1.0/usergroups/{id}: Grupos.

Parâmetros de caminho

idstringobrigatório

Id do grupo, em decimal (ou UUID).

PUT/api/usergroups/{id}Admin

Atualizar um grupo de usuários (rota sem versão)

Igual a PUT /api/v1.0/usergroups/{id}: Grupos.

Parâmetros de caminho

idstringobrigatório

Id do grupo, em decimal (ou UUID).

DELETE/api/usergroups/{id}Admin

Excluir um grupo de usuários (rota sem versão)

Igual a DELETE /api/v1.0/usergroups/{id}: Grupos.

Parâmetros de caminho

idstringobrigatório

Id do grupo, em decimal (ou UUID).

GET/api/users/{user_id}/usergroupsAdmin

Grupos de um usuário (rota sem versão)

Igual a GET /api/v1.0/users/{user_id}/usergroups: Vínculo com grupos.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

POST/api/users/{user_id}/usergroupsAdmin

Vincular um usuário a um grupo (indisponível) (rota sem versão)

Igual a POST /api/v1.0/users/{user_id}/usergroups: Vínculo com grupos. Não disponível em lojas comuns: responde 404.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

PUT/api/users/{user_id}/usergroups/{group_id}Admin

Definir o status de um usuário num grupo (rota sem versão)

Igual a PUT /api/v1.0/users/{user_id}/usergroups/{group_id}: Vínculo com grupos.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

group_idstringobrigatório

Id do grupo, em decimal (ou UUID).

DELETE/api/users/{user_id}/usergroups/{group_id}Admin

Tirar um usuário de um grupo (rota sem versão)

Igual a DELETE /api/v1.0/users/{user_id}/usergroups/{group_id}: Vínculo com grupos.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

group_idstringobrigatório

Id do grupo, em decimal (ou UUID).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/usergroups?type=C"
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/users/1036002250/usergroups/418" \
  -H "Content-Type: application/json" -d '{"status": "A"}'

Resposta

200Grupos (trecho, ids decimais)

json

{
  "params": { "page": 1, "items_per_page": 1, "total_items": 1 },
  "usergroups": [
    { "usergroup_id": "418", "usergroup": "Atacado", "status": "A", "type": "C", "description": "", "members_count": 12 }
  ]
}

Erros

São os da rota /api/v1.0 correspondente. A mais comum: id decimal que não corresponde a nenhum registro.

Status	Quando	Corpo
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Grupo ou usuário inexistente (consulta e alteração)	`{"message":"Usergroup not found","status":404}`

Veja também

Rotas sem versão

As rotas /api/usergroups e /api/users/{id}/usergroups, gêmeas das /api/v1.0, que usam ids decimais.

Use a forma sem versão só se o seu cliente já foi escrito para ela, e não misture as duas formas no mesmo cliente. Para tudo o que é novo, use as rotas com /v1.0 descritas em Grupos.

GET/api/usergroupsAdmin

Listar grupos de usuários (rota sem versão)

Igual a GET /api/v1.0/usergroups: Grupos.

POST/api/usergroupsAdmin

Criar um grupo de usuários (rota sem versão)

Igual a POST /api/v1.0/usergroups: Grupos.

GET/api/usergroups/{id}Admin

Consultar um grupo de usuários (rota sem versão)

Igual a GET /api/v1.0/usergroups/{id}: Grupos.

Parâmetros de caminho

idstringobrigatório

Id do grupo, em decimal (ou UUID).

PUT/api/usergroups/{id}Admin

Atualizar um grupo de usuários (rota sem versão)

Igual a PUT /api/v1.0/usergroups/{id}: Grupos.

Parâmetros de caminho

idstringobrigatório

Id do grupo, em decimal (ou UUID).

DELETE/api/usergroups/{id}Admin

Excluir um grupo de usuários (rota sem versão)

Igual a DELETE /api/v1.0/usergroups/{id}: Grupos.

Parâmetros de caminho

idstringobrigatório

Id do grupo, em decimal (ou UUID).

GET/api/users/{user_id}/usergroupsAdmin

Grupos de um usuário (rota sem versão)

Igual a GET /api/v1.0/users/{user_id}/usergroups: Vínculo com grupos.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

POST/api/users/{user_id}/usergroupsAdmin

Vincular um usuário a um grupo (indisponível) (rota sem versão)

Igual a POST /api/v1.0/users/{user_id}/usergroups: Vínculo com grupos. Não disponível em lojas comuns: responde 404.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

PUT/api/users/{user_id}/usergroups/{group_id}Admin

Definir o status de um usuário num grupo (rota sem versão)

Igual a PUT /api/v1.0/users/{user_id}/usergroups/{group_id}: Vínculo com grupos.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

group_idstringobrigatório

Id do grupo, em decimal (ou UUID).

DELETE/api/users/{user_id}/usergroups/{group_id}Admin

Tirar um usuário de um grupo (rota sem versão)

Igual a DELETE /api/v1.0/users/{user_id}/usergroups/{group_id}: Vínculo com grupos.

Parâmetros de caminho

user_idstringobrigatório

Id do usuário, em decimal (ou UUID).

group_idstringobrigatório

Id do grupo, em decimal (ou UUID).

Exemplo de requisição

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/usergroups?type=C"
curl -u "$EMAIL:$API_KEY" -X PUT "$BASE_URL/api/users/1036002250/usergroups/418" \
  -H "Content-Type: application/json" -d '{"status": "A"}'

Resposta

200Grupos (trecho, ids decimais)

json

{
  "params": { "page": 1, "items_per_page": 1, "total_items": 1 },
  "usergroups": [
    { "usergroup_id": "418", "usergroup": "Atacado", "status": "A", "type": "C", "description": "", "members_count": 12 }
  ]
}

Erros

São os da rota /api/v1.0 correspondente. A mais comum: id decimal que não corresponde a nenhum registro.

Status	Quando	Corpo
401	Sem credenciais ou chave inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Grupo ou usuário inexistente (consulta e alteração)	`{"message":"Usergroup not found","status":404}`