API 文档

通用约定

1. 创建应用

   在「应用管理」创建应用，得到 appid 与 appkey。

2. 配置白名单

   把回调域名写进该应用的白名单；支持 * 通配，例如 *.example.com。

3. 按需充值

   实名认证按次扣「应用所有者」的积分，余额不足接口返回 1010。

4. 联调

   先跑通 /api/verify/init.php 或 /api/oauth.php，再接收回调 / 轮询结果。

请求与响应

• 参数一律从 POST 表单读取（application/x-www-form-urlencoded 或 multipart）；授权入口是 GET。
• 响应 Content-Type: application/json，HTTP 状态码恒为 200，业务结果看 code。
• 成功：code = 0，msg = success，业务数据在 data。
• 失败：code 为四位错误码（见各接口表），msg 为可直接展示的中文说明。

POST /api/token.php HTTP/1.1
Content-Type: application/x-www-form-urlencoded

appid=YOUR_APPID&appkey=YOUR_APPKEY&code=e3b0c44298fc1c14

{"code":0,"msg":"success","data":{"access_token":"9f2c...","expires_in":7200,"openid":"oToeE6j_YK4PA0kiR41cyDriyEL4"}}

域名白名单规则

匹配对象是回调地址的 host（去掉端口）：白名单里的 * 转为 .*，其余字符做正则转义，整串锚定匹配。例如白名单 *.example.com 可以命中 a.example.com:8443，但不命中 example.com。

一、实名认证

第三方站点传入姓名与身份证号，本系统调用支付宝实人认证，返回跳转链接；用户在支付宝完成核验后，本系统更新记录并回调你的地址。

1. 初始化认证

返回示例：

{"code":0,"msg":"success","data":{
  "record_id": 123,
  "auth_url": "https://openapi.alipay.com/gateway.do?alipay_user_certify_open_initialize_response...",
  "expire_in": 300
}}

把 auth_url 交给用户打开（或生成二维码），用户在支付宝完成人脸核验后会被带回 callback_url。

计费说明：费用 = verify_config.amount × settings.recharge_rate，从 应用所有者（创建该应用的用户）的积分扣除，每次扣费都会写入 points_log（type=verify）；初始化失败会原路退回并记 type=verify_refund。

2. 查询认证结果

{"code":0,"msg":"success","data":{
  "status": 1,
  "real_name": "张三",
  "cert_no": "11010119900307663X",
  "result_msg": "认证通过"
}}

status：0 待认证、1 通过、2 失败。

3. 异步回调

认证结束后，本系统会以 GET 请求你的 callback_url（追加 ? 或 &），参数如下：

签名算法：sign = md5(record_id + real_name + private_key)，字符串直接拼接、无分隔符，private_key 取自后台配置的支付宝应用私钥。请务必校验后再信任回调内容；超时或非 2xx 响应会被忽略且不重试。

回调是「尽力投递」：也可以只用 /api/verify/query.php 轮询，两条路径都安全。

二、微信登录（公众号验证码模式）

用户关注你的公众号后发送关键词，公众号回复一次性验证码；用户把验证码填回你的站点，你的服务端用授权码换取用户标识。

1. 授权入口

https://app.2bmzf.com/api/oauth.php?appid=YOUR_APPID&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&state=123456

校验通过后 302 到 /wechat_login.php?api=1，用户输入公众号收到的 6 位验证码；成功后跳回：

https://example.com/callback?code=e3b0c442...&state=123456&type=wx

失败时返回纯文本：参数缺失、无效的回调地址、回调域名不在白名单、应用不存在或已禁用、验证码无效或已过期、会话过期，请重新发起授权。

2. 授权码换令牌

{"code":0,"msg":"success","data":{
  "access_token": "9f2c1d...",
  "expires_in": 7200,
  "openid": "oToeE6j_YK4PA0kiR41cyDriyEL4"
}}

3. 拉取用户信息

{"code":0,"msg":"success","data":{
  "openid": "oToeE6j_YK4PA0kiR41cyDriyEL4",
  "nickname": "微信用户",
  "avatar": "https://thirdwx.qlogo.cn/...",
  "gender": 1
}}

4. 公众号服务器配置

• GET 验签：微信服务器配置时校验 signature（sha1 排序拼接 token/timestamp/nonce），通过后回显 echostr；若后台开启「跳过验签」，直接回显。
• POST 收消息：关注事件回复订阅模板，用户发关键词回复验证码模板，模板中的占位符 %code%、%time%、%keyword% 会被替换。
• 验证码：6 位数字，5 分钟有效，同一 openid 未使用的旧码会被作废。

5. 站内消息推送

{"code":0,"msg":"发送成功"}

错误码汇总

常见问题

为什么一直是 1003？

白名单比对的是 callback_url / redirect_uri 的 host（含子域）。若你的站点是 app.example.com，白名单要写 app.example.com 或 *.example.com，只写 example.com 不匹配。

授权链接里的 redirect_uri 要编码几次？

服务端会对 redirect_uri 做两次解码再校验，因此整串只需要按 URL 参数正常编码一次（与旧站行为一致）。

认证回调收不到怎么办？

回调是尽力投递、不重试，且只接受 2xx。生产环境建议以 /api/verify/query.php 轮询为准，回调只作为加速通知。

access_token 能复用多久？

有效期 7200 秒，过期后需要用户重新走一次授权（code 是一次性的，不能重复换令牌）。

积分不足会怎样？

/api/verify/init.php 返回 1010，不会创建认证记录；请在「积分充值」补充积分后重试。