国内银行信息查询 · 开放 API

一、概述

本接口提供国内银行业金融机构的联行号（CNAPS 号）、分支机构与总行信息的标准化查询能力，供外部系统以编程方式调用。所有接口返回统一的 JSON 结构，支持按关键字、省市、总行、联行号等多维度检索。

二、基础信息

接口根地址

https://open.suujee.com/bank/api.php

请求方法

GET 或 POST（参数合并读取，推荐使用 GET + 请求头鉴权）

字符编码

UTF-8（请求与响应均为 application/json; charset=utf-8）

数据格式

请求参数使用 query string / form；响应统一为 JSON

时间字段

created_at / updated_at 为 YYYY-MM-DD HH:MM:SS（服务器时区）；信封 timestamp 为 Unix 秒级时间戳

跨域

已开启 CORS：Access-Control-Allow-Origin: *，支持 OPTIONS 预检，允许头 X-API-Key

三、鉴权

所有接口均需在请求中携带有效的 API Key。密钥由用户在「用户中心 → API 密钥」中手动生成，属于平台级密钥，可调用平台下所有应用的对外接口。

四、限流说明

为防止滥用，接口按每个用户（密钥）独立进行滑动窗口限流：

维度	取值	说明
限流粒度	每个 API Key（用户）	不同用户的请求互不影响
窗口长度	60 秒	滑动窗口：每次请求以当前时间重新计算窗口
单窗口上限	120 次 / 60 秒	超过即拒绝，终止本次窗口计数
超限响应	HTTP 429	{ "code":429, "message":"请求过于频繁，请稍后再试" }
窗口重置	自动	距上次请求超过 60 秒后，计数自动归零

五、通用响应结构

所有接口返回统一 JSON 信封：

{
  "code": 0,                 // 业务码：0 成功，非 0 见错误码表
  "message": "ok",           // 人类可读提示
  "data": { ... },           // 业务数据，结构因接口而异；出错时通常为 null
  "timestamp": 1690000000    // 服务器 Unix 秒级时间戳
}

HTTP 状态码与 code 字段保持一致语义（401 / 400 / 404 / 429 / 500）。成功时 code=0 且 HTTP 200。

六、错误码

HTTP	code	message（示例）	含义 / 处理建议
401	401	缺少 API Key（请…）	未携带密钥。检查 X-API-Key 头或 api_key 参数。
401	401	API Key 无效	密钥错误、已被撤销、或所属账户已禁用。请重新生成或确认账户状态。
400	400	缺少参数 cnaps	必要参数缺失或格式非法。核对请求参数。
404	404	未找到该联行号对应的分支机构	查询条件无匹配数据。确认联行号 / ID 是否正确。
429	429	请求过于频繁，请稍后再试	触发限流。降低频率或稍后重试。
500	500	服务端用户表未初始化…	服务端异常（如未执行初始化）。请联系平台方。

七、数据对象字段

7.1 分支机构对象（item / items[]）

字段	类型	说明
id	int	分支机构内部 ID
branch_name	string	分支机构（网点）全称
branch_cnaps	string	联行号（CNAPS 号，12 位）
province	string	省 / 直辖市（全称，如「浙江省」）
city	string	市（全称，如「杭州市」）
region_id	string	大区标识（多数记录为空）
province_code	string	省级行政区划代码（6 位）
city_code	string	市级行政区划代码（6 位）
address	string	详细地址（可能为空）
phone	string	联系电话（可能为空）
former_name	string	曾用名（可能为空）
status	int	状态：1=正常，2=停业
status_text	string	状态文案：正常 / 停业
head	object	所属总行对象（见 7.2）
created_at	string	记录创建时间
updated_at	string	记录更新时间

7.2 总行对象（head）

字段	类型	说明
id	int	总行内部 ID
name	string	总行名称（如「中国邮政储蓄银行」）
cnaps	string	总行联行号（CNAPS 号）
code	string	总行行别代码（如 PSBC）

八、接口详情

8.1 分支机构搜索 GET action=search / list

按关键字、省市、总行、状态组合筛选分支机构，支持分页。这是最常用的列表接口。

参数	必填	类型	说明
action	是	string	search 或 list
q	否	string	关键字：匹配网点名称 / 总行名称 / 联行号 / 省市
province	否	string	省全称精确过滤（如「浙江省」）
city	否	string	市全称精确过滤
head_id / head	否	int	按总行 ID 过滤（两个参数名等效）
status	否	int	1=正常，2=停业
page	否	int	页码，默认 1
per_page	否	int	每页条数，默认 20，最大 100

curl -H "X-API-Key: pk_你的密钥" \
  "https://open.suujee.com/bank/api.php?action=search&q=支行&province=浙江省&page=1&per_page=20"

data 字段：

字段	类型	说明
items	array	分支机构对象数组（见 7.1）
total	int	符合条件的总记录数
page / per_page	int	当前页 / 每页条数
total_pages	int	总页数
keyword / province / city / head_id / status	—	回显的请求参数（便于分页拼接）

8.2 按联行号查询 GET action=byCnaps / by_cnaps

参数	必填	类型	说明
action	是	string	byCnaps 或 by_cnaps
cnaps	是	string	12 位联行号

curl -H "X-API-Key: pk_你的密钥" \
  "https://open.suujee.com/bank/api.php?action=byCnaps&cnaps=102100000026"

data：{ "item": 分支机构对象 }；未找到返回 HTTP 404。

8.3 按内部 ID 查询 GET action=byId / by_id

参数	必填	类型	说明
action	是	string	byId 或 by_id
id	是	int	分支机构内部 ID

curl -H "X-API-Key: pk_你的密钥" \
  "https://open.suujee.com/bank/api.php?action=byId&id=123"

data：{ "item": 分支机构对象 }；未找到返回 HTTP 404。

8.4 总行列表 GET action=heads / heads_search

参数	必填	类型	说明
action	是	string	heads 或 heads_search
q	否	string	总行名称 / 联行号 / 行别代码关键字
page	否	int	页码，默认 1
per_page	否	int	每页条数，默认 50，最大 100

curl -H "X-API-Key: pk_你的密钥" \
  "https://open.suujee.com/bank/api.php?action=heads&q=工商"

data.items[] 字段：id、head_name、head_cnaps、head_code、branch_count（下属网点数）、status、created_at、updated_at。

8.5 统计概览 GET action=stats

参数	必填	类型	说明
action	是	string	stats

curl -H "X-API-Key: pk_你的密钥" \
  "https://open.suujee.com/bank/api.php?action=stats"

data：{ "total": 总网点数, "heads": 总行数, "normal": 正常网点数, "cancelled": 停业网点数 }

九、快速开始

curl -H "X-API-Key: pk_你的密钥" \
  "https://open.suujee.com/bank/api.php?action=stats"

十、常见问题