square-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Square Automation via Rube MCP

通过Rube MCP实现Square自动化

Automate Square payment processing, order management, and invoicing through Composio's Square toolkit via Rube MCP.

通过Composio的Square工具包，借助Rube MCP实现Square支付处理、订单管理和发票流程的自动化。

Prerequisites

前提条件

Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
Active Square connection via
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
square
```
Always call
```
RUBE_SEARCH_TOOLS
```
first to get current tool schemas

必须已连接Rube MCP（需确保
```
RUBE_SEARCH_TOOLS
```
可用）
通过
```
RUBE_MANAGE_CONNECTIONS
```
激活Square连接，工具包选择
```
square
```
请始终先调用
```
RUBE_SEARCH_TOOLS
```
以获取最新的工具架构

Setup

设置步骤

Get Rube MCP: Add

https://rube.app/mcp

as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

Verify Rube MCP is available by confirming
```
RUBE_SEARCH_TOOLS
```
responds
Call
```
RUBE_MANAGE_CONNECTIONS
```
with toolkit
```
square
```
If connection is not ACTIVE, follow the returned auth link to complete Square OAuth
Confirm connection status shows ACTIVE before running any workflows

获取Rube MCP：在客户端配置中添加

https://rube.app/mcp

作为MCP服务器。无需API密钥 —— 只需添加端点即可使用。

确认
```
RUBE_SEARCH_TOOLS
```
可正常响应，以此验证Rube MCP是否可用
调用
```
RUBE_MANAGE_CONNECTIONS
```
并指定工具包为
```
square
```
如果连接状态未显示为ACTIVE，请按照返回的授权链接完成Square OAuth认证
在运行任何工作流之前，确认连接状态为ACTIVE

Core Workflows

核心工作流

1. List and Monitor Payments

1. 列出并监控支付记录

When to use: User wants to view payment history or check payment status

Tool sequence:

```
SQUARE_LIST_PAYMENTS
```
- Retrieve payments with optional filters [Required]
```
SQUARE_CANCEL_PAYMENT
```
- Cancel a pending payment if needed [Optional]

Key parameters:

```
begin_time
```
/
```
end_time
```
: RFC 3339 timestamps for date range filtering
```
sort_order
```
: 'ASC' or 'DESC' for chronological ordering
```
cursor
```
: Pagination cursor from previous response
```
location_id
```
: Filter payments by specific location

Pitfalls:

Timestamps must be RFC 3339 format (e.g., '2024-01-01T00:00:00Z')
Pagination required for large result sets; follow
```
cursor
```
until absent
Only pending payments can be cancelled; completed payments require refunds
```
SQUARE_CANCEL_PAYMENT
```
requires exact
```
payment_id
```
from list results

适用场景：用户需要查看支付历史或检查支付状态

工具调用流程:

```
SQUARE_LIST_PAYMENTS
```
- 检索支付记录，可添加可选筛选条件 [必填]
```
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. Search and Manage Orders

2. 搜索并管理订单

When to use: User wants to find orders by criteria or update order details

Tool sequence:

```
SQUARE_LIST_LOCATIONS
```
- Get location IDs for filtering [Prerequisite]
```
SQUARE_SEARCH_ORDERS
```
- Search orders with filters [Required]
```
SQUARE_RETRIEVE_ORDER
```
- Get full details of a specific order [Optional]
```
SQUARE_UPDATE_ORDER
```
- Modify order state or details [Optional]

Key parameters:

```
location_ids
```
: Array of location IDs to search within (required for search)
```
query
```
: Search filter object with date ranges, states, fulfillment types
```
order_id
```
: Specific order ID for retrieve/update operations
```
cursor
```
: Pagination cursor for search results

Pitfalls:

```
location_ids
```
is required for SEARCH_ORDERS; get IDs from LIST_LOCATIONS first
Order states include: OPEN, COMPLETED, CANCELED, DRAFT
UPDATE_ORDER requires the current
```
version
```
field to prevent conflicts
Search results are paginated; follow
```
cursor
```
until absent

适用场景：用户需要按条件查找订单或更新订单详情

工具调用流程:

```
SQUARE_LIST_LOCATIONS
```
- 获取地点ID用于筛选 [前置步骤]
```
SQUARE_SEARCH_ORDERS
```
- 按筛选条件搜索订单 [必填]
```
SQUARE_RETRIEVE_ORDER
```
- 获取特定订单的完整详情 [可选]
```
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. Manage Locations

3. 地点管理

When to use: User wants to view business locations or get location details

Tool sequence:

```
SQUARE_LIST_LOCATIONS
```
- List all business locations [Required]

Key parameters:

No required parameters; returns all accessible locations
Response includes
```
id
```
,
```
name
```
,
```
address
```
,
```
status
```
,
```
timezone
```

Pitfalls:

Location IDs are required for most other Square operations (orders, payments)
Always cache location IDs after first retrieval to avoid redundant calls
Inactive locations may still appear in results; check
```
status
```
field

适用场景：用户需要查看业务地点或获取地点详情

工具调用流程:

```
SQUARE_LIST_LOCATIONS
```
- 列出所有业务地点 [必填]

关键参数:

无必填参数；返回所有可访问的地点
响应包含
```
id
```
、
```
name
```
、
```
address
```
、
```
status
```
、
```
timezone
```
字段

注意事项:

地点ID是大多数其他Square操作（订单、支付）的必填项
首次检索后请缓存地点ID，避免重复调用
已停用的地点仍可能出现在结果中；请检查
```
status
```
字段

4. Invoice Management

4. 发票管理

When to use: User wants to list, view, or cancel invoices

Tool sequence:

```
SQUARE_LIST_LOCATIONS
```
- Get location ID for filtering [Prerequisite]
```
SQUARE_LIST_INVOICES
```
- List invoices for a location [Required]
```
SQUARE_GET_INVOICE
```
- Get detailed invoice information [Optional]
```
SQUARE_CANCEL_INVOICE
```
- Cancel a scheduled or unpaid invoice [Optional]

Key parameters:

```
location_id
```
: Required for listing invoices
```
invoice_id
```
: Required for get/cancel operations
```
cursor
```
: Pagination cursor for list results
```
limit
```
: Number of results per page

Pitfalls:

```
location_id
```
is required for LIST_INVOICES; resolve via LIST_LOCATIONS first
Only SCHEDULED, UNPAID, or PARTIALLY_PAID invoices can be cancelled
CANCEL_INVOICE requires the invoice
```
version
```
to prevent race conditions
Cancelled invoices cannot be uncancelled

适用场景：用户需要列出、查看或取消发票

工具调用流程:

```
SQUARE_LIST_LOCATIONS
```
- 获取地点ID用于筛选 [前置步骤]
```
SQUARE_LIST_INVOICES
```
- 列出指定地点的发票 [必填]
```
SQUARE_GET_INVOICE
```
- 获取发票的详细信息 [可选]
```
SQUARE_CANCEL_INVOICE
```
- 取消已排期或未支付的发票 [可选]

关键参数:

```
location_id
```
: 列出发票的必填项
```
invoice_id
```
: 获取/取消操作的必填项
```
cursor
```
: 列表结果的分页游标
```
limit
```
: 每页返回的结果数量

注意事项:

```
LIST_INVOICES
```
必须提供
```
location_id
```
；需先通过
```
LIST_LOCATIONS
```
获取
仅SCHEDULED（已排期）、UNPAID（未支付）或PARTIALLY_PAID（部分支付）的发票可被取消
```
CANCEL_INVOICE
```
需要发票的
```
version
```
字段以避免竞争条件
已取消的发票无法恢复

Common Patterns

通用模式

ID Resolution

ID解析

Location name -> Location ID:

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

Order lookup:

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

地点名称 -> 地点ID:

1. 调用SQUARE_LIST_LOCATIONS
2. 在响应中按名称查找地点
3. 提取id字段（例如：'L1234ABCD'）

订单查询:

1. 调用SQUARE_SEARCH_ORDERS并传入location_ids和查询筛选条件
2. 从结果中提取order_id
3. 使用order_id执行RETRIEVE_ORDER或UPDATE_ORDER操作

Pagination

分页

Check response for
```
cursor
```
field
Pass cursor value in next request's
```
cursor
```
parameter
Continue until
```
cursor
```
is absent or empty
Use
```
limit
```
to control page size

检查响应中的
```
cursor
```
字段
在下次请求的
```
cursor
```
参数中传入该值
持续操作直至
```
cursor
```
不存在或为空
使用
```
limit
```
控制每页结果数量

Date Range Filtering

日期范围筛选

Use RFC 3339 format:
```
2024-01-01T00:00:00Z
```
For payments:
```
begin_time
```
and
```
end_time
```
parameters
For orders: Use query filter with date_time_filter
All timestamps are in UTC

使用RFC 3339格式：
```
2024-01-01T00:00:00Z
```
支付记录：使用
```
begin_time
```
和
```
end_time
```
参数
订单：在查询筛选器中使用date_time_filter
所有时间戳均为UTC时区

Known Pitfalls

已知注意事项

ID Formats:

Location IDs are alphanumeric strings (e.g., 'L1234ABCD')
Payment IDs and Order IDs are longer alphanumeric strings
Always resolve location names to IDs before other operations

Versioning:

UPDATE_ORDER and CANCEL_INVOICE require current
```
version
```
field
Fetch the resource first to get its current version
Version mismatch returns a 409 Conflict error

Rate Limits:

Square API has per-endpoint rate limits
Implement backoff for bulk operations
Pagination should include brief delays for large datasets

Response Parsing:

Responses may nest data under
```
data
```
key
Money amounts are in smallest currency unit (cents for USD)
Parse defensively with fallbacks for optional fields

ID格式:

地点ID为字母数字字符串（例如：'L1234ABCD'）
支付ID和订单ID为更长的字母数字字符串
在执行其他操作前，请务必将地点名称解析为ID

版本控制:

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

速率限制:

Square API对每个端点都有速率限制
批量操作请实现退避机制
处理大型数据集时，分页请求间需添加短暂延迟

响应解析:

响应数据可能嵌套在
```
data
```
键下
金额以最小货币单位表示（例如美元为美分）
解析时需添加防御性处理，为可选字段设置默认值

Quick Reference

快速参考

Task	Tool Slug	Key Params
List payments	SQUARE_LIST_PAYMENTS	begin_time, end_time, location_id, cursor
Cancel payment	SQUARE_CANCEL_PAYMENT	payment_id
Search orders	SQUARE_SEARCH_ORDERS	location_ids, query, cursor
Get order	SQUARE_RETRIEVE_ORDER	order_id
Update order	SQUARE_UPDATE_ORDER	order_id, version
List locations	SQUARE_LIST_LOCATIONS	(none)
List invoices	SQUARE_LIST_INVOICES	location_id, cursor
Get invoice	SQUARE_GET_INVOICE	invoice_id
Cancel invoice	SQUARE_CANCEL_INVOICE	invoice_id, version

任务	工具标识	关键参数
列出支付记录	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
列出地点	SQUARE_LIST_LOCATIONS	无
列出发票	SQUARE_LIST_INVOICES	location_id, cursor
获取发票详情	SQUARE_GET_INVOICE	invoice_id
取消发票	SQUARE_CANCEL_INVOICE	invoice_id, version