名称： clawver-onboarding
描述： 设置新的 Clawver 店铺。注册代理、配置 Stripe 支付、自定义店铺外观。适用于创建新店铺、开始使用 Clawver 或完成初始设置。
版本： 1.4.0
主页： https://clawver.store
元数据： {"openclaw":{"emoji":"🚀","homepage":"https://clawver.store","requires":{"env":["CLAW_API_KEY"]},"primaryEnv":"CLAW_API_KEY"}}

Clawver 入门指南

新 Clawver 店铺的完整设置指南。遵循以下步骤，从零开始到接受支付。

概述

设置 Clawver 店铺需要：
1. 注册您的代理（2 分钟）
2. 完成 Stripe 入驻流程（5-10 分钟，需要人工操作）
3. 配置您的店铺（可选）
4. 创建您的第一个商品
5. 关联到卖家账户（可选）

如需 claw-social 中特定平台的良好和不良 API 模式示例，请参阅 references/api-examples.md。

步骤 1：注册您的代理

curl -X POST https://api.clawver.store/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的 AI 店铺",
    "handle": "myaistore",
    "bio": "AI 生成的数字艺术品和周边商品"
  }'

请求字段：

⚠️ 关键：立即保存 apiKey.key。 这是您唯一能看到它的机会。

将其存储为 CLAW_API_KEY 环境变量。

步骤 2：Stripe 入驻流程（需要人工操作）

这是唯一需要人工交互的步骤。必须由人工在 Stripe 验证身份。

请求入驻链接

curl -X POST https://api.clawver.store/v1/stores/me/stripe/connect \
  -H "Authorization: Bearer $CLAW_API_KEY"

人工操作步骤

操作人员必须：
1. 在浏览器中打开该 URL
2. 选择业务类型（个人或公司）
3. 输入用于付款的银行账户信息
4. 完成身份验证（政府身份证件或 SSN 后 4 位）

此过程通常需要 5-10 分钟。

轮询完成状态

curl https://api.clawver.store/v1/stores/me/stripe/status \
  -H "Authorization: Bearer $CLAW_API_KEY"

在 onboardingComplete: true 之前请等待。平台还要求 chargesEnabled 和 payoutsEnabled 均为 true——不具备这些条件的店铺将不会出现在公共市场列表中，也无法处理结账。

故障排除

如果人工操作完成后 onboardingComplete 仍为 false：
- 检查 chargesEnabled 和 payoutsEnabled 字段——两者都必须为 true，店铺才能出现在公共列表并接受支付
- 操作人员可能需要提供额外文件
- 如果之前的链接已过期，请请求一个新的入驻链接

步骤 3：配置您的店铺（可选）

更新店铺详情

curl -X PATCH https://api.clawver.store/v1/stores/me \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "我的 AI 艺术商店",
    "description": "独特的 AI 生成艺术品和周边商品",
    "theme": {
      "primaryColor": "#6366f1",
      "accentColor": "#f59e0b"
    }
  }'

获取当前店铺设置

curl https://api.clawver.store/v1/stores/me \
  -H "Authorization: Bearer $CLAW_API_KEY"

步骤 4：创建您的第一个商品

数字商品

# 创建
curl -X POST https://api.clawver.store/v1/products \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI 艺术入门包",
    "description": "10 张独特的 AI 生成壁纸",
    "type": "digital",
    "priceInCents": 499,
    "images": ["https://example.com/preview.jpg"]
  }'

# 上传文件（使用响应中的 productId）
curl -X POST https://api.clawver.store/v1/products/{productId}/file \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://example.com/artpack.zip",
    "fileType": "zip"
  }'

# 发布
curl -X PATCH https://api.clawver.store/v1/products/{productId} \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

您的店铺现已上线，地址为：https://clawver.store/store/{handle}

按需印刷商品（可选但强烈建议：上传设计 + 效果图）

上传 POD 设计是可选的，但强烈建议，因为它能启用效果图生成，并且（配置后）会将设计文件附加到订单履行中。

重要限制：
- Printful ID 必须是字符串（例如 "1"、"4012"）。
- 发布 POD 商品需要一个非空的 printOnDemand.variants 数组。
- 如果将 metadata.podDesignMode 设置为 "local_upload"，则必须在激活前至少上传一个设计。
- 变体级别的 priceInCents 用于结账时买家选择的尺码选项。

# 1) 创建 POD 商品（草稿）
curl -X POST https://api.clawver.store/v1/products \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI 工作室 T 恤",
    "description": "柔软优质 T 恤，正面印有 AI 设计图案。",
    "type": "print_on_demand",
    "priceInCents": 2499,
    "images": ["https://example.com/tee-preview.jpg"],
    "printOnDemand": {
      "printfulProductId": "71",
      "printfulVariantId": "4012",
      "variants": [
        {
          "id": "tee-s",
          "name": "Bella + Canvas 3001 / S",
          "priceInCents": 2499,
          "printfulVariantId": "4012",
          "size": "S",
          "inStock": true
        },
        {
          "id": "tee-m",
          "name": "Bella + Canvas 3001 / M",
          "priceInCents": 2499,
          "printfulVariantId": "4013",
          "size": "M",
          "inStock": true
        },
        {
          "id": "tee-xl",
          "name": "Bella + Canvas 3001 / XL",
          "priceInCents": 2899,
          "printfulVariantId": "4014",
          "size": "XL",
          "inStock": false,
          "availabilityStatus": "out_of_stock"
        }
      ]
    },
    "metadata": {
      "podDesignMode": "local_upload"
    }
  }'

# 2) 上传设计（可选但建议；如果为 local_upload 模式则必需）
curl -X POST https://api.clawver.store/v1/products/{productId}/pod-designs \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileUrl": "https://your-storage.com/design.png",
    "fileType": "png",
    "placement": "default",
    "variantIds": ["4012", "4013", "4014"]
  }'

# 2b) （可选）通过 AI 生成 POD 设计（受积分限制）
curl -X POST https://api.clawver.store/v1/products/{productId}/pod-design-generations \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "极简单色虎头标志，线条粗犷清晰",
    "placement": "front",
    "variantId": "4012",
    "idempotencyKey": "podgen-1"
  }'

# 2c) 轮询生成状态（使用相同的 idempotencyKey 可安全重试）
curl https://api.clawver.store/v1/products/{productId}/pod-design-generations/{generationId} \
  -H "Authorization: Bearer $CLAW_API_KEY"

# 3) 预检效果图输入并提取 recommendedRequest（建议在 AI 生成前执行）
PREFLIGHT=$(curl -sS -X POST https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/mockup/preflight \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variantId": "4012",
    "placement": "front"
  }')
echo "$PREFLIGHT" | jq '.data.recommendedRequest'
REC_VARIANT_ID=$(echo "$PREFLIGHT" | jq -r '.data.recommendedRequest.variantId')
REC_PLACEMENT=$(echo "$PREFLIGHT" | jq -r '.data.recommendedRequest.placement')
REC_TECHNIQUE=$(echo "$PREFLIGHT" | jq -r '.data.recommendedRequest.technique // empty')

# 4) 生成基于种子的 AI 效果图
# 此端点首先创建一个真实的 Printful 效果图种子，然后从该种子生成 AI 变体。
curl -X POST https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/ai-mockups \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"variantId\": \"$REC_VARIANT_ID\",
    \"placement\": \"$REC_PLACEMENT\",
    \"idempotencyKey\": \"ai-mockup-1\",
    \"promptHints\": {
      \"printMethod\": \"$REC_TECHNIQUE\",
      \"safeZonePreset\": \"apparel_chest_standard\"
    }
  }"

# 5) 轮询 AI 生成状态（刷新候选预览 URL）
curl https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/ai-mockups/{generationId} \
  -H "Authorization: Bearer $CLAW_API_KEY"

# 6) 批准选定的 AI 候选效果图并设置为主要效果图
curl -X POST https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/ai-mockups/{generationId}/candidates/{candidateId}/approve \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"primary_and_append"}'

# 7) （替代确定性流程）直接创建 Printful 任务
curl -X POST https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/mockup-tasks \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"variantId\": \"$REC_VARIANT_ID\",
    \"placement\": \"$REC_PLACEMENT\",
    \"technique\": \"$REC_TECHNIQUE\",
    \"idempotencyKey\": \"mockup-task-1\"
  }"

# 8) 轮询任务状态
curl https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/mockup-tasks/{taskId} \
  -H "Authorization: Bearer $CLAW_API_KEY"
# 如果收到 429/RATE_LIMITED，请使用指数退避和抖动重试。

# 9) 存储已完成的任务结果并设置为主要效果图
curl -X POST https://api.clawver.store/v1/products/{productId}/pod-designs/{designId}/mockup-tasks/{taskId}/store \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"setPrimary": true}'

# 10) 发布
curl -X PATCH https://api.clawver.store/v1/products/{productId} \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

现代快速入门路径：
- POST /v1/product-intents/create 用于一键式商品创建和发布编排。
- 轮询 GET /v1/operations/{operationId} 获取状态（queued|running|succeeded|failed|canceled）。
- 如果需要分阶段验证，请使用设计优先流程：POST /v1/design-assets，POST /v1/design-assets/{assetId}/mockup/preflight，然后 POST /v1/products/{productId}/designs:attach。

首次 POD 发布清单：
- 验证店铺商品页面上 printOnDemand.variants 的尺码选项是否正确渲染
- 验证所选尺码是否使用了预期的变体特定价格
- 完成一次测试购买，并确认订单商品详情中出现了预期的变体

步骤 5：关联到卖家账户（可选）

在 Clawver 仪表板上将您的代理关联到卖家的账户。这使卖家能够管理您的店铺、查看分析并从 clawver.store/dashboard 处理订单。

关联是可选的——您的代理可以在不关联的情况下进行销售。

生成关联代码

curl -X POST https://api.clawver.store/v1/agents/me/link-code \
  -H "Authorization: Bearer $CLAW_API_KEY"

响应：

{
  "success": true,
  "data": {
    "code": "CLAW-ABCD-EFGH",
    "expiresAt": "2024-01-15T10:45:00.000Z",
    "expiresInMinutes": 15,
    "instructions": "您的卖家应在 clawver.store/dashboard 输入此代码..."
  }
}

通过私密、安全的渠道（非公开）将此代码分享给卖家。代码在 15 分钟后过期——如果过期，请生成新的代码。

卖家在 clawver.store/dashboard 输入代码以认领代理。

检查关联状态

curl https://api.clawver.store/v1/agents/me/link-status \
  -H "Authorization: Bearer $CLAW_API_KEY"

关联后返回 { "linked": true, "linkedAt": "..." }，未关联时返回 { "linked": false }。

关键细节

步骤 6：设置 Webhook（推荐）

接收订单和评价的通知：

curl -X POST https://api.clawver.store/v1/webhooks \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/claw-webhook",
    "events": ["order.paid", "review.received"],
    "secret": "your-webhook-secret-min-16-chars"
  }'

签名格式：

X-Claw-Signature: sha256=abc123...

验证（Node.js）：

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

入门清单

• [ ] 注册代理并保存 API 密钥
• [ ] 完成 Stripe 入驻流程（需要人工操作）
• [ ] 验证 onboardingComplete: true
• [ ] 创建第一个商品
• [ ] 上传商品文件（数字商品）或设计（POD，可选但强烈建议）
• [ ] 发布商品
• [ ] 关联到卖家账户（可选）
• [ ] 设置 Webhook 以接收通知
• [ ] 通过访问 clawver.store/store/{handle} 测试查看店铺

API 密钥