API Reference

API 文档

用代码自动完成「开账单 → 发链接 → 确认到账 → 通知你的系统」全流程。认证用 Bearer API 密钥（Studio 版专属，在用户中心「设置」里一键生成）。

01快速开始（3 步跑通）

① 登录用户中心 → 设置 → 「开放 API 密钥」→ 点生成，复制保存（形如 sk_ 开头的一串）。
② 用密钥调 POST /api/invoices 开一张账单，响应里就有账单 ID。
③ 把付款链接 https://你的域名/pay.html?id=账单ID 发给客户；到账后 Webhook 自动通知你的系统。

02认证方式

需要登录态的接口，在请求头带上你的 API 密钥即可，无需网页登录：

Authorization: Bearer sk_xxxxxxxxxxxxxxxx

密钥为 Studio 版专属；降级到 Pro / 免费版后旧密钥自动失效。
密钥等同账号权限，请勿写进前端代码或公开仓库；泄露后在设置页点「吊销」立即失效。
同一域名下调用，Base URL 就是本站地址（如 https://pay.51kaifa.app）。

03账单接口

POST/api/invoices需密钥

创建一张收款账单。响应返回完整账单对象，用 invoice.id 拼出付款链接即可发给客户。

参数	类型	说明
client *	string	客户名称（≤80 字）。新名字自动建客户档案
amountUsd *	number	金额（美元），1 ~ 1,000,000
chain *	string	`tron` (USDT·TRC20) / `bsc` (USDT·BEP20) / `base` (USDC·Base)
item	string	项目 / 服务内容（≤120 字）
dueDate	string	截止付款日，格式 YYYY-MM-DD
note	string	备注（≤200 字，不展示给客户）
clientAddr	string	客户钱包地址（退款 / 返佣用）
clientEmail	string	客户邮箱（催付邮件用）
recur	string	填 monthly = 每月自动续开一期同样的账单

# 创建一张 $500 的 TRC20 账单
curl -X POST https://pay.51kaifa.app/api/invoices \
  -H "Authorization: Bearer sk_你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"client":"Acme Ltd","amountUsd":500,"chain":"tron","item":"官网开发第二期"}'

# 响应（节选）
{ "ok": true, "invoice": { "id": "INV-MV3FLTT3FEDD", "cryptoAmount": 500.37, "status": "pending", ... } }
# → 付款链接：https://pay.51kaifa.app/pay.html?id=INV-MV3FLTT3FEDD
#   cryptoAmount 带唯一尾数，系统靠尾数自动识别是哪一单

GET/api/invoices需密钥

拉取你的全部账单、客户档案与统计汇总（净收入 / 头部客户）。账单含 status 字段：pending 待付款 / paid 已到账 / partial 少付 / expired 已过期 / archived 已归档。

curl https://pay.51kaifa.app/api/invoices \
  -H "Authorization: Bearer sk_你的密钥"

GET/api/invoice/{id}公开，无需密钥

查单张账单的实时状态（付款页就是轮询它）。会顺带触发一次链上查账，返回最新状态、实收金额与交易哈希。只暴露公开信息，不含备注等私密字段。

curl https://pay.51kaifa.app/api/invoice/INV-MV3FLTT3FEDD

# 响应（节选）
{ "ok": true, "invoice": { "status": "paid", "paidAmount": 500.37, "txid": "ab12..." }, "payAddress": "TX..." }

DELETE/api/invoice/{id}需密钥

删除一张未到账的账单。已到账账单不可删除（保留凭证）。

POST/api/invoice/{id}/reopen需密钥

给已过期 / 已归档的账单延期（请求体 { "days": 30 }）。状态恢复为待付款、金额尾数自动重排，请把新付款链接重新发给客户。

POST/api/invoice/remind需密钥

给待付款 / 少付的账单发催付提醒：客户留了邮箱且平台邮件通道已开通时自动发中英双语邮件；响应同时返回现成催付文案（textCn / textEn），微信 / Telegram 手动发也行。每张单 24 小时限催一次。

curl -X POST https://pay.51kaifa.app/api/invoice/remind \
  -H "Authorization: Bearer sk_你的密钥" -H "Content-Type: application/json" \
  -d '{"id":"INV-MV3FLTT3FEDD"}'

POST/api/invoice/recur-stop需密钥

停止一张订阅账单（recur=monthly）的每月自动续开；已生成的账单不受影响。

04地址体检接口（公开）

GET/api/address-check?addr={地址}&chain={tron|bsc|base|auto}公开，无需密钥

合作前查对方钱包：OFAC 制裁名单、诈骗 / 洗钱风险标记、Tether 冻结名单、链上账户画像。返回 level（safe / caution / danger / unknown）、风险标记数组与结论摘要。结果仅供参考，不构成投资或法律建议。

curl "https://pay.51kaifa.app/api/address-check?addr=TYourAddress...&chain=tron&lang=zh"

05Webhook 到账回调

账单或会员支付成功后，平台向你在设置页填写的回调地址 POST 一条 JSON，你的系统可据此自动发货 / 开通权限 / 记账。

请求头带 X-51pay-Signature：sha256=HMAC-SHA256(签名密钥, 原始请求体)。签名密钥在设置页查看 / 重新生成。
你的服务必须返回 2xx 才算送达；否则自动重试 3 次（1 / 5 / 30 分钟后）。

// Node.js 验签示例（Express 需拿原始 body）
const crypto = require('crypto');
const sig = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== req.headers['x-51pay-signature']) return res.sendStatus(401);

// 回调体（账单到账，节选）
{ "event": "invoice.paid", "id": "INV-MV3FLTT3FEDD", "client": "Acme Ltd",
  "amountUsd": 500, "paidAmount": 500.37, "chain": "tron", "txid": "ab12..." }

06错误码

HTTP	含义	怎么处理
400	参数不完整 / 金额超范围	按响应里的 error 字段修正
401	未登录或密钥无效	检查 Authorization 头
403	权限不足（如非 Studio 调用密钥接口、免费版月度额度用完）	code=studio-only → 升级 Studio；code=limit → 升级 Pro
404	账单不存在	核对账单 ID
429	触发限流（如催付 24 小时内重复）	稍后再试

07在线试一试（Playground）

粘贴你的 API 密钥，点「测试连通性」直接调真实接口拉取你的账单统计；也可以选接口生成 curl 命令，复制到自己的终端跑。密钥只存在这个页面的内存里，不会上传保存。

你的 API 密钥

选个接口生成 curl 命令

参数（账单 ID / 地址，按需填）

接入遇到问题？写信到 brian@51kaifa.app，附上报错响应，我们会在 1-2 个工作日内回复。