# 快速上手

## API 權限申請流程

### Step1：申請安裝 OPEN API

104 HR Max 提供 API 串接功能，若您是 HR Max 的客戶，需要透過 API 串接跨系統資料，請聯繫 104 服務人員安裝 OPEN API。

安裝完成後，104 會透過 E-mail 提供貴司 API 管理後台的連結，請使用身分為 「Admin 使用者」 的後台管理帳號登入 API 管理後台，以設定相關開放人員及資料權限。

### Step2：新增 API 使用帳號

登入 HR Max  API 管理後台後，前往： 「api連接帳號及權限」 ，接著點擊右上角 【新增帳號】 ，並完成以下必填欄位設定。

1. API登入帳號：
   * 該帳號登入的帳號，建議用英文或數字設定
2. 帳號名稱：
   * 可填寫中文，做後台管理時好辨識該帳號是開放給哪個人員使用
3. API 串接模式：
   * Token串接模式：適用提供給外部廠商或者無固定IP位置的人員使用。
     * 依據設定的使用者帳號、密碼後，提供帳號密碼給開發者即可使用。
   * API金鑰模式：適合提供給內部開發者或者有固定IP位置的人員使用。
     * 依據設定的IP位置(由開發者提供)，再點擊「產生」取得金鑰，提供金鑰給開發者即可使用。
4. 帳號狀態：
   * ON 則帳號可使用，OFF則帳號關閉。
   * 若原使用的人員離職或不開放給開發者時，建議關閉

### Step3：設定 API 使用帳號的權限

點擊帳號左方對應的 【變更權限】 按鈕，並完成以下必填欄位設定。

* 可存取公司：
  * 可設定想要開放給予存取的公司即可，若為貴司僅有一個公司那可設定全部公司選項。
* API 是否可使用：
  * API 分為登入(api/auth開頭)、組織(api/os)、人事(api/ed)、出勤(api/am)、薪資(api/pb)、表單(api/wf)、系統(api/sys)、檔案(api/file)…等類別。
  * 依據要開放給開發者設定勾選可使用即可，若非相關需求建議不開放。
  * 舉例：提供給外部績效考核系統做存取，建議就開放登入(api/auth)、組織(api/os)、人事(api/ed)的API勾選使用。
* API 回傳欄位如何設定：
  * 通常勾選API可使用後，會自動帶出可回傳欄位值。
  * 若有不想開放的欄位值再手動刪除，建議不去手動刪除。

{% hint style="info" %}
**特別注意：若帳號為 【Token串接模式】，一定要勾選以下 API ，該帳號才可使用帳號密碼登入**。

* `/api/auth/signIn 登入`
* `/api/auth/signOut 登出`
* `/api/auth/token/refresh 更新access token`
* `/api/os/company 取得公司資訊`
  {% endhint %}

### Step4：開發 API 串接相關應用

依據帳號的 API 串接模式不同，HR 需提供給開發人員不同串接所需資訊：

* Token串接模式：設定API登入帳號、設定密碼。
* API金鑰模式：帳號設定頁面點擊產生出的金鑰。

開發人員可參考下方流程圖，進行 API 權限設定。

<figure><img src="https://1470294451-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FtWgkeITsy3LpiZcJRWJC%2Fuploads%2FI81hSDzRncqeXBcKuHbL%2F%7B1C7DF895-B35D-4ED1-AEF0-A2853C5EAD07%7D.png?alt=media&#x26;token=f583e166-71e8-46ac-ac09-85eff18acc15" alt=""><figcaption></figcaption></figure>

* Token串接模式：
  * 將收到的帳號密碼透過 `/api/auth/signIn 登入系統` 取得 ”ACCESS\_TOKEN”。
  * 將取得的 ”ACCESS\_TOKEN” 加進 header 的 authorization 屬性，使用 Bearer 驗證方式，即可順利發送需求。
  * 每次呼叫  `/api/auth/signIn 登入系統` 會產生一組新的 ”ACCESS\_TOKEN”。
  * 若 ”ACCESS\_TOKEN” 失效，請使用 `/api/auth/token/refresh 更新 access token`  重新取得  ”ACCESS\_TOKEN”。
* API金鑰模式：
  * 於 `Authorize Values` 輸入框內，填入 API 管理後台提供的金鑰代碼。

## API 使用注意事項

1. access token 時效為 1 小時，過期後須重取。
2. 每秒最多 30 次。
3. API 串接可能遇到例外狀況(如網路異常、停機)，建議串接時設計重送機制。