機器對接

API 與 Webhook

v1 REST API 讓外部系統讀寫人資資料，webhook 讓 FincoHR 主動通知你事情發生了。

驗證

權杖，不是帳號密碼

外部系統用 API 權杖存取，不是用某個人的帳號。權杖在設定頁核發，可以隨時停用而不影響任何人登入。

  • 租戶由權杖決定，請求裡不帶 schema 也不能指定
  • 每支權杖各自計算流量限制，一個對接爆量不會拖垮其他對接
  • 停用是保留紀錄的停用，不是刪除 —— 誰曾經有過存取權這件事會留下來
curl https://console.example.com/api/v1/employees \ -H "Authorization: Bearer $FINCOHR_TOKEN" \ -H "Accept: application/json"
權限範圍

一支權杖，只開它需要的門

讀與寫是分開的範圍。一個只需要推班表的系統，不應該因此就能讀到薪資。

hr.employees.read 讀取

讀取員工清單與個別員工資料。

hr.employees.write 寫入

建立與更新員工資料。

hr.attendance.read 讀取

讀取出勤紀錄與月度彙總。

hr.attendance.write 寫入

寫入打卡事件與工作紀錄。

hr.leave.read 讀取

讀取假別餘額與請假申請。

hr.schedules.read 讀取

讀取班表與可排班人員。

hr.schedules.write 寫入

批次寫入排班。

hr.webhooks.manage 寫入

管理 webhook 訂閱與查詢送達紀錄。

端點

v1 提供哪些端點

目前的端點集中在會被外部系統實際用到的部分：員工、出勤、假別餘額與班表。

GET /api/v1/employees GET /api/v1/employees/{id} POST /api/v1/employees PATCH /api/v1/employees/{id} GET /api/v1/attendance GET /api/v1/attendance/summary POST /api/v1/attendance/clock-events POST /api/v1/attendance/work-records GET /api/v1/leave/balances GET /api/v1/leave/requests GET /api/v1/schedules GET /api/v1/schedules/available-staff POST /api/v1/schedules/bulk GET /api/v1/webhooks POST /api/v1/webhooks GET /api/v1/webhooks/{id}/deliveries DELETE /api/v1/webhooks/{id}
Webhook

不用輪詢，事情發生時通知你

註冊一個網址並訂閱事件，人事異動或薪資結算發生時，Console 主動把載荷 POST 過去。

  • 每個訂閱有自己的簽章密鑰，加密存放而非明文
  • 送達紀錄保留下來：這個端點被通知了什麼、什麼時候
  • 更換密鑰是獨立動作，不會因為改個標籤就讓接收端失效
可訂閱的事件
6 種
employee.created 新員工建立時
employee.terminated 員工離職時
leave.approved 請假核准時
leave.cancelled 假單取消時
payroll.finalized 薪資期間結算時
attendance.anomaly 出勤異常被標記時
核發權杖是獨立權限

核發一支能讀員工資料的權杖，比自己在畫面上讀員工資料是更大的行為。所以 hr.api.manage 是獨立的權限碼，不包含在一般設定權限裡。

密鑰加密存放

Webhook 簽章密鑰以應用程式金鑰加密後儲存。也因此 APP_KEY 與它的任何備份都必須當成機密資料看待。

停用而非刪除

權杖撤銷與 webhook 取消註冊都是停用，資料列保留下來。存取權消失了，但「這個端點曾經有過存取權」的紀錄還在。

下一步

想知道能不能接上貴公司的流程？

告訴我們貴公司現在怎麼算薪資、用什麼打卡機、有幾個部門，我們直接回覆能不能對接。

進入體驗環境 聯絡我們