Guias Práticos

Fluxo de Captação de Pessoas Candidatas em Plataformas Externas

Esse fluxo permite que os dados de uma pessoa candidata sejam enviados pela API e ela seja convidada para o processo seletivo

Suggest Edits

O objetivo dessa integração é possibilitar a captação de pessoas candidatas em plataformas externas e enviá-las para uma vaga específica aberta na Gupy.

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

Início do fluxo de integração

  1. Captar e salvar os dados do candidato (nome, sobrenome, e-mail, telefone celular e url do perfil do Linkedin) em um formulário, site, chatbot ou quaisquer outras ferramentas que estejam sendo usada para essa finalidade.
  2. Consultar a vaga em que você deseja inserir a pessoa candidata, através do endpoint Listing Jobs para obter o id Gupy dessa vaga (jobId) que será utilizado nos próximos passos. No exemplo abaixo, utilizamos como parâmetros de filtro da vaga o nome da vaga e o code . O id que precisamos salvar está no results da consulta.

    Requisição:

    curl --request GET \
     --url 'https://api.gupy.io/api/v1/jobs?code=0266-4465559&name=P%26D&perPage=10&page=1' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'

    Resultado:

    {
  "results": [
    {
      "id": 22222,
      "code": "0266-4465559",
      "name": "P&D",
      "status": "published",
      "type": "vacancy_type_effective",
      "publicationType": "internal",
      "numVacancies": 2,
      "departmentId": 371703,
      "departmentName": "1CR |  Atendimento ao Cliente",
      "roleId": 495304,
      "roleName": "1CR |  Analista de Atendimento Pleno",
      "createdAt": "2023-03-16T20:33:24.724Z",
      "updatedAt": "2024-04-09T18:42:56.457Z",
      "branchId": null,
      "branchName": null
    }
  ],
  "totalResults": 1,
  "page": 1,
  "totalPages": 1
}

  3. Inserir a pessoa candidata na vaga em questão. Para isso acesso endpoint Creating an application inserindo as informações do candidato e o id da vaga (jobId) conforme o exemplo de requisição abaixo:
curl --request POST \
     --url https://api.gupy.io/api/v1/jobs/22222/applications \
     --header 'accept: application/json' \
     --header 'authorization: Bearer xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx' \
     --header 'content-type: application/json' \
     --data '
{
  "manualCandidate": {
    "insertionSource": "hunting",
    "name": "Maria",
    "lastName": "da silva souza",
    "email": "[email protected]",
    "mobileNumber": "1999999999",
    "linkedinProfileUrl": "https://meulinkedin.com"
  }
}
'

No retorno as informações serão como no exemplo abaixo:

{
  "id": 438051111,
  "tags": [],
  "score": null,
  "job": {
    "id": 22222,
    "name": "P&D"
  },
  "currentStep": {
    "id": 26439730,
    "name": "Cadastro"
  },
  "candidate": null,
  "manualCandidate": {
    "id": 52378000,
    "name": "Maria",
    "lastName": "da silva souza",
    "email": "[email protected]",
    "mobileNumber": "1999999999",
    "linkedinProfileUrl": "https://meulinkedin.com",
    "insertionSource": "hunting"
  }
}
  • Interpretando o retorno:
    • O primeiro id se refere ao id da candidatura que foi gerada, ou seja, o applicationId (chave única da relação do candidato com essa vaga) e que deve ser armazenado para os próximos passos da integração.
    • O objeto manualCandidate traz as informações que foram inseridas no POST e também o id gerado desse candidato no banco de dados, ou seja, esse é o identificador dessa pessoa candidata no ambiente.
  • Dúvidas frequentes:
    • Como a Gupy valida se essa pessoa já está na base ou não para gerar um novo Id do candidato? Através do e-mail inserido.
    • Quando eu insiro as informações no objeto manualCandidate mas a pessoa já existe na Gupy, ele vai dar erro ou duplicar o cadastro? O cadastro não é duplicado, retornamos o candidateId registrado para que aquele e-mail e você pode inserir à pessoa na vaga normalmente, porém deve utilizar o parâmetro candidateId ao invés do manualCandidate, veja um exemplo de retorno desse cenário: 
      {
  "title": "Conflict Error",
  "detail": "Candidate already exists with candidateId 52378000. You must use the candidateId instead of manualCandidate in the request.",
  "status": 409,
  "data": {
    "candidateId": 52378000
  }
}

    • Quando eu insiro uma pessoa candidata em uma vaga que ela já está inscrita, ocorre algum erro ou duplicação da candidatura? Não ocorre duplicação da candidatura, informamos que a pessoa já está inscrita e retornamos o id dessa candidatura (applicationId), veja o exemplo de retorno desse cenário: 
      {
  "title": "Conflict Error",
  "detail": "Candidate already exists in this job with applicationId 438051111",
  "status": 409,
  "data": {
    "applicationId": 438051111,
    "candidateId": 52378000
  }
}

  1. Convidando a pessoa candidata para participar do processo seletivo. Para que a pessoa candidata possa participar do processo seletivo além de inseri-la na vaga como fizemos até agora, precisamos enviar um convite para que ela aceite participar do processo e complete o seu cadastro nessa oportunidade. Para realizar esse processo utilize a API Create Invite onde você deverá passar na requisição os campos jobId e applicationId obtidos nos passos 2 e 3 respectivamente. Veja o exemplo abaixo:

Requisição:

curl --request POST \
     --url https://api.gupy.io/api/v1/jobs/22222/applications/438051111/invites \
     --header 'accept: application/json' \
     --header 'authorization: Bearer xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx'

Retorno:

Created

Updated 6 months ago