# Shopify 管理 GraphQL 与 Shopify 的 GraphQL 管理 API 交互的综合技能。这项技能使 Claude 能够查询和管理 Shopify 商店数据的各个方面，包括产品、订单、客户、库存、营销、折扣、翻译、履行等。 ## 先决条件 * 具有管理 API 访问权限的 Shopify 商店 * 具有适当范围的管理 API 访问令牌 * 配置环境变量： * `SHOPIFY_STORE_URL` \- 您的商店 URL（例如，`my-store.myshopify.com`） * `SHOPIFY_ACCESS_TOKEN` \- 管理 API 访问令牌 ## 快速入门 ### 基本产品查询查询{ 产品（第一：10）{ 节点{ 编号标题状态 } } } ### 创建产品突变 CreateProduct($product: ProductCreateInput!) { 产品创建（产品：$产品）{ 产品{ 编号标题 } 用户错误{ 领域留言 } } } 变量： { “产品”：{ "title": "新产品", “状态”：“草案” } } ## 说明使用 Shopify GraphQL 时： 1. **始终使用`shopify_graphql`工具**来执行查询和突变 2. **检查响应中的错误**： * `errors` 数组表示 GraphQL/语法问题 * 突变中的“userErrors”表示验证/业务逻辑问题 3. **对带有 `first`/`after` 游标的大型结果集使用分页** 4. **正确设置 ID 格式** \- 所有 Shopify ID 都是全局的：`gid://shopify/Resource/123` ## 关键操作和权限重要提示：在执行以下任何操作之前，您必须请求明确的用户许可。这些操作是不可逆转的或具有重大业务影响。 ### 立即危险操作 * 退款：创建退款（永久财务交易，无法撤消） * Order Cancellations：取消订单（可能会触发自动退款） * 礼品卡停用：永久禁用礼品卡（不可逆转） * 礼品卡余额变更：信用卡或借记卡礼品卡余额（影响客户资金） * 库存调整：修改库存水平（影响产品可用性） ### 状态改变操作 * 激活/停用折扣：更改折扣状态（立即影响客户定价） * 产品状态更改：发布产品（使客户可见） * 完成草稿订单：将草稿订单转换为真实订单（提交交易） * 履行创建：创建履行（触发向客户发送发货通知） * 取消履行：取消履行（可能会让客户感到困惑） * 保留/释放履行订单：暂停或恢复订单处理 ### 删除操作 * 删除产品/变体：永久删除（无法恢复） * 删除折扣：永久删除（客户不能再使用代码） * 删除草稿订单：永久删除 * 删除 Webhooks：停止事件通知（可能会破坏集成） * 批量删除操作：一次删除多个项目（高影响力） ### 权限协议当克劳德遇到任何关键操作时： 1. 描述操作及其具体影响 2. 显示将更改/删除的内容（ID、名称、值） 3. 等待用户明确确认后再继续 4. 仅在收到“是”、“确认”、“继续”或同等肯定答复后才继续 5. 即使用户的请求看起来很明确，也不要假设获得许可示例：警告：这将永久停用礼品卡 gid://shopify/GiftCard/123 余额为 50.00 美元。此操作无法撤消。您想继续吗？（是/否） ## 能力此技能为所有主要 Shopify 域提供了全面的模式： ### 核心商务域名 |运营|文件 ---|---|--- **产品** |列出、获取、搜索、创建、更新、删除产品和变型 | [products.md]() **订单** |列出、获取详细信息、履行、取消订单 | [orders.md]() **客户** |列出、获取、创建、更新客户 | [customers.md]() **库存** |检查水平、调整数量、管理位置 | [inventory.md]() **收藏** |列出产品系列，管理产品系列中的产品 | [collections.md]() ### 营销与促销域名 |运营|文件 ---|---|--- **折扣** |代码/自动折扣，BXGY，免费送货| [discounts.md]() **营销** |营销活动、事件、同意| [marketing.md]() **细分** |目标客户群 | [segments.md]() ### 国际域名 |运营|文件 ---|---|--- **翻译** |翻译产品、页面、内容 | [translations.md]() **市场** |多市场设置、本地化内容 | [markets.md]() ### 内容和店面域名 |运营|文件 ---|---|--- **页面** |创建/更新商店页面 | [pages.md]() **博客** |博客和文章 | [blogs.md]() **菜单** |导航菜单| [menus.md]() **文件** |文件上传、媒体库 | [files.md]() **元字段** |自定义数据、元对象 | [metafields.md]() ### 履行和运输域名 |运营|文件 ---|---|--- **履行** |创建履行、跟踪 | [fulfillments.md]() **运输** |交付概况、区域、费率 | [shipping.md]() **地点** |管理库存地点 | [locations.md]() ### 金融域名 |运营|文件 ---|---|--- **订单草案** |代表客户创建订单 | [draft-orders.md]() **退款** |处理退款、补货 | [refunds.md]() **礼品卡** |创建信用卡、借记卡礼品卡 | [gift-cards.md]() **订阅** |订阅合同、计费 | [subscriptions.md]() ### 店铺管理域名 |运营|文件 ---|---|--- **商店** |商店信息、设置、ShopifyQL | [shop.md]() **网络钩子** |活动订阅 | [webhooks.md]() **批量操作** |大型异步查询/突变 | [bulk-operations.md]() ## 常见模式 ### ID 格式所有 Shopify GraphQL ID 都是全球唯一的： gid://shopify/产品/123 gid://shopify/订单/456 gid://shopify/客户/789 ### 分页对大型数据集使用基于游标的分页：查询($first: Int!, $after: String) { 产品（第一：$第一，之后：$之后）{ 页面信息{ 有下一页结束光标 } 节点{ 编号标题 } } } ### 金钱领域价格作为 `MoneyV2` 对象返回：总价格集 { 商店钱{ 金额货币代码 } } ### 突变总是返回 userErrors 始终请求并检查“userErrors”：突变{ 产品创建（产品：$产品）{ 产品{id} 用户错误{ 领域留言 } } } ### 搜索语法过滤查询使用 Shopify 的搜索语法：产品（第一个：10，查询：“标题：*衬衫* AND 状态：ACTIVE”） ## 所需的 API 范围 ### 核心范围 * `read_products`, `write_products` \- 产品和变体 * `read_orders`, `write_orders` \- 订单和履行 * `read_customers`, `write_customers` \- 客户数据 * `read_inventory`, `write_inventory` \- 库存水平 ### 营销与折扣 * `read_discounts`, `write_discounts` \- 折扣代码 * `read_marketing_events`, `write_marketing_events` \- 营销活动 ### 内容 * `read_content`, `write_content` \- 页面、博客、文章 * `read_online_store_navigation`, `write_online_store_navigation` \- 菜单 * `read_files`, `write_files` \- 文件上传 * `read_metafields`, `write_metafields` \- 元字段 * `read_metaobjects`, `write_metaobjects` \- 元对象 ### 国际 * `read_translations`, `write_translations` \- 翻译 * `read_markets`, `write_markets` \- 市场 * `read_locales`, `write_locales` \- 语言环境 ### 履行 * `read_shipping`, `write_shipping` \- 运送设置 * `read_locations` \- 位置数据 * `read_assigned_fulfillment_orders`, `write_signed_fulfillment_orders` \- 用于履行服务 ### 金融 * `read_draft_orders`, `write_draft_orders` \- 草稿订单 * `read_gift_cards`, `write_gift_cards` \- 礼品卡 * `read_own_subscription_contracts`, `write_own_subscription_contracts` \- 订阅 ## 故障排除错误 |解决方案 ---|--- `访问被拒绝` |检查 API 令牌是否具有所需的范围 `无效的 ID` |确保 ID 格式为 `gid://shopify/Resource/123` 返回“用户错误”|检查特定于字段的验证消息 “节流” |降低请求率，使用批量操作进行大更新 `找不到资源` |验证 ID 是否存在并且您具有读取权限 ## 示例 ### 列出最近的订单和客户信息查询最近订单{ 订单（第一个：10，排序键：CREATED_AT，反向：true）{ 节点{ 编号姓名创建于显示财务状况总价格集 { 商店钱{ 金额货币代码 } } 客户{ 显示名称默认电子邮件地址 { 电子邮件地址 } } } } } ### 按标题搜索产品查询 SearchProducts($query: 字符串!) { 产品（第一个：20，查询：$query）{ 节点{ 编号标题状态供应商 } } } 变量： `{ "query": "title:*shirt* AND status:ACTIVE" }` ### 更新库存突变AdjustInventory($input: InventoryAdjustQuantitiesInput!) { 库存调整数量（输入：$输入）{ 库存调整组{ 原因改变{ 姓名三角洲 } } 用户错误{ 领域留言 } } } ### 创建折扣代码突变 CreateDiscount($basicCodeDiscount: DiscountCodeBasicInput!) { discountCodeBasicCreate(basicCodeDiscount: $basicCodeDiscount) { 代码折扣节点 { 编号 } 用户错误{ 领域留言 } } } ## 最佳实践 1. **使用批量操作**进行大数据导出/导入 2. **对可能增长的列表实施分页** 3. **检查所有突变响应中的 userErrors** 4. **仅请求所需的字段**以优化响应大小 5. **使用 webhooks** 而不是轮询实时更新 6. **适当时缓存**以减少API调用 7. **使用指数退避处理速率限制**

龙虾管理API

包含技能