跳转到主要内容

​
认证概述

Waffo Pancake 支持两种 API 访问认证方式：
方式使用场景说明
API Key服务器间通信使用 Merchant ID 和私钥的永久认证
Store Slug公开结账流程通过 X-Store-Slug 和 X-Environment 请求头进行公开访问

​
API Key 认证

API Key 提供永久的服务器间认证。私钥永远不会离开您的服务器。
API Key 认证由 SDK 自动处理。安装 @waffo/pancake-ts 后，只需提供 Merchant ID 和私钥，SDK 会自动完成请求签名。

​
使用 SDK（推荐）

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

// 所有请求自动完成认证
const { store } = await client.stores.create({ name: "My Store" });
API Key 认证不需要 X-Environment 请求头。环境由密钥注册时选择的环境（test 或 prod）决定。

​
创建 API Key

1

进入开发者页面

导航到控制台 —> 开发者 —> API 密钥
2

创建 API 密钥

点击”创建 API 密钥”生成新的密钥对。公钥会自动发送到服务器。
3

命名和配置

给密钥一个描述性名称（如”生产服务器”），并选择目标环境（测试或生产）。
4

下载私钥

立即下载您的私钥。之后不会再显示。
删除 API Key 是即时且不可逆的。使用已删除密钥的请求将返回 401 Unauthorized。

​
安全最佳实践

  • 切勿暴露私钥 — 不要放在客户端代码、版本控制或公共仓库中
  • 使用环境变量 在服务器应用中存储密钥
  • 分离测试和生产密钥 — 为每个环境创建不同的密钥
  • 定期轮换密钥，特别是在团队变动后
  • 监控 API 使用 在控制台中查看异常活动
# 将密钥存储为环境变量
export WAFFO_PRIVATE_KEY="your-private-key-content"
export WAFFO_MERCHANT_ID="your-merchant-uuid"

​
认证错误

状态码消息解决方案
401API Key 无效验证 Merchant ID 和私钥是否正确
401缺少认证信息确保 SDK 已使用有效凭据初始化
403权限不足使用具有所需权限的密钥