开发者中心

开发者中心包含四个子页面：项目与密钥、用量统计、调用日志、Webhooks。所有接口均需 Web 登录态（JWT），API Key 用于服务端调用开放接口。

项目与密钥 `/app/developers/projects`

概念：一个「项目」对应一对 API 凭据，用于在请求头中鉴权并隔离配额与用量统计。

创建项目：

点击右上角「新建项目」；

填写项目名称（例如「生产环境」「测试环境」），点击「创建」；

系统生成 API Key，弹窗展示完整密钥，此时是唯一一次可见完整密钥；

点击「复制 Key」保存到安全位置，关闭弹窗后仅能看到掩码。

项目列表字段：

字段	说明
项目名称	创建时填写
API Key	掩码展示，支持一键复制
创建时间	创建于 {date}
操作	复制 Key

管理建议：

生产与测试使用不同项目，便于分环境统计与快速吊销；

密钥只存放在服务端环境变量或密钥管理系统中，禁止硬编码到前端代码或提交到 Git；

密钥泄露时立即在控制台删除对应项目并重建。

用量统计 `/app/developers/usage`

指标	说明
近 7 天调用	7 天累计调用次数，并显示「较上周 ±x%」
本月已用	当月已消耗配额与剩余次数
峰值 QPS	近 7 天单秒最高并发
每日调用量	柱状/折线趋势图
接口分布	按接口维度统计调用占比

无数据时显示「暂无数据」。上周无数据时百分比提示为「暂无上周数据」。

调用日志 `/app/developers/logs`

日志来源为数据库表 client_query_log，记录每次企业查询。

列	说明
时间	请求发生时间（本地时区）
查询内容	CNPJ 或关键词
类型	CNPJ 精确查询 / 名称搜索
渠道	web（控制台）/ api（API Key）
结果数	命中条数
缓存	命中 / 未命中
来源 IP	客户端 IP

支持分页（上一页 / 下一页），默认每页 20 条。日志为只读，不支持删除。

排障用法：

用户反馈「查询无结果」时，先在日志中确认请求是否到达、结果数是否为 0；

反馈「接口报错」时，结合返回的 request_id 在服务端日志中检索完整链路。

Webhooks `/app/developers/webhooks`

用途：当企业数据更新或报告生成完成时，向你的服务推送事件，避免轮询。

创建订阅：

点击「添加 Webhook」；

填写回调地址（必须是可公网访问的 HTTPS URL，例如 https://example.com/webhook）；

选择事件类型；

保存后生成签名密钥（Secret），用于校验请求来源。

事件类型：

事件	触发时机	状态
`company.created`	企业首次入库	保留定义；当前版本全量数据已导入，不再产生该事件
`report.completed`	报告生成完成	正常触发

请求格式：

签名校验（Node.js 示例）：

import crypto from "node:crypto";

function verify(rawBody: string, signature: string, secret: string) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

注意：必须使用原始请求体（未解析的字符串）参与签名计算。

订阅管理：

操作	说明
启用 / 停用	关闭后不再推送，但保留配置
复制密钥	复制 Secret 到剪贴板
删除	二次确认后删除，之后不再推送

重试策略（建议实现方对齐）：

2xx 视为成功；

非 2xx 或超时（10s）视为失败，按指数退避重试；

连续失败达到阈值后自动停用并邮件通知。

项目与密钥 /app/developers/projects#

用量统计 /app/developers/usage#

调用日志 /app/developers/logs#

Webhooks /app/developers/webhooks#

项目与密钥 `/app/developers/projects`

用量统计 `/app/developers/usage`

调用日志 `/app/developers/logs`

Webhooks `/app/developers/webhooks`