常用卡系统 · 开发对接文档

版本 1.1 ｜更新于 2026-06-16 ｜提供银行卡活跃状态查询服务

目录： 1. 接入概览 · 2. 获取密钥 · 3. 签名规则 · 4. 银行卡查询 · 5. 结果回查 · 6. 数据结构 · 7. 收费规则 · 8. 返回码 · 9. 安全与隐私

1. 接入概览

商户通过 RESTful API 接入，提交身份证号或手机号，即可查询该用户名下的银行卡编码及活跃分值。请求与响应均为 application/json。

接口基础地址：https://bank.1.taolianwl.cn
银行卡查询：POST /api/query/bank-card　结果回查：POST /api/query/result

2. 获取密钥

登录商户端 →「API 密钥」页，获取你的 app_id 与 app_secret。app_secret 用于计算签名，请妥善保管、勿泄露；如怀疑泄露可在商户端重置（重置后旧密钥立即失效）。

3. 签名规则

每次请求都必须携带 app_id、timestamp、sign 三个公共参数。

签名公式

sign = MD5(app_id + app_secret + timestamp)   // 结果取小写十六进制

注意：timestamp 为秒级 Unix 时间戳（10 位），与服务器时间偏差不得超过 5 分钟，否则返回「请求已过期」。

代码示例

// Node.js
const crypto = require('crypto');
const sign = crypto.createHash('md5').update(appId + appSecret + timestamp).digest('hex');

// PHP
$sign = md5($appId . $appSecret . $timestamp);

// Python
import hashlib, time
sign = hashlib.md5(f"{app_id}{app_secret}{int(time.time())}".encode()).hexdigest()

4. 银行卡查询接口

POST/api/query/bank-card

请求参数

参数	类型	必填	说明
app_id	String	是	商户 AppID
timestamp	String	是	秒级时间戳（10 位）
sign	String	是	签名，见第 3 节
id_type	String	是	身份类型：`"1"`-身份证号，`"2"`-手机号
id_card	String	条件	身份证号明文（id_type="1" 时必填）
phone	String	条件	手机号明文（id_type="2" 时必填）
name	String	否	姓名明文（强烈建议传入，可提升匹配率）
encrypt_type	String	否	上游比对算法：1-SHA256，2-MD5，3-SM3。缺省为 2(MD5)，推荐传 "1"(SHA256)
out_order_no	String	否	商户自定义查询号，便于对账

关于 encrypt_type：身份证/手机号/姓名请直接提交明文，平台会按 encrypt_type 指定的算法在转发上游前自动哈希处理，商户无需自行加密。

请求示例（curl）

curl -X POST https://bank.1.taolianwl.cn/api/query/bank-card \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "bk_xxxxxxxxxxxx",
    "timestamp": "1718500000",
    "sign": "a1b2c3d4e5f6......",
    "id_type": "1",
    "id_card": "110101199001011234",
    "name": "张三",
    "encrypt_type": "1",
    "out_order_no": "MY20260616001"
  }'

成功响应（查得数据）

{
  "code": 0,
  "message": "success",
  "data": {
    "order_no": "BK20260616121200123456",
    "out_order_no": "MY20260616001",
    "id_type": "1",
    "result_count": 3,
    "bank_cards": [
      { "bankCode": "PSBCCNBJ", "bankName": "邮政储蓄银行", "cardType": "2", "activityScore": 85 },
      { "bankCode": "ICBKCNBJ", "bankName": "工商银行",     "cardType": "2", "activityScore": 72 },
      { "bankCode": "ICBKCNBJ", "bankName": "工商银行",     "cardType": "3", "activityScore": 60 }
    ],
    "fee": "1.00",
    "status": "success"
  }
}

查无数据响应（不收费）

{
  "code": 0,
  "message": "success",
  "data": {
    "order_no": "BK20260616121200123456",
    "out_order_no": "MY20260616001",
    "id_type": "1",
    "result_count": 0,
    "bank_cards": [],
    "fee": "0.00",
    "status": "no_data"
  }
}

失败响应（签名错误 / 余额不足 / 参数错误等）

{
  "code": -1,
  "message": "签名验证失败",
  "data": null
}

判定逻辑：code === 0 即调用成功，再看 data.status 区分「有数据(success)/无数据(no_data)」；code !== 0 表示失败，原因见 message。

5. 结果回查接口

POST/api/query/result　用于按系统查询号回查历史结果。

参数	类型	必填	说明
app_id / timestamp / sign	String	是	同上，公共鉴权参数
order_no	String	是	查询接口返回的系统查询号 `order_no`

响应示例

{
  "code": 0,
  "message": "success",
  "data": {
    "order_no": "BK20260616121200123456",
    "out_order_no": "MY20260616001",
    "id_type": "1",
    "status": "success",
    "result_count": 3,
    "bank_cards": [ { "bankCode": "PSBCCNBJ", "bankName": "邮政储蓄银行", "cardType": "2", "activityScore": 85 } ],
    "fee": "1.00",
    "created_at": "2026-06-16 12:12:00"
  }
}

6. 银行卡数据结构

字段	类型	说明
bankCode	String	银行编码（如 PSBCCNBJ、ICBKCNBJ）
bankName	String	银行名称
cardType	String	卡类型：`"2"`-借记卡，`"3"`-贷记卡
activityScore	Integer	活跃分值，0–99，分值越高越活跃

7. 收费规则

仅当查得有效数据（status=success、result_count>0）时收费；查无数据（no_data）、查询失败（failed）均不收费。单次费率以商户在管理端配置的费率为准（默认 1.00 元/次），费用从商户余额实时扣减，余额不足将拒绝查询。

8. 返回码与状态

顶层 code

code	说明
0	调用成功（再看 data.status 区分有/无数据）
-1	调用失败，原因见 message（如：缺少必填参数、签名验证失败、请求已过期、商户余额不足、商户不存在或已禁用、上游返回错误等）

data.status

status	说明	是否扣费
success	查询成功，返回有效银行卡数据	是
no_data	查询成功，但该用户无银行卡数据	否
failed	查询失败（上游异常等）	否

9. 安全与隐私

商户提交明文身份证号/手机号/姓名；平台以哈希值参与上游数据源比对，原始要素仅用于查询与对账记录。
平台与上游数据源之间采用国密 SM2 数字信封加密传输业务数据。
请求签名（sign）防篡改伪造，时间戳（timestamp）防重放（5 分钟有效）。
请务必通过 HTTPS 调用，妥善保管 app_secret。