合作夥伴指南：建立與 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 UI 內實現這些操作。
一般工作流程
整合通常涉及透過插件或自訂使用 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。
資訊不正確： 如果請求除了存取權杖錯誤之外還有一個或多個錯誤，我們將在 errors 欄位中返回所有錯誤的清單，請求狀態為 422。例如：
{
"errors": [
"標題是必填欄位",
"面試時間範圍無效",
"......."
]
}