GET /v2/token/generate 获取业务令牌的凭证。在每个请求的 X-BH-TOKEN 请求头中发送的是该令牌,而不是密钥。在获取令牌之前,VelaFi 必须为您的账户开通 API 访问权限,必须启用双重身份验证(2FA),并且密钥必须配置 IP 白名单。本指南将逐步引导您完成每个步骤。
前提条件
- 一个有效的 VelaFi 账户。如果您尚未注册,请参阅创建您的 VelaFi 账户。
- 至少已创建一个商户,并已完成 KYC/KYB 验证。请参阅创建并验证商户。
分步设置
1
申请 API 访问权限
API 访问权限默认未开通。请联系 VelaFi 团队为您的账户开通。发送邮件至 contact@velafi.com,或通过联系表单提交申请。请附上您的账户邮箱以及对预期集成的简要说明。VelaFi 会在您的账户开通 API 访问权限后进行确认。在此之前,令牌请求将失败并返回代码
-5033。2
启用双重身份验证(2FA)
如果尚未启用 2FA,平台会在您尝试创建 API 密钥时提示您启用。请在继续之前启用,以免中断。登录您的账户,进入安全设置以开启 2FA。
3
进入 API 管理
登录后,从控制台菜单中打开 API Management,或访问 velafi.com/security/interface。您可以在此创建、查看和管理所有 API 密钥及 IP 白名单。
4
创建您的 API 密钥
在 API 管理页面点击 Create API Key 按钮。在 Notes 字段中输入 1–30 个字符的描述性标签——例如
Production Integration。该字段为必填项。此标签可帮助您日后识别该密钥的用途。点击 Continue,然后输入您的 2FA 验证码进行确认。API Key Created 窗口会显示您的 Api Key 和 Api Secret。5
复制并存储您的 API 密钥和密钥密文
请立即复制这两个值,并将其存储在安全的位置。请遵循以下存储最佳实践:
- 不要将 API 密钥存储在明文文件、版本控制系统或任何公开位置。
- 要使用密码管理器或密钥管理工具(例如 AWS Secrets Manager、HashiCorp Vault 或 1Password)安全地存储密钥。
- 不要通过 Slack、电子邮件或其他消息平台分享您的 API 密钥。
6
配置 IP 白名单
为密钥添加 IP 白名单。此步骤为必需步骤:没有白名单的密钥无法获取令牌(代码
-1023)。在 API 管理页面,选择该密钥上的 Whitelist,输入将调用 API 的服务器的公网 IP 地址,并使用您的 2FA 验证码确认。每个密钥最多可添加 5 个 IPv4 或 IPv6 地址。请逐个输入地址;不接受 CIDR 范围。来自任何其他 IP 地址的请求都会被拒绝,即使使用有效的 API 密钥或令牌也是如此。白名单可确保即使密钥泄露,攻击者也无法从未知位置使用该密钥。使用您的 API 密钥
您的服务器使用 API 密钥和密钥密文获取令牌,然后在X-BH-TOKEN 请求头中发送该令牌:
- 构造字符串
timestamp=<ms>,其中<ms>为当前的 Unix 时间(毫秒)。以您的 API 密钥密文作为密钥计算其 HMAC-SHA256,并将结果编码为小写十六进制。 - 在
X-BH-APIKEY请求头中携带您的 API 密钥,调用GET /v2/token/generate?timestamp=<ms>&signature=<signature>。 - 在每个请求的
X-BH-TOKEN请求头中发送返回的token。请在expireTime之前申请新令牌。
Content-Type: application/json。
示例:获取令牌并调用 API
以下示例获取令牌并使用它查询您的账户详情。生产环境与沙盒环境
请为每个环境使用单独的 API 密钥。切勿在测试环境中使用生产密钥,反之亦然。沙盒环境密钥和生产环境密钥是不同的凭证。准备正式上线时,请在生产账户设置中生成新的 API 密钥,并相应地更新集成配置。

