<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 身份证二要素核验

> 校验「真实姓名 + 18 位身份证号」是否与公安权威库一致，秒级返回。

适用于注册实名、下单风控、账户绑定等场景。仅返回是否一致，不返回任何额外户籍信息；身份证号在响应中脱敏回显。请在取得被核验人授权后调用。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `idcard-2c` |
| 接口名称 | 身份证二要素核验 |
| 接口地址 | `https://v1.apizero.cn/api/idcard-2c` |
| 请求方法 | `POST` |
| 分类 | kyc |
| 提供方 | 极数本源 |
| 计费模式 | 按次付费 |
| 单次消耗 | 0 积分 |
| 起步价 | ¥0.00 / 1000 次 |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 0 次（已认证用户） |
| 匿名每日额度 | 0 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

需要 API Key（Authorization: Bearer <key>）。按次计费 ¥0.10/次，核验失败也计费（以上游返回为准）。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `name` | `string` | 是 | 真实姓名（中文） | `张三` |
| `idcard` | `string` | 是 | 18 位身份证号（末位可为 X） | `11010519491231002X` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 是 | Bearer <你的 API Key> | — |
| `Content-Type` | `string` | 否 | 请求体格式 | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl -X POST "https://v1.apizero.cn/api/idcard-2c" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "张三",
  "idcard": "11010519491231002X"
}'
```

### Python

```python
import requests

resp = requests.request(
    "POST",
    "https://v1.apizero.cn/api/idcard-2c",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
    "name": "张三",
    "idcard": "11010519491231002X",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const res = await fetch("https://v1.apizero.cn/api/idcard-2c", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "张三",
    "idcard": "11010519491231002X"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"name":"张三","idcard":"11010519491231002X"}`)
	req, _ := http.NewRequest("POST", "https://v1.apizero.cn/api/idcard-2c", bytes.NewBuffer(body))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}
```

### PHP

```php
<?php
$payload = json_encode([
    "name" => "张三",
    "idcard" => "11010519491231002X",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://v1.apizero.cn/api/idcard-2c");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `name` | `string` | 回显的姓名 | — |
| `idcard` | `string` | 脱敏后的身份证号 | — |
| `valid` | `boolean` | 是否一致：true=一致 | — |
| `result_code` | `number` | 100=一致 101=不一致 102=库中无此号 | — |
| `message` | `string` | 结果描述 | — |

## 7. 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "name": "张三",
    "idcard": "110***********002X",
    "valid": true,
    "result_code": 100,
    "message": "一致"
  },
  "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `VALIDATION_ERROR` | 缺少必填参数或身份证号格式错误 |
| `4022` | `INSUFFICIENT_BALANCE` | 余额不足，请充值后再试 |
| `5020` | `UPSTREAM_ERROR` | 上游核验服务不可用 |
| `5021` | `UPSTREAM_INVALID` | 上游返回格式异常 |
| `5030` | `UPSTREAM_MISSING` | 上游 Token 未配置，联系管理员 |

## 9. 变更日志

- **v1.0** (2026-06-10)
  - 首次上线：身份证二要素核验。

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/idcard-2c`

Source: `https://apizero.cn/aidocs/idcard-2c/raw.md`
Last updated: 2026-06-10T19:18:14+08:00