、請求示例與返回字段解讀)
在線開戶、支付綁卡這類流程里讓用戶手動輸入一長串卡號既慢又容易出錯。銀行卡識別接口可以從圖片中識別卡號與有效期輔助錄入和核對。本文從第一次調(diào)用寫起要準備什么、最小請求怎么發(fā)、返回值怎么看。一、適用場景在線開戶用戶上傳銀行卡照片后自動填入卡號減少手輸錯誤。支付綁卡輔助錄入識別后由用戶確認再進入后續(xù)流程。卡號核對用戶提交的卡號與圖片識別結(jié)果做一致性比對。客服工單用戶上傳卡面截圖時輔助提取關(guān)鍵信息。注意識別結(jié)果是“輔助錄入”用的最終仍應讓用戶確認不要直接跳過人工確認環(huán)節(jié)。二、接口能力邊界項目說明請求方法POST參數(shù)input_type、input_data識別內(nèi)容銀行卡號、有效期輸入方式URL、Base64 兩種圖片格式jpg、png文件大小不超過 10MB識別效果圖片清晰、卡面完整時效果更好需要明確接口只識別卡號與有效期不校驗卡號真實性也不做銀行歸屬查詢。識別成功不等于卡號有效業(yè)務上仍需走各自的校驗流程。三、請求參數(shù)與鑒權(quán)參數(shù)共兩個參數(shù)說明input_type輸入類型區(qū)分 URL 與 Base64具體取值以文檔為準input_data輸入數(shù)據(jù)與input_type對應鑒權(quán)方式、請求頭字段名與請求體編碼素材未給出以文檔為準。接入前請先在文檔中確認 API Key 的傳遞位置。調(diào)用前先做本地校驗文件格式是否為 jpg/png、大小是否在 10MB 以內(nèi)、卡面是否完整。這三項能過濾掉大部分失敗請求。四、最小請求示例下面是一個可復制的 curl 模板YOUR_API_KEY、input_type取值與input_data內(nèi)容均為占位請按文檔替換。curl -X POST https://v1.apizero.cn/api/ocr-bank-card \ -H Content-Type: application/json \ -H Authorization: YOUR_API_KEY \ -d { input_type: 按文檔填寫區(qū)分 URL 與 Base64, input_data: 圖片 URL 或 Base64 字符串 }對應的 Python 調(diào)用示例用本地圖片轉(zhuǎn) Base64 后提交import base64 import requests def read_bank_card(image_path: str, input_type: str, api_key: str) - dict: with open(image_path, rb) as f: raw f.read() if len(raw) 10 * 1024 * 1024: raise ValueError(圖片超過 10MB) input_data base64.b64encode(raw).decode(utf-8) resp requests.post( https://v1.apizero.cn/api/ocr-bank-card, headers{Authorization: api_key}, json{input_type: input_type, input_data: input_data}, timeout15, ) resp.raise_for_status() return resp.json()如果使用 URL 方式只需把input_data換成可公網(wǎng)訪問的圖片地址input_type按文檔對應取值。五、返回值解讀素材說明返回“卡號與有效期”具體字段名以文檔為準。接入時建議按以下方式處理讀取卡號字段去掉識別結(jié)果中的空格再做長度與數(shù)字格式校驗。讀取有效期字段格式如 MM/YY 或 MM/YY 以外的形式以文檔為準展示前統(tǒng)一格式化。任一字段缺失時按“識別不完整”處理引導用戶重拍或手動輸入。一個防御式解析示例字段名請?zhí)鎿Q為文檔中的實際名稱def parse_card(payload: dict) - dict: data payload.get(data) or {} number (data.get(number) or ).replace( , ) # 字段名以文檔為準 expiry data.get(expiry) or # 字段名以文檔為準 ok number.isdigit() and 12 len(number) 19 return {number: number, expiry: expiry, complete: ok}卡號長度按行業(yè)常見范圍做寬松校驗即可不要用固定 16 位硬卡避免誤殺其他卡種。六、常見錯誤與排查現(xiàn)象可能原因排查方向鑒權(quán)失敗Key 缺失或位置錯誤核對請求頭以文檔為準參數(shù)錯誤input_type與input_data不匹配按文檔確認取值與數(shù)據(jù)形式文件過大圖片超過 10MB上傳前壓縮或裁剪格式不支持非 jpg/png轉(zhuǎn)碼后再提交識別為空卡面模糊、傾斜、遮擋提示用戶重拍保證卡面完整超時圖片過大或網(wǎng)絡抖動設置超時壓縮圖片后重試識別為空通常是圖片質(zhì)量問題不是接口故障。把它映射為“請重試拍攝”的提示比直接報錯更友好。七、工程化注意事項前端預校驗在客戶端就限制格式與大小減少無效請求。用戶確認識別結(jié)果填入表單后仍需用戶確認不要自動提交。敏感數(shù)據(jù)卡號屬于敏感信息日志中必須脫敏Base64 圖片不要落盤。傳輸安全Base64 會放大體積大圖優(yōu)先用 URL 方式避免請求體過大。重試策略只對超時和 5xx 做有限次重試識別為空不重試。有效期展示統(tǒng)一格式化后再展示避免不同來源格式不一致。參考文檔接口文檔 銀行卡識別接口接入教程：參數(shù)、請求示例與返回字段解讀
在線開戶、支付綁卡這類流程里讓用戶手動輸入一長串卡號既慢又容易出錯。銀行卡識別接口可以從圖片中識別卡號與有效期輔助錄入和核對。本文從第一次調(diào)用寫起要準備什么、最小請求怎么發(fā)、返回值怎么看。一、適用場景在線開戶用戶上傳銀行卡照片后自動填入卡號減少手輸錯誤。支付綁卡輔助錄入識別后由用戶確認再進入后續(xù)流程。卡號核對用戶提交的卡號與圖片識別結(jié)果做一致性比對。客服工單用戶上傳卡面截圖時輔助提取關(guān)鍵信息。注意識別結(jié)果是“輔助錄入”用的最終仍應讓用戶確認不要直接跳過人工確認環(huán)節(jié)。二、接口能力邊界項目說明請求方法POST參數(shù)input_type、input_data識別內(nèi)容銀行卡號、有效期輸入方式URL、Base64 兩種圖片格式jpg、png文件大小不超過 10MB識別效果圖片清晰、卡面完整時效果更好需要明確接口只識別卡號與有效期不校驗卡號真實性也不做銀行歸屬查詢。識別成功不等于卡號有效業(yè)務上仍需走各自的校驗流程。三、請求參數(shù)與鑒權(quán)參數(shù)共兩個參數(shù)說明input_type輸入類型區(qū)分 URL 與 Base64具體取值以文檔為準input_data輸入數(shù)據(jù)與input_type對應鑒權(quán)方式、請求頭字段名與請求體編碼素材未給出以文檔為準。接入前請先在文檔中確認 API Key 的傳遞位置。調(diào)用前先做本地校驗文件格式是否為 jpg/png、大小是否在 10MB 以內(nèi)、卡面是否完整。這三項能過濾掉大部分失敗請求。四、最小請求示例下面是一個可復制的 curl 模板YOUR_API_KEY、input_type取值與input_data內(nèi)容均為占位請按文檔替換。curl -X POST https://v1.apizero.cn/api/ocr-bank-card \ -H Content-Type: application/json \ -H Authorization: YOUR_API_KEY \ -d { input_type: 按文檔填寫區(qū)分 URL 與 Base64, input_data: 圖片 URL 或 Base64 字符串 }對應的 Python 調(diào)用示例用本地圖片轉(zhuǎn) Base64 后提交import base64 import requests def read_bank_card(image_path: str, input_type: str, api_key: str) - dict: with open(image_path, rb) as f: raw f.read() if len(raw) 10 * 1024 * 1024: raise ValueError(圖片超過 10MB) input_data base64.b64encode(raw).decode(utf-8) resp requests.post( https://v1.apizero.cn/api/ocr-bank-card, headers{Authorization: api_key}, json{input_type: input_type, input_data: input_data}, timeout15, ) resp.raise_for_status() return resp.json()如果使用 URL 方式只需把input_data換成可公網(wǎng)訪問的圖片地址input_type按文檔對應取值。五、返回值解讀素材說明返回“卡號與有效期”具體字段名以文檔為準。接入時建議按以下方式處理讀取卡號字段去掉識別結(jié)果中的空格再做長度與數(shù)字格式校驗。讀取有效期字段格式如 MM/YY 或 MM/YY 以外的形式以文檔為準展示前統(tǒng)一格式化。任一字段缺失時按“識別不完整”處理引導用戶重拍或手動輸入。一個防御式解析示例字段名請?zhí)鎿Q為文檔中的實際名稱def parse_card(payload: dict) - dict: data payload.get(data) or {} number (data.get(number) or ).replace( , ) # 字段名以文檔為準 expiry data.get(expiry) or # 字段名以文檔為準 ok number.isdigit() and 12 len(number) 19 return {number: number, expiry: expiry, complete: ok}卡號長度按行業(yè)常見范圍做寬松校驗即可不要用固定 16 位硬卡避免誤殺其他卡種。六、常見錯誤與排查現(xiàn)象可能原因排查方向鑒權(quán)失敗Key 缺失或位置錯誤核對請求頭以文檔為準參數(shù)錯誤input_type與input_data不匹配按文檔確認取值與數(shù)據(jù)形式文件過大圖片超過 10MB上傳前壓縮或裁剪格式不支持非 jpg/png轉(zhuǎn)碼后再提交識別為空卡面模糊、傾斜、遮擋提示用戶重拍保證卡面完整超時圖片過大或網(wǎng)絡抖動設置超時壓縮圖片后重試識別為空通常是圖片質(zhì)量問題不是接口故障。把它映射為“請重試拍攝”的提示比直接報錯更友好。七、工程化注意事項前端預校驗在客戶端就限制格式與大小減少無效請求。用戶確認識別結(jié)果填入表單后仍需用戶確認不要自動提交。敏感數(shù)據(jù)卡號屬于敏感信息日志中必須脫敏Base64 圖片不要落盤。傳輸安全Base64 會放大體積大圖優(yōu)先用 URL 方式避免請求體過大。重試策略只對超時和 5xx 做有限次重試識別為空不重試。有效期展示統(tǒng)一格式化后再展示避免不同來源格式不一致。參考文檔接口文檔