Fluxo de integração de Grupos

❗️

Pontos importantes para cadastro de grupos:

• Considere construir a hierarquia de Grupos inicialmente, antes de fazer a carga de colaboradores.
• Caso possua hierarquia de grupos, considere realizar os cadastros seguindo a hierarquia, cadastrando de cima para baixo, assim, o vínculo de grupo-pai pode ser realizado já no cadastro do grupo, não havendo necessidade de realizar alterações.
• Os grupos devem possuir nomes únicos e não repetidos dentro da plataforma.
• Os grupos devem seguir uma hierarquia vertical, não podendo haver "looping" de grupos, como por exemplo:

Hierarquia de Grupos Incorreta

Grupo A
Grupo B
Grupo C
Grupo A

• Caso ocorra o exemplo citado acima, a plataforma não irá reconhecer os grupos em sua hierarquia e devido a isso, os grupos, apesar de estarem cadastrados, não serão apresentados nos filtros dos resultados de pesquisas, necessitando do seu ajuste.

Hierarquia de Grupos Correta

Grupo A
Grupo B
Grupo C
Grupo D

Cadastrando grupo:

Para cadastrar grupos, disponibilizamos o método POST. Na requisição o campo name é de preenchimento obrigatório,. Já o campo parent_id deve ser informado caso o grupo criado tenha um grupo-pai.

Para cadastrar um grupo temos os seguintes campos disponíveis para envio:

Fluxo de integração:

• Acesse o endpoint Create a group e preencha as informações do cadastro do grupo conforme necessidade da empresa.

📘

Grupos com o mesmo nome não são aceitos.

É possível enviar um cadastro de cada vez. Caso haja algum grupo com o mesmo nome já exista, o grupo não será criado.

Exemplo de requisição:

curl --location 'https://www.pulses.com.br/api/engage/v1/groups/' \
--header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Cookie: PHPSESSID=p2luntge36c571jqi29a7f3tp4' \
--data ''

Exemplo de response:

Após recebido, a requisição será processada em segundo plano retornando a resposta conforme o modelo abaixo.

{
  "code": 1,
  "message": "success",
  "values": [
    {
      "id_group": 0,
      "name": "string",
      "parent_id": 0,
      "employees": 0
    }
  ]
} 

Atualizando grupo:

O endpoint Update a group é utilizado para realizar atualizações nos cadastros de grupos. Para que ele seja utilizado é necessário passar na requisição o id_group do grupo a ser atualizado.

🚧

O que é o id_group?

O id_group que faz parte das informações do grupo, é uma informação interna criada pela plataforma no momento da criação do cadastro, assim, sendo um identificador interno da plataforma.****

Exemplo de requisição: https://www.pulses.com.br/api/engage/v1/groups/{id_group}/

• Para atualizar um grupo temos os seguintes campos disponíveis para envio:

Início do fluxo de integração:

1. Recupere o id_group do grupos através dos endpoints Get all groups in alphabetical list ou Get all groups in tree list format . Caso deseje, também é possível procurar por um grupo específico passando na requisição o nome do grupo ao utilizar o endpoint Find groups by name;
2. Acesse o endpoint Update a Group;
3. Coloque o identificador no parâmetro correspondente;
4. Preencha os parâmetros referentes aos campos que necessitam da alteração, lembrando que o campo name não pode ser igual à outro já cadastrado.

Exemplo de requisição:

curl --location --request PUT 'https://www.pulses.com.br/api/engage/v1/groups/[id_group]/' \
--header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'Cookie: PHPSESSID=no7nfpgscdfaognveehf0ob54q' \
--data '{
    "name":"string"
}'

Exemplo de response:

Após recebido, a requisição será processada em segundo plano retornando a resposta conforme o modelo abaixo.

{
    "code": 1,
    "message": "Group successfully updated!",
    "values": {
        "id_group": "0"
    }
}

Excluindo um grupo:

❗️

Atenção ao excluir um grupo:

Antes de excluir um grupo, deve-se retirar todos os grupos-filhos vinculados a ele. Caso contrário, será recebido o retornos abaixo:

{
"code": 0,
"message": "It is not possible to delete a group with subgroups in it."
}

Para fazer a exclusão de um grupo, o envio das informações devem ser realizadas utilizando o método DELETE, identificando o id_group do grupo.

Para excluir um grupo temos os seguintes campos disponíveis para envio:

Fluxo de integração:

1. Recupere o id_group do grupos através dos endpoints Get all groups in alphabetical list ou Get all groups in tree list format .Caso deseje, também é possível procurar por um grupo específico passando na requisição o nome do grupo ao utilizar o endpoint Find groups by name;
2. Acesse o endpoint delete a group;
3. Coloque o identificador no parâmetro correspondente;

Exemplo de requisição:

curl --location --request DELETE 'https://www.pulses.com.br/api/engage/v1/groups/441043/' \
--header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Cookie: PHPSESSID=no7nfpgscdfaognveehf0ob54q' \
--data ''

Exemplo de response:

Após recebido, a requisição será processada em segundo plano retornando a resposta conforme o modelo abaixo.

{
    "code": 1,
    "message": "Group successfully deleted!"
}

Exemplo de erros mais comuns, e suas soluções:

• No filtros, no front-end, não está sendo possível filtrar por grupos, fica carregando a listagem infinitamente:
  Solução: Certamente existe um looping de grupos dentro de uma hierarquia, ou seja, indevidamente um grupo-pai foi vinculado como grupo-filho de uma hierarquia abaixo da dele.
  Grupo A
  Grupo B
  Grupo A
  Correto é:
  Grupo A
  Grupo B
  Grupo C
• "message": "The given name is already in use, please enter another name for the group."
  Solução: Já existe um grupo com esse mesmo nome, tente criar o grupo com outro nome.
• "message": "No group found"
  Solução: Não existe código com esse id_group ou esse nome. Conferir e buscar com as informações corretas.
• "message": "It is not possible to delete a group with subgroups in it."
  Solução: Não é possível excluir um grupo que contém subgrupos. Antes da exclusão os subgrupos devem ser desvinculados.

📘

NOTA

Esperamos que este material tenha sido esclarecedor e que a sua empresa colha bons frutos a partir da implementação da integração com a API de gestão de colaboradores! Caso você ainda tenha alguma dúvida, não hesite em entrar em contato com o nosso suporte: [email protected].