# 快速上手

## 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="/files/jM29qii12RLt5VFN4QPj" 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 串接可能遇到例外狀況(如網路異常、停機)，建議串接時設計重送機制。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://104ha-docs.gitbook.io/104-ha-openapi/clients/104-hr-max/quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.