Grupos organizam os usuários por área, equipe ou unidade — e definem o que cada um vê na plataforma. Este artigo mostra como colocar um usuário em um grupo, como tirá-lo e os dois cuidados que evitam vínculos errados.
Neste artigo
- Antes de começar
- Dois caminhos
- Vincular e desvincular
- Pelo cadastro de usuário
- Cuidados
- Problemas comuns
Antes de começar
- As credenciais da sua instância, reunidas em Passo 1: credenciais para integrar com a API da Engage, e um token gerado em Passo 4: Obtendo o access_token (POST /auth).
- O usuário de serviço precisa da permissão Importação de dados.
- O usuário e o grupo precisam existir, e o grupo precisa estar ativo.
- Teste em homologação:
https://sandbox.engage.bz/api/v1.
Dois caminhos
| Situação | Use |
|---|---|
| Vincular, desvincular ou mover usuários entre grupos | POST /{customer_id}/users/groups/import — este artigo |
| Cadastrar ou atualizar o usuário e já colocá-lo em grupos | O array groups do cadastro de usuário (POST /{customer_id}/users) |
O primeiro é o único que remove vínculo de forma direta. Para manter os grupos sincronizados com o seu sistema, é ele que você vai usar.
Vincular e desvincular
1Descubra o código externo do grupo
A remoção de vínculo funciona pelo código externo do grupo. Consulte pelos códigos que você conhece — vários de uma vez, separados por vírgula:
GET https://sandbox.engage.bz/api/v1/{customer_id}/groups/externalCodes/{codigo1},{codigo2}
Authorization: Bearer {access_token}
Resposta da consulta de grupos por código externo, com o group_id e o external_code destacados
Cada item de results traz o group_id, o name e o external_code do grupo. Se nenhum código for encontrado, a resposta é HTTP 404 — trate como "zero resultados".
2Envie os vínculos
POST https://sandbox.engage.bz/api/v1/{customer_id}/users/groups/import?customerToken={customer_token}
Authorization: Bearer {access_token}
Content-Type: application/json
[
{ "user_login": "joao.silva", "group_code": "depto-vendas", "status": "ativo" },
{ "user_login": "joao.silva", "group_code": "depto-suporte", "status": "delete" }
]| Campo | Obrigatório | Exemplo | Observação |
|---|---|---|---|
user_login | Sim | joao.silva | Login de um usuário que já existe na instância |
group_code | Sim | depto-vendas | O código externo do grupo. Para remover, só o código externo funciona |
status | Sim | ativo | ativo ou true vinculam; delete, inativo ou false removem |
Corpo do request de vínculo no Postman: um objeto que vincula e outro que remove
Sucesso
Cada item volta com "success": true e a mensagem "Operação concluída com sucesso". Confira o resultado consultando o usuário: os grupos aparecem no campo groups.
Pelo cadastro de usuário
Ao criar ou atualizar o usuário, o array groups aceita os IDs dos grupos:
[
{ "login": "joao.silva", "name": "João da Silva", "status": true, "groups": [9518, 9517] }
]Atenção
O array groups soma, nunca substitui. Enviar "groups": [10] para quem já está nos grupos 20 e 30 deixa o usuário em 10, 20 e 30. Para mover alguém de grupo, vincule ao novo e remova o antigo pela Etapa 2.
Cuidados
Cuidado
Para remover, o group_code precisa ser o código externo. Com o ID numérico, o vínculo não é removido — e a resposta ainda assim vem como sucesso. Para vincular, ID e código externo funcionam igual; só a remoção é exigente.
- HTTP 200 não significa que tudo deu certo. Percorra
resultse confira osuccessde cada item. - Grupo inativo não aceita vínculo. Se o grupo foi desativado na área administrativa, o retorno é
invalid_group_code. - Não use
PUT /users/{userId}/groups. Esse endpoint não grava os vínculos e mesmo assim responde201 Created. Use os caminhos deste artigo. - Envie sempre o cabeçalho
Authorization: Bearernas consultas de grupos. - Vínculo "sumiu" sem ninguém mexer? Confira se a sua rotina não está enviando
deletepara grupos que não deveria, e se o grupo não foi inativado.
Problemas comuns
O código de cada erro vem em detail_messages[].event_code.
| O que aparece | Causa provável | O que fazer |
|---|---|---|
login_is_required | Faltou user_login em algum item | Preencha o login em todos os itens |
invalid_login | O login não existe na instância | Cadastre o usuário antes |
group_code_is_required | Faltou group_code | Informe o código externo do grupo |
invalid_group_code | Grupo inexistente ou inativo | Confira na consulta da Etapa 1 |
status_is_required ou status_invalido | status ausente ou fora dos valores aceitos | Use ativo, true, delete, inativo ou false |
duplicate_data | O mesmo par usuário + grupo aparece duas vezes no envio | Remova a duplicidade |
success: true, mas o vínculo continua | Remoção feita com o ID numérico | Repita usando o código externo |
success: true, mas o usuário está em grupos a mais | O array groups do cadastro soma | Remova os antigos pela Etapa 2 |
| HTTP 401 | Token expirado ou sem a permissão necessária | Gere um novo token e confira a permissão Importação de dados |
Próximo passo
Confira os vínculos consultando o usuário pela API — veja Consultar usuário.
Precisa de ajuda?
Escreva para meajuda@engage.bz informando o customer_id, o ambiente e a resposta completa da chamada. Nunca envie senhas, tokens ou o client_secret por e-mail.
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo