“客戶資料接口”是為增強客服能力，對有自建客戶系統，同時又具備一定開發對接能力的用戶，提供的對接接口。完成對接后，可以在知你客服后臺顯示用戶在您的客戶管理系統中的用戶信息，如訂單，歷史服務記錄等等。接口分為兩個部分：“查詢接口”和“綁定接口（非必須）”。 ## 查詢接口 查詢接口是通過知你唯一用戶ID(uid)去你方的客戶系統查詢具體的客戶信息。返回結果顯示在聚合聊天的“客戶資料”選項卡里。 **查詢接口配置方法：** **1. 超級管理賬號在設置-API對接中填寫你方的查詢地址** 舉例：https://example.zhinikefu.com/query  配置好后，當公眾號或小程序用戶點擊客服發起咨詢時，我們會帶上用戶咨詢來源小程序或公眾號的appid，用戶在該公眾號或小程序的openid及其他相關參數信息，向這個查詢接口獲取具體的客戶信息。 示例：https://example.zhinikefu.com/query?uid=xxx&timestamp=xxx&nonce=xxx&sign=xxx。具體參數如下： | 參數名 |說明| 備注 | | --- | --- | --- | | uid | 用戶ID | 必選參數 | | appid | 查詢公眾號和小程序信息時，用戶所在公眾號或小程序的appid |公眾號、小程序用戶使用此參數，其它渠道用戶不使用此參數 | openid| 查詢公眾號和小程序信息時，用戶openid|公眾號、小程序用戶使用此參數，其它渠道用戶不使用此參數 | cid| 網站接入網頁在線客服插件代碼中的channel\_id|網頁在線客服咨詢用戶使用此參數，其它渠道用戶不使用此參數 | tpuid| 網頁在線客服插件中自定義的訪客唯一身份標識client\_id|網頁在線客服咨詢用戶使用此參數，其它渠道用戶不使用此參數 | timestamp | 請求時間戳 | 可以對時間做一個校驗，降低重放攻擊 | | nonce | 長度16的隨機數（字母+數字） | 增加簽名結果的隨機性 | | sign | 簽名 | 詳情見「關于簽名」 | **2. 查詢結果輸出參數要求** 如果客戶系統查詢到相關客戶信息，**請您按以下參數要求輸出返回JSON的形式數據**： ``` { "errcode": 0, // 0 為正常響應 "data": { "crm_info": [ { "label": "手機號", "type": "text", //文本類型信息 "value": "13100000000" }, { "label": "訂單記錄", "type": "link", //鏈接類型信息 "value": "點擊查看訂單詳情", "url": "https://zhinikefu.com/" //需要打開的鏈接 }, { "label": "活動名稱", "value": "活動詳情", "type": "wxmapp", //微信小程序類型信息 "appid": "wx899webu3383a", //微信小程序的appid "ghid": "gh_ae6449501a82", //微信小程序gh開頭的原始ID "path": "/pages/detail/detail?eid=676a24ad3f16efd7c6965924", //選填，需要打開的小程序路徑，默認空時會打開首頁 "url": "https://zhinikefu.com/" //選填，備用鏈接，如果無法打開小程序會打開此url } ] } } ``` **返回參數說明：** data里的每一個對象，都是一組用戶信息，label表示標題，value表示具體的客戶信息。**errcode為-100的時候，表示用戶未綁定**，會展示下圖頁面,其它非0值表示獲取用戶信息失敗  <br> <br> ## 綁定接口（非必須） 對于公眾號和小程序用戶，如果您的客戶系統中可以通過 appid 和 openid 確定并返回用戶信息，則不需要綁定。 <br> 但如果您的客戶系統除了appid 和 openid外，需要更多用戶信息參數（如 手機號）才能允許查詢到您客戶系統對應的用戶信息，則需要您額外配置 “綁定接口” 。 <br> 綁定接口配置完成后，當客戶咨詢發起對話時，客服需要在我的對話頁面中的“客戶資料”選項卡界面，手動填寫額外的用戶信息后才能完整用戶綁定過程，綁定后就可以直接查詢到該用戶在您客戶系統中的信息了。 <br> **綁定接口配置方法：** **1. 超級管理賬號在設置-API對接中填寫你方的綁定地址**  當客服在“客戶資料”選項卡界面發起綁定操作的。發送POST請求到綁定地址。綁定參數這一欄，“綁定參數名”是給客服看到，參數key是給服務端對接獲取用的。例如，我們給自己客服系統增加的配置：  **2. 客服同學手動填寫額外用戶信息完成綁定過程** 當客戶咨詢發起對話時，客服需要在我的對話頁面中的“客戶資料”選項卡界面，手動填寫額外的用戶信息后完成用戶綁定過程，你方系統需要記錄客服手動填寫的用戶綁定信息和該用戶的綁定關系，綁定后我方系統會通過上面的查詢接口去你方客戶系統中查詢該用戶在的信息。 例如：  當客服填入手機號：13100000000，點擊綁定后，我們會組裝一個POST請求，發送到綁定地址。 具體發送參數如下： | 參數名 |說明| 備注 | | --- | --- | --- | | uid | 用戶ID | | | appid | 公眾號或小程序appid|公眾號、小程序使用此參數查詢，其它渠道用戶不使用此參數 | openid| 公眾號或小程序openid |公眾號、小程序使用此參數查詢，其它渠道用戶不使用此參數 | bind | 表示綁定還是解綁（0：解綁 1：綁定）| | | bind_key | 參數名（bind=0不存在此字段） |比如：phone | | bind_value | 參數值（bind=0不存在此字段） | 比如：13100000000 | | name | 用戶名稱（bind=0不存在此字段） | | | avatar | 用戶頭像（bind=0不存在此字段） | | | timestamp | 請求時間 | | | nonce | 長度16的隨機數（字母+數字） | | | sign | 簽名 | 用于合法性驗證 | **返回參數說明：** 如果客服輸入的手機號在客戶系統查到，綁定成功后，應返回JSON格式的消息體，errcode為0，如：{"errcode":0}，網頁端收到正確的返回值后，會自動調用一次查詢接口，查詢關聯的客戶信息。當收到errcode值不為0時，則認為綁定失敗，會重新顯示綁定界面。 <br> ## 關于簽名 為了接口合法使用，我們對接口調用進行了鑒權。在設置界面完善信息后，我們系統會生成一串隨機碼，即密鑰（SecretKey）。在調用貴司接口的時候，我們服務端會根據SecretKey，計算出簽名值，即sign，具體算法如下： 所有發送的數據為集合M，集合M中添加secret= SecretKey (客戶資料對接界面顯示的secretKey)，將集合M內參數按照參數名ASCII碼從小到大排序（字典序），使用URL鍵值對的格式（即key1=value1&key2=value2…）拼接成字符串stringA，并對stringA進行sha256運算，再將得到的字符串所有字符轉換為大寫，得到sign值signValue