API 文件

開通 API

1. 先聯絡客服開戶。
2. 把需要的服務、帳號和伺服器對外 IP 提供給客服。
3. 開通後我們會核發 API 金鑰和完整串接文件。金鑰有效期 1–730 天，每把金鑰最多綁定 32 個對外 IP。

基本約定

驗證

每個請求都要帶 Authorization: Bearer <API 金鑰>

User-Agent

必須帶，缺少時會被 Cloudflare 攔截（error 1010）

格式

請求和回應都是 JSON（上傳檔案除外），編碼為 UTF-8

時間

UTC Unix 毫秒時間戳記

金額

最多八位小數，請用十進位定點數型別處理，不要四捨五入成兩位

串接流程

1. 查詢服務清單和餘額，保存要使用的 productId。
2. 查詢資料使用聲明；尚未確認時，請閱讀後確認。
3. 上傳號碼檔案，保存回傳的 fileId。
4. 用 productId 和 fileId 取得報價，核對筆數、單價和總價。
5. 產生並保存冪等鍵，再依報價下單。下單會實際扣款。
6. 設定 Webhook 接收訂單狀態推送；同時每 5–10 分鐘用 updatedSince 對帳一次，避免漏收。
7. 訂單完成後列出結果檔案，逐一下載並用 sha256 校驗。成功和未成功的檔案都要下載。

curl 範例

把預留位置換成實際值。報價和下單的完整參數請見開通時提供的串接文件。

1. 設定金鑰，查詢服務

   複製

   export CHECKIM_TOKEN='替換為客服提供的 API 金鑰'
   export CHECKIM_BASE='https://api.checkim.ai/openapi/v1'
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/products"

2. 上傳號碼檔案

   複製

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -F 'file=@./numbers.csv;type=text/csv' \
     "$CHECKIM_BASE/files"

3. 取得報價

   複製

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"productId":"<productId>","name":"batch-001","fileId":"<fileId>"}' \
     "$CHECKIM_BASE/orders/check"

4. 下單

   複製

   # 會實際扣款。重試時請保持冪等鍵和請求內容完全不變。
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: partner-request-001' \
     -d '{"quoteId":"<quoteId>","clientOrderId":"partner-batch-001"}' \
     "$CHECKIM_BASE/orders"

5. 查詢訂單，或依變動時間對帳

   複製

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" \
     "$CHECKIM_BASE/orders?updatedSince=<UTC ms>&size=100"

6. 列出並下載結果，校驗 sha256

   複製

   curl -H "Authorization: Bearer $CHECKIM_TOKEN" "$CHECKIM_BASE/orders/<orderId>/results"
   
   curl -H "Authorization: Bearer $CHECKIM_TOKEN" -o result.csv \
     "$CHECKIM_BASE/orders/<orderId>/results/<fileId>/download"
   shasum -a 256 result.csv

介面清單

查詢訂單與對帳

• 訂單清單預設依建立時間由新到舊排序。回應帶 nextCursor 時，把它當作下一次的 cursor 繼續取；游標分頁在持續新增訂單時不會漏、不會重複。
• 可依 status 和建立時間（createdFrom、createdTo，UTC 毫秒）篩選，也可以用 clientOrderId 查回某一筆訂單。
• updatedSince 只回傳該時間之後狀態有變動的訂單，依變動時間由舊到新排序。定期用它補拉，即使漏收 Webhook 也不會遺失狀態。

下載結果

• 結果清單中每個檔案都有 sha256。下載回應的 ETag 是同一個值，下載後請比對。
• 支援 Range 斷點續傳。續傳前先確認 sha256 沒變；若變了表示檔案已重新產生，需要整份重新下載。
• 已有完整檔案時，帶 If-None-Match 請求，內容沒變會回傳 304，不再傳輸。
• 啟用分批交付的大訂單，執行中會先列出已完成批次的檔案；訂單完成後的最終檔案為權威版本。
• 含頭像的服務（TG/WS 高級檢查、性別年齡檢查）會在結果 CSV 的 avatar 欄位提供帶簽章的圖片連結，在結果保存期內可直接 GET 取得圖片（不需帶 Authorization 標頭，支援 If-None-Match）。

Webhook 推送

• 透過 API 下的訂單狀態變動時，平台會向你的 HTTPS 網址 POST 一則事件。需要 webhook:manage 權限。
• 每則事件帶 CheckIM-Signature 簽章標頭（t=時間戳記,v1=簽章）。請用簽章金鑰對「t.原始請求內容」做 HMAC-SHA256 校驗。
• 回應 2xx 即視為送達；失敗會在約 2 天內重試 9 次。同一事件可能收到多次，請依事件 id 去重。
• 請求來自固定對外 IP 34.21.195.36，可以只放行這個位址。

訂單狀態

限流與注意事項

• 預設每分鐘上限：同一對外 IP 1,200 次、同一帳號 240 次、同一金鑰 120 次。回應標頭 RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset 會告訴你本分鐘還剩多少次。
• 報價和上傳較慢，同一帳號同時進行中的最多 3 個，超過時回傳 429 TOO_MANY_CONCURRENT_REQUESTS。
• 收到 429 或 503 時，依 Retry-After 給出的秒數等待後，用原請求重試。
• 沒有測試環境，下單即實際扣款。
• 查詢等待逾時不代表下單失敗。請先用 orderId 或 clientOrderId 查回訂單，不要重新下單。

常見錯誤

錯誤回應帶 code、requestId、message 和選填的 detail.field。程式請依 code 處理；message 依 Accept-Language 回傳 9 種語言之一，僅供顯示。