、請求示例與返回字段解讀)
實名核驗是注冊、下單、賬戶綁定等業(yè)務(wù)里經(jīng)常遇到的一環(huán)。身份證二要素核驗用于判斷「真實姓名 18 位身份證號」是否與公安權(quán)威庫一致。本文按“準(zhǔn)備 - 最小請求 - 返回值 - 錯誤處理 - 工程化”的順序把這個接口從第一次調(diào)用講清楚。一、適用場景與能力邊界典型使用場景注冊實名用戶填寫姓名與身份證號后做一致性校驗。下單風(fēng)控高風(fēng)險交易前補(bǔ)充身份一致性判斷。賬戶綁定綁定實名信息時校驗填寫是否匹配。需要明確的能力邊界項目說明核驗對象真實姓名 18 位身份證號返回內(nèi)容僅返回是否一致不返回任何額外戶籍信息身份證號回顯響應(yīng)中脫敏回顯返回速度素材描述為秒級返回具體時延以文檔與實際調(diào)用為準(zhǔn)授權(quán)要求需在取得被核驗人授權(quán)后調(diào)用也就是說這個接口只回答“一致 / 不一致”不能用來查詢地址、出生日期、照片等衍生信息業(yè)務(wù)設(shè)計時不要把核驗接口當(dāng)成信息查詢接口使用。二、調(diào)用前需要準(zhǔn)備什么接口地址與方法POST https://v1.apizero.cn/api/idcard-2c。鑒權(quán)方式素材未給出具體鑒權(quán)字段與 Header 名稱以文檔為準(zhǔn)。接入前請先在文檔中確認(rèn) API Key 的傳遞位置Header 或參數(shù)。請求參數(shù)name真實姓名、idcard18 位身份證號。請求編碼建議使用application/x-www-form-urlencoded或 JSON具體以文檔為準(zhǔn)。合規(guī)前提確認(rèn)已獲得被核驗人的授權(quán)并準(zhǔn)備好授權(quán)留存的說明。三、最小請求示例下面是一個可復(fù)制的 curl 模板。其中鑒權(quán)字段與請求體格式請按文檔替換示例中的YOUR_API_KEY、姓名和身份證號均為占位內(nèi)容。curl -X POST https://v1.apizero.cn/api/idcard-2c \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: YOUR_API_KEY \ --data-urlencode name張三 \ --data-urlencode idcard110101199001011234如果文檔要求以 JSON 提交可改為curl -X POST https://v1.apizero.cn/api/idcard-2c \ -H Content-Type: application/json \ -H Authorization: YOUR_API_KEY \ -d {name:張三,idcard:110101199001011234}兩點提醒身份證號必須是 18 位調(diào)用前先做格式校驗避免把明顯不合法的數(shù)據(jù)發(fā)到服務(wù)端。姓名與身份證號需與用戶提交內(nèi)容保持一致不要自行去空格以外的任何“修正”。四、返回字段解讀素材僅說明“返回是否一致”以及“身份證號脫敏回顯”未給出完整響應(yīng)體字段名。因此字段名、狀態(tài)碼枚舉、錯誤碼含義以文檔為準(zhǔn)。接入時建議按以下方式處理先看 HTTP 狀態(tài)碼區(qū)分網(wǎng)絡(luò)層失敗與業(yè)務(wù)層失敗。再解析響應(yīng)體中的“是否一致”字段映射為業(yè)務(wù)枚舉例如MATCH/MISMATCH。讀取脫敏后的身份證號用于日志與頁面回顯不要期望拿到完整號碼。對響應(yīng)體做容錯解析字段缺失時按“核驗失敗”處理不要默認(rèn)放行。一個防御式解析的偽代碼示例字段名請?zhí)鎿Q為文檔中的實際名稱import requests def verify(name: str, idcard: str, api_key: str) - str: resp requests.post( https://v1.apizero.cn/api/idcard-2c, headers{Authorization: api_key}, data{name: name, idcard: idcard}, timeout5, ) if resp.status_code ! 200: return ERROR data resp.json() matched data.get(matched) # 字段名以文檔為準(zhǔn) if matched is True: return MATCH if matched is False: return MISMATCH return ERROR五、常見錯誤與排查思路現(xiàn)象可能原因排查方向401 / 403鑒權(quán)信息缺失或錯誤核對 API Key 與傳遞位置以文檔為準(zhǔn)參數(shù)錯誤name或idcard缺失、身份證號非 18 位調(diào)用前做必填與格式校驗返回不一致姓名與號碼不匹配提示用戶核對不要自動重試超時網(wǎng)絡(luò)或服務(wù)端處理耗時設(shè)置合理超時配合重試策略響應(yīng)體解析失敗字段名與預(yù)期不符以文檔字段名為準(zhǔn)做容錯解析特別注意“不一致”不是錯誤而是正常的業(yè)務(wù)結(jié)果。不要把不一致當(dāng)成異常拋給用戶也不要因此觸發(fā)自動重試。六、工程化注意事項日志脫敏請求與響應(yīng)中的身份證號必須脫敏落盤避免明文進(jìn)入日志系統(tǒng)。超時與重試只對網(wǎng)絡(luò)超時和 5xx 做有限次重試業(yè)務(wù)結(jié)果類響應(yīng)不重試。冪等設(shè)計核驗是只讀判斷可按“姓名身份證號”做短時緩存但緩存時長需結(jié)合業(yè)務(wù)合規(guī)要求確定。授權(quán)留存保留用戶授權(quán)記錄明確核驗?zāi)康呐c范圍。失敗兜底核驗失敗時給出人工復(fù)核或補(bǔ)充材料通道而不是直接拒絕。監(jiān)控告警對錯誤率、超時率單獨(dú)打點便于定位問題。參考文檔接口文檔 身份證二要素核驗接口接入教程：參數(shù)、請求示例與返回字段解讀
實名核驗是注冊、下單、賬戶綁定等業(yè)務(wù)里經(jīng)常遇到的一環(huán)。身份證二要素核驗用于判斷「真實姓名 18 位身份證號」是否與公安權(quán)威庫一致。本文按“準(zhǔn)備 - 最小請求 - 返回值 - 錯誤處理 - 工程化”的順序把這個接口從第一次調(diào)用講清楚。一、適用場景與能力邊界典型使用場景注冊實名用戶填寫姓名與身份證號后做一致性校驗。下單風(fēng)控高風(fēng)險交易前補(bǔ)充身份一致性判斷。賬戶綁定綁定實名信息時校驗填寫是否匹配。需要明確的能力邊界項目說明核驗對象真實姓名 18 位身份證號返回內(nèi)容僅返回是否一致不返回任何額外戶籍信息身份證號回顯響應(yīng)中脫敏回顯返回速度素材描述為秒級返回具體時延以文檔與實際調(diào)用為準(zhǔn)授權(quán)要求需在取得被核驗人授權(quán)后調(diào)用也就是說這個接口只回答“一致 / 不一致”不能用來查詢地址、出生日期、照片等衍生信息業(yè)務(wù)設(shè)計時不要把核驗接口當(dāng)成信息查詢接口使用。二、調(diào)用前需要準(zhǔn)備什么接口地址與方法POST https://v1.apizero.cn/api/idcard-2c。鑒權(quán)方式素材未給出具體鑒權(quán)字段與 Header 名稱以文檔為準(zhǔn)。接入前請先在文檔中確認(rèn) API Key 的傳遞位置Header 或參數(shù)。請求參數(shù)name真實姓名、idcard18 位身份證號。請求編碼建議使用application/x-www-form-urlencoded或 JSON具體以文檔為準(zhǔn)。合規(guī)前提確認(rèn)已獲得被核驗人的授權(quán)并準(zhǔn)備好授權(quán)留存的說明。三、最小請求示例下面是一個可復(fù)制的 curl 模板。其中鑒權(quán)字段與請求體格式請按文檔替換示例中的YOUR_API_KEY、姓名和身份證號均為占位內(nèi)容。curl -X POST https://v1.apizero.cn/api/idcard-2c \ -H Content-Type: application/x-www-form-urlencoded \ -H Authorization: YOUR_API_KEY \ --data-urlencode name張三 \ --data-urlencode idcard110101199001011234如果文檔要求以 JSON 提交可改為curl -X POST https://v1.apizero.cn/api/idcard-2c \ -H Content-Type: application/json \ -H Authorization: YOUR_API_KEY \ -d {name:張三,idcard:110101199001011234}兩點提醒身份證號必須是 18 位調(diào)用前先做格式校驗避免把明顯不合法的數(shù)據(jù)發(fā)到服務(wù)端。姓名與身份證號需與用戶提交內(nèi)容保持一致不要自行去空格以外的任何“修正”。四、返回字段解讀素材僅說明“返回是否一致”以及“身份證號脫敏回顯”未給出完整響應(yīng)體字段名。因此字段名、狀態(tài)碼枚舉、錯誤碼含義以文檔為準(zhǔn)。接入時建議按以下方式處理先看 HTTP 狀態(tài)碼區(qū)分網(wǎng)絡(luò)層失敗與業(yè)務(wù)層失敗。再解析響應(yīng)體中的“是否一致”字段映射為業(yè)務(wù)枚舉例如MATCH/MISMATCH。讀取脫敏后的身份證號用于日志與頁面回顯不要期望拿到完整號碼。對響應(yīng)體做容錯解析字段缺失時按“核驗失敗”處理不要默認(rèn)放行。一個防御式解析的偽代碼示例字段名請?zhí)鎿Q為文檔中的實際名稱import requests def verify(name: str, idcard: str, api_key: str) - str: resp requests.post( https://v1.apizero.cn/api/idcard-2c, headers{Authorization: api_key}, data{name: name, idcard: idcard}, timeout5, ) if resp.status_code ! 200: return ERROR data resp.json() matched data.get(matched) # 字段名以文檔為準(zhǔn) if matched is True: return MATCH if matched is False: return MISMATCH return ERROR五、常見錯誤與排查思路現(xiàn)象可能原因排查方向401 / 403鑒權(quán)信息缺失或錯誤核對 API Key 與傳遞位置以文檔為準(zhǔn)參數(shù)錯誤name或idcard缺失、身份證號非 18 位調(diào)用前做必填與格式校驗返回不一致姓名與號碼不匹配提示用戶核對不要自動重試超時網(wǎng)絡(luò)或服務(wù)端處理耗時設(shè)置合理超時配合重試策略響應(yīng)體解析失敗字段名與預(yù)期不符以文檔字段名為準(zhǔn)做容錯解析特別注意“不一致”不是錯誤而是正常的業(yè)務(wù)結(jié)果。不要把不一致當(dāng)成異常拋給用戶也不要因此觸發(fā)自動重試。六、工程化注意事項日志脫敏請求與響應(yīng)中的身份證號必須脫敏落盤避免明文進(jìn)入日志系統(tǒng)。超時與重試只對網(wǎng)絡(luò)超時和 5xx 做有限次重試業(yè)務(wù)結(jié)果類響應(yīng)不重試。冪等設(shè)計核驗是只讀判斷可按“姓名身份證號”做短時緩存但緩存時長需結(jié)合業(yè)務(wù)合規(guī)要求確定。授權(quán)留存保留用戶授權(quán)記錄明確核驗?zāi)康呐c范圍。失敗兜底核驗失敗時給出人工復(fù)核或補(bǔ)充材料通道而不是直接拒絕。監(jiān)控告警對錯誤率、超時率單獨(dú)打點便于定位問題。參考文檔接口文檔