Guias Práticos

Fluxo de Envio e Retorno para Plataforma de Validações ou Exames externos

Este fluxo contempla o envio de candidaturas cadastradas na Gupy para plataformas externas de validações ou exames e o retorno das informações disponibilizadas pelo sistema terceiro.

Suggest Edits

Esse fluxo possibilita saber se a pessoa candidata foi aprovada ou não nas validações, além de suas notas ou informações adicionais que podem ser necessárias.

O retorno do sistema terceiro utilizado para os testes será inserido na plataforma em formato de TAGs na candidatura da pessoa ou comentários na timeline.

📘

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

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

Definição de etapas

Antes de iniciar o fluxo, é necessário definir em qual etapa as pessoas candidatas irão passar pela avaliação escolhida, pois a movimentação do candidato para essa etapa é o evento gatilho de disparo do webhook.

Caso seja necessário criar uma etapa, veja nesse guia como fazer isso. Lembrando que o nome da etapa fica público para todo os participantes do processo seletivo.

Fluxo de integração

Configurar webhook application moved

  1. Acessar POST Webhooks (https://developers.gupy.io/reference/createwebhook)
  2. Alterar parâmetro action para application.moved
  3. Inserir no postbackUrl o endereço para onde será direcionado o webhook
  4. Inserir bearer token e depois em "Try it!"

Exemplo de requisição

curl --request POST \
     --url https://api.gupy.io/api/v1/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "action": "application.moved",
     "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 webhook application moved event dispara sempre que a pessoa candidata é movida entre as etapas do processo seletivo, sendo necessário filtrar pela etapa desejada.

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

  • body.data.job.id,
  • body.data.application.id
  • body.data.application.currentStep.name

Operações na plataforma de validações

Após o recebimento das informações do webhook, é necessário uma ação por parte da pessoa candidata, sendo necessário que ela:

  1. Acesse o sistema de validações ou receba a data dos exames;
  2. Responda todos as perguntas necessárias ou compareça aos exames marcados;
  3. Receba um resultado das validações ou exames.

Apenas após a última ação da pessoa candidata é possível continuar para o fluxo de inserção de tags ou de comentários na timeline.

Parâmetros obrigatórios

Para fazer o envio das tags, é necessário obter a jobId da vaga e a applicationId da pessoa candidata, pois são parâmetros obrigatórios. Para isso:

  • Envie requisição para o endpoint GET Jobs
  • Utilize o parâmetro currentStep.name para filtrar apenas por pessoas candidatas que estão na etapa onde ficarão elegíveis para a verificação.
  • Envie requisição para o endpoint GET applications

Inserindo 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":"Apto"}'

Exemplo de resposta

{
  "id": 34486644, 
  "applicationId": 654321,
  "jobId": 123456,
  "name": "Apto"
}

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": "O candidato realizou os testes técnicos e foi aprovado"
}
'

Exemplo de resposta

{
  "id": 12307223,
  "userId": 22011,
  "hidden": false,
  "text": "O candidato realizou os testes técnicos e foi aprovado",
  "createdAt": "2023-05-13T10:24:26.838Z",
  "updatedAt": "2023-05-13T10:24:26.838Z"
}

Possíveis erros

Recebimento no agente integrador

O ambiente precisa estar público para poder receber os dados, caso contrário, acontecerá um erro.

Como ficará essa integração na Gupy?

  • TAG na plataforma

  • Comentário na timeline na plataforma

Updated 6 months ago