# 租赁API下单与商户回调示例 ## 首页立即租赁 PROXY_ACCOUNT 的“我的套餐”点击立即租赁,填写资源接收地址、应用 API Key / Secret、租期(秒)、API对接基地址、可选回调地址、商户订单号。先获取预计费用,再点击确认费用并租赁。移除了该按钮对后台 `rent:order:create` 权限的依赖,实际下单仍由应用凭证验签和所属用户的套餐绑定、账户余额共同校验。 Secret只在弹窗内存中用于签名,关闭弹窗清除,不写浏览器缓存、不作为请求参数发送。浏览器签名使用Web Crypto,需要HTTPS页面或localhost。应用Secret只在签发时展示,遗失时请重新签发。不要填节点凭证。所填凭证决定实际应用和扣费用户;填写当前账户自己的应用凭证。 默认API基地址为当前前端配置的代理前缀,例如 `/prod-api`。远程对接填写 `https://rent.example.com`,不含 `/api/rental/v1/create`;远程服务需允许浏览器当前来源、POST和X-Rent-*请求头。反向代理应将前缀去除,使服务端看到原始 `/api/rental/v1/quote` 或 `/api/rental/v1/create` 路径。时钟需同步。 ## 报价与计费 `POST /api/rental/v1/quote` 和 `create` 都要求 `X-Rent-Key`、`X-Rent-Timestamp`(毫秒)、`X-Rent-Nonce`、`X-Rent-Signature`。HMAC协议保持不变:API域、POST、服务端实际路径、原始UTF-8请求体SHA256,按换行连接后HMAC-SHA256,小写十六进制。签名后不得重新序列化JSON。 示例请求体(两接口共用,create额外带expected_amount): ```json { "network": "NILE", "resource_type": "ENERGY", "duration_seconds": 7200, "receiver_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "merchant_order_no": "WEB_UNIQUE_ORDER_NO", "notify_url": "https://merchant.example.com/api/rental/v1/demo/callback/async" } ``` network和resource_type为报价与下单必填项,服务端按所属用户匹配分类套餐;禁止提交package_id。弹窗可切换网络、资源类型,切换后必须重新报价。 报价返回 `amount`(精确十进制字符串)、`currency=USDT`、`duration_seconds`、`network`、`resource_quantity`。确认下单传 `expected_amount`,服务端重新计算并比较,价格变更则拒绝。所有费用使用BigDecimal。 租期为套餐基础租期的1至720个整数倍,总售价、供应商毛收入同比例增加,资源数量同步按租期倍数增加。例如基础3600秒、售价3USDT,7200秒为6USDT。该规则同时作用于登录入口及外部API;不传租期继续使用基础租期,兼容现有调用。实际资源回收按订单租期快照执行。请求超时后使用相同商户单号及原参数重试;不要更换单号重复扣费。 回调地址只允许公网HTTPS、443端口、无查询参数,不允许内网或回环目标。留空沿用应用默认地址。订单创建成功是同步API响应,不代表链上已经交付;以查询API及已验签异步通知为准。当前协议没有浏览器return_url跳转回调。 ## 同步、异步验签Controller 实现:`RentalCallbackDemoController`,默认关闭,仅演示商户接收端。部署于同一云端项目中,或连同验签工具、事务仓储迁入商户项目。 先执行 `sql/rent_callback_demo.sql` 创建独立演示收件箱;租赁基础表(含rent_nonce)仍需先初始化。然后通过外部配置启用,凭证必须是该应用当前ACTIVE凭证: ```yaml rental: callback-demo: enabled: true api-key: ${RENT_DEMO_API_KEY:} api-secret: ${RENT_DEMO_API_SECRET:} ``` 接口使用既有 `/api/rental/v1/**` 公开入口,但每个请求都验证WEBHOOK域签名、Key、60秒时间窗、随机数和原始请求体;没有关闭认证。不要在日志输出Secret、签名或请求体。轮换应用凭证后同步更新接收端凭证;生产建议支持受控的多Key过渡。 | 接口 | 处理流程 | 成功确认 | | --- | --- | --- | | POST /api/rental/v1/demo/callback/sync | 验签→随机数防重放→event_no去重→同步事务记录处理结果 | 事务提交后返回HTTP 200、纯文本ok | | POST /api/rental/v1/demo/callback/async | 验签→随机数防重放→event_no去重→持久化待处理收件箱 | 持久化提交后返回HTTP 200、纯文本ok;每3秒扫描事务处理 | 无效签名返回400,持久化失败返回503,不返回ok。并发事件冲突会回滚并让云端用新随机数重投;重复事件内容一致则确认,内容冲突拒绝。同一HTTP报文重放不通过随机数唯一约束。异步处理不使用易丢失的内存队列,重启后扫描继续。 示例业务仅记录验签事件/消费标记,不执行真实商户履约或入账。接入实际业务时,应保存所需通知字段,在同一事务中按本地订单号及event_no更新业务,并利用order_event_sequence防止乱序状态回退;外部副作用使用事务发件箱。不要照搬演示标记替代实际业务处理。 租赁云端仅在回调HTTP 200且正文严格为`ok`时确认,失败按既有任务重试,达到上限保留DEAD记录供处理。应用当前有效凭证用于签名,WEBHOOK域与API域严格隔离。 ## 验证 JDK8下64项租赁测试通过,覆盖已签名报价/下单、报价不扣费、租期计费、冻结资金、幂等重试、价格变化拒绝,以及回调原文/路径/域/时间窗验签、落库确认、重复事件及异步消费。前端ESLint、Vue模板/CSS解析、独立HMAC及UTF8签名校验通过,staging完整构建成功;保留其他模块已有导出缺失和资源体积警告。实际浏览器、公网回调、数据库迁移及链上交付尚需部署后联调。