开放接口文档

开放平台接口文档

本文说明对外接口（OpenAPI 3.0）的接入方式、签名规则、端点清单与错误码。所有内容均取自本站代码实读（app/middleware/OpenApiAuth.php、app/controller/openapi/Doc.php、route/app.php）。

1. 接入地址

已确认：契约 YAML 内 servers.url 当前已指向本站 https://www.huiyingclub.com/openapi/v1（r164 已完成由物业站 web.zhsqzfxt.com 迁移后的地址修正）。

2. 鉴权与签名

2.1 公共参数

2.2 待签串与签名计算

\\\\n\\\\t
1. 收集全部请求参数（GET query + POST body）；
\\\\n\\\\t
2. 剔除 sign，并剔除值为空（'' / null）的参数；
\\\\n\\\\t
3. 按参数名升序排序（ksort）；
\\\\n\\\\t
4. 做 http_build_query 得到待签串；
\\\\n\\\\t
5. 计算签名：\\\\n\\\\t\\\\t
   \\\\n\\\\t\\\\t\\\\t
   • HMAC-SHA256：hash_hmac('sha256', 待签串, appsecret)，取小写十六进制；
   \\\\n\\\\t\\\\t\\\\t
   • RSA-SHA256：对待签串做 SHA256 私钥签名后 base64，服务端用应用公钥 openssl_verify 校验。
   \\\\n\\\\t\\\\t
   \\\\n\\\\t
\\\\n

2.3 安全约束

\\\\n\\\\t
• 时间戳窗口：±300 秒（OpenApiAuth::TS_DIFF）
\\\\n\\\\t
• nonce 防重放窗口：300 秒（NONCE_TTL）
\\\\n\\\\t
• 限流：100 次/分钟/应用（RATE_LIMIT）
\\\\n\\\\t
• 支持按应用配置 IP 白名单
\\\\n\\\\t
• 接口异常不会返回 HTTP 500，统一以 HTTP 200 + code 信封返回
\\\\n

3. 免鉴权端点

以下路径前缀在 OpenApiAuth::PUBLIC_PREFIX 中配置为免签名校验：health、oauth/authorize、oauth/token、oauth/refresh、doc、metrics。

路由开放状态：health 与 doc 已在 route/app.php 显式注册，当前可直接访问；oauth/authorize、oauth/token、oauth/refresh、metrics 已注册路由并对外可达（GET 返回实时计数 rate_limited/auth_fail/exception），OAuth2 其余端点（token/refresh/revoke/authorize）路由亦已打通，详见第 4 节状态列。

4. 端点清单

数据层说明：开放平台所需的 5 张数据表（ddwx_openapi_app、ddwx_openapi_oauth_code、ddwx_openapi_oauth_token、ddwx_openapi_fee_order_rel、ddwx_openapi_log）已于 2026-09-20 在生产库创建，并初始化了运营站应用凭证。上方各签名 / OAuth2 端点现已返回真实业务响应（不再因缺表而 500）。联调示例：GET /oauth/authorize → 取 authorization_code → POST /oauth/token（grant_type=authorization_code）换取 access_token / refresh_token。

5. OAuth2 Bearer 方式

除签名外，也支持在请求头携带 Authorization: Bearer <access_token>，服务端在 ddwx_openapi_oauth_token 表中校验令牌有效性。

6. 错误码

7. 响应结构

{\\\\n  "code": 0,\\\\n  "msg": "success",\\\\n  "data": { }\\\\n}