square-automation

通过 Rube MCP 自动化 Square

通过 Rube MCP 使用 Composio 的 Square 工具包，自动处理 Square 付款、订单管理和开票。

前提条件

• 必须已连接 Rube MCP（可使用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Square 连接，工具包为 square
• 始终先调用 RUBE_SEARCH_TOOLS，获取最新的工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。请确认当前 MCP 和服务身份验证状态；仅添加端点并不能建立经过身份验证的连接。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 使用工具包 square 调用 RUBE_MANAGE_CONNECTIONS
3. 如果连接状态不是 ACTIVE，请按照返回的身份验证链接完成 Square OAuth
4. 确认连接状态显示为 ACTIVE，然后再运行任何工作流

操作边界

操作前，先确定准确的账户／环境和 ID。只读列表操作不代表已获准取消付款、修改订单或修改发票。预览具体影响，并且只执行用户授权的操作；记录返回的身份标识和状态，对结果不明确的写入操作，在重试前先进行核对；并验证最终状态，而不能将请求已受理视为操作已完成。

核心工作流

1. 列出并监控付款

适用情况：用户想查看付款历史或检查付款状态

工具调用顺序：

1. SQUARE_LIST_PAYMENTS - 获取付款记录，可选使用筛选条件［必需］
2. SQUARE_CANCEL_PAYMENT - 如有需要，取消待处理的付款［可选］

关键参数：

• begin_time / end_time：用于按日期范围筛选的 RFC 3339 时间戳
• sort_order：使用 'ASC' 或 'DESC' 按时间顺序排序
• cursor：上一次响应中的分页游标
• location_id：按特定地点筛选付款

注意事项：

• 时间戳必须采用 RFC 3339 格式（例如 '2024-01-01T00:00:00Z'）
• 结果较多时必须分页；持续使用 cursor，直至其不存在
• 只有待处理的付款可以取消；已完成的付款需要退款
• SQUARE_CANCEL_PAYMENT 需要列表结果中的确切 payment_id

2. 搜索并管理订单

适用情况：用户想按条件查找订单或更新订单详情

工具调用顺序：

1. SQUARE_LIST_LOCATIONS - 获取用于筛选的地点 ID［前提］
2. SQUARE_SEARCH_ORDERS - 使用筛选条件搜索订单［必需］
3. SQUARE_RETRIEVE_ORDER - 获取特定订单的完整详情［可选］
4. SQUARE_UPDATE_ORDER - 修改订单状态或详情［可选］

关键参数：

• location_ids：要搜索的地点 ID 数组（搜索时必需）
• query：包含日期范围、状态和履约类型的搜索筛选对象
• order_id：用于检索／更新操作的特定订单 ID
• cursor：搜索结果的分页游标

注意事项：

• SEARCH_ORDERS 必须提供 location_ids；请先从 LIST_LOCATIONS 获取 ID
• 订单状态包括：OPEN、COMPLETED、CANCELED、DRAFT
• UPDATE_ORDER 需要当前的 version 字段，以防止冲突
• 搜索结果采用分页方式；持续使用 cursor，直至其不存在

3. 管理地点

适用情况：用户想查看营业地点或获取地点详情

工具调用顺序：

1. SQUARE_LIST_LOCATIONS - 列出所有营业地点［必需］

关键参数：

• 没有必需参数；会返回所有可访问的地点
• 响应包含 id、name、address、status、timezone

注意事项：

• 大多数其他 Square 操作（订单、付款）都需要地点 ID
• 首次获取后，请始终缓存地点 ID，以避免重复调用
• 结果中可能仍会显示未启用的地点；请检查 status 字段

4. 发票管理

使用时机：用户想要列出、查看或取消发票

工具调用顺序：

1. SQUARE_LIST_LOCATIONS - 获取用于筛选的 location ID [前置条件]
2. SQUARE_LIST_INVOICES - 列出某个 location 的发票 [必需]
3. SQUARE_GET_INVOICE - 获取详细的发票信息 [可选]
4. SQUARE_CANCEL_INVOICE - 取消已计划或未支付的发票 [可选]

关键参数：

• location_id：列出发票时必需
• invoice_id：获取/取消操作时必需
• cursor：列表结果的分页游标
• limit：每页结果数量

易错点：

• LIST_INVOICES 需要 location_id；请先通过 LIST_LOCATIONS 解析
• 只有 SCHEDULED、UNPAID 或 PARTIALLY_PAID 状态的发票可以取消
• CANCEL_INVOICE 需要发票的 version 以防止竞态条件
• 已取消的发票无法恢复

常见模式

ID 解析

Location 名称 -> Location ID：

1. Call SQUARE_LIST_LOCATIONS
2. Find location by name in response
3. Extract id field (e.g., 'L1234ABCD')

订单查询：

1. Call SQUARE_SEARCH_ORDERS with location_ids and query filters
2. Extract order_id from results
3. Use order_id for RETRIEVE_ORDER or UPDATE_ORDER

分页

• 检查响应中的 cursor 字段
• 在下一个请求的 cursor 参数中传入游标值
• 持续进行，直到 cursor 不存在或为空
• 使用 limit 控制每页大小

日期范围筛选

• 使用 RFC 3339 格式：2024-01-01T00:00:00Z
• 对于支付：使用 begin_time 和 end_time 参数
• 对于订单：使用带 date_time_filter 的查询筛选器
• 所有时间戳均为 UTC

已知易错点

ID 格式：

• Location ID 是字母数字字符串（例如 'L1234ABCD'）
• Payment ID 和 Order ID 是更长的字母数字字符串
• 在其他操作之前，始终先将 location 名称解析为 ID

版本控制：

• UPDATE_ORDER 和 CANCEL_INVOICE 需要当前的 version 字段
• 先获取资源以取得其当前版本
• 版本不匹配会返回 409 Conflict 错误

速率限制：

• Square API 有按端点的速率限制
• 为批量操作实现退避
• 对于大型数据集，分页应包含短暂延迟

响应解析：

• 响应可能将数据嵌套在 data 键下
• 金额使用最小货币单位（USD 为分）
• 防御性地解析，并为可选字段提供回退

快速参考

任务	工具标识	关键参数
列出支付	SQUARE_LIST_PAYMENTS	begin_time, end_time, location_id, cursor
取消支付	SQUARE_CANCEL_PAYMENT	payment_id
搜索订单	SQUARE_SEARCH_ORDERS	location_ids, query, cursor
获取订单	SQUARE_RETRIEVE_ORDER	order_id
更新订单	SQUARE_UPDATE_ORDER	order_id, version
列出 locations	SQUARE_LIST_LOCATIONS	(无)
列出发票	SQUARE_LIST_INVOICES	location_id, cursor
获取发票	SQUARE_GET_INVOICE	invoice_id
取消发票	SQUARE_CANCEL_INVOICE	invoice_id, version

使用时机

本技能适用于执行概述中描述的工作流或操作。

限制

• 仅当任务与上述范围明确匹配时才使用本技能。
• 不要将输出视为针对特定环境的验证、测试或专家审查的替代品。
• 如果缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。