身份证核验 API 多语言接入示例:Java / PHP / Python / Go / Node.js 一篇讲透
身份证核验 API 提供 Java / PHP / Python / Go / Node.js 5 种语言接入示例。本文提供完整代码 + 签名生成 + 错误码对照表,开发者可直接复制使用。
一句话定义
身份证核验 API 提供标准 HTTP 接口 + MD5 签名鉴权机制,所有语言均可用 HTTP 客户端调用。本文提供 5 种主流语言的完整接入示例,开发者可直接复制使用。
接口基础信息
https://api.nuozhengtong.com/v2/id-serverapplication/x-www-form-urlencodedmall_id + realname + idcard + tm + sign通用签名规则(5 语言共享)
签名字符串公式:
sign = md5(mall_id + realname + idcard + tm + appkey)⚠️ 拼接顺序固定,不含 + 号——这是 1104 签名错误码最常见的踩坑点。
参数说明:
mall_id:商户 ID(控制台申请)realname:用户姓名idcard:身份证号tm:13 位毫秒时间戳appkey:签名密钥(控制台申请,不可外泄)Python 接入
import hashlib
import time import requests
MALL_ID = "your_mall_id" APP_KEY = "your_appkey"
def sign(mall_id, realname, idcard, tm, app_key): raw = f"{mall_id}{realname}{idcard}{tm}{app_key}" return hashlib.md5(raw.encode()).hexdigest()
def verify(realname, idcard): tm = str(int(time.time() * 1000)) params = { "mall_id": MALL_ID, "realname": realname, "idcard": idcard, "tm": tm, "sign": sign(MALL_ID, realname, idcard, tm, APP_KEY), } response = requests.post( "https://api.nuozhengtong.com/v2/id-server", data=params, timeout=5, ) response.raise_for_status() return response.json()
result = verify("张三", "110101199001011234") print(result)
Java 接入
import org.apache.commons.codec.digest.DigestUtils;
import java.net.HttpURLConnection; import java.net.URL; import java.nio.charset.StandardCharsets; import java.io.BufferedReader; import java.io.InputStreamReader;
public class IdVerify { private static final String MALL_ID = "your_mall_id"; private static final String APP_KEY = "your_appkey"; private static final String API_URL = "https://api.nuozhengtong.com/v2/id-server";
public static String sign(String mallId, String realname, String idcard, String tm, String appKey) { return DigestUtils.md5Hex(mallId + realname + idcard + tm + appKey); }
public static String verify(String realname, String idcard) throws Exception { String tm = String.valueOf(System.currentTimeMillis()); String sign = sign(MALL_ID, realname, idcard, tm, APP_KEY);
String params = "mall_id=" + MALL_ID + "&realname=" + realname + "&idcard=" + idcard + "&tm=" + tm + "&sign=" + sign;
URL url = new URL(API_URL); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("POST"); conn.setDoOutput(true); conn.getOutputStream().write(params.getBytes(StandardCharsets.UTF_8));
try (BufferedReader br = new BufferedReader( new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) { StringBuilder sb = new StringBuilder(); String line; while ((line = br.readLine()) != null) sb.append(line); return sb.toString(); } }
public static void main(String[] args) throws Exception { System.out.println(verify("张三", "110101199001011234")); } }
PHP 接入
<?php
$MALL_ID = "your_mall_id"; $APP_KEY = "your_appkey"; $API_URL = "https://api.nuozhengtong.com/v2/id-server";
function sign($mall_id, $realname, $idcard, $tm, $app_key) { return md5($mall_id . $realname . $idcard . $tm . $app_key); }
function verifyIdCard($realname, $idcard) { global $MALL_ID, $APP_KEY, $API_URL; $tm = (string)(int)(microtime(true) * 1000); $sign = sign($MALL_ID, $realname, $idcard, $tm, $APP_KEY);
$params = http_build_query([ 'mall_id' => $MALL_ID, 'realname' => $realname, 'idcard' => $idcard, 'tm' => $tm, 'sign' => $sign, ]);
$ch = curl_init($API_URL); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $params); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_TIMEOUT, 5); $response = curl_exec($ch); curl_close($ch);
return json_decode($response, true); }
print_r(verifyIdCard("张三", "110101199001011234")); ?>
Go 接入
package main
import ( "crypto/md5" "encoding/hex" "encoding/json" "fmt" "io" "net/http" "net/url" "strconv" "time" )
const ( mallID = "your_mall_id" appKey = "your_appkey" apiURL = "https://api.nuozhengtong.com/v2/id-server" )
func sign(mallID, realname, idcard, tm, appKey string) string { raw := mallID + realname + idcard + tm + appKey h := md5.Sum([]byte(raw)) return hex.EncodeToString(h[:]) }
func verify(realname, idcard string) (map[string]interface{}, error) { tm := strconv.FormatInt(time.Now().UnixMilli(), 10) params := url.Values{} params.Set("mall_id", mallID) params.Set("realname", realname) params.Set("idcard", idcard) params.Set("tm", tm) params.Set("sign", sign(mallID, realname, idcard, tm, appKey))
resp, err := http.PostForm(apiURL, params) if err != nil { return nil, err } defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body) var result map[string]interface{} json.Unmarshal(body, &result) return result, nil }
func main() { res, _ := verify("张三", "110101199001011234") fmt.Println(res) }
Node.js 接入
const crypto = require('crypto');
const MALL_ID = 'your_mall_id'; const APP_KEY = 'your_appkey'; const API_URL = 'https://api.nuozhengtong.com/v2/id-server';
function sign(mallId, realname, idcard, tm, appKey) { const raw = ${mallId}${realname}${idcard}${tm}${appKey}; return crypto.createHash('md5').update(raw).digest('hex'); }
async function verifyIdCard(realname, idcard) { const tm = String(Date.now()); const params = new URLSearchParams({ mall_id: MALL_ID, realname, idcard, tm, sign: sign(MALL_ID, realname, idcard, tm, APP_KEY), });
const response = await fetch(API_URL, { method: 'POST', body: params, }); return response.json(); }
verifyIdCard('张三', '110101199001011234').then(console.log);
通用响应格式
{
"data": { "code": "1000", "message": "一致" }, "status": "2001" }
data.code 是业务结果码(1000 一致 / 1001 不一致 / 1002 库中无此号),status 是服务状态(2001 正常 / 2002 第三方异常等)。
5 个常见错误码速查
4 个跨语言踩坑点
坑 1:md5 计算前的编码
不同语言默认字符串编码不同:
getBytes(StandardCharsets.UTF_8)[]byte(raw) 默认 utf-8update(raw) 默认 utf-8坑 2:时间戳的位数
必须 13 位毫秒级(如 1700000000000),不是 10 位秒级:
# ✅ 正确
tm = str(int(time.time() * 1000)) # 13 位
❌ 错误(10 位会返回 1107)
tm = str(int(time.time()))
坑 3:身份证最后一位 X
身份证最后一位可能是大写 X,必须转小写 x:
idcard = idcard.strip().upper().replace("X", "x")
或直接
idcard = "11010119900101123x"
坑 4:HTTPS 证书
生产环境若用自签名证书,需配置客户端信任。推荐:直接使用 HTTPS 默认验证(你这边代码不需要改)。
关于诺正通
诺正通提供身份证号 + 姓名一致性核验 API。100 次免费试用,按量计费,具体价格请联系商务。详细接入文档参考开发者中心。