Guias Práticos

Fluxo de Validação de Pessoas Candidatas Interno

Esse fluxo contempla a integração do Gupy R&S com um sistema interno de validação de pessoas candidatas utilizado pela sua empresa.

Suggest Edits

Nesse fluxo trabalhamos com duas pernas: Gupy > Sistema Interno e Sistema Interno > Gupy. O retorno será inserido na plataforma em formato de TAGs na candidatura da pessoa ou na forma de comentário na timeline.

Um dos exemplos mais usuais de aplicação desse fluxo é identificar se a pessoa candidata trabalha atualmente na empresa ou se já trabalhou. Entretanto, podemos utiliza-lo para as pessoas gestoras ou recrutadoras, validar as informações de regras de elegibilidade desta pessoa candidata, como por exemplo: Tempo de casa, salário atual vs previsto na posição...

📘

Esse fluxo utiliza webhook

Para realizar integrações utilizando Webhooks é necessário um agente integrador (middleware) para receber e tratar os dados.

Para implementar integrações a partir de webhooks é necessário uma configuração prévia através da própria API Gupy: Veja aqui mais informações sobre o recebimento de webhooks

❗️

Atenção!

A URL usada para receber o webhook DEVE ser um endereço HTTPS válido, exposto publicamente. Para configurar o webhook, consulte Webhook Configuração .

URLs com alta taxa de erro (100% dos erros nos últimos 7 dias) serão removidas sem aviso prévio.

O Webhook espera uma resposta em 30.000 ms. Caso a resposta não tenha ocorrido antes deste tempo, consideramos um timeout, consequentemente, um erro.

O sistema garante pelo menos uma entrega, então podem haver várias notificações do mesmo evento, use a propriedade id para identificar duplicatas.

Não há garantia de ordem de entrega, use a propriedade date para verificar qual evento aconteceu primeiro e classifique os eventos. Exemplo: um application.moved pode ser notificado antes de application.created

NÃO USE serviços como requestcatcher, eles podem expor dados.

Quando setamos algum valor no clientHeaders, o header padrão 'Content-type: application/json;charset=utf-8' não é mais enviado, pois o valor dos headers passa a ser o que foi definido. Se for necessário que o Content-type tenha sempre o valor padrão, recomendamos passá-lo junto no clientHeaders.

Definição de tags/comentários na timeline

Antes de criar as tags, é necessário definir o que ela informará para a pessoa recrutadora. Elas devem ser criadas a partir da relação que o cliente tem no sistema provedor.

Veja alguns exemplos de definição:

  • Enviar tags de "apto" e "inapto" para sinalizar se a pessoa deve continuar ou não no processo seletivo
  • Enviar tags apenas de "inapto" e não enviar tags para os que estão aptos ou vice-versa
    Esse processo precisa ser definido com o RH.

Caso o retorno do sistema terceiro seja muito grande para uma TAG é possível inseri-lo na forma de comentário na timeline do candidato.

Gerando o token

Para utilizar este fluxo, é necessário utilizar o Bearer Token gerado nas configurações avançadas da plataforma. Acesse nossa seção de autenticação para saber como gerar o o token de autenticação.

No momento de gerar o token habilite os seguintes endpoints da V1:

  • Applications
  • Webhook Configurations

Fluxo de integração

Configurar webhook application created

Exemplo de requisição

curl --request POST \
     --url https://api.gupy.io/api/v1/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --data '
{
     "action": "application.created",
     "status": "active",
     "postbackUrl": "https://urldo.agenteintegrador.net",
     "techOwnerName": "Nome Sobrenome",
     "techOwnerEmail": "[email protected]"
}
'

Exemplo de resposta

{
  "id": "d5b2eca6-09c5-4014-9eb8-1d729dd2e3d6",
  "action": "application.completed",
  "postbackUrl": "https://urldo.agenteintegrador.net",
  "status": "active"
}

Recebimento no agente integrador

O agente integrador receberá os dados webhook (conforme contrato-JSON application created) e será necessário guardar os seguintes campos:

  • body.data.job.id,
  • body.data.application.id
  • body.data.candidate.identificationDocument

Para fazer a validação da pessoa candidata, passe o CPF (body.data.candidate.identificationDocument) como parâmetro para o endpoint disponibilizado pelo sistema terceiro.

Importante relembrar que após o recebimento no agente integrador, é importante que você se comunique com o sistema interno, crie as regras/validações e retorno para o sistema da Gupy. Obs.: como este processo é único para cada sistema interno, não há uma orientação padrão de como realiza-lo.

Inserindo o retorno como TAGs na candidatura

Envie requisição para o endpoint PUT tags

Exemplo de requisição

curl --request PUT \
     --url https://api.gupy.io/api/v1/jobs/123456/applications/654321/tags \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '{"name":"Colaborador Interno"}'

Exemplo de resposta

{
  "id": 34486644,
  "candidateId": 33172137,
  "applicationId": 654321,
  "jobId": 123456,
  "name": "Colaborador Interno"
}

Obs.: para cada "tag" desejada, será necessário repetir o processo anterior e alterando o campo "name" da request.

Inserindo retorno como comentário na timeline

Envie requisição para o endpoint Creating a comment in candidate timeline

Exemplo de requisição

curl --request POST \
     --url https://api.gupy.io/api/v1/jobs/269691/applications/33428140/comments \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Após validação o candidato encontra-se apto para continuidade no processo seletivo"
}
'

Exemplo de resposta

{
  "id": 12307223,
  "userId": 22011,
  "hidden": false,
  "text": "Após validação o candidato encontra-se apto para continuidade no processo seletivo",
  "createdAt": "2023-05-13T10:24:26.838Z",
  "updatedAt": "2023-05-13T10:24:26.838Z"
}

Reprovando a pessoa candidata

Pode ser que o fluxo de negócio implique na reprovação da pessoa candidata caso ela não tenha atingido os critérios de validação/exames. Para realizar a reprovação siga as instruções abaixo:

  1. Acesse o endpoint moving an application
  2. Insira o jobId e applicationId que foram enviados pelo webhook
  3. Escolha o novo status como "reproved"
  4. Escolha o motivo da reprovação

Exemplo de requisição:

curl --request PATCH \
     --url https://api.gupy.io/api/v1/jobs/123456/applications/54734634 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "status": "reproved",
  "disapprovalReason": "test_result_below_cutoff"
}
'

Possíveis erros

Recebimento no agente integrador

  1. O ambiente precisa estar público para poder receber os dados, caso contrário, acontecerá um erro.
  2. O CPF não ser encontrado no sistema interno do cliente, e caso isto ocorra, entendemos que tal registro deverá ser ignorado.

Como ficará essa integração na Gupy?:

  • TAG na plataforma

  • Comentário na timeline na plataforma

Quando usar TAGs ou Inserir comentários na timeline?

As TAGs tem maior visibilidade na plataforma, de forma que não é preciso acessar a candidatura ou buscar dentre outros comentários aquele que deseja. Além disso é possível realizar filtros de busca a partir das mesmas.

Já os comentários na timeline são ótimas opções para casos onde o retorno não fique explícito ou quando o mesmo é muito grande (frases longas).

Updated 7 months ago