认证 - Waffo Pancake

认证概述

Waffo Pancake 支持两种 API 访问认证方式：

方式	使用场景	说明
API Key	服务端到服务端调用	使用 RSA-SHA256 签名的永久认证方式
Store Slug	公开收银台流程	使用 `X-Store-Slug` 和 `X-Environment` 请求头的公开访问方式

API Key 认证

API Key 提供基于 RSA-SHA256 签名的永久服务端到服务端认证。私钥始终保存在您的服务器上。

请求头

X-Merchant-Id: MER_2aUyqjCzEIiEcYMKj7TZtw
X-Timestamp: 1705312200
X-Signature: BASE64_ENCODED_SIGNATURE
Content-Type: application/json

API Key 认证不需要 X-Environment 请求头。 每个 API Key 在创建时已绑定到 test 或 prod 环境。系统通过验证签名成功的密钥来确定环境。

使用 SDK（推荐）

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

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

// All requests are automatically signed
const { store } = await client.stores.create({ name: "My Store" });

签名算法（手动集成）

如果您不使用 SDK，需要自行实现 RSA-SHA256 请求签名：

1. Build the canonical request:
   canonicalRequest = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + SHA256_BASE64(BODY)

2. Sign with RSA-SHA256:
   signature = RSA-SHA256(canonicalRequest, privateKey)

3. Base64 encode:
   X-Signature = Base64(signature)

手动签名示例

const crypto = require('crypto');

const MERCHANT_ID = 'MER_2aUyqjCzEIiEcYMKj7TZtw';
const PRIVATE_KEY = `-----BEGIN RSA PRIVATE KEY-----
...your private key...
-----END RSA PRIVATE KEY-----`;

async function callApiWithSignature(method, path, body) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const bodyStr = JSON.stringify(body);
  const bodyHash = crypto.createHash('sha256').update(bodyStr).digest('base64');

  // Build canonical request
  const canonicalRequest = `${method}\n${path}\n${timestamp}\n${bodyHash}`;

  // RSA-SHA256 sign
  const signature = crypto.sign('sha256', Buffer.from(canonicalRequest), PRIVATE_KEY).toString('base64');

  const response = await fetch(`https://api.waffo.ai${path}`, {
    method,
    headers: {
      'Content-Type': 'application/json',
      'X-Merchant-Id': MERCHANT_ID,
      'X-Timestamp': timestamp,
      'X-Signature': signature
    },
    body: bodyStr
  });

  return response.json();
}

// Usage
const result = await callApiWithSignature('POST', '/v1/actions/store/create-store', {
  name: 'My Store'
});

MERCHANT_ID="MER_2aUyqjCzEIiEcYMKj7TZtw"
TIMESTAMP=$(date +%s)
BODY='{"name":"My Store"}'
BODY_HASH=$(echo -n "$BODY" | openssl dgst -sha256 -binary | base64 | tr -d '\n')
CANONICAL_REQUEST="POST
/v1/actions/store/create-store
$TIMESTAMP
$BODY_HASH"

# Sign with openssl (requires private_key.pem file)
SIGNATURE=$(echo -n "$CANONICAL_REQUEST" | openssl dgst -sha256 -sign private_key.pem | base64 | tr -d '\n')

curl -X POST "https://api.waffo.ai/v1/actions/store/create-store" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: $MERCHANT_ID" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -d "$BODY"

import hashlib
import time
import base64
import json
import requests
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

MERCHANT_ID = 'MER_2aUyqjCzEIiEcYMKj7TZtw'
PRIVATE_KEY = '''-----BEGIN RSA PRIVATE KEY-----
...your private key...
-----END RSA PRIVATE KEY-----'''

def call_api_with_signature(method, path, body):
    timestamp = str(int(time.time()))
    body_str = json.dumps(body, separators=(',', ':'))
    body_hash = base64.b64encode(hashlib.sha256(body_str.encode()).digest()).decode()

    # Build canonical request
    canonical_request = f"{method}\n{path}\n{timestamp}\n{body_hash}"

    # RSA-SHA256 sign
    private_key = serialization.load_pem_private_key(PRIVATE_KEY.encode(), password=None)
    signature = private_key.sign(canonical_request.encode(), padding.PKCS1v15(), hashes.SHA256())
    signature_b64 = base64.b64encode(signature).decode()

    response = requests.post(
        f'https://api.waffo.ai{path}',
        headers={
            'Content-Type': 'application/json',
            'X-Merchant-Id': MERCHANT_ID,
            'X-Timestamp': timestamp,
            'X-Signature': signature_b64
        },
        data=body_str
    )

    return response.json()

# Usage
result = call_api_with_signature('POST', '/v1/actions/store/create-store', {
    'name': 'My Store'
})

私钥安全

切勿在客户端代码中暴露私钥
不要将私钥提交到版本控制系统
将私钥存储在环境变量中
定期轮换密钥，尤其是团队人员变动后
时间戳最多可比服务器时间早 5 分钟，最多可比服务器时间晚 1 分钟

保持服务器时钟与 NTP 同步时间戳的可接受窗口是不对称的：从服务器时间之前 5 分钟到服务器时间之后 1 分钟。时钟走快是更紧的约束 —— 如果您的服务器时钟快了超过 1 分钟，即使签名本身正确，每个已签名请求都会被拒绝并返回 401 Unauthorized。

Store Slug 认证

对于面向公众的收银台流程，使用 Store Slug 认证。这允许访客在无需 API Key 凭证的情况下创建收银台会话和查询公开的门店数据。

请求头

X-Store-Slug: my-awesome-store-k8x2m9ab
X-Environment: test | prod
Content-Type: application/json

示例

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "X-Store-Slug: my-awesome-store-k8x2m9ab" \
  -H "X-Environment: test" \
  -H "Content-Type: application/json" \
  -d '{"productId": "PROD_4cWAslE1GKkGeaOMl9Vbmy", "productType": "onetime", "currency": "USD"}'

const response = await fetch('https://api.waffo.ai/v1/graphql', {
  method: 'POST',
  headers: {
    'X-Store-Slug': 'my-awesome-store-k8x2m9ab',
    'Content-Type': 'application/json',
    'X-Environment': 'prod'
  },
  body: JSON.stringify({
    query: `query { store { id name onetimeProducts { id name prices } } }`
  })
});

创建 API Key

进入 API 与开发页面

导航至 Dashboard → API 与开发 → API Keys

创建 API Key

点击 “Create API Key” 生成新的 RSA 密钥对。公钥会自动发送到服务器。

命名和配置

为其设置一个描述性名称（例如 “Production Server”），并选择目标环境（Test 或 Production）。

下载私钥

立即下载您的私钥。 私钥不会再次显示。

删除 API Key 是即时且不可逆的操作。使用已删除密钥签名的所有请求都将返回 401 Unauthorized。

认证方式对比

功能	API Key	Store Slug
服务端使用	是	否
客户端使用	否	是
需要 X-Environment	否	是
签发 Session Token	是	否
创建 Checkout Session	是	是
商品管理	是	否
GraphQL 查询	是	是（仅公开数据）
有效期	永久（密钥控制）	-

认证错误

状态码	错误	解决方案
401	Invalid signature	检查签名算法、私钥和时间戳新鲜度（可接受窗口：服务器时间之前 5 分钟至之后 1 分钟）
401	Invalid or expired token	重新认证或使用有效的 API Key
403	Insufficient permissions	检查角色是否有权访问该端点
400	Missing authentication	确保所需的请求头已提供

{
  "data": null,
  "errors": [
    {
      "message": "Invalid signature",
      "layer": "gateway"
    }
  ]
}

安全最佳实践

切勿暴露私钥 — 不要放在客户端代码、版本控制或公开仓库中
使用 HTTPS 进行所有 API 请求
验证 Webhook 签名 以防止伪造请求
分离测试和生产密钥 — 为每个环境创建独立的密钥
定期轮换密钥，尤其是团队成员变动后
监控 API 使用情况 — 在 Dashboard 中查看异常活动

概览

认证

商户 API（API Key）

Customer Portal API（Session Token）

GraphQL

认证

认证概述

API Key 认证

请求头

使用 SDK（推荐）

签名算法（手动集成）

手动签名示例

Store Slug 认证

请求头

示例

创建 API Key

认证方式对比

认证错误

安全最佳实践

​认证概述

​API Key 认证

​请求头

​使用 SDK（推荐）

​签名算法（手动集成）

​手动签名示例

​Store Slug 认证

​请求头

​示例

​创建 API Key

​认证方式对比

​认证错误

​安全最佳实践

认证概述

API Key 认证

请求头

使用 SDK（推荐）

签名算法（手动集成）

手动签名示例

Store Slug 认证

请求头

示例

创建 API Key

认证方式对比

认证错误

安全最佳实践