> 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/request-methods.md).

# 請求方式說明

FIRST LINE 的 REST API 依端點使用 `GET`、`POST`、`PUT`、`DELETE` 等 HTTP 方法，**實際 Method 以各端點文件為準**。

| 方法       | 常見用途      | 參數放置位置                            |
| -------- | --------- | --------------------------------- |
| `GET`    | 查詢資料      | Path Parameters、Query Parameters  |
| `POST`   | 建立資料或執行動作 | Path Parameters、JSON Request Body |
| `PUT`    | 更新資料      | Path Parameters、JSON Request Body |
| `DELETE` | 刪除資料      | Path Parameters；其他資料依個別端點規定       |

## 標準 Headers

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

請在 `Authorization` Header 帶入 Access Token，不要放在網址中。若請求沒有 JSON Body（例如 GET），可省略 `Content-Type`。

## POST：建立客戶的範例

```bash
curl -X POST "https://{API_HOST}/api/v1/contact" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "陳",
    "last_name": "大華",
    "membership_no": "R0000555",
    "gender": 0,
    "birth_at": "1990-01-01"
  }'
```

在 Postman 中選擇 **Body → raw → JSON**；不要把 `first_name` 等建立資料放進 URL query string。

## GET：以 Query Parameters 篩選

```bash
curl -G "https://{API_HOST}/api/v1/contact" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "page=1" \
  --data-urlencode "search=John"
```

**GET 查詢條件應透過 Query Parameters 傳送，不要以 GET Request Body 提供 JSON。**

## PUT：更新客戶的範例

```bash
curl -X PUT "https://{API_HOST}/api/v1/contact/2" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"王","last_name":"小明"}'
```

若端點標示使用 `PUT`，請直接以 `PUT` 發送請求。若使用的串接工具不支援該方法，請確認工具設定；不要自行將所有 `PUT` 改成 `POST`。

## HTTP 狀態碼

| 狀態碼         | 說明與建議                           |
| ----------- | ------------------------------- |
| `200`       | 請求成功；讀取回應 JSON                  |
| `201`       | 資源建立成功（依各端點實際回應）                |
| `204`       | 成功且沒有 Response Body；不要嘗試解析 `{}` |
| `400`       | 請求格式不正確                         |
| `401`       | 未通過身分驗證或 Token 失效               |
| `403`       | 已驗證但權限不足                        |
| `404`       | 指定資源不存在或不可存取                    |
| `405`       | HTTP Method 不受該端點支援             |
| `422`       | 欄位驗證失敗；依錯誤訊息調整輸入                |
| `429`       | 請求過於頻繁；降低頻率並退避重試                |
| `500`、`503` | 伺服器或服務暫時異常，保留 Request ID／時間以利排查 |

{% hint style="info" %}
同一狀態碼的實際回應格式會依 API 不同。請以各端點列出的成功狀態碼、Response Body 與驗證規則為準。
{% endhint %}