> For the complete documentation index, see [llms.txt](https://help.firstline.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.firstline.cc/developer/api.md).

# API 說明

{% hint style="success" %}

## **API 與 Webhook 串接須知**

串接 API 與 Webhook 需由具備相關背景的**工程或技術人員進行整合作業**，FIRST LINE 客服團隊**不提供此類技術支援服務**。

建議您在進行操作前自行評估內部技術資源。如您有進一步整合需求或需要協助，也可參考我們的**進階付費技術支援項目**，以獲得更完整的技術協助與導入建議。
{% endhint %}

## 認證方式與適用範圍

一般 FIRST LINE API 使用**員工存取權杖（Access Token）**，可操作的資料與功能取決於該員工的權限。**Headless Conversation API 使用獨立的管道憑證**，與員工存取權杖不能混用。

### 方式一：從員工介面取得 Token

由有權限的管理者在 FIRST LINE「系統 → 員工」找到對應員工並產生 Token。若重新產生，請同步更新串接系統保存的 Token，避免原有連線失效。

<figure><img src="https://842546780-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MNRu7dk70ei7JV9HlW9%2Fuploads%2F7CcR52Z5UkdGtmNh3kvJ%2Fimage.png?alt=media&amp;token=b24624b8-d39c-4385-948d-9e97d0c83e24" alt=""><figcaption></figcaption></figure>

### 方式二：由 API 登入取得 Token

**POST** `https://{API_HOST}/api/v1/auth`

使用 **JSON Request Body**，不要把帳號或密碼放進 URL。

| JSON 欄位    | 類型      | 必填 | 說明                                |
| ---------- | ------- | -- | --------------------------------- |
| `name`     | string  | 是  | 員工登入帳號                            |
| `password` | string  | 是  | 員工密碼                              |
| `ttl`      | integer | 否  | 有效時間（分鐘），預設 60；是否允許較長期限依實際權限與安全政策 |

```bash
curl -X POST "https://{API_HOST}/api/v1/auth" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"name":"YOUR_EMPLOYEE_ACCOUNT","password":"YOUR_PASSWORD","ttl":60}'
```

成功回應會包含 Access Token 與相關資訊；後續請求以 `Authorization: Bearer YOUR_ACCESS_TOKEN` 帶入。

### 更新 Token

**PUT** `https://{API_HOST}/api/v1/auth`

使用目前有效的 Access Token 取得新 Token，**不需要再次傳送帳號或密碼**。

```bash
curl -X PUT "https://{API_HOST}/api/v1/auth" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

成功後會回傳新的 `access_token`、`token_type`、`expires_in`，請更新串接端保存的 Token。

### 使 Token 失效

**POST** `https://{API_HOST}/api/v1/auth/logout`

```bash
curl -X POST "https://{API_HOST}/api/v1/auth/logout" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

成功回應：

```json
{"message":"Successfully logged out"}
```

### 呼叫其他 API

```http
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
```

`Content-Type` 用於有 JSON Request Body 的請求；GET 等沒有 Body 的請求通常只需 `Accept`。請**勿把 Access Token 放在網址參數中**（例如 `?token=...`），以免憑證出現在網址紀錄中。

{% hint style="warning" %}
Token 僅應儲存在可信任的後端環境。請求發生 `401`、`403` 時，先檢查憑證是否有效、員工權限是否足夠，以及 Token 是否被重新產生或撤銷。
{% endhint %}

{% hint style="success" %}

### 🔗 需要專家提供 API 開發與串接支援？

提供額外付費的專業服務，能協助您順利導入內外部系統的介接，包括機器人腳本等資料流程整合。我們致力於完善 API 策略佈署和資料串接，以確保系統整合流暢，提供最佳的使用體驗。

我們的專業團隊將為您提供全方位的支援，確保您的需求得到有效解決。
{% endhint %}