Integração com testes de provedores externos

A Gupy possui um modelo extensível para integração com testes de provedores externos.
Esta página é destinada a provedores de testes que desejem integrar-se à plataforma Gupy para que usuários clientes possam fazer a utilização dos testes em seus processos de contratação.

Como funciona

Após os parceiros implementarem sua API de acordo com as regras definidas no contrato de integração criado pela Gupy (que será apresentado mais adiante), o cliente poderá durante a criação de uma etapa de teste em uma vaga selecionar um dos testes disponibilizados pelos parceiros conforme a imagem abaixo.

Uma vez definido os testes em uma vaga pelo usuário empresa, quando a etapa estiver disponível para o candidato, o mesmo será redirecionado para a plataforma do parceiro após o clique em "Iniciar teste".

Uma vez finalizado o teste, o candidato é redirecionado de volta para a plataforma da Gupy para a página com o resultado do teste (exibir um resultado para o candidato é imprescindível para que ele tenha uma ótima experiência durante o processo).

📘
Ambiente de teste
Não dispomos de um ambiente de teste, portanto para validar a integração é necessário realizar os testes em conjunto com o cliente diretamente na plataforma da Gupy.

Como testar?

Para realizar o teste da integração será necessário criar uma vaga e ter pelo menos uma inscrição. Siga os passos a seguir:

Crie uma vaga na Gupy (recomendamos que seja não-listada, pois essa vaga tem a finalidade apenas de validar a integração) e na etapa de teste selecione um dos testes do parceiro;
Publique a vaga para que ela fique disponível para receber a inscrição do candidato de teste.
A inscrição na vaga pode ser a partir de um cadastro fictício desde que sejam utilizados dados válidos, mas também pode ser realizada pelo próprio time que está validando o fluxo;
Na visão empresa, movimente o candidato recém inscrito para a etapa que tenha o teste selecionado;
O candidato receberá um e-mail informando que a etapa está desbloqueada e é possível fazer o teste;
Como candidato, abra o link recebido no e-mail, clique em Iniciar teste e realize o teste por completo (é necessário finalizar o teste para o sucesso da integração)

Fluxo de comunicação para integração com API de testes de parceiros

A imagem abaixo descreve o fluxo de comunicação entre a plataforma da Gupy e API de testes fornecida pelo parceiro.

📘
Não esqueça de chamar o callback
Após a pessoa candidata finalizar o teste, a API do parceiro de teste deve realizar um GET na URL de callback presente no campo callback_url para que o teste seja registrado e a pessoa candidata seja redirecionada à plataforma.

📘
Garanta o envio do resultado através do campo result_webhook_url
Algumas vezes por falhas de rede ou fechamento inesperado por parte da candidata, o processo de callback pode falhar. Nesse caso a Gupy nunca conseguirá buscar a nota do teste. Para evitar quaisquer problemas relacionados ao não recebimento da nota, é possível enviar o resultado do teste de forma assíncrona, fazendo um POST para o endpoint que está no result_webhook_url. Essa é uma URL pública e não necessita de nenhuma autenticação. O payload a ser enviado é o mesmo do TestResult, que se encontra no schema abaixo.

Contrato da API de testes de provedores externos

Abaixo está a documentação do contrato da API que deve ser implementada pelo parceiro. A API contém 3 endpoints, um que lista os testes, um que "registra" o candidato na plataforma do parceiro e um que requisita o resultado do teste. Em todas as requisições é enviado o "apiKey", um token no formato Bearer para autenticação. A definição dos payloads das requisições e das respostas também estão inclusos no arquivo do contrato.

swagger: '2.0'

info:
  description: API de testes de provedores externos da Gupy
  version: 1.0.0
  title: API de teste de parceiros Gupy

securityDefinitions:
  ApiKey:
    type: apiKey
    description: Token no formato Bearer
    name: Authorization
    in: header

paths:
  /test:
    get:
      security:
        - ApiKey: []
      tags:
        - Testes
      summary: Lista de testes disponíveis para a empresa requisitante
      operationId: searchTest
      description: Endpoint retorna uma lista de testes disponíveis para empresa requisitante.
      produces:
        - application/json
      parameters:
        - in: query
          name: searchString
          description: Passa uma string opcional para filtrar os testes por nome
          required: false
          type: string
        - in: query
          name: offset
          description: Posição do primeiro registo a ser retornado
          type: integer
          format: int32
          minimum: 0
        - in: query
          name: limit
          description: Número máximo de registros a serem retornados, onde o limite máximo de registros aceitos é 400
          type: integer
          format: int32
          minimum: 0
          maximum: 400
      responses:
        200:
          description: Resultado da busca por teste
          schema:
            $ref: '#/definitions/TestItems'


  /test/candidate:
    post:
      security:
        - ApiKey: []
      tags:
        - Candidato
      summary: Registra candidato para fazer o teste
      description: Endpoint para registrar o candidato no teste, é passado para a plataforma de teste parceira uma URL de callback, para ser redirecionada assim que o candidato terminar o teste, dados do candidato e o id do teste que o candidato deverá fazer.
      operationId: candidateRegistration
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/BodyCandidateRegistration'
      responses:
        201:
          description: Retorna ID do resultado para que seja possível recupera-lo posteriormente e o link para que o candidato possa fazer o teste.
          schema:
            $ref: '#/definitions/CandidateRegistrationResponse'
  
  
  /test/result/{resultId}:
    get:
      security:
        - ApiKey: []
      tags:
        - Testes
      summary: Recuperar o resultado de um teste
      operationId: getResult
      description: O id do resultado, retornado no momento do registro do candidato para fazer o teste, será usado neste endpoint para obter o resultado do teste realizado pelo candidato.
      produces:
        - application/json
      parameters:
        - name: resultId
          in: path
          description: ID do resultado
          required: true
          type: string          
      responses:
        200:
          description: Resultado do teste do candidato
          schema:
            $ref: '#/definitions/TestResult'

          
definitions:
  TestItems:
    type: object
    properties:
      limit:
        type: integer
        example: 50
      offset:
        type: integer
        example: 0
      total_tests:
        type: integer
        example: 1500
      payload:
        type: array
        items:
          $ref: '#/definitions/Test'

  Test:
    type: object
    required:
      - id
      - name
    properties:
      id:
        type: string
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      name:
        type: string
        example: Teste de lógica
      category:
        type: string
        example: STEM
      description:
          type: string
          example: Este é um teste de habilidades lógicas e matemáticas
      level:
        type: string
        enum: [advanced, intermediate, basic]
        example: Teste de lógica

  BodyCandidateRegistration:
    type: object
    required:
      - name
      - email
      - document_id
      - callback_url
    properties:
      name:
        type: string
        example: Robson Ventura
      email:
        type: string
        example: [email protected]
      document_id:
        type: integer
        format: int64
        example: 1
      test_id:
        type: string
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      company_id:
        type: integer
        format: int64
        example: 1
      job_id:
        type: integer
        format: int64
        example: 100
      callback_url:
        type: string
        example: https://example.com
      candidate_type:
        type: string
        enum: [internal, external]
        example: internal
      previous_result:
        type: string
        enum: [fail, null]
        example: fail
      result_webhook_url:
        type: string
        example: https://api.io/result/{applicationId}/{applicationStepId}

  CandidateRegistrationResponse:
    type: object
    properties:
      test_result_id:
        type: string
        example: d290f1ee-6c54-4b01-90e6-d701748f0851
      test_url:
        type: string
        example: https://plataforma_teste.com/test/{testId}

  TestResult:
    type: object
    properties:
      title:
        type: string
        example: Teste de Lógica Avançado
      testCode:
        type: string
        example: advanced_logic
      description:
        type: string
        example: Este é o resultado do seu teste de lógica avançado.
      providerName:
        type: string
        example: Nome do parceiro
      company_result_string:
        type: string
        example: Texto markdown que será apresentado para a empresa.
      providerLink:
        type: string
        example: https://nomedoparceiro.com.br
      status:
        type: string
        enum: [paused, done, notStarted]
        example: done
      result_page_url:
        type: string
        example: link com resultado que será apresentado para a recrutadora
      result_candidate_page_url:
        type: string
        example: link com o resultado que será apresentado para a candidata
      results:
        type: array
        items:
          $ref: '#/definitions/TestResultItem'

  TestResultItem:
    type: object
    required:
      - score
      - type_result
      - title
      - tier
    properties:
      score:
        type: integer
        example: 90
      result_string:
        type: string
        example: Você tem atenção bastante elevada, se comporta seguindo as regras éticas aceitas socialmente
      type_result:
        type: string
        example: percentage
      tier:
        type: string
        example: minor
        description: Ranqueia a importância do resultado
        enum: [major, minor]
      title:
        type: string
        example: Conscienciosidade
      description:
        type: string
        example: Cuidadoso; que obedece regras; de realização detalhada; teoria conscienciosa; discurso consciencioso.
      date:
        type: string
        example: '1988-02-05'
      other_informations:
        type: object
        example: {"time": 11, "pause_count": 2, "test_type": "IFC", "factor": "Abertura"}

Para os dados do BodyCandidateRegistration siga o padrão das informações como descritas abaixo:

Parâmetro	Descrição
name	Nome completo do candidato que será registrado para a execução do teste no sistema do provedor parceiro.
email	Endereço de e-mail do candidato, utilizado pelo provedor para envio de convites e comunicações relacionadas ao teste.
document_id	Identificador único do candidato utilizado dentro da plataforma da Gupy.
test_id	Identificador único do teste selecionado que o candidato deverá realizar, previamente obtido via o endpoint `/test` (endpoint que retorna a lista de testes disponíveis). Esse identificador não pode ser alterado.
company_id	Identificador da empresa na Gupy, garantindo que o registro do candidato e do teste sejam associados à organização correta.
job_id	Identificador da vaga vinculada ao processo seletivo, possibilitando rastrear em qual oportunidade o teste está sendo aplicado.
callback_url	URL para a qual o parceiro deve redirecionar o candidato após o término do teste.
candidate_type	Tipo do candidato no processo: `internal` para colaboradores internos ou `external` para candidatos de fora da empresa; ajuda a definir regras de fluxo diferentes.
previous_result	Indica se existe um resultado prévio do candidato neste teste: `fail` para reprovações anteriores ou `null` caso seja a primeira tentativa.
result_webhook_url	URL pública para envio assíncrono do resultado do teste (mesmo payload de TestResult) via POST para garantir que o resultado seja enviado mesmo em situações de falha de redirecionamento da URL de callback ou interrupção de redirecionamento por parte da pessoa candidata; não requer autenticação adicional.

Para os dados do TestResult siga o padrão das informações como descritas abaixo:

Parâmetro	Descrição
title	Título do teste apresentado à pessoa candidata e à recrutadora (ex: "Teste de Lógica Avançado").
testCode	Código identificador do teste no provedor, geralmente em formato legível (ex: "advanced_logic").
description	Descrição do teste exibida para a pessoa candidata ao final da execução.
providerName	Nome do provedor do teste, que será apresentado nos resultados.
company_result_string	Texto em Markdown que será exibido apenas para a empresa, com interpretações e instruções do resultado.
providerLink	URL do site do provedor do teste, caso desejem redirecionar para mais informações.
status	Estado do teste: `notStarted`, `paused` ou `done`, indicando se foi iniciado, pausado ou concluído.
result_page_url	Link com o resultado do teste que será apresentado para a recrutadora.
result_candidate_page_url	Link com o resultado do teste que será apresentado para a candidata.
results	Lista de objetos do tipo `TestResultItem` contendo os resultados detalhados por fator ou dimensão do teste.

Para os dados do TestResultItem siga o padrão das informações como descritas abaixo:

Parâmetro	Descrição
score	Nota da pessoa candidata nesse fator específico do teste. Deve ser um número inteiro (0 a 100).
result_string	Interpretação textual do resultado daquele fator, apresentada à pessoa candidata.
type_result	Tipo do valor apresentado, geralmente `percentage`, podendo indicar como o dado deve ser interpretado pela Gupy.
tier	Importância do fator avaliado: `major` (relevante para análise geral) ou `minor` (secundário).
title	Nome do fator ou dimensão avaliada (ex: "Conscienciosidade").
description	Definição ou explicação conceitual do fator avaliado.
date	(Opcional) Data relacionada ao resultado daquele fator, geralmente usada quando o resultado é datado.
other_informations	(Opcional) Objeto com dados complementares sobre o teste, como tempo de execução, número de pausas ou tipo de teste aplicado.

👍
Se atente à lista de opções e formato para cada campo
No POST que "registra" o candidato para realizar o teste temos campos que possuem uma lista de opções: O campo candidate_type aceita internal ou externale previous_resultaceita fail ou null.

Exemplo de requisição `(/test/candidate)`:

curl --request POST \
     --url https://example.com/test/candidate \
     --header 'accept: application/json' \
     --header 'Authorization: XXXXXXXXXXXXXXXXX' \
     --header 'content-type: application/json' \
     --data '
{
  "name": "Candidato Teste",
  "email": "[email protected]",
  "document_id": 4398157034,
  "company_id": 1,
  "callback_url": "https://example.com",
  "candidate_type": "external",
  "previous_result": "null",
  "job_id": 100,
  "test_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "result_webhook_url": "https://example.com"
}
'

Ativação da integração

Uma vez que os endpoints listados acima foram implementados pelo parceiro, é necessário entrar em contato com a Gupy para a ativação da integração. Para isso é necessário:

Fornecer a URL da API;
Fornecer o token de autenticação (indicamos que cada empresa cliente que fará uso dos testes tenha seu próprio token).

Para mais informações, acesse o artigo relacionado a esse passo clicando aqui

Resultado dos testes

Conforme descrito na documentação, o resultado do teste TestResultItem possui diferentes propriedades para atender a diferentes tipos de dados e resultados, porém atualmente só é possível exibir 2 tipos de resultados: resultado numérico único e resultado numérico múltiplo.

Abaixo é possível visualizar exemplos das respostas esperadas de ambos tipos de resultado, bem como visualizações do resultado pelo usuário empresa e pelo candidato.

Outros tipos de resultados ou a não existência de resultado não são suportados na integração.

1. Resultado numério único

Payload exemplo da resposta do endpoint /test/result/{resultId}:

{
    "title": "Teste 1",
    "status": "done",
    "results": [
        {
            "tier": "major",
            "score": 73,
            "title": "Resultado major 1",
            "type_result": "percentage"
        }
    ],
    "testCode": "test1",
    "description": "Decrição do resultado do teste",
    "providerLink": "https://sitedoparceiro.com.br",
    "providerName": "Nome do parceiro provedor de testes",
    "company_result_string":"Texto markdown que será apresentado para a empresa"
}

Visão empresa do resultado numérico único:

Visão candidato do resultado numérico único:

2. Resultado numérico múltiplo

Uma particularidade do resultado numérico múltiplo é a possibilidade de exibição de resultados distintos entre empresa e candidato. Para empresa serão apresentados todos os resultados que possuem a propriedade tier com valor minor ou major, enquanto para o candidato serão apresentados somente os resultados onde a propriedade tier tiver o valor major conforme exemplificado nas imagens abaixo.

Para cada um dos resultados é possível ter um título e uma descrição que serão apresentados tanto para empresa quanto para o candidato (seguindo as regras em relação ao tier).

Payload exemplo da resposta do endpoint /test/result/{resultId}:

{
    "title": "Teste 1",
    "status": "done",
    "results": [
        {
            "tier": "minor",
            "score": 100,
            "title": "Resultado minor 1",
            "type_result": "percentage"
        },
        {
            "tier": "minor",
            "score": 43,
            "title": "Resultado minor 2",
            "type_result": "percentage"
        },
        {
            "tier": "minor",
            "score": 30,
            "title": "Resultado minor 3",
            "type_result": "percentage"
        },
        {
            "tier": "major",
            "score": 73,
            "title": "Resultado major 1",
            "type_result": "percentage"
        }
    ],
    "testCode": "test1",
    "description": "Decrição do resultado do teste",
    "providerLink": "https://sitedoparceiro.com.br",
    "providerName": "Nome do parceiro provedor de testes",
    "company_result_string":"Texto markdown que será apresentado para a empresa"
}

Visão empresa do resultado numérico múltiplo:

Visão candidato do resultado numérico múltiplo:

📘
A nota está em porcentagem!
A Gupy entende porcentagem (0 a 100). Caso a sua API entenda apenas de 0 a 10 será necessário multiplicar o resultado do teste por 10.

Como funciona

Ambiente de teste

Como testar?

Fluxo de comunicação para integração com API de testes de parceiros

Não esqueça de chamar o callback

Garanta o envio do resultado através do campo result_webhook_url

Contrato da API de testes de provedores externos

Se atente à lista de opções e formato para cada campo

Exemplo de requisição (/test/candidate):

Ativação da integração

Resultado dos testes

1. Resultado numério único

2. Resultado numérico múltiplo

A nota está em porcentagem!

Exemplo de requisição `(/test/candidate)`: