客戶 API

建立、查詢、更新和刪除店鋪中的客戶。

端點列表

GET

/customers

customers:read

取得分頁客戶列表。

GET

/customers/:id

customers:read

透過 ID 取得單一客戶資訊。

POST

/customers

customers:write

建立新客戶。

PUT

/customers/:id

customers:write

更新現有客戶資訊。支援部分更新。

DELETE

/customers/:id

customers:write

軟刪除客戶。記錄可在 30 天內恢復。

欄位參考

欄位	類型	必填	描述
id	string	否	唯一客戶識別碼（唯讀）
name	string	是	客戶姓名
email	string	是	客戶電子郵件
phone	string	否	含國碼的電話號碼
createdAt	datetime	否	ISO 8601 時間戳（唯讀）
updatedAt	datetime	否	ISO 8601 時間戳（唯讀）

查詢參數（列表）

欄位	類型	必填	描述
page	integer	否	頁碼（預設：1）
limit	integer	否	每頁筆數（預設：20，最大：100）
q	string	否	依客戶姓名或郵件搜尋

範例

分頁取得客戶列表

bash

curl "https://api.mercozy.com/api/v1/external/customers?page=1&limit=20" \
  -H "X-API-Key: mk_live_xxxxx"

建立客戶

bash

curl -X POST "https://api.mercozy.com/api/v1/external/customers" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

回應範例

json

{
  "data": {
    "id": "cust_abc123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "createdAt": "2025-12-15T10:30:00Z",
    "updatedAt": "2025-12-15T10:30:00Z"
  }
}