Skip to main content

會員API

新增 / 更新會員 API

將會員資料推送進 iftek 平台。平台會依「手機號碼」自動判斷要新增還是更新會員（upsert）。

目錄

總覽

項目 內容
用途 由貴公司系統將會員資料匯入 iftek 平台
方法 POST
端點 /api/v1/openApi/memberInfo
內容格式 application/json
行為 依手機號碼自動 新增或更新（upsert）

快速開始

curl -X POST https://<iftek-host>/api/v1/openApi/memberInfo \
  -H "Content-Type: application/json" \
  -d '{
    "token": "company-auth-token-xxxxx",
    "memName": "王小明",
    "memMobile": "0912345678",
    "memEmail": "[email protected]"
  }'

成功時回應：

{ "status": "success" }

認證

  • 每個請求的 body 都必須帶上 token 欄位，平台會用它換出對應的公司（comId）。
  • token 由 iftek 提供，請妥善保管，勿外洩。
狀況 回應
token 有效 200，{ "status": "success" }
token 無效 / 未授權 403（error token）

新增 / 更新 判斷邏輯

平台以 公司（由 token 推得）+ 手機號碼（memMobile） 來比對既有會員：

情況 結果
有帶 memMobile，且查到既有會員 更新該會員
有帶 memMobile，但查不到 新增會員
未帶 memMobile 一律視為新增（無法比對既有會員）

💡 若希望走「更新」流程，請務必帶上正確的 memMobile。

請求格式

請求 body 是一個 JSON 物件。除了必填的 token，其餘 key 可以是「系統預設欄位」或「自訂欄位」。

系統預設欄位

使用 camelCase 名稱，value 為字串。

欄位 說明 必填
token 公司授權 token（用於識別公司） ✅
memMobile 手機號碼（新增/更新的比對鍵） 建議
memName 客戶姓名
memTel 電話
memEmail Email
memSex 性別
memNickName 暱稱
memBirthday 生日（西元）
memCountry 客戶國別
memAddress 地址
memRemark 備註
introducerName 介紹人姓名
introducerMobile 介紹人電話
introducerType 介紹人身份
thirdPartyCustomerId 第三方客戶編號

必填欄位的檢核由平台後端負責，若不合法會回錯誤。

自訂欄位

key 使用貴公司在「會員設定頁」設定的 apiCode，平台會自動對應回內部欄位。 value 格式依該欄位類型（mscType）而定：

mscType 類型 value 格式 範例
1 西元日期 物件 { "gregorianDate": "yyyy-MM-dd" } {"gregorianDate":"2024-03-15"}
2 農曆 物件 { "yearCyclical", "monthCode", "lunarDay" } {"yearCyclical":"甲子","monthCode":"4X","lunarDay":15}
3 文字框 字串 "自由輸入"
4 文字區域 字串 "多行文字"
5 城市 城市 pk（數字） 100
6 區域 區域 pk（數字） 1001
7 道路 道路 pk（數字） 5001
8 地址 字串 "忠孝東路一段1號"
9 郵遞區號 字串 "100"
10 特殊標籤 暫不支援匯入（傳了會被忽略） —

農曆 monthCode 規則： "4" = 4 月、"4X" = 閏 4 月；lunarDay 為數字。

回應

HTTP 狀態 說明 Body
200 匯入成功 { "status": "success" }
403 token 無效 / 未授權 error token

完整範例

{
  "token": "company-auth-token-xxxxx",
  "memName": "王小明",
  "memMobile": "0912345678",
  "memEmail": "[email protected]",
  "memSex": "1",
  "memBirthday": "1990-01-01",

  "custom_text_field": "自由輸入內容",
  "custom_gregorian_field": {
    "gregorianDate": "2024-03-15"
  },
  "custom_lunar_field": {
    "yearCyclical": "甲子",
    "monthCode": "4X",
    "lunarDay": 15
  },
  "custom_city_field": 100
}

注意事項

  • ⚠️ 西元日期、農曆必須傳「物件」，不可傳純字串，否則會解析失敗並回錯誤。
  • ⚠️ 城市 / 區域 / 道路傳的是 pk（數字），不是名稱。
    • 註：iftek 主動推播給貴公司的 outbound webhook 輸出的是「名稱」字串，與此匯入 API 所需的 pk 格式不同，串接時請勿直接把收到的名稱回傳。
  • 未被識別的 key 會原樣帶入後端，由後端驗證決定是否接受。
  • 必填欄位的檢核由後端負責；不合法會回錯誤。
  • 特殊標籤（mscType 10）目前暫不支援匯入，傳了會被忽略。
Back to top