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 (ex.: Whatsapp, chatbot, site da empresa, etc.) 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 token de autenticação.

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

  • Applications
  • Jobs

Fluxo de integração

  1. Consultando a vaga em que você deseja inserir a pessoa candidata

Faça a consulta 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. O id que precisamos salvar está no results da consulta.

  1. Captando e salvando os dados do candidato

Consulte os dados como: 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.

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
}

  1. Inserindo a pessoa candidata na vaga escolhida

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>"
  }
}
'

Em caso de sucesso o retorno será conforme 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.

  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

Exemplo de interações:

Chatbot:
Olá! Seja bem-vindo ao processo seletivo. Me diga para qual área deseja localizar vagas?

Candidato:
Oi! Estou à procura de vagas para Analista de Marketing.

Back-end: GET https://api.gupy.io/api/v1/jobs?name=Analista de Marketing&perPage=10&page=1

Chatbot:
Ótimo! 😊 Encontrei a vaga de Analista de Marketing Pleno aberta em nossa unidade de São Paulo. Essa mesma?

Candidato:
Sim, essa mesmo.

Chatbot:
Perfeito! Para prosseguir com sua candidatura, vou precisar de algumas informações.
Escreva seu primeiro nome.
Escreva seu sobrenome.
Escreva seu CPF.
Escreva seu e-mail.
Digite seu número de celular com o DDD para contato.

Candidato:
João Pedro
da Silva
[email protected]
(11) 91234-5678

Chatbot:
Tudo certo até aqui. 😊 Agora, só mais uma etapa: você poderia enviar seu perfil do LinkedIn?

Candidato:
https://meulinkedin.com

Back-end: POST https://api.gupy.io/api/v1/jobs/{jobId}/applications

Chatbot:
Sua candidatura foi registrada. Em breve, você receberá um convite para participar do nosso processo seletivo na Gupy

Deseja se aplicar em mais alguma vaga?

Candidato:
Por enquanto não. 

Chatbot:
Ótimo! Qualquer dúvida, é só me chamar por aqui. Boa sorte no processo, João! 🍀

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
  }
}

Updated 4 days ago