身份实名认证API文档

POST

身份实名认证

验证姓名与身份证号是否匹配

验证姓名与身份证号是否匹配。每次调用消耗1次身份实名认证API调用次数。

请求参数

参数名	类型	是否必填	描述
api_key	string	必填	用户API密钥
name	string	必填	姓名（2-50个字符，支持中文、英文、空格、连字符）
idcard	string	必填	身份证号（18位）

响应字段说明

字段名	类型	说明
success	boolean	请求是否成功
message	string	响应消息
matched	boolean	姓名与身份证号是否匹配
extra	object	补充信息（根据上游接口返回，可能包含：sex/gender性别、birthday/birth出生日期、address/location地址、age年龄、nation民族、province省份、city城市、district区县等）

参数传递方式

参数可通过以下方式传递（优先级从高到低）：
1. HTTP Header（如 api_key: your_api_key）
2. JSON Body (Content-Type: application/json)
3. POST Form (Content-Type: application/x-www-form-urlencoded)
4. GET Query String

请求示例

// JSON 请求示例 (application/json)
{
  "api_key": "your_api_key",
  "name": "张三",
  "idcard": "110101199001011234"
}

// POST 请求示例 (application/x-www-form-urlencoded)
api_key=your_api_key&name=张三&idcard=110101199001011234

// GET 请求示例
api/id_verification_api.php?api_key=your_api_key&name=张三&idcard=110101199001011234

// HTTP Header 请求示例（api_key 通过 Header 传递）
// 其他参数可通过 JSON Body / POST Form / GET 任意方式传递
curl -X POST api/id_verification_api.php \
     -H "api_key: your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"name":"张三","idcard":"110101199001011234"}'

响应示例

注意：本接口存在两种响应格式：
1. 认证/参数错误（如密钥无效、参数缺失、次数不足）：使用统一格式 {"code": 1003, "message": "..."}
2. 核验业务结果（认证通过后执行核验）：使用原格式 {"success": true, "matched": true, "message": "...", "extra": {...}}

{
  "success": true,
  "message": "核验通过",
  "matched": true,
  "extra": {
    "sex": "男",
    "birthday": "19900101",
    "address": "北京市东城区"
  }
}

{
  "success": true,
  "message": "核验不通过，姓名与身份证号不匹配",
  "matched": false,
  "extra": {}
}

{
  "code": 1003,
  "message": "用户名或API密钥无效"
}

{
  "code": 1004,
  "message": "身份实名认证调用次数不足"
}

错误码说明

响应格式说明：
认证/参数类错误使用统一错误码格式 {"code": 错误码, "message": "错误信息"}；
核验业务结果使用原格式 {"success": false, "message": "..."}。

错误码	错误信息	说明
1001	缺少必要参数	未提供 api_key / name / idcard 参数
1002	参数验证失败	身份证号或姓名格式校验失败
1003	用户名或API密钥无效	API密钥不存在或无效
1004	身份实名认证调用次数不足	用户调用次数不足
5000	系统内部错误	服务器异常
-	核验失败: xxx	上游API返回的错误（success=false 格式）

身份实名认证API

API 基本信息

身份实名认证

错误码说明

注意事项