身份认证概览 (Authentication)

1. 获取您的 API 凭证

在开始集成前，您需要准备好以下两项核心参数。这两项参数在业务语境中分别对应 appid 和 secret 字段：

• API Key (appid): 您的商户唯一识别码。
• API Secret (secret): 用于身份验证的机密密钥，切勿泄露。

📥

如何获取凭证？

1. 邮件通知：在您的 API 权限开通后，系统会自动向您的注册邮箱发送包含 API Key 和 API Secret 的正式邮件。
2. 商户后台：您可以随时登录 [DogPay 商户管理后台] -> [API 管理] 页面查看当前的 API Key。出于安全考虑，API Secret 支持在此界面进行手动重置。

2. 生成访问令牌 (Access Token)

通过调用认证接口，将您的凭证兑换为 access_token。

• 接口地址: POST /open-api/v1/auth/access_token
• 授权类型: grant_type 必须设置为 client_credential

# 示例请求
curl -X POST "[https://prod.wavepool.global/open-api/v1/auth/access_token](https://prod.wavepool.global/open-api/v1/auth/access_token)" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "client_credential",
           "appid": "您的_API_Key",
           "secret": "您的_API_Secret"
         }'

3. 使用令牌进行请求

获取令牌后，请将其置于所有后续 HTTP 请求的 Authorization 头部：

⏳ 令牌生命周期管理

理解令牌的有效期对于构建稳定的系统至关重要：

有效期限制

• 有效期：令牌自颁发之日起 2 小时 (7200 秒) 内有效。
• 刷新机制：本 API 不提供 刷新令牌（Refresh Token）。当令牌过期后，您只需重复上述步骤获取新令牌即可。

💡

开发者最佳实践

• 令牌缓存：请在您的服务器端缓存令牌，避免在每次调用 API 前都请求新令牌，否则可能会触发频率限制（Rate Limiting）。
• 预触发更新：建议在令牌到期前 5–10 分钟 提前获取新令牌，以确保业务的无缝衔接。
• 异常处理：若接口返回 401 Unauthorized 错误，说明令牌已失效，请立即触发重新获取令牌的逻辑。

⚠️ 安全注意事项

• 禁止前端调用：严禁在移动端应用、浏览器插件或任何前端代码中硬编码 API Secret。令牌交换逻辑必须在您的后端服务器完成。
• 环境隔离：请确保测试环境与生产环境使用对应的 API Key，避免数据污染。