合作伙伴指南：构建与HackerRank的集成
Last updated: February 7, 2026
概述
本文件适用于希望与HackerRank for Work开发集成的合作伙伴。 我们不断与ATS供应商合作，开发更好的用户体验的集成。本文件将为您提供开发集成所需的所有信息。
背景
我们的许多企业客户——即那些在评估阶段使用HackerRank for Work测试和面试的客户——还使用其他一些IT系统来管理他们的整体招聘流程。这些系统可以是商业现成（COTS）系统，如Oracle Taleo、Jobvite、Greenhouse、Lever、Kenexa、RecruiterBox等，或一些定制的自主开发系统。我们将这些应用统称为申请人跟踪系统（ATS）。
此类客户经常要求在他们的ATS与HackerRank for Work之间进行集成，以便在他们的ATS工作流程中完成管理候选人的日常操作。这些日常操作的示例包括（a）邀请入围候选人参加HackerRank for Work测试，（b）在他们的ATS中查看此类候选人的测试结果，（c）安排工程师与候选人之间的HackerRank面试会话，（d）在ATS界面内查看面试报告等。因此，最常请求的集成点涉及从现有的HackerRank for Work账户中提取数据，并在ATS界面内执行特定操作。我们有API调用，可以帮助在ATS界面内实现这些操作。
一般工作流程
集成通常涉及通过插件或使用HackerRank for Work API的定制，为ATS添加功能。这最好通过以下图示进行直观说明。
以下工作流程中使用的约定：
集成设置 - 一次性活动
注意： 每个官方ATS集成都将在HackerRank for Work中有一个部分，公司的账户管理员将能够生成密钥。您的ATS将显示在以下位置：https://www.hackerrank.com/work/settings/api
整体测试流程
整体CodePair（面试API）流程
集成流程
注册免费试用
前往 https://www.hackerrank.com/work/signup 注册我们的产品免费试用14天。需要使用此账户以便探索我们的API（见下文）并测试您的集成。
探索我们的API
我们有一个简单的RESTful API，将作为集成的基础。您应该在这里开始了解我们的API：
https://www.hackerrank.com/work/apidocs
注意：上述文档是以我们的最终客户为目标编写的。您应该以最终客户的身份在您的测试账户中探索API。如果您对API有任何疑问，您应该联系您的HackerRank联系人或通过写信support@hackerrank.com提出支持请求
注册您的集成
一旦您熟悉了API并规划了您想支持的流程，请联系您的HackerRank联系人或写信support@hackerrank.com，申请一个合作伙伴密钥和秘密令牌。您还将获得一个“公司范围的API密钥”以用于您的集成。
在您的集成代码中更改认证机制
您需要进行三项更改：
添加自定义头部 “X-HRW-Partner-Authorization: abcd”，其中 abcd 应替换为 PartnerKey:PartnerSecret 的base64编码版本。
添加自定义头部 “HRW-User-Email: user@email.com”，其中 user@email.com 应替换为发起请求的用户的电子邮件。此电子邮件应与客户的HRW账户中的现有用户匹配。
使用公司范围的API密钥，代替您在账户中探索API时使用的个人访问令牌。
每次调用时，您还可以选择在您的负载中包含一些额外的元数据，如果有需要HackerRank保存的元数据。常见的字段包括
user_email 应识别发起请求的用户。此字段应与客户的HRW账户中的现有用户匹配。
candidateId 可能是此候选人在您的系统中的唯一标识符。有些API调用不是针对候选人的，在这种情况下，您可以忽略此字段。
applicationId 如果候选人可以申请多个职位，则可以使用此字段。它可以是不同的字段，用于标识具体的申请。在某些API调用中不是针对候选人的，在这种情况下，您可以忽略此字段。
{
...
"metadata": {
"candidateId": "16651587",
"applicationId": "25145412",
"user_email": "abcd@example.com"
}
}
使用合作伙伴授权令牌和每个公司的密钥非常重要，因为我们有一套不同的政策和速率限制。这也有助于我们更容易排查由您引起的客户问题，从而提供更好的用户体验。
集成验证
一旦您修改了集成以使用上述合作伙伴授权，我们将评估集成的正常路径以及我们过去遇到的一些已知边角案例。
审查终端用户文档将是验证工作的重要部分。
正式发布
验证完成后，我们将在ATS集成页面添加一个条目，显示所有支持的集成。通过该界面，普通客户将能够自行启用或禁用您的集成。
您的集成将作为我们集成设置页面的一个选项：https://www.hackerrank.com/work/settings/api
集成最佳实践
错误场景
根据我们与ATS的经验，导致邀请候选人出错的一些常见场景包括：
API密钥对您的HackerRank for Work账户无效。（需要是每个公司的密钥，并且合作伙伴授权应正常工作）
ATS账户的招聘官电子邮件地址（通过元数据发送）与HackerRank for Work中使用的电子邮件不同（例如在ATS账户中使用sriram.karra@hackerrank.com，在HRW账户中使用sriram@hackerrank.com）。只要它们相同，修复哪个都可以。
候选人电子邮件地址缺失或无效
已邀请过此电子邮件的候选人。
招聘官没有HackerRank上的“招聘席位”，因此没有权限邀请候选人
招聘官没有权限访问特定测试
招聘官的HackerRank账户未激活。
我们建议您测试所有上述场景的集成，并确保应用行为优雅。
错误处理
测试API
对于测试API，我们以两种不同的格式返回错误——您需要涵盖这两种响应格式，并向最终用户显示正确的消息类型。
案例 1： 错误仅在候选人本身，例如重新邀请候选人。其格式如下：
{
"data": {
"username": “error@hackerrank.com",
"password": "96d3efe9",
"test_link": “link",
"status": false,
"error": 1002,
"error_message": "候选人已被邀请参加相同的测试。如果您想重新邀请，请先在您的 HackerRank for Work 账户中取消邀请。"
},
"message": "没有候选人被邀请。",
}
加粗字段表示发生了错误。如果在创建候选人时出现未捕获的错误，它们也会以此格式显示。
案例 2： 如果招聘者的配置本身出现错误（通常是由于配置错误或格式错误），则以以下格式返回：
{
"data": {},
"status": false,
"message": "不存在此测试",
}
触发此错误的操作包括无效的招聘者账户、无效的电子邮件、错误的测试ID等。
成功的请求将返回200响应码。
访问令牌错误： 除了这两种错误场景外，如果用户配置了错误的访问码，我们将以响应码401返回以下格式的错误：
{
"model": {},
"message": "无效的访问令牌"
}
CodePair API（面试API）
访问令牌错误：如果请求中存在的访问令牌无效，我们将返回一个空响应，状态码为403。
信息无效： 如果请求中除了访问令牌错误之外还有一个或多个错误，我们将以错误字段中的所有错误列表返回，请求状态为422。例如：
{
"errors": [
"标题是必填字段",
"面试时间范围无效",
"......."
]
}