# K12開(kāi)發(fā)文檔

# 1. 接口規(guī)范

問(wèn)題：基于平臺(tái)提供的通用接口能力，服務(wù)商自由度高但缺少經(jīng)驗(yàn)，方案落地后出現(xiàn)接口調(diào)用不合理、無(wú)法正常使用，代扣時(shí)序和模版不清晰，家長(zhǎng)質(zhì)疑扣錯(cuò)款導(dǎo)致客訴。

目標(biāo)：指導(dǎo)服務(wù)商合理地使用接口能力封裝方案，學(xué)校上線后避免用戶鏈路中斷或體驗(yàn)感極差而導(dǎo)致客訴。

接入規(guī)范：
詳情請(qǐng)點(diǎn)擊進(jìn)入《離線刷臉SDK商戶接入規(guī)范（終端）》查閱。
詳情請(qǐng)點(diǎn)擊進(jìn)入《離線刷臉后端接口商戶接入規(guī)范（后臺(tái)）》查閱。
簽約/解約接入規(guī)范請(qǐng)查閱下述內(nèi)容。

# 1.1 簽約

# 1.1.1 簽約后信息同步

問(wèn)題1：小程序傳入?yún)?shù)錯(cuò)誤，用戶無(wú)法進(jìn)入k12官方小程序進(jìn)行簽約？

方案：

【接口文檔】必須遵守如下規(guī)則：

【界面提示】常見(jiàn)參數(shù)異常提示優(yōu)化，讓服務(wù)商可以自行快速地調(diào)整。

目前彈窗提示與優(yōu)化后的彈窗提示分別如下圖所示：

傳參異常提示列表：

問(wèn)題2：用戶簽約后，學(xué)生信息（姓名/班級(jí)/手機(jī)號(hào)）等在簽約后因?yàn)閾Q班、家長(zhǎng)換手機(jī)等情況修改，如果沒(méi)有及時(shí)同步給微信平臺(tái)，會(huì)導(dǎo)致學(xué)生無(wú)法正常使用刷臉。
方案：當(dāng)學(xué)生信息有變更時(shí)，調(diào)用用戶信息修改接口、傳入最新信息。

# 1.1.2 簽約后重新采集人臉

問(wèn)題：用戶簽約后，因?yàn)椴慑e(cuò)照片等原因無(wú)法刷臉識(shí)別？
方案：服務(wù)商可調(diào)用重新采集接口、在學(xué)校給學(xué)生重采人臉；然后讓家長(zhǎng)打開(kāi)小程序，確認(rèn)重采的學(xué)生人臉照片后，系統(tǒng)即替換掉簽約時(shí)的照片。

# 1.2 代扣

# 1.2.1 訂單補(bǔ)扣

問(wèn)題：代扣發(fā)起時(shí)間在深夜或節(jié)假日，家長(zhǎng)收到后質(zhì)疑亂扣費(fèi)，導(dǎo)致客訴？

接口規(guī)范建議：

【補(bǔ)扣時(shí)間】不干擾家長(zhǎng)休息
● 建議時(shí)段，對(duì)于三餐都有的學(xué)校，建議工作日早上6：00-8：00、中午11:00-14:00、晚上16:00-20:00，對(duì)于僅中午有食堂的學(xué)校，建議中午11:00-14:00；周末節(jié)假日如果學(xué)生不在校，建議不發(fā)起補(bǔ)扣；
● 建議頻率，每筆訂單每天嘗試扣款最多5次，超過(guò)5次會(huì)被攔截。

【公眾號(hào)通知】說(shuō)明清晰，避免誤解
● 每筆訂單單獨(dú)進(jìn)行補(bǔ)扣，不建議多筆欠款合并一起扣款；
● 強(qiáng)調(diào)“訂單延遲扣款”，與正常支付消息區(qū)分明顯，避免誤以為重復(fù)扣款；
● 設(shè)備斷網(wǎng)、銀行系統(tǒng)維護(hù)等原因也會(huì)導(dǎo)致扣款延誤，所以避免用“欠款”字樣等可能引起用戶抵觸的文字。
延時(shí)扣款消息與普通支付消息分別如下圖所示：

延遲原因與文案建議：

# 1.2.2 訂單跨節(jié)假日支付

問(wèn)題：學(xué)校放假時(shí)關(guān)閉設(shè)備，部分訂單未及時(shí)上傳，節(jié)后發(fā)現(xiàn)訂單過(guò)期無(wú)法扣費(fèi)？
接入規(guī)則建議：
設(shè)備使用后預(yù)留1小時(shí)，等訂單上傳完成后，再關(guān)機(jī)或斷網(wǎng)。
訂單有效期為7天，節(jié)假日會(huì)適當(dāng)延長(zhǎng)，如果遇到訂單失效，則需向平臺(tái)方申請(qǐng)延長(zhǎng)有效期。

# 1.2.3 大額代扣調(diào)用

問(wèn)題：學(xué)校包餐制，單筆金額大于100元？
可以調(diào)用大額代扣接口：
消費(fèi)額度：?jiǎn)喂P最大額度為500元。
頻率限制：教職工微信號(hào)限頻為40次/月、userid為20次/月；學(xué)生的簽約微信號(hào)為5次/月。

# 1.2.4 支付憑證內(nèi)容展示

問(wèn)題：支付憑證內(nèi)容不清晰，家長(zhǎng)不確定是否學(xué)生本人刷臉消費(fèi)，導(dǎo)致客訴核實(shí)？
接口規(guī)范建議：扣費(fèi)內(nèi)容信息要具體、清晰，避免家長(zhǎng)疑惑。

樣式示例：

# 1.3 解約

# 1.3.1 解約后重新簽約

問(wèn)題：微信號(hào)凍結(jié)/丟失等原因，無(wú)法還款、導(dǎo)致無(wú)法再使用刷臉代扣？
指導(dǎo)服務(wù)商獲取還款鏈接，讓用戶通過(guò)其他微信號(hào)還款，然后通過(guò)后臺(tái)接口進(jìn)行解約，讓用戶使用其他微信號(hào)重新簽約。
● 還款鏈接：服務(wù)商后臺(tái)獲取墊資的還款鏈接、線下向用戶核實(shí)后，人工轉(zhuǎn)發(fā)給還款的微信號(hào)；

● 后臺(tái)解約：服務(wù)商調(diào)用后臺(tái)解約接口進(jìn)行解約。

# 1.3.2 畢業(yè)批量解約

問(wèn)題：畢業(yè)季學(xué)生家長(zhǎng)未解約，服務(wù)商如何清理數(shù)據(jù)？

● 后臺(tái)解約：調(diào)用后臺(tái)解約接口，服務(wù)商獲知畢業(yè)學(xué)生名單后，可以對(duì)畢業(yè)學(xué)生進(jìn)行批量解約，注意控制調(diào)用解約接口的頻率。

# 2. 簽約小程序

跳轉(zhuǎn)一共包含3種場(chǎng)景，簽約，集采照片和確認(rèn)重采照片。

跳轉(zhuǎn)方式：詳情請(qǐng)點(diǎn)擊wx.navigateToMiniProgram查看。

場(chǎng)景1：集采照片

主要用于學(xué)校統(tǒng)一采集學(xué)生照片場(chǎng)景，目的是為了提高簽約效率，實(shí)現(xiàn)錄入照片的操作。

wx.navigateToMiniProgram({
	appId:'wx5931af4836330935', //采集小程序appid
	path:'/pages/face_take_photos/take_photos?is_first=1', //小程序路徑
	extraData: {
		type:'take_photo',//采集跳轉(zhuǎn)
		user_name: '張三',   //刷臉用戶姓名
		school_name:'深圳中學(xué)', //學(xué)校
		user_type:'STAFF', //職業(yè)(STUDENT：學(xué)生,STAFF：職員)
		student_info:{'class_name':'1班'}, //class_name:班級(jí)，user_type為STUDENT時(shí)必傳
		staff_info:{'occupation':'教師'}, //occupation:職業(yè), user_type為STAFF時(shí)必傳
		school_list:["深圳中學(xué)", "寶安中學(xué)"],// 學(xué)校列表，至少包含本學(xué)校
		organization_id: 'O1947FD2089aed8785', //organazition_id
		out_user_id: 'test',  // out_user_id，商戶側(cè)的用戶ID，唯一不可重復(fù)
		account:'15988866666', // 簽約手機(jī)號(hào)
		token:'XCXab19673d0d0b5c0ffd980fb60ce82f5e', //商戶認(rèn)證憑據(jù)
	},
	envVersion: 'trial',    // 如果要跳轉(zhuǎn)體驗(yàn)版，加上這個(gè)參數(shù)，否則請(qǐng)不要加這個(gè)參數(shù)
	success(res) {
		// 成功跳轉(zhuǎn)到簽約小程序
	},
	fail(res) {
		// 未成功跳轉(zhuǎn)到簽約小程序
	}
})

referrerInfo字段說(shuō)明

{
	appId:'wx5931af4836330935', //采集小程序appid
	extraData:{
		'return_code':'SUCCESS',  //狀態(tài)碼
		'return_msg':'錄入成功',   //提示信息
	}
}

場(chǎng)景2：簽約

簽約正常流程，如果已有集采的照片，在簽約時(shí)會(huì)展示已經(jīng)錄入的照片，否則有錄入照片的流程。

wx.navigateToMiniProgram({
	appId:'wx5931af4836330935', //小程序id
	path:'/pages/face_index/index?is_first=1', //小程序路徑
	extraData: {
		type:'sign',//簽約跳轉(zhuǎn)
		user_name: '張三',   //刷臉用戶姓名
		school_name:'深圳中學(xué)', //學(xué)校
		user_type:'STAFF', //職業(yè)(STUDENT：學(xué)生,STAFF：職員)
		student_info:{'class_name':'1班'}, //class_name:班級(jí)，user_type為STUDENT時(shí)必傳
		staff_info:{'occupation':'教師'}, // occupation:職業(yè), user_type為STAFF時(shí)必傳
		school_list:["深圳中學(xué)", "寶安中學(xué)"],// 學(xué)校列表，至少包含本學(xué)校
		organization_id: 'oea567edbgADeG', // 機(jī)構(gòu)ID
		out_user_id: 'SEGdget123987789',  // 商戶側(cè)用戶ID
		account:'15988866666', // 簽約手機(jī)號(hào)
		token:'PRESIGN_DGET1233543djgegeedde'
	},
	success(res) {
		// 成功跳轉(zhuǎn)到簽約小程序
	},
	fail(res) {
		// 未成功跳轉(zhuǎn)到簽約小程序
	}

})

referrerInfo字段說(shuō)明

referrerInfo字段說(shuō)明 {
	appId:'wx5931af4836330935',
	extraData:{
		'return_code':'SUCCESS',
		'return_msg':'簽約成功',
	}
}

場(chǎng)景3：家長(zhǎng)確認(rèn)學(xué)生重采照片(低頻)

只要用戶學(xué)生照片質(zhì)量不合格，就需要重新錄入照片，家長(zhǎng)進(jìn)行確認(rèn)后即可使用新的照片刷臉消費(fèi)。

跳轉(zhuǎn)k12小程序參數(shù)字段

wx.navigateToMiniProgram({
	appId:'wx5931af4836330935', // 確認(rèn)小程序appid
	path:'/pages/photo_confirm_user/photo_confirm_user',//小程序路徑
	extraData: {
		type:'confirm_register_photo',// 家長(zhǎng)確認(rèn)學(xué)生重采照片場(chǎng)景
		user_name: '張三',   // 刷臉用戶姓名，學(xué)生名字
		school_name:'深圳中學(xué)', // 學(xué)校
		user_type:'STAFF', //職業(yè)(STUDENT：學(xué)生,STAFF：職員)
		organization_id: 'O1947FD2089aed8785', // 機(jī)構(gòu)ID
		out_user_id: '516064415', // 商戶的用戶ID
		account:'15988866666', //簽約手機(jī)號(hào)
		token:'XCXab19673d0d0b5c0ffd980fb60ce82f5e'
	},
	envVersion: 'trial',    // 如果要跳轉(zhuǎn)體驗(yàn)版，加上這個(gè)參數(shù)，否則請(qǐng)不要加這個(gè)參數(shù)
	success(res) {
		// 成功跳轉(zhuǎn)到小程序確認(rèn)流程
	},
	fail(res) {
		// 未成功跳轉(zhuǎn)到小程序確認(rèn)流程
	}
})

跳轉(zhuǎn)回商戶小程序攜帶參數(shù)

referrerInfo字段說(shuō)明 {
	appId:'wx5931af4836330935', // 商戶小程序appID
	extraData:{
		'return_code':'SUCCESS',
		'return_msg':'確認(rèn)成功',
	}
}

# 3. 終端接入

# 3.1 常用參考

請(qǐng)參考《刷臉Android SDK接入指南》。

# 3.2 業(yè)務(wù)流程

# 3.3 注意點(diǎn)

A、流程1、流程2任選其一即可；
B、使用“流程1”耗時(shí)可以更優(yōu)，適用于支付金額在開(kāi)始識(shí)別之前就已知的情況；
C、使用“流程2”耗時(shí)可以更長(zhǎng)，適用于支付金額在開(kāi)始識(shí)別之前未明確的情況；
D、展示完用戶信息后，獲取支付憑證和用戶點(diǎn)擊確認(rèn)可以并行處理，優(yōu)化支付耗時(shí)。

# 3.4 使用說(shuō)明

使用方式
A、安裝人臉App；
B、商戶接入人臉SDK。

注意點(diǎn)
A、商戶使用SDK接口均封裝在WxPayFace類(lèi)中，該類(lèi)以單例形式存在。調(diào)用結(jié)果統(tǒng)一由IWxPayfaceCallback回調(diào)；
B、參數(shù)或回調(diào)結(jié)果以Map形式傳遞，方便擴(kuò)展，具體字段名稱(chēng)及返回值定義參考文檔；
C、每次SDK退出（release或異常），如果重新調(diào)用任何其它api，都會(huì)重新調(diào)用init，并且回調(diào)之前的callback，這里建議init的callback固定為同?個(gè)，可以持續(xù)監(jiān)聽(tīng)對(duì)應(yīng)的回調(diào)事件。

//IWxPayfaceCallback//繼承?AIDL接?，?便服務(wù)商使?。?前僅提?個(gè)統(tǒng)?的回調(diào)接?。
public abstract interface IWxPayfaceCallback {
	public abstract void response(Map info) throws RemoteException;
}

# 3.5 通用請(qǐng)求參數(shù)（每個(gè)請(qǐng)求都需要帶）

經(jīng)過(guò)“初始化”，“獲取rawData”、“銷(xiāo)毀并釋放資源” 步驟外的所有流程都需要帶授權(quán)憑據(jù)和商戶基礎(chǔ)信息。

# 3.6 通用返回參數(shù)（每個(gè)請(qǐng)求都會(huì)回應(yīng)）

當(dāng)商戶刷臉APP向微信離線刷臉SDK請(qǐng)求時(shí)，都會(huì)返回通用的參數(shù)。

# 3.7 通用err_code

通用err_code（注意判空，不?定返回，只用于輔助查問(wèn)題作歸因，不存在的時(shí)候可以使用return_msg直接歸因）。

# 3.8 常規(guī)接口

（1）初始化（initWxpayface）
接口作用：對(duì)人臉SDK進(jìn)行初始化

public void initWxpayface(Context ctx,Map info, IWxPayfaceCallback callback);

請(qǐng)求參數(shù)（無(wú)通用參數(shù)）

返回參數(shù)
無(wú)特殊參數(shù)，只有returncode和returnmsg

示例

private void initPayFace() {
	Map<String, String> m1 = new HashMap<>();
	m1.put("ip", "xxx.xxx.xxx.xxx");
//若沒(méi)有代理,則不需要此行,代理ip請(qǐng)自行尋找
	m1.put("port", "8888");
//若沒(méi)有代理,則不需要此行，代理端口不一定是8888，根據(jù)代理設(shè)置來(lái)決定
	WxPayFace.getInstance().initWxpayface(this, m1, new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return ;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			Log.d(TAG, "response info :: " + code + " | " + msg);
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息: " + msg).printStackTrace();
				return ;
			}
			Log.d(TAG, "調(diào)用返回成功");
			/*
			在這里處理您自己的業(yè)務(wù)邏輯
			*/
		}
	});
}

建議：
A、您可以自定義一個(gè)Application，然后在自定義Application的onCreate()中調(diào)用initPayFace()完成人臉識(shí)別模塊的初始化；
B、您可以只在被調(diào)用人臉識(shí)別模塊的activity的onCreate()中完成initPayFace()的調(diào)用；
C、失敗或者超時(shí)請(qǐng)release后重試。

（2）獲取數(shù)據(jù)（getWxpayfaceRawdata）

public void getWxpayfaceRawdata(IWxPayfaceCallback callback);

請(qǐng)求參數(shù)
無(wú)參數(shù)

返回參數(shù)（包含returncode和returnmsg）

示例

private void getWxpayfaceRawdata() {
	WxPayFace.getInstance().getWxpayfaceRawdata(new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("returncode");
			String msg = (String) info.get("returnmsg");
			String rawdata = (String)info.get("rawdata");
			if (code == null || rawdata == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
			/*
			在這里處理您自己的業(yè)務(wù)邏輯
			*/
		}
	});
}

建議：失敗或者超時(shí)請(qǐng)重新release。

（3）獲取調(diào)用授權(quán)憑據(jù)authinfo

接口定義

POST https://api.mch.weixin.qq.com/v3/offlineface/authinfo

請(qǐng)求參數(shù)

返回結(jié)果

請(qǐng)求示例

<return_code>SUCCESS</return_code>
<return_msg>請(qǐng)求成功</return_msg>
<nonce_str>Tivppi4UXAbgLxk8e1Sij76YdowOFFii</nonce_str>
<sign>PL0EUID6A7ICWNKHCSMQC0UIXOYNSE5B</sign>
<appid>wx31fdaErqR31</appid>
<mch_id>12345689</mch_id>
<authinfo>q3OPhFtQBf6KZGqmZhejKCRy5K/ch0kwS11YSsEj9XmUGqcsT2QPHt0Oa7xaCMCoSZTWMmShCo4dOiO5tU+OJEsvSxXzn5m3Nkh747tinNlbpJmVq1zOPj+FJNndkzanxoiAddO8p1EfrmUhJs/aNf0pDfrPoVfkAapK+ZY6blwyaDQ9bB7+KkZq29kObsXOZ3thg+bxP4RAqC0oxNS4JiyP0uA1Euzxtkc9lCTebloFied8stILrMehUKukeMGkZ1SzTyc8/HFHApzHahNPX6yD8ttzYnhe+IRMFJgpuTlIvEOYZUxenPXE1A5clrPvOBeJDszX/OvZl4fpYWPpXAcVQlw+gfYhblt+rT6ALMsD73w/rT4NRriQEEraC4Pfb5yua4qAqv4TVo04</authinfo>
<expires_in>3600</expires_in>

建議：返回的接口憑證authinfo，可以在expires_in指定的有效期內(nèi)，同一臺(tái)機(jī)具上重復(fù)使用。

注意：authinfo有效期一般是36個(gè)小時(shí)，建議設(shè)備自動(dòng)每小時(shí)更新一次。

（4）銷(xiāo)毀并釋放資源（releaseWxpayface）

public void releaseWxpayface((Context cxt);

請(qǐng)求參數(shù)
無(wú)參數(shù)

返回參數(shù)
無(wú)參數(shù)

示例

private void releasePayFace() {
	WxPayFace.getInstance().releaseWxpayface(this);
}

注意：獲取rawdata和authinfo失敗或者超時(shí)時(shí)，調(diào)用此接口，即release后重試。

（5）手動(dòng)更新人臉庫(kù)（manualUpdateFaceDatas）

public void manualUpdateFaceDatas(Map info,IWxPayfaceCallback cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
如果returncode不為成功，可以使用返回的returnmsg，比如“正在更新中...” 可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void manualUpdateFaceDatas() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().manualUpdateFaceDatas(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
		}
	});
}
}

注意：
A、商戶app啟動(dòng)必須調(diào)用更新人臉庫(kù)；
B、SDK有自身的自動(dòng)更新邏輯，但是沒(méi)有回調(diào)，適用于同步少量數(shù)據(jù)的時(shí)間，比如商戶就餐期間等；
C、手動(dòng)更新同步存在回調(diào)，適用于同步大量數(shù)據(jù)的時(shí)間，比如商戶就餐前登錄賬號(hào)的時(shí)間，保證數(shù)據(jù)盡快同步到本地，使用時(shí)希望能設(shè)置loading頁(yè)面，禁止用戶操作，必須等待回調(diào)再開(kāi)始操作；
D、自動(dòng)更新同步在網(wǎng)絡(luò)良好的情況下一般要前端修改用戶信息3分鐘左右，手動(dòng)更新會(huì)更快一些，并且適用于機(jī)器重置數(shù)據(jù)后同步恢復(fù)數(shù)據(jù)狀態(tài)。
同步的原因主要是是增加新用戶信息；對(duì)刪除用戶出庫(kù)；更新用戶狀態(tài)（比如調(diào)整欠費(fèi)狀態(tài)、是否禁用等）。

（6）預(yù)加載識(shí)別資源（preloadSdkEnv）

public void preloadSdkEnv(Map info,IWxPayfaceCallback cb);

說(shuō)明：
一般情況下，應(yīng)用啟動(dòng)后的第一次調(diào)用開(kāi)啟攝像頭等api會(huì)耗時(shí)較長(zhǎng)，因?yàn)樯婕暗絊DK的初始化工作，涉及到很多io讀寫(xiě)，如果人臉庫(kù)規(guī)模越大，初始化時(shí)間越長(zhǎng)，如果提前preloadsdkenv加載資源，可以保證第一次開(kāi)啟攝像頭和識(shí)別啟動(dòng)很快。

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
無(wú)特殊參數(shù)，只有returncode和returnmsg，可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void preloadEnv() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().preloadSdkEnv(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || sdkVersion == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
			/*
			在這里處理您自己的業(yè)務(wù)邏輯
			*/
		}
	});
}

（7）獲取支付SDK相關(guān)信息（getSdkInfo）

public void getSdkInfo(Map info,IWxPayfaceCallback cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）

非通用錯(cuò)誤碼

無(wú)特殊參數(shù)，只有returncode和returnmsg，可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void getSdkInfo() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().getSdkInfo(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			String sdkVersion = (String)info.get("sdk_version");
			String faceFeatureVersion = (String)info.get("face_feature_version");
			int faceFeatureVersion = (Integer)info.get("user_info_dbcount");
			if (code == null || sdkVersion == null ||
			        !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
			/*
			在這里處理您自己的業(yè)務(wù)邏輯
			*/
		}
	});
}

（8）獲取用戶信息狀態(tài)（getUserInfo）

public void getUserInfo(Map info,IWxPayfaceCallback cb);

用途：
落地排查問(wèn)題專(zhuān)用，商戶需要獲取用戶信息在機(jī)器上的同步狀態(tài)，避免因?yàn)橥蕉鴮?dǎo)致的無(wú)法交易問(wèn)題。

請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）

示例

private void getUserInfo() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().getUserInfo(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
			final String status = (String) info.get(FacePayConstants.KEY_RET_FACE_FEATURE_STATUS);
			final String syncTimeStr = (String) info.get(FacePayConstants.KEY_RET_USER_SYNCTIME);
			final String updateTimeStr = (String) info.get(FacePayConstants.KEY_RET_USER_UPDATETIME);
			String result = TextUtils.isEmpty(status) ? "用戶不存在" : "用戶當(dāng)前狀態(tài):" + status;
		}
	});
}
}

（9）設(shè)置預(yù)覽view（setCameaPreview）

public void setCameaPreview(SurfaceView surfaceView,Map info,IWxPayfaceCallback cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）

可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void setCameaPreview(SurfaceView surfaceview) {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().setCameaPreview(surfaceview,params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
		}
	});
}
}

注意：
A、預(yù)覽view主要是用于攝像頭的圖像畫(huà)面回調(diào)，必須保證surface一定不能為空；
B、如果綁定的surfaceview調(diào)用surfaceDestroyed銷(xiāo)毀后，記得需要重新綁定。

（10）移除預(yù)覽view（removeCameaPreview）

public void removeCameaPreview(SurfaceView surfaceView,Map info,IWxPayfaceCallback cb);

注意：
預(yù)覽界面默認(rèn)可以自行進(jìn)行綁定和移除，特殊的surfaceview可以考慮自行移除預(yù)覽view。

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void removeCameaPreview(SurfaceView surfaceview) { //params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().removeCameaPreview(surfaceview,params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
		}
	});
}
}

（11）開(kāi)始識(shí)別（startVerify）

public void startVerify( Map info, IWxPayFaceCallbackAIDL cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

特殊的return_code

二級(jí)錯(cuò)誤碼參考

其它異常問(wèn)題可以直接參考接口返回的異常信息來(lái)做展示，needrestart

public class UserInfo implements Parcelable {
	private String userId;
	private String outUserId;
	private String status;
	//用戶狀態(tài)，F(xiàn)S_NORMAL為正常，其余非法，不能扣款
	...
}

示例

private void startVerify() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayface.getInstance().startVerify(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + "   ").printStackTrace();
				return ;
			}
			List<UserInfo> userInfos =(List<UserInfo>)info.get("user_info_list");
//是否需要輔助驗(yàn)證
			final Boolean needExtVerify = (Boolean) (info.get(FacePayConstants.KEY_RET_PARAMS_NEED_EXT_VERIFY));
			final Bitmap bitmap =(Bitmap)info.get("best_face_img");
			Handler handler = new Handler(Looper.getMainLooper());
			handler.post(new Runnable() {
				@Override
				public void run() {
					mImageView.setImageBitmap(bitmap);
					mImageView.requestLayout();
				}
			});
		}
	});
}

注意：
A、識(shí)別接口分為開(kāi)啟和停止，識(shí)別成功后會(huì)自動(dòng)停止；
B、識(shí)別失敗會(huì)自動(dòng)重新開(kāi)啟，并返回對(duì)應(yīng)的錯(cuò)誤信息，注意271378467/271378468/271378469的返回碼；
C、識(shí)別成功返回的userInfo類(lèi)型，記得在proguard里需要keep對(duì)應(yīng)的class -keep class com.tencent.wxpayface.data.UserInfo{ *; }；
D、startVerify后成功流程應(yīng)該是finishverify->getFacePayCredential；如果中途異常退出需要調(diào)用stopVerify，流程只支持串行，并行會(huì)提示271378531 ，上次識(shí)別未完成。

返回參數(shù)有提供人臉識(shí)別框的坐標(biāo)范圍，主要優(yōu)化現(xiàn)場(chǎng)照有多個(gè)人臉存在的場(chǎng)景，請(qǐng)商戶自己考慮勾選框?qū)?yīng)的顏色問(wèn)題。

（12）停止識(shí)別（stopVerify）

public void stopVerify(Map info,IWxPayfaceCallback cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）

可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void stopVerify() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().stopVerify(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
		}
	});
}
}

注意：
任意時(shí)刻都可以調(diào)用該接口，但是注意該接口調(diào)用后并不會(huì)清除上一次的識(shí)別數(shù)據(jù)，仍然可以走完支付流程。

（13）完成識(shí)別流程（ finishFaceVerify）

public void finishFaceVerify(Map info,IWxPayfaceCallback cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

二級(jí)錯(cuò)誤碼參考

示例

private void finishFaceVerify() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mchid等)
	WxPayFace.getInstance().finishFaceVerify(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("returncode");
			String msg = (String) info.get("returnmsg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,returnmsg:" + msg + " ").printStackTrace();
				return ;
			}
			UserInfo userInfo =(UserInfo)info.get("userinfo");
			if(userInfo == null || TextUtils.isEmpty(userInfo.getUserId()) {
			new RuntimeException("調(diào)用返回非成功信息,returnmsg: 用戶信息為空").printStackTrace();
				return ;
			}
//到此處才算成功，一定要注意userinfo和userid判空
		});
	}
}
}
}

注意：
開(kāi)始識(shí)別返回用戶信息后，不論是確認(rèn)還是取消，都需要調(diào)用完成才能進(jìn)行下一次識(shí)別。
如果識(shí)別成功返回了單個(gè)用戶信息，則不需要傳遞手機(jī)號(hào)，直接可以拿到當(dāng)前的識(shí)別用戶信息。
如果返回多個(gè)用戶信息，需要商戶傳遞手機(jī)號(hào)來(lái)獲得對(duì)應(yīng)的識(shí)別用戶信息。

（14）獲取支付憑證（getFacePayCredential）

public void getFacePayCredential(Map info,IWxPayfaceCallback cb);

請(qǐng)求參數(shù)
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

二級(jí)錯(cuò)誤碼參考

示例

private void getFacePayCredential() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().getFacePayCredential(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			String faceToken= (String)info.get("face_token");
			if (code == null || !code.equals("SUCCESS") || TextUtils.isEmpty(faceToken)) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
//到此處才算成功，一定要注意faceToken判空
		}
	});
}
}

注意：
開(kāi)始識(shí)別返回用戶信息后，不論是確認(rèn)還是取消，都需要調(diào)用完成才能進(jìn)行下一次識(shí)別。確認(rèn)了會(huì)生成支付憑證，支付憑證生成需要一定時(shí)間。

（15）啟動(dòng)掃碼（startCodeScanner）

public void startCodeScanner(Map info,IWxPayfaceCallback cb);

作用：
微信人臉sdk啟動(dòng)攝像頭進(jìn)入掃碼模式，掃描二維碼。

注意：
A、該方法注冊(cè)的回調(diào)接口在stopCodeScanner之前，掃碼成功都會(huì)回調(diào)；
B、該方法可以多次調(diào)用，但是掃碼結(jié)果只會(huì)回調(diào)最后一次注冊(cè)的回調(diào)；
C、掃碼模式和刷臉互斥，一旦開(kāi)始刷臉則SDK會(huì)退出掃碼模式，掃碼回調(diào)失效，如果需要掃碼功能，需要刷臉結(jié)束后再次調(diào)用該方法啟動(dòng)掃碼。

返回參數(shù)（包含通用返回參數(shù)和通用errCode）

示例

WxPayFace.getInstance().startCodeScanner(params,new IWxPayfaceCallback() {
	@Override
	public void response(Map info) throws RemoteException {
		if (info != null) {
			String return_code = (String) info.get("return_code");
			Integer errcode = (Integer) info.get("err_code");
			String return_msg = (String) info.get("return_msg");
			String code_msg = (String) info.get("code_msg");
			final String resultString = "startCodeScanner, return_code : " + return_code + " return_msg : " + return_msg + " code_msg: " + code_msg;
			/** 這里添加業(yè)務(wù)自定義的工作即可 注意該回調(diào)在異步線程 **/
		}
	}
});

（16）停止掃碼（stopCodeScanner）

public void stopCodeScanner(Map info,IWxPayfaceCallback cb);

作用：
微信人臉sdk停止攝像頭掃碼，退出掃碼模式。

返回參數(shù)（包含通用返回參數(shù)和通用errCode）

示例

WxPayFace.getInstance().stopCodeScanner(params,,new IWxPayfaceCallback() {
	@Override
	public void response(Map info) throws RemoteException {
		if (info == null) {
			new RuntimeException("調(diào)用返回為空").printStackTrace();
			return;
		}
		String code = (String) info.get("return_code");
		String msg = (String) info.get("return_msg");
		if (code == null || !code.equals("SUCCESS")) {
			new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
			return ;
		}
	}
});

（17）跳轉(zhuǎn)出廠檢測(cè)（goToFactoryPage）

public void goToFactoryPage(Map info,IWxPayfaceCallback cb);

作用：
微信人臉sdk進(jìn)入出廠檢測(cè)頁(yè)面

注意：
無(wú)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
無(wú)特殊參數(shù)，只有成功和系統(tǒng)錯(cuò)誤兩種

示例

WxPayFace.getInstance().goToFactoryPage(params,new IWxPayfaceCallback() {
	@Override
	public void response(Map info) throws RemoteException {
		if (info == null) {
			new RuntimeException("調(diào)用返回為空").printStackTrace();
			return;
		}
		String code = (String) info.get("return_code");
		String msg = (String) info.get("return_msg");
		if (code == null || !code.equals("SUCCESS")) {
			new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
			return ;
		}
	}
});

# 3.9 非必調(diào)接口

（1）清除人臉數(shù)據(jù)（clearFaceDatas）兜底邏輯接口

public void clearFaceDatas(Map info,IWxPayfaceCallback cb);

注意：
A、只是用于邏輯兜底，保證特征同步異常情況下可以重新同步，不同機(jī)構(gòu)會(huì)有不同的數(shù)據(jù)庫(kù)，切換機(jī)構(gòu)不建議調(diào)用此方法；
B、使用異常會(huì)導(dǎo)致機(jī)構(gòu)不可用時(shí)間增長(zhǎng)，建議緊急情況下使用；
C、清理本地人臉數(shù)據(jù)，清除不會(huì)立馬拉取。

請(qǐng)求參數(shù)：
包含通用請(qǐng)求參數(shù)

返回參數(shù)：
如果returncode不為成功，則需要記錄對(duì)應(yīng)的errMsg，可以提示“清除人臉數(shù)據(jù)失敗” 可能返回errcode 271378620 和 271378621，具體處理方式參考err_code說(shuō)明。

示例

private void clearFaceDatas() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等)
	WxPayFace.getInstance().clearFaceDatas(params,new IWxPayfaceCallback() {
		@Override
		public void response(Map info) throws RemoteException {
			if (info == null) {
				new RuntimeException("調(diào)用返回為空").printStackTrace();
				return;
			}
			String code = (String) info.get("return_code");
			String msg = (String) info.get("return_msg");
			if (code == null || !code.equals("SUCCESS")) {
				new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
				return ;
			}
		}
	});
}
}

（2）關(guān)閉攝像頭常開(kāi)（stopCamera）非常規(guī)接口

public void stopCamera(Map info,IWxPayfaceCallback cb);

注意：
這里關(guān)閉攝像頭建議在長(zhǎng)時(shí)間無(wú)交易的時(shí)段來(lái)自行處理，關(guān)閉攝像頭會(huì)有損識(shí)別效率，對(duì)于華捷的攝像頭如果散熱OK不建議做操作。

請(qǐng)求參數(shù)：
包含通用請(qǐng)求參數(shù)

返回參數(shù)（包含通用返回參數(shù)和通用errCode）
可能返回errcode 271378620 和 271378621，具體處理方式參考errcode說(shuō)明。

示例

private void stopCamera() {
//params包含請(qǐng)求通用參數(shù)(authinfo,mch_id等) WxPayFace.getInstance().stopCamera(params,new IWxPayfaceCallback() {
	@Override
	public void response(Map info) throws RemoteException {
		if (info == null) {
			new RuntimeException("調(diào)用返回為空").printStackTrace();
			return;
		}
		String code = (String) info.get("return_code");
		String msg = (String) info.get("return_msg");
		if (code == null || !code.equals("SUCCESS")) {
			new RuntimeException("調(diào)用返回非成功信息,return_msg:" + msg + " ").printStackTrace();
			return ;
		}
	}
});
}
}

（3）AAR日志自定義(setLog) 非常規(guī)接口

public void setLog(WxLog log);

請(qǐng)求參數(shù)：
傳入WxLog的實(shí)現(xiàn)

返回參數(shù)：
無(wú)

示例

private void setLog() {
	WxLog logImpl = new WxLog() {
		@Override
		public void d(String tag, String msg) {
//可使用服務(wù)商自己的日志輸出
		}
		@Override
		public void i(String tag, String msg) {
//可使用服務(wù)商自己的日志輸出
		}
		@Override
		public void e(String tag, String msg) {
//可使用服務(wù)商自己的日志輸出
		}
		@Override
		public void e(String tag, String msg, Throwable e) {
//可使用服務(wù)商自己的日志輸出
		}
	};
	WxPayFace.getInstance().setLog(logImpl);
}

# 3.10 終端標(biāo)準(zhǔn)流程

（1）設(shè)備運(yùn)行機(jī)制

定期重啟機(jī)制一定要有，避免因ROM或者商戶APP或者支付SDK運(yùn)行太長(zhǎng)時(shí)間導(dǎo)致突發(fā)異常，建議凌晨非高峰期可以自行重啟一次（推薦時(shí)間凌晨1：00-3:00，將凌晨1:00前作為升級(jí)時(shí)間）。

（2）獲取支付憑證去后臺(tái)扣款流程
A、建議UI上明確區(qū)分在線模式和斷網(wǎng)模式，只有極端網(wǎng)絡(luò)情況才運(yùn)行斷網(wǎng)模式，常規(guī)網(wǎng)絡(luò)都要走在線模式；
B、在線模式是在用戶點(diǎn)擊確認(rèn)后，必須后臺(tái)扣款成功才能展示成功結(jié)果，壞賬率低，無(wú)需和支付側(cè)對(duì)接扣款失敗和墊資問(wèn)題；
C、斷網(wǎng)模式是在用戶點(diǎn)擊確認(rèn)后，后臺(tái)可以延后扣款，終端拿到支付憑證并且商戶確認(rèn)可以扣款就能展示成功結(jié)果，因?yàn)槲唇?jīng)過(guò)后端風(fēng)控，可能導(dǎo)致壞賬、扣款失敗和墊資問(wèn)題；
D、獲取用戶信息后，獲取支付憑證和用戶點(diǎn)擊確認(rèn)流程可以并行，從而優(yōu)化支付耗時(shí)。

（3）預(yù)覽綁定流程
A、綁定surfaceview推薦全局使用同一個(gè)示例；
B、綁定最佳時(shí)機(jī)為surfaceview不會(huì)再發(fā)生大小改變或者隱藏的時(shí)刻，避免需要?jiǎng)討B(tài)適配；
C、可以手動(dòng)removeSurfaceview，重新綁定也會(huì)自動(dòng)進(jìn)行remove。

（4）識(shí)別&支付流程
默認(rèn)流程成功:

取消訂單（用戶希望取消/結(jié)束流程）:

頁(yè)面跳轉(zhuǎn)可能的異化流程
開(kāi)始識(shí)別->停止識(shí)別->完成識(shí)別->獲取支付憑證->開(kāi)始識(shí)別->完成識(shí)別->停止識(shí)別->獲取支付憑證

關(guān)閉攝像頭渲染和識(shí)別時(shí)機(jī)
A、停止識(shí)別；
B、完成識(shí)別；
C、獲取支付憑證；
D、開(kāi)始識(shí)別（會(huì)停掉前一次識(shí)別）。

清除上一次識(shí)別數(shù)據(jù)時(shí)機(jī)
A、完成識(shí)別(僅限失敗)；
B、獲取支付憑證(不論成功失敗)。

“停止識(shí)別”和“清除當(dāng)前識(shí)別數(shù)據(jù)”

停止識(shí)別作用只是停止攝像頭渲染和識(shí)別，并不會(huì)清除掉上次的數(shù)據(jù)，可以在任何階段調(diào)用，標(biāo)準(zhǔn)的結(jié)束必須以獲取支付憑證為結(jié)尾。

A、調(diào)用“開(kāi)始識(shí)別”會(huì)自動(dòng)清除當(dāng)前識(shí)別數(shù)據(jù)，并停止識(shí)別再啟動(dòng)識(shí)別，如果成功會(huì)直接停止識(shí)別；
B、調(diào)用“停止識(shí)別”只停止當(dāng)前識(shí)別，不清除當(dāng)前識(shí)別數(shù)據(jù)；
C、調(diào)用“完成識(shí)別”失敗會(huì)清理上次識(shí)別數(shù)據(jù)，成功不做處理；
D、調(diào)用“獲取憑證”不論成功失敗都會(huì)直接停止當(dāng)前識(shí)別并清理識(shí)別數(shù)據(jù)。

# 3.11 常見(jiàn)問(wèn)題

（1）刷臉SDK僅用于識(shí)別，支付環(huán)節(jié)默認(rèn)走非微信支付渠道
需要保證獲取支付憑證接口被調(diào)用，保證真實(shí)金額傳入獲取支付憑證，可以用金額0去后臺(tái)對(duì)當(dāng)前支付憑證的安全性進(jìn)行驗(yàn)證，保證支付流程完善。

（2）初始化提示“初始化失敗”
A、檢查對(duì)應(yīng)的release調(diào)用時(shí)機(jī)，不要太頻繁的release，每次release后初始化耗時(shí)較長(zhǎng)；
B、調(diào)用其它API都依賴(lài)初始化成功后再操作，如果初始化未完成就調(diào)用任意非初始化API，就會(huì)提示該問(wèn)題，碰上這兩類(lèi)錯(cuò)誤碼，只需要重試初始化即可。

（3）K12UserInfo和UserInfo的keep問(wèn)題
AAR對(duì)返回的json字符串做了類(lèi)型封裝，本質(zhì)上新舊AAR對(duì)apk的調(diào)用都沒(méi)有異常，這里商戶app升級(jí)后使用新版aar需要簡(jiǎn)單調(diào)整下對(duì)應(yīng)的userinfo類(lèi)型，并且在proguard里 -keep class com.tencent.wxpayface.data.UserInfo{ *; }；

（4）parcelable exception 空指針
注意對(duì)err_code判空，不能直接轉(zhuǎn)換為int，而應(yīng)該使用Integer，否則會(huì)導(dǎo)致支付SDK無(wú)響應(yīng)。

（5）攝像頭溫度過(guò)熱問(wèn)題
優(yōu)先保證攝像頭常開(kāi)，保證體驗(yàn)；如果散熱問(wèn)題特別嚴(yán)重，可以嘗試連續(xù)一段時(shí)間比如10分鐘內(nèi)沒(méi)有識(shí)別，調(diào)用stopCamera，下一次啟動(dòng)識(shí)別耗時(shí)會(huì)變長(zhǎng)，但是可以緩解散熱問(wèn)題。

（6）認(rèn)證失敗問(wèn)題
認(rèn)證失敗可能出現(xiàn)在任意請(qǐng)求之內(nèi)，如果出現(xiàn)新獲取的authinfo無(wú)法調(diào)用，請(qǐng)檢查機(jī)器時(shí)間，原則上機(jī)器時(shí)間應(yīng)與網(wǎng)絡(luò)時(shí)間同步。

（7）第一次調(diào)用攝像頭或者其它api耗時(shí)超長(zhǎng)
獲取authinfo啟動(dòng)app后，第一次識(shí)別需要加載識(shí)別相關(guān)資源，可以提前調(diào)用preloadSdkEnv來(lái)提前預(yù)啟動(dòng)，保證第一次識(shí)別速度很快。

（8）商戶識(shí)別流程設(shè)計(jì)
盡可能保證時(shí)序串行，避免出現(xiàn)重復(fù)扣款情況。
注意：商戶可以按需求設(shè)計(jì)，比如不允許同人同金額10s內(nèi)支付等邏輯。

（9）現(xiàn)場(chǎng)用戶需要彎腰踮腳
建議將預(yù)覽畫(huà)面按照長(zhǎng)寬比3:4來(lái)實(shí)現(xiàn)，方便用戶最大范圍進(jìn)行識(shí)別，避免出現(xiàn)用戶臉不在預(yù)覽畫(huà)面中心，誤以為不能識(shí)別，其實(shí)可以識(shí)別的情況。

（10）數(shù)據(jù)庫(kù)初始化失敗271378588錯(cuò)誤
A、部分設(shè)備可能重啟或者運(yùn)行時(shí)間久后，設(shè)備讀寫(xiě)速度變慢，建議開(kāi)機(jī)重啟后延遲一段時(shí)間，比如5s再進(jìn)行init，避免時(shí)序紊亂；
B、不要頻繁地調(diào)用release，release后需要重新環(huán)境初始化，導(dǎo)致耗時(shí)增加，可能出現(xiàn)該錯(cuò)誤。

（11）雙胞胎算法不能區(qū)分問(wèn)題
A、雙胞胎不需要區(qū)分
綁定相同?機(jī)號(hào)、微信號(hào)，系統(tǒng)會(huì)默認(rèn)合并到和現(xiàn)場(chǎng)照更相似的用戶身份進(jìn)?扣款。

B、雙胞胎需要區(qū)分
綁定不同?機(jī)號(hào)、微信號(hào)，系統(tǒng)會(huì)提示需要輸入手機(jī)號(hào)驗(yàn)證，從?區(qū)分當(dāng)前身份。

# 4. 后臺(tái)接口

名詞定義
● 商戶后臺(tái)系統(tǒng)：商戶側(cè)后臺(tái)處理系統(tǒng)。
● 商戶刷臉APP：商戶側(cè)的刷臉支付APP。
● 商戶小程序：商戶提供給用戶的小程序。
● 微信刷臉后臺(tái)系統(tǒng)：微信側(cè)刷臉后臺(tái)處理系統(tǒng)。
● 微信離線刷臉SDK：微信側(cè)提供的刷臉識(shí)別SDK。
● 微信刷臉小程序：微信側(cè)提供的小程序，用戶刷臉用戶開(kāi)通、簽約等操作。
● 刷臉用戶：刷臉消費(fèi)用戶。如學(xué)生、教職工。
● 支付用戶：實(shí)際支付的用戶，如家長(zhǎng)、教職工。
● 收銀員：負(fù)責(zé)收款的人或機(jī)器。
● 機(jī)構(gòu)：學(xué)校、公司等都是機(jī)構(gòu)，當(dāng)前以機(jī)構(gòu)為單位維護(hù)人臉特征庫(kù)。
● out_user_id：刷臉用戶標(biāo)識(shí)，需要商戶保證同一個(gè)刷臉用戶在一個(gè)機(jī)構(gòu)下唯一，不要給同一個(gè)用戶創(chuàng)建多個(gè)out_user_id，否則可能導(dǎo)致用戶無(wú)法識(shí)別，目前限制同一個(gè)微信號(hào)不允許綁定同一個(gè)機(jī)構(gòu)下多個(gè)同名用戶。
● user_id：刷臉用戶標(biāo)識(shí)，微信側(cè)生成。
● organization_id：機(jī)構(gòu)唯一標(biāo)識(shí)，一個(gè)機(jī)構(gòu)下的所有用戶的人臉特征組成了該機(jī)構(gòu)對(duì)應(yīng)的人臉特征庫(kù)。
● face_feature_version：人臉特征版本。由于算法升級(jí)，不同版本的識(shí)別算法提取的人臉特征會(huì)有差異。

業(yè)務(wù)流程
微信離線人臉APP調(diào)用憑證獲取

參考獲取authinfo接口。

商戶錄入刷臉用戶流程
目前錄入刷臉用戶有如下入口，分別為：
（1）商家統(tǒng)一采集學(xué)生信息，家長(zhǎng)簽約時(shí)則無(wú)需錄入照片。

（2）家長(zhǎng)簽約時(shí)錄入照片。

（3）重新采集時(shí)更換學(xué)生照片。

扣款流程
扣款流程為同步接口，獲取扣款相關(guān)參數(shù)請(qǐng)參考微信離線人臉APP接入文檔。

錯(cuò)誤碼和錯(cuò)誤提示
當(dāng)請(qǐng)求處理失敗時(shí)，除了HTTP狀態(tài)碼表示錯(cuò)誤之外，API將在消息體返回錯(cuò)誤相應(yīng)說(shuō)明具體的錯(cuò)誤原因。

錯(cuò)誤字段列表為：

code列表：

簽名
所有接口調(diào)用均需要簽名，請(qǐng)點(diǎn)擊簽名方法進(jìn)行查閱。

字段有效性規(guī)定

敏感字段列表

根據(jù)微信APIv3的要求，所有敏感信息經(jīng)網(wǎng)絡(luò)傳輸需要進(jìn)行二次加密，加密方法請(qǐng)參考《敏感信息加解密》。

敏感字段列表如下：

下面將不再單獨(dú)對(duì)每個(gè)字段進(jìn)行說(shuō)明。

測(cè)試環(huán)境聯(lián)調(diào)方法
注意測(cè)試環(huán)境不保證服務(wù)可用性，因此僅在特殊情況下使用與微信側(cè)進(jìn)行聯(lián)調(diào)，其他非必要場(chǎng)景請(qǐng)不要使用測(cè)試環(huán)境，使用前請(qǐng)與微信側(cè)確認(rèn)測(cè)試環(huán)境可用，配置方法如下，任選其一即可，不可同時(shí)配置：
方法一：HTTP代理模式，139.199.171.252:8089
方法二：HOST模式，183.3.224.148 api.mch.weixin.qq.com

接口列表

# 4.1 查詢機(jī)構(gòu)信息接口

機(jī)構(gòu)申請(qǐng)請(qǐng)點(diǎn)擊參考《學(xué)校機(jī)構(gòu)ID申請(qǐng)說(shuō)明》。

接口定義
根據(jù)organization_id查詢機(jī)構(gòu)信息：
GET https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations?organization_id=xxx

根據(jù)organization_name查詢機(jī)構(gòu)信息：
GET https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations?organization_name=url_encode(name)

請(qǐng)求參數(shù)
無(wú)

返回結(jié)果

狀態(tài)為200時(shí)：

# 4.2 獲取授權(quán)憑證接口

授權(quán)憑證用與拉起小程序、H5等。
token有效期為5分鐘，在商戶小程序跳轉(zhuǎn)簽約小程序時(shí)獲取，不要提前獲取。
集中采集時(shí)建議使用該接口。
用戶簽約時(shí)建議使用預(yù)簽約接口。

接口定義
POST https://api.mch.weixin.qq.com/v3/offlinefacemch/tokens

請(qǐng)求參數(shù)

web_init_data：

返回結(jié)果

狀態(tài)碼為200時(shí)，結(jié)果參數(shù)為：

# 4.3 刷臉用戶信息查詢接口

接口定義
GET https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations/{organization_id}/users/out-user-id/{out_user_id}

請(qǐng)求參數(shù)
無(wú)

返回結(jié)果

狀態(tài)碼為200時(shí)，返回如下字段：

student_info：

staff_info：

# 4.4 刷臉用戶信息修改接口

接口定義

PATCH https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations/{organization_id}/users/out-user-id/{out_user_id}

請(qǐng)求參數(shù)

返回結(jié)果

# 4.5 獲取authinfo接口

注意：建議authinfo每1小時(shí)內(nèi)獲取一次。

接口定義
POST https://api.mch.weixin.qq.com/v3/offlineface/authinfo

請(qǐng)求參數(shù)

返回結(jié)果

# 4.6 解除刷臉用戶簽約關(guān)系接口

接口定義

POST https://api.mch.weixin.qq.com/v3/offlinefacemch/organizations/{organization_id}/users/user-id/{user_id}/terminate-contract

請(qǐng)求參數(shù)
無(wú)

返回結(jié)果

# 4.7 預(yù)簽約接口

接口定義
POST https://api.mch.weixin.qq.com/v3/offlineface/contracts/presign

用戶能夠扣款的前提是已經(jīng)完成簽約操作，簽約流程如下：
A、用戶在商戶小程序發(fā)起簽約；
B、商戶調(diào)用該接口進(jìn)行預(yù)簽約，該接口會(huì)返回presign_token；
C、商戶小程序攜帶presign_token跳轉(zhuǎn)到微信側(cè)人臉小程序，用戶在微信側(cè)人臉小程序完成簽約操作。
注意：
a、一鍵綁卡不是支持所有銀行卡，上線前請(qǐng)先測(cè)試是否支持該銀行卡；
b、建議上線前一周完成調(diào)試；
c、簽約完成務(wù)必多次扣款，防止由于銀行限制每日扣款次數(shù)、扣款金額等影響用戶消費(fèi)；
d、指定卡簽約建議異步扣款，否則銀行維護(hù)會(huì)導(dǎo)致不能扣費(fèi)，影響學(xué)生吃飯；
e、presign_token有效期為5分鐘，在商戶小程序跳轉(zhuǎn)簽約小程序時(shí)獲取，不要提前獲取。

請(qǐng)求參數(shù)

facepay_user：

limit_bank_card：

identification：

返回結(jié)果

# 4.8 申請(qǐng)扣款接口

接口定義
POST https://api.mch.weixin.qq.com/v3/offlineface/transactions

請(qǐng)求參數(shù)

amount定義如下：

scene_info定義如下：

business定義如下：

settle_info定義如下：

返回結(jié)果

狀態(tài)碼為200時(shí)：

payer定義如下：

amount定義如下：

返回碼處理建議：

# 4.9 簽約查詢接口

根據(jù)簽約id查詢簽約信息。
接口定義
GET https://api.mch.weixin.qq.com/v3/offlineface/contracts/{contract_id}?appid=XXXX

請(qǐng)求參數(shù)

返回結(jié)果

狀態(tài)碼為200時(shí)，結(jié)果參數(shù)為：

# 4.10 簽約狀態(tài)變更回調(diào)通知（簽約、解約都會(huì)回調(diào)）

能力背景

服務(wù)商為學(xué)校開(kāi)發(fā)基于師生的用戶管理體系時(shí)，需要維護(hù)用戶的采集和簽約狀態(tài)，并同步至刷臉設(shè)備。目前，服務(wù)商只能獲取用戶簽約信息，不能獲取用戶解約信息，導(dǎo)致服務(wù)商無(wú)法維護(hù)用戶狀態(tài)，影響用戶正常使用。

能力簡(jiǎn)介

刷臉用戶在完成簽約或解約后，微信會(huì)通知商戶用戶簽約狀態(tài)變更。商戶需要接收處理，并返回應(yīng)答。

具體開(kāi)發(fā)內(nèi)容請(qǐng)點(diǎn)擊《離線刷臉簽約狀態(tài)變更回調(diào)》進(jìn)行查閱。

接入流程

詳情接入請(qǐng)見(jiàn)《申請(qǐng)用戶解約通知申請(qǐng)表》。

接入周期
每周五12：00截止本周配置信息收集，并在下個(gè)工作日上午12：00前配置完成。

# 4.11 還款小程序跳轉(zhuǎn)協(xié)議

appid：wxa834b152dd018e25
path：pages/index/index?business_product_id=XXXX（2表示K12，11表示企業(yè)團(tuán)餐）

# 4.12 查詢重采請(qǐng)求接口

離線刷臉業(yè)務(wù)中，偶爾會(huì)出現(xiàn)前期采集頭像質(zhì)量不高，導(dǎo)致算法升級(jí)后，舊的頭像無(wú)法生成有效的人臉特征，影響用戶使用刷臉?lè)?wù)。因此，需要對(duì)用戶的頭像進(jìn)行重采。

接口定義
GET https://api.mch.weixin.qq.com/v3/offlineface/face-collections/{collection_id}。

請(qǐng)求參數(shù)

返回結(jié)果

狀態(tài)碼為200時(shí)，結(jié)果參數(shù)為：

# 4.13 查詢重采用戶列表接口

通過(guò)該接口，商戶可以獲取需要重采的用戶列表。 根據(jù)該列表，可以安排進(jìn)入學(xué)校進(jìn)行集中采集或者通知家長(zhǎng)配合采集。
采集完成后，通過(guò)小程序的重采確認(rèn)接口，讓用戶確認(rèn)重采的人臉照片。
建議商戶在收到重采通知后，或者是定時(shí)輪詢(輪詢周期不用太高, 填級(jí)別即可)，通過(guò)該接口獲取重采列表, 安排后續(xù)工作。

接口定義
GET https://api.mch.weixin.qq.com/v3/offlineface/face-collections?organization_id={organization_id}。

請(qǐng)求參數(shù)

返回結(jié)果

狀態(tài)碼為200時(shí)，結(jié)果參數(shù)為：

重采列表單個(gè)對(duì)象結(jié)構(gòu)：

# 4.14 查單接口

接口定義
GET https://api.mch.weixin.qq.com/v3/offlineface/transactions/out-trade-no/{out_trade_no}?sp_mchid={sp_mchid}&sub_mchid={sub_mchid}&business_product_id={business_product_id}

請(qǐng)求參數(shù)

狀態(tài)碼為200時(shí)：body和申請(qǐng)扣款接口一致。

payer定義如下：

amount定義如下：

返回碼處理建議：

# 4.15 獲取還款鏈接接口

接口定義
POST https://api.mch.weixin.qq.com/v3/offlineface/repayment-url

請(qǐng)求參數(shù)

返回結(jié)果

# 5. 非刷臉交易上報(bào)

開(kāi)發(fā)集成后，還需要完成APP里的微信非刷臉交易上報(bào)?，?否則會(huì)影響審批。

詳情請(qǐng)見(jiàn)交易上報(bào)(reportOrder)