Guia do Parceiro para construir uma integração com o HackerRank

Last updated: February 7, 2026

Visão Geral

Este documento é destinado a parceiros que desejam desenvolver uma integração com o HackerRank for Work. Estamos constantemente trabalhando com fornecedores de ATS para desenvolver integrações para uma melhor experiência do usuário. Este documento fornecerá todas as informações necessárias para que você mesmo desenvolva uma integração.

 

Contexto

Vários de nossos clientes corporativos - ou seja, aqueles que usam HackerRank for Work Tests e Entrevistas na fase de avaliação, também utilizam alguns outros sistemas de TI para gerenciar seu processo de contratação como um todo. Esses sistemas podem ser sistemas comerciais prontos (COTS), como Oracle Taleo, Jobvite, Greenhouse, Lever, Kenexa, RecruiterBox, etc., ou algum sistema personalizado desenvolvido internamente. Nos referiremos a esses aplicativos conjuntamente como Sistemas de Rastreamento de Candidatos (ATS).

Esses clientes frequentemente solicitam integração entre seus ATS e o HackerRank for Work para que ações rotineiras de gerenciamento de seus candidatos possam ser feitas dentro do fluxo de trabalho do ATS. Exemplos dessas ações rotineiras incluem (a) convidar um candidato pré-selecionado para fazer um teste no HackerRank for Work, (b) visualizar os resultados de um teste para esses candidatos em seu ATS, (c) agendar uma sessão de entrevista no HackerRank entre um engenheiro e um candidato selecionado, (d) visualizar relatórios de entrevistas na interface do ATS, etc. Assim, os pontos de integração mais solicitados envolvem puxar dados de uma conta existente do HackerRank for Work e realizar ações específicas a partir da interface do ATS. Temos chamadas de API que ajudarão a implementar essas ações dentro da interface do ATS.

 

Fluxo de Trabalho Geral

A integração geralmente envolve adicionar funcionalidades ao ATS via um plugin ou personalização usando a API do HackerRank for Work. Isso é melhor explicado visualmente usando os seguintes diagramas.

Convenções usadas nos fluxos de trabalho abaixo:

 

Configuração de Integração - Atividade de uma única vez

Nota: Toda integração oficial do ATS terá uma seção dentro do HackerRank for Work onde o administrador da conta de cada empresa poderá gerar uma chave. Seu ATS aparecerá no seguinte local: https://www.hackerrank.com/work/settings/api 

Fluxo Geral de Teste

Fluxo Geral do CodePair (API de Entrevistas)

O Processo de Integração

Inscreva-se para um Teste Gratuito

Vá para https://www.hackerrank.com/work/signup para se inscrever em um teste gratuito de 14 dias do nosso produto. Essa conta será necessária para explorar nossa API (veja abaixo) e testar sua integração.

Explore nossa API

Temos uma API RESTful simples que servirá de base para a integração. Você deve começar a aprender sobre nossa API aqui:

https://www.hackerrank.com/work/apidocs 

Nota: A documentação acima foi escrita pensando em nossos clientes finais. Você deve explorar a API em sua conta de teste como um cliente final. Se tiver alguma dúvida sobre a API, entre em contato com seu ponto de contato na HackerRank ou envie uma solicitação de suporte escrevendo para support@hackerrank.com

Registre sua Integração

Depois de se familiarizar com a API e mapear os fluxos que deseja suportar, entre em contato com seu ponto de contato na HackerRank ou escreva para nós em support@hackerrank.com solicitando uma chave de parceiro e token secreto. Você também receberá uma ‘Chave de API de toda a empresa’ para usar com sua integração.

Alterar o mecanismo de autenticação no seu código de integração

Você precisará fazer três alterações:

  1. Adicionar um cabeçalho personalizado “X-HRW-Partner-Authorization: abcd” onde abcd deve ser substituído por uma versão codificada em base64 de PartnerKey:PartnerSecret.

  2. Adicionar um cabeçalho personalizado “HRW-User-Email: user@email.com” onde user@email.com deve ser substituído pelo email do usuário que inicia a solicitação através do seu aplicativo. Isso deve corresponder a um usuário existente na conta HRW do cliente.

  3. Usar a Chave de API de toda a empresa  no lugar do Token de Acesso Pessoal que você teria usado ao explorar a API na sua conta.

  4. Com cada chamada que você fizer, você também pode optar por incluir alguns metadados adicionais  em sua carga útil se houver metadados que você precisa que a HackerRank salve. Alguns campos comumente vistos incluem

  5. user_email deve identificar o usuário que inicia a solicitação. Isso deve corresponder a um usuário existente na conta HRW do cliente.

  6. candidateId pode ser o identificador único para este candidato em seu sistema. Algumas chamadas de API não são específicas de candidatos, e, nesses casos, você pode ignorar esse campo.

  7. applicationId pode ser usado se um candidato puder se candidatar a mais de uma vaga. Isso pode ser um campo diferente e identificar a inscrição específica. Algumas chamadas de API não são específicas de candidatos, e, nesses casos, você pode ignorar esse campo.

{

    ...

    "metadata": {

        "candidateId": "16651587",

        "applicationId": "25145412",

         "user_email": "abcd@example.com"

    }

}

Usar o token de autorização do parceiro e chaves por empresa são importantes, pois temos um conjunto diferente de políticas e limites de taxa. Isso também nos ajuda a solucionar problemas de clientes originados de você com mais facilidade, levando a uma melhor experiência do usuário.

Validação de Integração

Assim que você modificar a integração para usar a autorização do parceiro acima, avaliaremos a integração para caminhos felizes e também alguns dos casos extremos conhecidos que encontramos com integrações no passado.

A revisão da Documentação do Usuário Final será uma parte importante do exercício de validação.

Disponibilidade Geral

Após a conclusão da validação, adicionaremos uma entrada na página de Integrações ATS que mostra todas as integrações suportadas. Usando essa interface, clientes comuns poderão ativar ou desativar sua integração por conta própria.

Sua integração estará disponível como uma opção na nossa Página de Configurações de Integração: https://www.hackerrank.com/work/settings/api 

 

Melhores Práticas de Integração

Cenários de Erro

Na nossa experiência com ATS, alguns cenários comuns que levam a erros ao convidar candidatos são:

  1. O API Key não é válido para sua conta HackerRank for Work. (Precisa ser a Chave por empresa e a autorização do parceiro deve estar funcionando corretamente)

  2. O endereço de email do recrutador para a conta ATS (enviado via os metadados) é diferente do email usado dentro do HackerRank for Work (por exemplo, usando sriram.karra@hackerrank.com na conta ATS e sriram@hackerrank.com em suas contas HRW). Não importa qual você corrija, desde que sejam os mesmos.

  3. Endereço de email do candidato está ausente ou inválido

  4. O candidato com este email já foi convidado.

  5. O recrutador não possui uma "Vaga de Recrutamento" no HackerRank, e, portanto, não tem o privilégio de convidar candidatos

  6. O recrutador não tem permissão para acessar um teste específico

  7. A Conta HackerRank do recrutador não está ativada.

 

Recomendamos que você teste sua integração para todos os cenários acima e garanta que o comportamento da aplicação seja gracioso.

Tratamento de Erros

API de Teste

Para a API de teste, retornamos erros em dois formatos diferentes - você precisa cobrir ambos os formatos de respostas e mostrar o tipo de mensagem correto ao usuário final.

Case 1: O erro é local ao candidato, por exemplo, re-convidar um candidato. Isso tem o seguinte formato:

{

  "data": {

    "username": “error@hackerrank.com",

    "password": "96d3efe9",

    "test_link": “link",

    "status": false,

    "error": 1002,

    "error_message": "O candidato já foi convidado a fazer o mesmo teste. Se desejar reenviar o convite, cancele o convite na sua conta HackerRank for Work primeiro."

  },

"message": "Nenhum candidato convidado.",

}

Os campos em negrito indicam que ocorreu um erro. Se houver erros não capturados na criação do candidato, eles também serão exibidos neste formato.

Case 2: Se houver um erro na própria configuração do recrutador (geralmente devido a uma configuração incorreta ou formato errado), ele será retornado no seguinte formato:

{

  "data": {},

  "status": false,

  "message": "Não existe tal teste",

}

As ações que acionam esse erro incluem conta de recrutador inválida, e-mails inválidos, ID de teste incorreto, etc.

Solicitações bem-sucedidas serão retornadas com códigos de resposta 200.

Token de Acesso Incorreto: Além desses dois cenários de erro, se o usuário configurou a integração com um código de acesso incorreto, retornaremos o erro no seguinte formato com código de resposta 401:

{

    "model": {},

    "message": "Token de Acesso Inválido"

}

API CodePair (API de Entrevistas)

Token de Acesso Incorreto: Se o token de acesso presente na solicitação for inválido, retornaremos uma resposta vazia com código de status 403.

Informação inválida: Se a solicitação tiver um ou mais erros além do erro do token de acesso, retornaremos uma lista de todos os erros no campo errors com um status de solicitação de 422. Por exemplo:

{

    "errors": [

        "o título é um campo obrigatório",

        "intervalo de tempo da entrevista é inválido",

        "......."

    ]

}