Guias Práticos

Fluxo de Admissão da Pessoa Contratada

Suggest Edits

Esse fluxo é destinado ao envio de dados das candidaturas que chegaram à fase final de Contratação nas vagas do R&S Gupy para um sistema de onboarding/admissão utilizado pela sua empresa.

A partir desse envio é possível receber retorno do sistema e adicioná-lo - em forma de "tag"- ou comentário na timeline para registro de status final ou informação relevante da conclusão do processo.

📘

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.

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
  • Jobs
  • Webhook Configurations

Fluxo de integração

Configurar webhook Candidate Hired Event

  • Acessar endpoint POST Webhooks (https://developers.gupy.io/reference/createwebhook)
  • Ajustar o parâmetro "action" para candidate.hired
  • Inserir no "postbackUrl" o endereço (URL segura) para onde será direcionado o webhook
  • Inserir o Bearer token e então no botão "Try it!"

Exemplo de requisição

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

Exemplo de resposta para um webhook cadastrado com sucesso

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

Recebimento no agente integrador

O evento será disparado quando esses dois requisitos forem cumpridos:

  1. Pessoa candidata for movida para a etapa de contratação (última etapa padrão nas vagas);
  2. As informações de contratação que aparecerem na tela de dados de contratação forem salvos pela pessoa recrutadora.

O agente integrador receberá os dados webhook (conforme contrato-JSON candidate hired)

❗️

Atenção!

O exemplo utilizado acima trata-se de um webhook modelo e não é indicado trabalhar o desenvolvimento a partir do mesmo. O ideal é que o desenvolvimento seja a partir de um payload real.

Para consultar como obter payloads reais, clique aqui.

Inserindo retorno como TAG

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":"Contratação finalizada"}'

Exemplo de resposta

{
  "id": 34486644,
  "candidateId": 33172137,
  "applicationId": 654321,
  "jobId": 123456,
  "name": "Contratação finalizada"
}

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 foi contratado para a posição de Engenheiro de Software"
}
'

Exemplo de resposta

{
  "id": 12307223,
  "userId": 22011,
  "hidden": false,
  "text": "O candidato foi contratado para a posição de Engenheiro de Software",
  "createdAt": "2023-05-13T10:24:26.838Z",
  "updatedAt": "2023-05-13T10:24:26.838Z"
}

Mapeamento de campos

Alguns campos enviados pela Gupy no webhook são na verdade uma lista de opções. Para auxiliá-los no processo de mapeamento trazemos desenvolvemos o glossário do webhook candidate.hired, onde vocês podem consultar todas as opções que um campo pode conter e suas regras de negócio, clique aqui para conhecer.

Possíveis erros

Recebimento no agente integrador

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

Informações obrigatórias faltantes

Pode ser que o sistema de admissão/onboarding utilizado pela sua empresa requer com obrigatoriedade algumas informações, portanto antes de preencher as informações da contratação em tela, verifique se todas as informações do candidato e da vaga estão preenchidas corretamente. Pode ser necessário inserir informações manualmente caso as mesmas não existam na Gupy.

Se o candidato aprovado foi inserido manualmente na vaga, lembre-se que é necessário que ele aceite o convite enviado por e-mail para que as suas informações pessoais sejam disponibilizadas na Gupy e o fluxo ocorra com sucesso.

Admissão da Pessoa Contratada x Candidato admitido

Para os clientes que possuem o produto Gupy Admissão temos um fluxo de negócio comumente utilizado chamado de Candidato admitido. Caso esse seja o seu caso, clique aqui para obter mais informações.

Updated 6 months ago