Fluxo de integração de Colaboradores.

Nesta seção estará disponível todas as informações necessárias para que as configurações da integração API para gestão de colaboradores seja realizada.

Suggest Edits

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 conterem informações.

Caso já haja algum registro com o 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:

Nome do campoDescriçãoObrigatório/regra de negócio
cpfCPF para usuários brasileirosCampo identificador obrigatório na ausência de informações nos campos e-mail e internal_number.
emaile-mail do usuárioCampo identificador obrigatório na ausência de informações nos campos cpf e internal_number.
internal_numberidentificador interno, usado geralmente para informar a matrícula do colaboradorCampo identificador obrigatório na ausência de informações nos campos cpf e e-mail.
namenome completo do usuárioNão obrigatório. Nome apresentado nas telas, será considerado o social_name, caso possua.
social_namenome socialNão obrigatório / ele será o nome principal na plataforma.
birth_namenome de nascimentoNão obrigatório. Caso possua social_name, esse nome não aparecerá nas telas e notificações, prevalecendo o social_name, mas continua no cadastro do colaborador.
cell_phonenúmero de telefoneNão obrigatório.
groupsnome ou id_group do(s) grupo(s) que o colaborador faz parteNão obrigatório. Caso o colaborador faça parte de 2 ou mais grupos, os identificadores informados devem ser informados separados por ponto e vírgula (;) dentro de um array.
leadersnome ou cpf ou internal_number ou id_person do líderNão obrigatório. Caso o colaborador tenha 2 ou mais líderes, os identificadores informados devem ser separados por ponto e vírgula (;) dentro de um array.
languageidioma da plataforma que o usuário acessará (pt-BR (padrão) / en-US / es-ES)Não obrigatório. Será o idioma que a plataforma terá durante o acesso do colaborador.
blockedbloqueia o recebimento de notificações/pulso (0 (padrão) ou 1)Não obrigatório. O bloqueio é utilizado em casos onde o colaborador está afastado temporiamente, exemplo: férias, licença maternidade, afastamento por doença, etc.
sexsexo do colaborador ("M" ou "F")Não obrigatório.
gendergênero do colaboradorNão obrigatório.
birthdaydata de nascimento (formato "YYYY-MM-DD")Não obrigatório.
hiring_datedata de contratação (formato YYYY-MM-DD)Não obrigatório.
positioncargo do colaboradorNão obrigatório.
scholaritygrau de escolaridadeNão obrigatório.
unit_businessunidade de negócioNão obrigatório. A informação de unidade de negócio é usada geralmente para informar o setor ou área que o colaborador está inserido.
unit_geographyunidade geográficaNão obrigatório. A informação de unidade geográfica é usada geralmente para informar o local de trabalho que o colaborador está inserido, principalmente quando a empresa possui unidades em diferentes cidades, estados e/ou países.
custom_attributesatributos customizadosNão obrigatório. Os atributos customizados deverão ser informados como um objeto, com os campos:"nome-atributo": "string" Ex.: "teste_atributo": "teste opção atributo"
tagstagsNão obrigatório. As tags que o colaborador possui serão informadas como string dentro de um array. Ex.: "tags": ["string1","string2",...,"string N"]

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 recebido, 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:

Nome do campoDescriçãoObrigatório/regra de negócio
cpfCPF para usuários brasileirosCampo identificador obrigatório na ausência de informações nos campos e-mail e internal_number.
emaile-mail do usuárioCampo identificador obrigatório na ausência de informações nos campos cpf e internal_number.
internal_numberidentificador interno, usado geralmente para informar a matrícula do colaboradorCampo identificador obrigatório na ausência de informações nos campos cpf e e-mail.
namenome completo do usuárioNão obrigatório.
social_namenome socialNão obrigatório / ele será o nome principal na plataforma.
birth_datenome de nascimentoNão obrigatório. Caso possua social_name, esse nome não aparecerá nas telas e notificações, prevalecendo o social_name, mas continua no cadastro do colaborador.
cell_phonenúmero de telefoneNão obrigatório.
groupsnome ou id_group do(s) grupo(s) que o colaborador faz parteNão obrigatório. Caso o colaborador faça parte de 2 ou mais grupos, os identificadores informados devem ser informados separados por ponto e vírgula (;) dentro de um array.
leadersnome ou cpf ou internal_number ou id_person do líderNão obrigatório. Caso o colaborador tenha 2 ou mais líderes, os identificadores informados devem ser separados por ponto e vírgula (;) dentro de um array.
languageidioma da plataforma que o usuário acessará (pt-BR (padrão) / en-US / es-ES)Não obrigatório. Será o idioma que a plataforma terá durante o acesso do colaborador.
blockedbloqueia o recebimento de notificações/pulso (0 (padrão) ou 1)Não obrigatório. O bloqueio é utilizado em casos onde o colaborador está afastado temporiamente, exemplo: férias, licença maternidade, afastamento por doença, etc.
sexsexo do colaborador ("M" ou "F")Não obrigatório.
gendergênero do colaboradorNão obrigatório.
birthdaydata de nascimento (formato "YYYY-MM-DD")Não obrigatório.
hiring_datedata de contratação (formato YYYY-MM-DD)Não obrigatório.
positioncargo do colaboradorNão obrigatório.
scholaritygrau de escolaridadeNão obrigatório.
unit_businessunidade de negócioNão obrigatório. A informação de unidade de negócio é usada geralmente para informar o setor ou área que o colaborador está inserido.
unit_geographyunidade geográficaNão obrigatório. A informação de unidade geográfica é usada geralmente para informar o local de trabalho que o colaborador está inserido, principalmente quando a empresa possui unidades em diferentes cidades, estados e/ou países.
custom_attributesatributos customizadosNão obrigatório. Os atributos customizados deverão ser informados como um objeto, com os campos:"nome-atributo": "string" Ex.: "teste_atributo": "teste opção atributo"
tagstagsNão obrigatório. As tags que o colaborador possui serão informadas como string dentro de um array. Ex.: "tags": ["string1","string2",...,"string N"]

❗️

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:

Nome do campoDescriçãoObrigatório/regra de negócio
id_personidentificador interno da plataformaObrigatório.
resignation_datedata de desligamento (formato YYYY-MM-DD)Obrigatório.
resignation_reasonmotivo do desligamentoObrigatório. Deve ser informado uma string com as opções: "V" para "Voluntário", "I" para "Involuntário", "TC" para "Término de Contrato" e "NA" para "Não se Aplica".
move_subordinatesmover subordinados para a liderança acimaNão obrigatório. Caso o colaborador desligado seja um líder, essa informação deve ser inserida para que os subordinados deste sejam inseridos sob a liderança acima. Deve ser inserido um boolean, true se existir a necessidade de movimentação de liderados ou false se não.

❗️

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.

Updated about 1 month ago