名称： clawver-orders
描述： 管理 Clawver 订单。列出订单、跟踪状态、处理退款、生成下载链接。当用户询问客户订单、履约、退款或订单历史时使用。
版本： 1.3.0
主页： https://clawver.store
元数据： {"openclaw":{"emoji":"📦","homepage":"https://clawver.store","requires":{"env":["CLAW_API_KEY"]},"primaryEnv":"CLAW_API_KEY"}}

Clawver 订单管理

管理您的 Clawver 店铺订单——查看订单历史、跟踪履约状态、处理退款以及生成下载链接。

前置条件

• 设置 CLAW_API_KEY 环境变量
• 拥有已产生订单的活跃店铺

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

列出订单

获取所有订单

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

按状态筛选

# 已确认（已支付）订单
curl "https://api.clawver.store/v1/orders?status=confirmed" \
  -H "Authorization: Bearer $CLAW_API_KEY"

# 处理中的按需印刷订单
curl "https://api.clawver.store/v1/orders?status=processing" \
  -H "Authorization: Bearer $CLAW_API_KEY"

# 已发货订单
curl "https://api.clawver.store/v1/orders?status=shipped" \
  -H "Authorization: Bearer $CLAW_API_KEY"

# 已送达订单
curl "https://api.clawver.store/v1/orders?status=delivered" \
  -H "Authorization: Bearer $CLAW_API_KEY"

订单状态说明：

paymentStatus 单独报告，可能为 pending、paid、failed、partially_refunded 或 refunded。

分页

curl "https://api.clawver.store/v1/orders?limit=20" \
  -H "Authorization: Bearer $CLAW_API_KEY"

支持 limit 参数。此端点目前未提供基于游标的分页功能。

获取订单详情

curl https://api.clawver.store/v1/orders/{orderId} \
  -H "Authorization: Bearer $CLAW_API_KEY"

对于按需印刷商品，订单数据包含：
- variantId（必需——履约变体标识符，必须与商品变体匹配）
- variantName（人类可读的所选尺码/变体标签）

注意：自 2026 年 2 月起，所有按需印刷结账商品都必须提供 variantId。缺货的变体将被拒绝。

生成下载链接

所有者下载链接（数字商品）

curl "https://api.clawver.store/v1/orders/{orderId}/download/{itemId}" \
  -H "Authorization: Bearer $CLAW_API_KEY"

当客户报告下载问题或请求新链接时使用此接口。

客户下载链接（数字商品）

curl "https://api.clawver.store/v1/orders/{orderId}/download/{itemId}/public?token={downloadToken}"

下载令牌按订单商品发放，可在结账收据中获取（GET /v1/checkout/{checkoutId}/receipt）。

客户订单状态查询（公开）

curl "https://api.clawver.store/v1/orders/{orderId}/public?token={orderStatusToken}"

获取结账收据（成功页面/客服支持）

curl "https://api.clawver.store/v1/checkout/{checkoutId}/receipt"

处理退款

全额退款

curl -X POST https://api.clawver.store/v1/orders/{orderId}/refund \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 2499,
    "reason": "Customer requested refund"
  }'

部分退款

curl -X POST https://api.clawver.store/v1/orders/{orderId}/refund \
  -H "Authorization: Bearer $CLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountInCents": 500,
    "reason": "Partial refund for missing item"
  }'

注意事项：
- amountInCents 为必需参数，必须是正整数
- reason 为必需参数
- amountInCents 不能超过剩余可退款金额
- 退款通过 Stripe 处理（1-5 个工作日到达客户账户）
- 订单的 paymentStatus 必须为 paid 或 partially_refunded

按需印刷订单追踪

对于按需印刷订单，发货后可获取追踪信息：

curl https://api.clawver.store/v1/orders/{orderId} \
  -H "Authorization: Bearer $CLAW_API_KEY"

检查响应中的 trackingUrl、trackingNumber 和 carrier 字段。

发货状态更新 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/webhook",
    "events": ["order.shipped", "order.fulfilled"],
    "secret": "your-secret-min-16-chars"
  }'

订单 Webhooks

接收实时通知：

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/webhook",
    "events": ["order.created", "order.paid", "order.refunded"],
    "secret": "your-webhook-secret-16chars"
  }'

签名格式：

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)
  );
}

常见工作流

每日订单检查

# 获取新支付/确认的订单
response = api.get("/v1/orders?status=confirmed")
orders = response["data"]["orders"]
print(f"新订单数量: {len(orders)}")

for order in orders:
    print(f"  - {order['id']}: ${order['totalInCents']/100:.2f}")

处理退款请求

def process_refund(order_id, amount_cents, reason):
    # 获取订单详情
    response = api.get(f"/v1/orders/{order_id}")
    order = response["data"]["order"]

    # 检查是否可退款
    if order["paymentStatus"] not in ["paid", "partially_refunded"]:
        return "订单无法退款"

    # 处理退款
    result = api.post(f"/v1/orders/{order_id}/refund", {
        "amountInCents": amount_cents,
        "reason": reason
    })

    return f"已退款 ${amount_cents/100:.2f}"

尺码错误支持流程

def handle_wrong_size(order_id):
    response = api.get(f"/v1/orders/{order_id}")
    order = response["data"]["order"]

    for item in order["items"]:
        if item.get("productType") == "print_on_demand":
            print("变体 ID:", item.get("variantId"))
            print("变体名称:", item.get("variantName"))

    # 在发起退款/换货流程前，确认所选变体。

重新发送下载链接

def resend_download(order_id, item_id):
    # 生成新的下载链接
    response = api.get(f"/v1/orders/{order_id}/download/{item_id}")

    return response["data"]["downloadUrl"]

订单生命周期

pending → confirmed → processing → shipped → delivered
               ↓
      cancelled / refunded (paymentStatus)

数字商品： confirmed → delivered（即时履约）
按需印刷商品： confirmed → processing → shipped → delivered