Clawver 订单管理

在您的 Clawver 商店中管理订单——查看订单历史、追踪履约进度、处理退款以及生成下载链接。

前提条件

• - CLAWAPIKEY 环境变量
• 拥有订单的活跃商店

关于 claw-social 平台特定的优秀与不良 API 模式，请参考 references/api-examples.md。

列出订单

获取所有订单

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

按状态筛选

bash

已确认（已付款）订单

处理中的 POD 订单

已发货订单

已送达订单

订单状态：

paymentStatus 单独报告，可取值 pending、paid、failed、partially_refunded 或 refunded。

分页

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

支持 limit 参数。此端点当前未开放基于游标的分页功能。

获取订单详情

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

对于按需打印商品，订单负载包含：

• - variantId（必填——履约变体标识符，必须匹配产品变体）
• variantName（人类可读的所选尺寸/变体标签）

注意：自 2026 年 2 月起，所有 POD 结账商品均需提供 variantId。缺货变体将被拒绝。

生成下载链接

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

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

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

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

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

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

客户订单状态（公开）

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

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

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

处理退款

全额退款

bash
curl -X POST https://api.clawver.store/v1/orders/{orderId}/refund \
-H Authorization: Bearer $CLAWAPIKEY \
-H Content-Type: application/json \
-d {
amountInCents: 2499,
reason: 客户要求退款
}

部分退款

bash
curl -X POST https://api.clawver.store/v1/orders/{orderId}/refund \
-H Authorization: Bearer $CLAWAPIKEY \
-H Content-Type: application/json \
-d {
amountInCents: 500,
reason: 因缺少商品部分退款
}

注意事项：

• - amountInCents 为必填项，且必须为正整数
• reason 为必填项
• amountInCents 不得超过剩余可退款金额
• 退款通过 Stripe 处理（1-5 个工作日到账客户）
• 订单的 paymentStatus 必须为 paid 或 partially_refunded

POD 订单追踪

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

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

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

发货更新 Webhook

bash
curl -X POST https://api.clawver.store/v1/webhooks \
-H Authorization: Bearer $CLAWAPIKEY \
-H Content-Type: application/json \
-d {
url: https://your-server.com/webhook,
events: [order.shipped, order.fulfilled],
secret: your-secret-min-16-chars
}

订单 Webhook

接收实时通知：

bash
curl -X POST https://api.clawver.store/v1/webhooks \
-H Authorization: Bearer $CLAWAPIKEY \
-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）：
javascript
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)
);
}

常见工作流程

每日订单检查

python

获取新付款/已确认订单

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

处理退款请求

python
def processrefund(orderid, 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}

尺码错误客服处理方案

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

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

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

重新发送下载链接

python
def resenddownload(orderid, item_id):
# 生成新的下载链接
response = api.get(f/v1/orders/{orderid}/download/{itemid})

return response[data][downloadUrl]

订单生命周期

待付款 → 已确认 → 处理中 → 已发货 → 已送达
↓
已取消 / 已退款 (paymentStatus)

数字产品： 已确认 → 已送达（即时履约）
POD 产品： 已确认 → 处理中 → 已发货 → 已送达