查看全局 API 说明（请求/响应头、通用 JSON 格式）

编码校验 API

提供 USCC、身份证、银行卡号等编码规则与校验位校验

Base URL https://www.resapi.cn/v1/validate

简介

提供 USCC、身份证、银行卡号等编码规则与校验位校验；身份证可附带地址码区划参考。均不提供权威机关真实性核验。

GET /v1/validate/uscc

统一社会信用代码（USCC）校验，校验内容：

长度与字符集合法性
校验位（第 18 位）是否正确

该接口仅做编码规则校验，不代表企业真实存在或工商登记状态。

查询参数

名称	类型	必填	说明	示例
code	string	是	统一社会信用代码	91110108MA01XXXXXX

响应字段

字段	说明
code	输入代码（转为大写）
is_valid_format	格式是否通过（长度/字符集）
is_valid_checksum	校验位是否通过
is_valid	综合结果（前两项均为 true）
expected_check	计算得到的校验位（格式通过时返回）
actual_check	实际校验位（格式通过时返回）
format_errors	格式错误列表
note	风险提示说明

GET /v1/validate/idcard

中华人民共和国居民身份证号码校验，校验内容：

长度与字符集（18 位，末位可为 X）
出生日期段（第 7–14 位）是否合理
校验位（第 18 位）是否正确
地址码（前 6 位）在本平台行政区划库中的最佳匹配（可选返回，仅供参考）

仅做编码规则与校验位校验，不代表真实身份、户籍或公安登记状态。地址码与统计用区划代码可能不一致，未匹配时 region 为 null。

查询参数

名称	类型	必填	说明	示例
number	string	是	身份证号码（18 位）	`370181199001011234`

响应字段

字段	说明
number	输入号码（末位 `x` 会转为大写 `X`）
is_valid_format	格式与出生日期是否通过
is_valid_checksum	校验位是否通过
is_valid	综合结果
area_code	地址码（前 6 位）
birth_date	出生日期 `YYYY-MM-DD`（格式通过时）
expected_check	计算得到的校验位
actual_check	实际校验位
format_errors	格式错误列表
region	区划库匹配结果，未命中为 `null`
region.code / name / level / full_name	匹配到的区划信息
note	风险提示说明

GET /v1/validate/bank-card

银行卡号校验（Luhn 算法），校验内容：

去除空格后仅含数字
长度 13–19 位（覆盖常见借记/信用卡号段）
Luhn 校验位

仅做号码规则与 Luhn 校验，不代表卡片真实存在、已开通或归属银行信息。

查询参数

名称	类型	必填	说明	示例
number	string	是	银行卡号	`6222021234567890123`

响应字段

字段	说明
number	去空格后的卡号
length	卡号长度
is_valid_format	格式是否通过
is_valid_luhn	Luhn 是否通过
is_valid	综合结果
format_errors	格式错误列表
note	风险提示说明

通用错误码

以下错误码适用于平台全部 /v1/* 接口（各接口在「错误代码」Tab 中另有本接口补充说明）。

错误响应格式

HTTP 状态码非 2xx 时，响应体一般为：

{
  "error": {
    "code": "错误码",
    "message": "错误信息"
  }
}

错误码一览

HTTP	code	message	说明
400	invalid_params	参数无效	必填参数缺失、格式不合法或超出允许范围
404	not_found	资源不存在	按编码或 ID 查询时无匹配记录
429	rate_limit_exceeded	请求过于频繁	超过当前 IP 的访问频率限制
500	internal_error	服务器内部错误	服务端或数据库异常，请稍后重试

限流、缓存等 HTTP 响应头含义见上文「响应头说明」。

本接口补充

HTTP	code	message	说明
400	invalid_params	参数无效	code/number 为空，或号码长度、字符集不合法（含银行卡号）

请求根地址为 https://www.resapi.cn。每个场景含 7 种语言（cURL → JavaScript → Python → Go → Java → PHP → C#）。

统一社会信用代码校验

GET /v1/validate/uscc?code=91310000MA1K3J2W5X

cURL

curl -s "https://www.resapi.cn/v1/validate/uscc?code=91310000MA1K3J2W5X" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/validate/uscc?code=91310000MA1K3J2W5X", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests
r = requests.get(
    "https://www.resapi.cn/v1/validate/uscc",
    params={"code": "91310000MA1K3J2W5X"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

package main
import (
  "encoding/json"
  "fmt"
  "log"
  "net/http"
)
func main() {
  url := "https://www.resapi.cn/v1/validate/uscc?code=91310000MA1K3J2W5X"
  req, _ := http.NewRequest(http.MethodGet, url, nil)
  req.Header.Set("Accept", "application/json")
  resp, err := http.DefaultClient.Do(req)
  if err != nil { log.Fatal(err) }
  defer resp.Body.Close()
  var out map[string]any
  json.NewDecoder(resp.Body).Decode(&out)
  fmt.Printf("%+v\n", out)
}

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Example {
  public static void main(String[] args) throws Exception {
    String url = "https://www.resapi.cn/v1/validate/uscc?code=91310000MA1K3J2W5X";
    HttpRequest req = HttpRequest.newBuilder().uri(URI.create(url)).header("Accept", "application/json").GET().build();
    HttpResponse<String> res = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    System.out.println(res.body());
  }
}

PHP

<?php
$url = "https://www.resapi.cn/v1/validate/uscc?code=91310000MA1K3J2W5X";
$ctx = stream_context_create(["http" => ["header" => "Accept: application/json\r\n"]]);
$json = file_get_contents($url, false, $ctx);
print_r(json_decode($json, true));

C#

using System.Net.Http.Headers;
var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
var json = await client.GetStringAsync("https://www.resapi.cn/v1/validate/uscc?code=91310000MA1K3J2W5X");
Console.WriteLine(json);

居民身份证校验

GET /v1/validate/idcard?number=370181199001011234

示例号码仅作格式演示，校验位可能不通过；请替换为真实格式号码测试。

cURL

curl -s "https://www.resapi.cn/v1/validate/idcard?number=370181199001011234" \
  -H "Accept: application/json"

JavaScript

const res = await fetch("https://www.resapi.cn/v1/validate/idcard?number=370181199001011234", {
  headers: { Accept: "application/json" },
});
if (!res.ok) throw new Error(res.statusText);
console.log(await res.json());

Python

import requests

r = requests.get(
    "https://www.resapi.cn/v1/validate/idcard",
    params={"number": "370181199001011234"},
    headers={"Accept": "application/json"},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Go

url := "https://www.resapi.cn/v1/validate/idcard?number=370181199001011234"
req, _ := http.NewRequest(http.MethodGet, url, nil)
req.Header.Set("Accept", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
	log.Fatal(err)
}
defer resp.Body.Close()
var out map[string]any
json.NewDecoder(resp.Body).Decode(&out)
fmt.Printf("%+v\n", out)

Java

String url = "https://www.resapi.cn/v1/validate/idcard?number=370181199001011234";
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Accept", "application/json")
    .GET()
    .build();
HttpResponse<String> res = HttpClient.newHttpClient()
    .send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

PHP

<?php
$url = "https://www.resapi.cn/v1/validate/idcard?number=370181199001011234";
$ctx = stream_context_create(["http" => ["header" => "Accept: application/json\r\n"]]);
print_r(json_decode(file_get_contents($url, false, $ctx), true));

C#

var json = await client.GetStringAsync(
    "https://www.resapi.cn/v1/validate/idcard?number=370181199001011234");
Console.WriteLine(json);

银行卡号 Luhn 校验

GET /v1/validate/bank-card?number=6222021234567890123

cURL

curl -s "https://www.resapi.cn/v1/validate/bank-card?number=6222021234567890123" \
  -H "Accept: application/json"