Fluxo de Extração de dados para fins de BI
Esta documentação tem como objetivo apresentar a nossa API como uma fonte de extração de dados.
A extração de dados tem como aplicação a composição de Banco de Dados e então seu uso interno junto à aplicações de BI (Business Intelligence) tais como PowerBI, Tableau, Data Studio, etc.; ou ainda, a montagem de relatórios e consultas personalizadas de métricas.
A Gupy fornece insumo (dados) através de suas APIs e Webhooks para que você possa construir uma forma de armazenar e exibir esses dados de acordo com a sua necessidade e demanda.
Chamadas diretas a partir da plataforma de dados (PowerBI, Tableau..)
Enviamos os dados em formato JSON, e normalmente as ferramentas não possuem a funcionalidade de tratamento do dado, por isso é necessário um middleware que realize a tabulação dos dados e não que a aplicação de dados faça a chamada direto.
Assim, o fluxo precisa ser: Recebe JSON > Trata os dados > Disponibiliza no formato adequado para o PowerBI > Monta as visualizações.
Formas de obtenção de dados a partir da API
Apresentamos o fluxo de integração para a obtenção dos dados. Lembrando que os dados a serem extraídos dependem de:
- Quais métricas a área de R&S/Análise de dados deseja apurar;
APIs trabalham por padrão com GMT 0
Considere o fator acima na construção de seus dashboards, pois quando ocorrem atualizações, o campo updatedAt registra a atualização considerando o GMT 0. Assim, se aplicarmos o filtro updatedAfter na consulta, ele irá trazer os dados considerando o horário do campo updatedAt.
Exemplo prático: Se uma atualização em uma candidatura ocorrer às 10:00 ela ficará registrada no campo updatedAt às 13:00. Caso o filtro de data seja construído com o valor de horário T10:30:00 a atualização das 10:00 irá aparecer, pois ela está registrada às 13:00.
Fluxo de integração - Consumindo a API
- Preparar a infraestrutura para desenvolvimento do fluxo:
- Configurar a base de dados para receber os dados da Gupy [Exemplo: Data Lake]
- Configurar o middleware que irá realizar a tradução dos dados para a ferramenta de BI
- Definir quais métricas serão utilizadas para construção do dashboard no BI.
- Obter o token de autenticação.
- Implementar o consumo recorrente das APIs. Através da versão V2 o consumo pode ser incremental, pois os endpoints da V2 possuem um novo parâmetro no filtro da chamada, chamado
updatedAfter, que permite obter os registros em intervalos baseados na data/hora de criação ou atualização das movimentações. Os intervalos de busca dos dados podem ser, por exemplo, o período de um dia fechado ou a partir da data/hora desde a última busca foi efetuada.
A documentação técnica destes novos endpoints pode ser acessada neste link.
Endpoints complementares
Dados complementares podem ser obtidos em endpoints secundários, a partir dos webhooks e endpoints citados acima, se utilizando de campos chaves (IDs) das entidades envolvidas. A documentação técnica dos demais endpoints pode ser acessada neste link.
Diagrama de relacionamento das principais entidades X endpoints
Detalhamos melhor o relacionamento destas 3 entidades no diagrama abaixo:
Detalhamento da estrutura dos novos endpoints (API v2.0)
Campos disponíveis e token de autorização:
Nem todos os campos disponíveis na v1 estão presentes na v2, portanto provavelmente será necessário consumir as duas versões das APIs. Nesses casos será necessário um token com permissão dos endpoints de ambas as versões, se atente a isso no momento da criação do token.
Os parâmetros são úteis para filtrar a extração dos dados a partir de determinados campos, neste caso recomendamos a utilização do parâmetro updatedAfter sozinho ou combinado com outro(s) parâmetro(s).
Applications - Parâmetros possíveis de Header
| CAMPO | ATRIBUIÇÃO |
|---|---|
| jobId | Código chave da vaga do contexto. Pode ser obtido previamente via webhook ou consumindo o endpoint de Listing Jobs |
| candidateId | Código chave do cadastro da pessoa candidata da candidatura do contexto |
| currentStepId | Número da etapa atual em que a pessoa candidata encontra-se |
| applicationId | Código chave da candidatura (vaga x pessoa candidata) |
| updatedAfter | Candidaturas criadas ou atualizadas a partir da data/hora informada |
| status | Status da candidatura (em andamento, contratada, reprovada, desistida) |
| expand | Lista de dados de entidades (sub-objetos) que se deseja obter no response, além do objeto da estrutura básica de dados da candidatura |
| maxPageSize | Quantidade máxima de registros a serem retornados por página, <= 100 |
| pageToken | Token de uma página em específico que se deseja consultar (obtido em consulta prévia) |
Applications - Glossário de dados do result (200-sucesso)
| CAMPO | ATRIBUIÇÃO |
|---|---|
| id | Código chave da candidatura (vaga x pessoa candidata) |
| status | Status da candidatura (em andamento, contratada, reprovada, retirada) |
| createdAt | Data/hora em que a candidatura foi criada |
| updatedAt | Data/hora mais recente em que a candidatura foi atualizada |
| jobId | Código chave da vaga do contexto. Pode ser obtido previamente via webhook ou consumindo o endpoint de Listing Jobs. Na tela do R&S Gupy, este código é visível em: Gestão de vagas abaixo do nome da vaga Na URL quando acessado detalhes da vaga |
| currentStepId | Número da etapa atual em que a pessoa candidata encontra-se na vaga |
| candidateId | Código chave do cadastro da pessoa candidata na Gupy |
| prospectId | Código chave do cadastro da pessoa candidata enquanto prospecto (caso tenha sido inserida manualmente na vaga por um usuário) |
| affinity | Score de afinidade atribuída pela Gaia, a IA da Gupy, à pessoa candidata conforme os requisitos da vaga |
| hiredAt | Data/hora em que a pessoa candidata foi movida para a etapa final de Contratado (se o status = hired) |
| disqualifiedAt | Data/hora em que a pessoa candidata foi reprovada (se o status = disqualified) |
| withdrawnAt | Data/hora em que a pessoa candidata abandonou o processo seletivo (se o status = withdrawn) |
| source | Canal de origem pela qual a pessoa candidata se inscreveu para a vaga do contexto |
| referral | Objeto contendo dados sobre eventual indicação da pessoa para a vaga do contexto (se aplicável) |
| referral.referrer | Sub-objeto contendo dados da pessoa colaboradora referenciada |
| referral.referrer.name | Nome da pessoa colaboradora |
| referral.referrer.email | E-mail da pessoa colaboradora |
| referral.status | Status da indicação definido pela pessoa colaboradora - "h-1": "Atribuição", "0-0": "id", "0-1": " |
| admission | Objeto contendo dados sobre a contratação da pessoa (se status = hired) |
| admission.type | Motivo da contratação |
| admission.date | Data/hora em que a pessoa candidata chegou na etapa final de Contratado |
| admission.salary | Sub-objeto de dados do salário da pessoa contratada |
| admission.salary.amount | Valor do salário |
| admission.salary.currency | Moeda do salário |
| admission.positionId | Número da posição/cadeira em que a pessoa candidata foi contratada (se foi definida na vaga) |
| tags | Etiquetas associadas a pessoa durante a candidatura do contexto |
| disqualification | Objeto contendo dados sobre a reprovação da pessoa na candidatura (se status = disqualified) |
| disqualification.reason | Motivo da reprovação |
| disqualification.observation | Observações |
| disqualification.trigger | Se a reprovação foi feita por algum usuario (manual) ou de forma automática (ex. via teste) |
| disqualification.feedbackSentAt | Data/hora em que o feedback de reprovação foi enviado à pessoa |
| disqualification.disqualifiedBy | Pessoa usuária que reprovou a pessoa candidata |
| expand | Objeto contendo blocos de dados complementares de entidades (candidate, job, currentStep, position, prospect) |
| expand.candidate | Sub-objeto referente aos dados da pessoa candidata |
| expand.candidate.id | Código chave do cadastro da pessoa candidata na Gupy |
| expand.candidate.firstName | Primeiro nome da pessoa candidata |
| expand.candidate.LastName | Sobrenome da pessoa candidata |
| expand.candidate.emailAddresses | E-mail da pessoa candidata |
| expand.job | Sub-objeto referente aos dados da vaga |
| expand.job.id | Código chave da vaga do contexto |
| expand.job.name | Nome da vaga |
| expand.job.status | Status atual da vaga |
| expand.currentStep | Sub-objeto referente à etapa atual da candidatura |
| expand.currentStep.id | Número da etapa da atual da candidatura |
| expand.currentStep.name | Nome da etapa da atual da candidatura |
| expand.currentStep.status | Status da candidatura na etapa atual da candidatura |
| expand.position | Sub-objeto referente a cada posição (uma ou mais) prevista(s) na vaga |
| expand.position.id | Numeral referência da posição na vaga (1, 2, 3…) |
| expand.position.code | Código personalizado atribuído à posição na vaga (preenchimento opcional) |
| expand.prospect | Sub-objeto referente às informações da pessoa candidata enquanto prospecto (se inserida manualmente na vaga por um usuário) |
| expand.prospect.id | Código chave do prospect |
| expand.prospect.firstName | Primeiro nome do prospect |
| expand.prospect.lastName | Sobrenome do prospect |
| expand.prospect.emailAddresses | Endereço de e-mail do prospect |
| nextPageToken | Chave de identificação da página corrente. Necessária para navegar dentre as páginas do result da consulta efetuada |
Candidates - Parâmetros possíveis de Header
Atenção
Para consultas sem utilização do filtro “updatedAfter” ou de “ids”, implementamos o padrão de retornar apenas os dados de pessoas candidatas que atualizaram suas informações nos últimos 6 meses a partir da data de consulta, em vez de abranger todo o histórico disponível na base de dados
| CAMPO | ATRIBUIÇÃO |
|---|---|
| id | Código chave do cadastro da pessoa candidata na Gupy |
| updatedAfter | Cadastro de pessoas candidatas criado ou atualizado a partir da data/hora informada |
| updatedBefore | Cadastro de pessoas candidatas criado ou atualizado até a data/hora informada |
| maxPageSize | Quantidade máxima de registros a serem retornados por página, <= 100 |
| pageToken | Token de uma página em específico que se deseja consultar (obtido em consulta prévia) |
Candidates - Glossário de dados do result (200-sucesso)
| CAMPO | ATRIBUIÇÃO |
|---|---|
| id | Código chave do cadastro da pessoa candidata na Gupy |
| firstName | Primeiro nome da pessoa candidata |
| lastName | Sobrenome da pessoa candidata |
| emailAdresses | Endereço de e-mail da pessoa candidata |
| identityDocument | Objeto contendo o documento de identificação principal da pessoa candidata |
| identityDocument.number | Número do CPF da pessoa candidata |
| phoneNumbers | Array contendo número de telefone(s) de contato da pessoa candidata |
| birthDate | Data de nascimento da pessoa candidata |
| createdAt | Data em que o cadastro da pessoa candidata foi feito na Gupy |
| updatedAt | Data da atualização mais recente do cadastro da pessoa candidata |
| addresses | Array contendo objeto(s) com dados de endereço(s) da pessoa candidata |
| addresses.street | Logradouro |
| addresses.city | Cidade |
| addresses.stateCode | UF |
| addresses.zipCode | CEP |
| addresses.countryCode | Código do país (ex. “BR”) |
| education | Array contendo objeto(s) do histórico de formação da pessoa candidata |
| education.degree | Grau de formação |
| education.institution | Instituição de ensino |
| education.course | Curso |
| education.status | Status de conclusão do curso |
| education.startMonth | Mês de início do curso |
| education.startYear | Ano de início do curso |
| education.endMonth | Mês de término do curso (se concluído) |
| education.endYear | Ano de término do curso (se concluído) |
| languages | Array contendo objeto(s) sobre os idiomas dominados pela pessoa candidata |
| languages.level | Nível do idioma |
| languages.name | Nome do idioma |
| nextPageToken | Chave de identificação da página corrente. Necessária para navegar dentre as páginas do result da consulta efetuada |
Prospects - Parâmetros possíveis de Header
| CAMPO | ATRIBUIÇÃO |
|---|---|
| updatedAfter | Pessoas candidatas enquanto prospectos (caso tenha sido inserida manualmente na vaga por um usuário) criadas partir da data/hora informada |
| maxPageSize | Quantidade máxima de registros a serem retornados por página, <= 100 |
| pageToken | Token de uma página em específico que se deseja consultar (obtido em consulta prévia) |
Prospects - Glossário de dados do result (200-sucesso)
| CAMPO | ATRIBUIÇÃO |
|---|---|
| nextPageToken | Token de uma página em específico que se deseja consultar (obtido em consulta prévia) |
| id | Código chave do cadastro da pessoa candidata enquanto prospecto (caso tenha sido inserida manualmente na vaga por um usuário) |
| firstName | Primeiro nome da pessoa candidata enquanto prospecto |
| lastName | Sobrenome da pessoa candidata enquanto prospecto |
| emailAddress | E-mail da pessoa candidata enquanto prospecto |
| phoneNumber | Número de contato da pessoa candidata enquanto prospecto |
| socialProfiles | Perfis em redes sociais da pessoa candidata enquanto prospecto |
| updatedAt | Data da atualização mais recente do cadastro da pessoa candidata |
Jobs - Parâmetros possíveis de Header
| CAMPO | ATRIBUIÇÃO |
|---|---|
| id | Código chave do cadastro da vaga na Gupy |
| updatedAfter | Vagas criadas partir da data/hora informada |
| expand | Lista de dados de entidades (sub-objetos) que se deseja obter no response, além do objeto da estrutura básica de dados da candidatura |
| maxPageSize | Quantidade máxima de registros a serem retornados por página, <= 100 |
| pageToken | Token de uma página em específico que se deseja consultar (obtido em consulta prévia) |
Jobs - Glossário de dados do result (200-sucesso)
| Campo | Atribuição |
|---|---|
| id | Código chave do cadastro da vaga na Gupy |
| acceptsDisabledPerson | Aceitação ou não de candidaturas de pessoas com deficiência para |
| code | Código chave oriundo de sistema externo do cliente |
| branchId | Código chave do cadastro da pessoa responsável por criar a vaga |
| creatorId | Código chave do cadastro da pessoa responsável por criar a vaga |
| departmentId | Código chave do departamento em que a vaga está inserida |
| name | Nome da vaga |
| numPositions | Quantidade de posições que serão contratadas para essa vaga |
| positionType | Tipo de contratação da vaga |
| recruiterId | Código chave do recrutador responsável pela vaga |
| roleId | Código chave do cargo atribuído à vaga |
| salary | Campo referente aos dados salariais da vaga |
| salary.currency | Moeda em que o salário será pago |
| salary.amount | Valor do salário |
| salary.from | Valor inicial da faixa salarial (caso use essa funcionalidade) |
| salary.to | Valor final da faixa salarial (caso use essa funcionalidade) |
| status | Estado de publicação da vaga |
| hiringDeadline | data/hora da expiração da vaga |
| expand.address | array de informações do endereço da vaga |
| expand.address.street | Rua/Logradouro do endereço da vaga |
| expand.address.number | Número do logradouro do endereço da vaga |
| expand.address.state | Estado do endereço da vaga |
| expand.address.stateCode | Sigla do Estado do endereço da vaga |
| expand.address.city | Cidade do endereço da vaga |
| expand.address.country | País do endereço da vaga |
| expand.address.countryCode | Abreviação (2 dígitos) do endereço da vaga |
| expand.address.zipCode | CEP do endereço da vaga |
| expand.address.latitude | Informação da latitude do endereço da vaga |
| expand.address.longitude | Informação da longitude do endereço da vaga |
| expand.company | array de informações da empresa |
| expand.company.id | id da empresa |
| expand.company.name | nome da empresa |
| expand.company.type | setor/ramo da empresa |
| expand.creator | Array com informações do criador da vaga |
| expand.creator.id | Id do usuário que criou a vaga |
| expand.creator.name | Nome do criador da vaga |
| expand.creator.email | E-mail do criador da vaga |
| expand.manager | Array com informações do gestor responsável pela vaga |
| expand.manager.id | Id do gestor atribuído à vaga |
| expand.manager.name | Nome do gestor responsável pela vaga |
| expand.manager.email | E-mail do gestor responsável pela vaga |
| expand.recruiter | Array com informações do recrutador responsável pela vaga |
| expand.recruiter.id | Id do recrutador atribuído à vaga |
| expand.recruiter.name | Nome do recrutador responsável pela vaga |
| expand.recruiter.email | E-mail do recrutador responsável pela vaga |
| expand.branch | Array com informações da filial da vaga |
| expand.branch.id | Id da filial da vaga (código gerado pela Gupy automaticamente) |
| expand.branch.name | Nome da filial da vaga |
| expand.branch.code | Código da filial (quando temos integração entre a Gupy e outro sistema, normalmente esse campo se refere ao código da filial no sistema integrado com a Gupy). |
| expand.department | Array com informações da área/departamento da vaga |
| expand.department.id | Id da área/departamento da vaga (código gerado pela Gupy automaticamente) |
| expand.department.name | Nome da área da vaga |
| expand.department.code | Código da área/filial (quando temos integração entre a Gupy e outro sistema, normalmente esse campo se refere ao código do departamento no sistema integrado com a Gupy). |
| expand.role | Array com informações do cargo da vaga |
| expand.role.id | Id do cargo da vaga (código gerado pela Gupy automaticamente) |
| expand.role.name | Nome do cargo da vaga |
| expand.role.code | Código do cargo (quando temos integração entre a Gupy e outro sistema, normalmente esse campo se refere ao código do cargo no sistema integrado com a Gupy). |
| expand.careerPage | Array com informações da página de carreiras em que a vaga foi publicada. |
| expand.careerPage.id | Id da página de carreira em que a vaga foi publicada |
| expand.careerPage.name | Nome da página de carreira em que a vaga foi publicada |
| expand.careerPage.subdomain | Subdomínio da pagina de carreira em que a vaga foi publicada |
| expand.positions | Array com informações das posições cadastradas na vaga |
| expand.positions.id | Número gerado automaticamente pela Gupy |
| expand.positions.code | Código das posições da vaga |
| expand.positions.status | Status da posição (ex: valid) |
| expand.positions.errorMessage | Mensagem de erro em casos onde a posição tem status de erro (ex: Duplicated code) |
| expand.posting | Array com informações da vaga que ficam disponíveis na página de carreiras |
| expand.posting.description | Descrição da vaga |
| expand.posting.responsibilities | Responsabilidades da vaga |
| expand.posting.prerequisites | Pré-requisitos da vaga |
| expand.posting.additionalInformation | Informações adicionais da vaga |
| expand.posting.publicationType | Tipo de publicação da vaga (interna, externa e não-listada) |
| expand.posting.imageUrl | URL de imagem inserida na página de carreiras em que a vaga foi publicada |
| expand.posting.socialPictureUrl | URL de imagem inserida na página de carreiras em que a vaga foi publicada |
| expand.posting.videoUrl | URL do vídeo da página de carreiras |
| createdAt | Data/hora de criação da vaga |
| updatedAt | Data/hora de atualização da vaga |
| approvedAt | Data/hora da aprovação da vaga |
| disapprovedAt | Data/hora da reprovação da vaga |
| publishedAt | Data/hora da publicação da vaga |
| closedAt | Data/hora do encerramento da vaga |
Diversidade - Parâmetros possíveis de Header
| Parâmetro | Tipo | Descrição |
|---|---|---|
| jobId | array de inteiros | Lista de IDs de vagas para filtragem. Lista separada por vírgulas. |
| currentStepId | array de inteiros | Lista de IDs de etapas atuais para filtragem. Lista separada por vírgulas. |
| updatedAfter | data-hora | Valor igual ou maior que a propriedade de atualização. |
| maxPageSize | número | Número máximo de itens na resposta (max 100). |
| pageToken | string | Token usado para navegar entre páginas. |
Diversidade - Glossário de dados
| CAMPO | Descrição | Tipo | Enum (se aplicável) | Formato |
|---|---|---|---|---|
| anonymizedId | Identificador anonimizado da pessoa candidata | string | - | - |
| jobId | ID da Vaga atual da pessoa candidata | integer | - | - |
| currentStepId | ID da Etapa atual da pessoa candidata | integer | - | - |
| status | Informação do status da Candidatura | string | in_process, reproved, give_up, hired | - |
| hasDisabilities | Informação de Candidato PCD | boolean | - | - |
| cityOfOrigin | Informação da Cidade de Origem do Candidato | string | - | - |
| stateOfOrigin | Informação do Estado de Origem do Candidato | string | - | UF |
| genderIdentity | Informação de identidade de gênero | string | cisgender, transgender, no_answer | - |
| sexualOrientation | Informação de orientação sexual | string | heterosexual, homosexual, bisexual, asexual, pansexual, no_answer | - |
| raceColor | Informação de raça | string | white, black, pardo, indigenous, yellow, no_answer | - |
| createdAt | Data da criação da application | string | - | date |
| updatedAt | Data da última atualização da application | string | - | date |
Modelagem de tabelas do Banco de Dados base para BI/Analytics
Uma vez que os registros estão sendo obtidos a partir da API Gupy, eles devem ser armazenados de forma incremental em tabelas de Banco de Dados no ambiente de domínio do cliente, para que então estejam acessíveis para a aplicação de BI ou outras formas de consulta internas. Sugerimos abaixo um diagrama de composição de tabelas normalizadas a partir das entidades Gupy disponibilizadas nos endpoints.
Note
A definição da modelagem dependerá de quais campos e métricas a área de negócio desejar apurar a partir dos registros armazenados, e recomendamos que seja submetida a uma análise interna de um(a) profissional (ex. DBA ou Analista de Dados).
Exemplos apuração de métricas a partir dos dados obtidos da API
Identificação de pessoas contratadas nas vagas
A partir dos campos status = hired, hiredAt e dos campos do objeto admission {} nos registros de application é possível fazer um acompanhamento de pessoas contratadas por período e salário de contratação.
Cálculos de diferentes tipos de SLA
SLA de aprovação de requisição de vaga (jobs)
approvedAt - createdAt
SLA de publicação (jobs)
Quando houver fluxo de aprovação: publishedAt - approvedAt
Quando não houver fluxo de aprovação: publishedAt - createdAt
Time to Hire (jobs e applications)
Diferentes pontos de vista para esse indicador, podendo ser:
createdAt - hiringDate
createdAt - closedAt
approvedAt - hiringDate
approvedAt - closedAt
publishedAt - hiringDate
publishedAt - closedAt
Candidaturas/contratações por indicação
Considerar todas as candidaturas com "referred": "true" usar o campo hiringDate para diferenciar quem chegou a ser contratado.
Dúvidas frequentes:
- Todos os dados de relatórios estão disponíveis na API? Não, nem todas informações presentes em relatórios são possíveis de obter através da API. Porém reforçamos que estamos em constante evolução de nossas APIs.
- Onde encontro os dados de workflow na API? Esses dados não estão disponíveis através da API
Updated 6 months ago