Fluxo de integração de Colaboradores

Cadastrando colaborador:

📘

Campos identificadores

Os campos cpf, internal_number e email são identificadores do colaborador, sendo obrigatório o preenchimento de pelo menos um deles, e podendo os três campos serem preenchidos.

Caso já haja algum registro com o mesmo e-mail, internal_number ou CPF, o usuário não será criado.

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

Fluxo de integração:

• Acesse o endpoint Create a employee e preencha as informações do cadastro do colaborador conforme necessidade da empresa. (É possível enviar apenas um cadastro de cada vez.)

Exemplo de requisição:

curl --location 'https://www.pulses.com.br/api/engage/v1/employees/' \
--header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "name": "string",
    "social_name": "string", 
    "birth_name": "string", 
    "email": "string",
    "cpf": "string",
    "internal_number": "string"
    "cell_phone": "string",
    "groups": "string",
    "leaders": "string",
    "blocked": 0,
    "language": "string",
    "sex": "string",
    "gender": "string",
    "birthday": "string",
    "position": "string",
    "scholarity": "string",
    "hiring_date": "string",
    "unit_business": "string",
    "unit_geography": "string",
    "custom_attributes": {
      "nome-atributo": "string", 
      "nome-atributo1": "string", 
      "nome-atributo2": "string"            
    },
    "tags": ["string","string",...,"string N"]
}'

Exemplo de response:

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

{
  "code": 1,
  "message": "Employee successfully registered!",
  "values": {
    "sex": "string",
    "name": "string",
    "email": "string",
    "internal_number": "string",
    "language": "pt-BR",
    "id_client": "0",
    "created_at": "YYYY-MM-DD HH:MM:SS",
    "token": "string",
    "id_person": "string",
    "id_attribute": "0",
    "hasNotificationToSent": false
  }
}

🚧

Atribuição de Perfis de Acesso

A atribuição de perfis de acesso (permission_profiles) não está disponível via API, devendo ser feita diretamente via plataforma, na tela de gestão de colaboradores. O perfil de acesso (permission_profiles) será apresentado apenas na consulta de colaboradores, de forma informativa.

🚧

Atribuição de Cargo

A atribuição de cargos (position) deverá ser realizada com muita atenção, pois caso seja informado um nome de cargo incorretamente, um novo cargo será cadastrado com este nome incorreto.

🚧

Atribuição de Grupos

A atribuição de cargos (groups) deverá ser realizada com muita atenção, pois caso seja informado um nome de grupo incorretamente, um novo grupo será cadastrado com este nome incorreto.

Atualizando cadastro de colaborador:

O endpoint Update a employee é utilizado para realizar atualizações nos cadastros de colaboradores. Para que ele seja utilizado é necessário identificar e citar na requisição o id_person do colaborador.

🚧

O que é o id_person?

O id_person que faz parte das informações do colaborador, é 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/employees/{id_person}/​

Para atualizar o cadastro de um colaborador temos os seguintes campos disponíveis para envio:

❗️

Atenção:

Quando a requisição para atualização de informações do cadastro de colaboradores for enviada contendo todos os campos, deve-se atentar a não enviar os campos resignation_date e resignation_reason, estes devem ser informados apenas nos casos de desligamento. Caso sejam informados em um caso que não seja de desligamento, mantendo os campos em branco, retornará um erro solicitando seus preenchimentos.

Início do fluxo de integração:

1. Recupere o id_person dos colaboradores através do endpoint Get all employees. É possível procurar por um colaborador específico passando na requisição o cpf, internal_number ou e-mail;
2. Acesse o endpoint Update a employee
3. Coloque o identificador no parâmetro correspondente;
4. Preencha os parâmetros referentes aos campos que necessitam da alteração

Exemplo de requisição:

curl --location --request PUT 'https://www.pulses.com.br/api/engage/v1/employees/https://www.pulses.com.br/api/engage/v1/employees/{id_person} \
--header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'Cookie: PHPSESSID=p2luntge36c571jqi29a7f3tp4' \
--data '{
    "name": "string",
    "social_name": "string",  
    "birth_name": "string",
    "email": "string",
    "cpf": "string",
    "internal_number": "string"
    "cell_phone": "string",
    "groups": "string",
    "leaders": "string",
    "blocked": 0,
    "language": "string",
    "sex": "string",
    "gender": "string",
    "birthday": "string",
    "position": "string",
    "scholarity": "string",
    "hiring_date": "string",
    "unit_business": "string",
    "unit_geography": "string",
    "custom_attributes": {
      "nome-atributo": "string", 
      "nome-atributo1": "string", 
      "nome-atributo2": "string"            
    },
    "tags": ["string","string",...,"string N"]
}'

Exemplo de response:

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

{
  "code": 1,
  "message": "Employee successfully updated!",
  "values": {
    "sex": "string",
    "name": "string",
    "email": "string",
    "internal_number": "string",
    "language": "pt-BR",
    "id_client": "0",
    "created_at": "YYYY-MM-DD HH:MM:SS",
    "token": "string",
    "id_person": "string",
    "id_attribute": "0",
    "hasNotificationToSent": false
  }
}

🚧

Atribuição de Perfis de Acesso

A atribuição de perfis de acesso (permission_profiles) não está disponível via API, devendo ser feita diretamente via plataforma, na tela de gestão de colaboradores. O perfil de acesso (permission_profiles) será apresentado apenas na consulta de colaboradores, de forma informativa.

🚧

Atribuição de Cargo

A atribuição de cargos (position) deverá ser realizada com muita atenção, pois caso seja informado um nome de cargo incorretamente, um novo cargo será cadastrado com este nome incorreto.

🚧

Atribuição de Grupos

A atribuição de cargos (groups) deverá ser realizada com muita atenção, pois caso seja informado um nome de grupo incorretamente, um novo grupo será cadastrado com este nome incorreto.

Desligando um colaborador dentro da plataforma:

Para fazer o desligamento de colaboradores, o envio das informações podem ser realizadas podemos utilizar os métodos PUT (não recomendado) ou DELETE. Para que qualquer um desses métodos sejam utilizados, é necessário identificar e citar na requisição o id_person do colaborador.

Para desligar um colaborador temos os seguintes campos disponíveis para envio:

❗️

Importante:

• O campo resignation_reason deve conter obrigatoriamente os valores “I” para “Involuntário”, “V” para “Voluntário” ou “NA” para “Não se aplica”.
• Os campos resignation_date e resignation_reason devem ser enviados juntos, contendo as duas informações, caso seja enviado apenas um campo, retornará um erro solicitando a inclusão do campo faltante.
• O campo move_subordinate irá transferir os liderados do líder desligado para a liderança acima. Caso o líder desligado seja o topo da hierarquia, ou seja, não possui líder, os liderados do líder desligado ficarão com a informação de liderança em branco.

Início do fluxo de integração:

1. Recupere o id_person dos colaboradores através do endpoint Get all employees. É possível procurar por um colaborador específico passando na requisição o cpf, internal_number ou e-mail;
2. Acesse o endpoint Delete a employee;
3. Coloque o identificador no parâmetro correspondente;
4. Preencha os parâmetros referentes aos campos com as informações de desligamento do colaborador;

Exemplo de requisição:

curl --location --request DELETE 'https://www.pulses.com.br/api/engage/v1/employees/{id_person}/' \
--header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--header 'Cookie: PHPSESSID=p2luntge36c571jqi29a7f3tp4' \
--data '{
  "resignation_date":"YYYY-MM-DD",
  "resignation_reason":"V"
}'

Exemplo de response:

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

{
    "code": 1,
    "message": "Employee successfully deleted",
    "values": {
        "id_person": "0",
        "id_client": "0",
        "id_attribute": "0"
    }
}

🚧

Histórico de Respostas do colaborador desligado.

O desligamento de um colaborador não irá apagar o histórico de respostas desse colaborador. O score considerará o histórico das respostas desse colaborador até o momento do seu desligamento.

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

• "message": "Social Security Number is already being used by another employee"
  Solução 1: Está sendo criado um colaborador e já existe o e-mail ou CPF cadastrado.
  Solução 2: Se os dados de e-mail, CPF ou identificador interno são únicos, verificar se a formatação do body está correto.
• "message": "Leader not found: JOAOZINHO, check if the leader's name is identical to the name entered in the import table."
  Solução 1: Verificar se existe um colaborador com o mesmo nome informado no campo “leaders”.
  Solução 2: Verificar se existem dois colaboradores com o mesmo nome. Caso seja esse caso, será necessário informar outro identificador para vincular a liderança, serão aceitos CPF, internal_number, e-mail ou id_person.
• "message": "It is not possible to delete this user because he has led"
  Solução: Esse colaborador que está sendo desligado possui liderados vinculados. Antes do seu desligamento os seus liderados devem ser desvinculados. Ou usar o campo "move_subordinates":"true" assim os liderados do líder desligado será vinculado a liderança superior.
• "message": "It is not possible to assign a leader from the hierarchy below the employee as the leader of the same"
  Solução: Não é possível atribuir um liderado do colaborador como líder do mesmo: Um colaborador não pode ser liderado de seu próprio liderado, direta ou indiretamente na hierarquia. Terá que ser verificado quem é o líder e liderado que está no envio e corrigir as informações.
• "message": "Employees are not allowed to be leaders of themselves"
  Solução: Não é possível o colaborador ser líder de si mesmo. Solicitar a correção das informações.
• Se a razão de desligamento (resignation_reason) for passada, é necessário passar a data de desligamento (resignation_date).
• Se a data de desligamento for passada (resignation_date), é necessário passar o motivo de desligamento (resignation_reason).

📘

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: https://suporte.gupy.io/s/suporte/.