归集开放平台

示例与 OpenAPI ​

示例中的 appID、密钥、地址和交易数据均为演示值。接口调用和回调接收程序在你的服务端运行。

OpenAPI 接口定义 ​

下载 OpenAPI 3.1 JSON

可以导入 Apifox、Postman 或支持 OpenAPI 的工具查看全部路径、请求头、参数和响应结构。接口定义只包含相对路径，导入后将 API 基础地址设置为平台提供的域名，不要使用文档站域名。

导入接口定义不会自动生成签名。 每次发送前仍需按请求签名计算 X-Sign。尤其是 POST 请求，参与签名的 JSON 字节必须与实际发送的字节完全一致。可以直接使用下方客户端完成序列化、签名和发送。

客户端示例 ​

文件运行环境内容
client.mjsNode.js 22.12.0Query 规范化、HMAC-SHA256 签名、获取令牌、业务调用、错误处理
client.pyPython 3.9+与 Node.js 相同的接口调用流程，仅使用标准库

设置环境变量后运行「获取令牌 → 查询钱包」：

bash
# 先在运行环境中设置 GUIJI_BASE_URL，值为平台提供的 API 域名（不含 /open/v1）。
: "${GUIJI_BASE_URL:?请先设置平台提供的 API 域名}"
export GUIJI_APP_ID='YOUR_APP_ID'
export GUIJI_APP_SECRET='YOUR_APP_SECRET'
bash
node client.mjs wallets
bash
python3 client.py wallets

运行此演示会获取新令牌，使该租户的旧令牌失效。正式接入应集中缓存当前令牌，业务调用通过客户端的 call 方法复用。创建钱包和归集任务的用法见快速开始及各接口示例。

回调接收示例 ​

文件运行环境内容
webhook.mjsNode.js 22.12.0HKDF 派生、AES-GCM 验证解密、SQLite 事务与事件去重、HTTP 应答
webhook.pyPython 3.9+同等功能的 Python 接收服务
requirements.txtPython固定版本的 cryptography 依赖

接收示例监听 127.0.0.1；请通过你自己的 HTTPS 服务将公网 /guiji/webhook 转发到它。在平台回调配置中保存实际公网 HTTPS 地址。

bash
export GUIJI_APP_ID='YOUR_APP_ID'
export GUIJI_APP_SECRET='YOUR_APP_SECRET'
export GUIJI_WEBHOOK_DB='/absolute/path/guiji-events.sqlite'
export GUIJI_WEBHOOK_PORT='8080'
# GUIJI_NETWORK 按平台提供的资产网络设置为 main 或 nile。
: "${GUIJI_NETWORK:?请先设置约定的资产网络}"
bash
# Node.js 22.12.0 的内置 SQLite 需要此启动参数。
node --experimental-sqlite webhook.mjs
bash
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python webhook.py

接收程序将到账或任务结果及事件 ID 在同一 SQLite 事务中保存，成功提交后才返回 {"code":"SUCCESS"}。对接你的数据库时，应将示例中的业务写入替换成你自己的业务事务，并保留事件 ID 的唯一约束。

完整字段、加密步骤和重试规则见接收与解密回调。

签名与解密测试数据 ​

Test vectors JSON 包含演示凭据、GET 编码、原始 POST 正文、期望 HMAC-SHA256 签名及可解密的完整回调密文。时间戳是固定值，仅用于离线校验，不可直接发往在线接口。

将下面的测试脚本、对应语言的客户端、回调接收程序和 test-vectors.json 放在同一个目录中：

bash
node --experimental-sqlite test_vectors.mjs
bash
.venv/bin/python test_vectors.py

测试涵盖签名结果、Query 编码、原始 JSON 字节、GCM 认证、篡改拒绝、接收服务重启后的事件去重和业务写入失败时的事务回滚。

运行回调示例前，将 GUIJI_NETWORK 设置为平台为你开通的资产网络（main 或 nile）。示例解密后核对 network，避免把不同网络的资产记入同一账户。该变量只用于你本地的回调校验，不是 API 请求参数。