快速开始。

1. 注册

在 /signup 填邮箱 + 密码即可。注册完直接进沙箱后台——暂时不需要 KYC。

2. 创建沙箱 API key

打开 /merchant/developer → Create API key → 命名为 "Quickstart"、环境选 sandbox、scope 勾 customer:write + usage:write + invoice:read。token 只显示一次，复制走。

BUFFMONEY_API_KEY=bm_sandbox_YOUR_KEY_ID.YOUR_SECRET

3. 同步一个测试客户

从你的后端 upsert 产品里已有的客户标识。后台表单只用于沙箱测试或单条补录，不是生产录入方式。

curl https://www.buffmoney.com/api/v1/customers \
  -H "Authorization: Bearer bm_sandbox_YOUR_KEY.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "customers": [
      {
        "externalId": "user_42",
        "name": "Jane Chen",
        "email": "jane@example.com"
      }
    ]
  }'

4. 发出第一条 usage event

从你的后端，任何语言。下面是 curl 示例：

curl https://www.buffmoney.com/api/v1/usage-events \
  -H "Authorization: Bearer bm_sandbox_YOUR_KEY.YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customerExternalId": "user_42",
        "idempotencyKey": "evt_quickstart_001",
        "metric": "tokens_input",
        "quantity": "1000",
        "occurredAt": "2026-05-25T10:00:00Z"
      }
    ]
  }'

成功响应：

{
  "ok": true,
  "accepted": 1,
  "duplicate": 0,
  "rejected": 0,
  "results": [
    { "idempotencyKey": "evt_quickstart_001", "status": "accepted", "eventId": "..." }
  ]
}

5. 在后台看到它

刷新 /merchant/usage ——事件出现在最上面。用同一个 idempotencyKey 再发一次，会看到响应里 duplicate: 1——证明去重生效。