Clawver Orders

核心用法

Clawver Orders 是面向 Clawver 电商平台卖家的订单管理工具，通过 RESTful API 提供完整的订单生命周期管理。核心功能包括：

• 订单查询：支持按状态筛选（pending/confirmed/processing/shipped/delivered/cancelled），支持分页
• 订单详情：获取完整订单信息，POD 商品包含 variantId 和 variantName
• 下载链接：为数字商品生成商家端和客户端下载链接
• 退款处理：支持全额/部分退款，金额以 cents 为单位，需指定原因
• 物流追踪：POD 订单发货后可通过 trackingUrl/trackingNumber/carrier 字段追踪
• Webhook 订阅：实时接收订单创建、支付、退款、发货等事件通知

API 认证方式

使用 Authorization: Bearer $CLAW_API_KEY Header 认证，需预先配置 CLAW_API_KEY 环境变量。

显著优点

1. 状态分离清晰：order status 与 paymentStatus 独立管理，退款流程灵活
2. POD 深度集成：专为 Print-on-Demand 设计，支持 variant 级别管理和物流追踪
3. Webhook 安全：提供 SHA-256 HMAC 签名验证机制，附 Node.js 验证示例
4. 场景化示例：包含日常订单检查、退款处理、尺码错误处理、下载链接重发等实用代码

潜在缺点与局限性

• 分页仅支持 limit 参数，无游标分页，大数据量场景效率受限
• 退款通过 Stripe 处理，到账需 1-5 个工作日，非即时到账
• 依赖外部支付状态（Stripe），退款金额不能超过剩余可退额度
• 数字商品下载令牌需额外获取（checkout receipt），非订单直接返回

适合人群

• Clawver 平台卖家及运营人员
• 需要自动化订单处理的技术团队
• 提供 POD 商品的客户支持团队

常规风险

• API Key 泄露风险：需妥善保管 CLAW_API_KEY，建议配置 IP 白名单
• 退款操作不可逆：需在调用前验证 paymentStatus
• Webhook 签名验证缺失可能导致伪造请求攻击
• 下载链接令牌有时效性，需及时使用或重新生成

核心用法

Clawver Orders 是一款面向电商卖家的订单管理技能，专为 Clawver 商店平台设计。该技能通过标准化的 REST API 接口，为商家提供完整的订单生命周期管理能力。核心功能包括：订单列表查询（支持按状态筛选）、订单详情获取、退款处理（全额/部分退款）、数字商品下载链接生成，以及 POD（按需印刷）订单的物流追踪。使用时需配置 CLAW_API_KEY 环境变量，所有 API 调用均采用 HTTPS 加密传输。

典型工作流

1. 日常订单巡查：获取 confirmed 状态订单，快速了解当日新单
2. 退款处理：验证订单支付状态后，执行全额或部分退款（1-5 工作日到账）
3. 客户支持：为数字商品生成新的下载链接，或查询 POD 订单物流信息
4. Webhook 集成：配置实时通知，自动响应订单创建、支付、发货等事件

显著优点

官方原生支持：所有 API 端点均为 Clawver 官方提供，数据权威可靠，接口稳定性有保障。

场景覆盖完整：从订单创建到交付的全链路支持，特别针对数字商品和 POD 商品的不同履约流程做了优化区分。

安全设计合理：采用 Bearer Token 认证，API Key 需显式配置，无硬编码风险；退款操作需二次确认支付状态，降低误操作风险。

Webhook 实时同步：支持订单事件实时推送，便于与内部 ERP、客服系统或物流系统对接，减少轮询成本。

潜在缺点与局限性

纯文档型技能：该 Skill 为 Markdown 参考文档，无内置可执行代码，实际调用需用户自行编写 HTTP 请求或使用外部工具（如 curl、Python requests）。

分页能力有限：订单列表仅支持 limit 参数，无游标分页，处理大量订单时效率受限。

退款不可逆：退款操作直接对接 Stripe，一旦执行无法撤销，且需 1-5 工作日到账，对即时退款场景不够友好。

POD 物流依赖第三方：物流追踪信息依赖 POD 供应商回传，可能存在更新延迟。

适合的目标群体

• Clawver 平台商家：需要批量管理订单、处理退款、追踪物流的店铺运营者
• 客服支持团队：需要快速查询订单状态、重发数字下载链接的一线客服人员
• 技术集成开发者：需要将 Clawver 订单数据同步至内部系统的技术团队
• 小型电商运营者：无复杂 ERP 系统，需要轻量级 API 工具管理订单履约的个人卖家

使用风险

API Key 泄露风险：CLAW_API_KEY 拥有订单查询和退款权限，若泄露可能导致订单数据暴露或恶意退款。建议存储于环境变量，定期轮换。

Webhook 安全风险：配置的 webhook URL 若指向不可信服务器，可能导致订单数据泄露。需验证签名并定期审查配置。

财务操作风险：退款功能涉及真实资金流转，建议在执行前建立人工审批流程，避免误操作。

依赖服务可用性：Clawver API 或 Stripe 服务中断将影响订单管理和退款处理。