Guias Práticos

Integração com testes de provedores externos

Suggest Edits

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:

  1. 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;
  2. Publique a vaga para que ela fique disponível para receber a inscrição do candidato de teste.
  3. 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;
  4. Na visão empresa, movimente o candidato recém inscrito para a etapa que tenha o teste selecionado;
  5. O candidato receberá um e-mail informando que a etapa está desbloqueada e é possível fazer o teste;
  6. 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 opicional 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
          type: integer
          format: int32
          minimum: 0
          maximum: 150
      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
      birthdate:
        type: string
        example: 1988-02-05
      gender:
        type: string
        enum: [male, female]
        example: male
      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"}

👍

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 gender aceita as opções male e female , 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,
  "birthdate": "1990-05-04",
  "gender": "male",
  "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.

Updated about 2 months ago