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