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.

Toolkit docs: composio.dev/toolkits/square

通过Composio的Square工具包，借助Rube MCP自动化Square支付处理、订单管理和发票开具等操作。

工具包文档：composio.dev/toolkits/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
```
工具包
如果连接状态未激活，请按照返回的授权链接完成Square OAuth认证
在运行任何工作流之前，确认连接状态显示为已激活

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
```
: 搜索结果的分页游标

注意事项:

location_ids

是

SQUARE_SEARCH_ORDERS

的必填参数；需先通过

SQUARE_LIST_LOCATIONS

获取ID

订单状态包括：OPEN（待处理）、COMPLETED（已完成）、CANCELED（已取消）、DRAFT（草稿）
```
SQUARE_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
```
: 每页返回的结果数量

注意事项:

location_id

是

SQUARE_LIST_INVOICES

的必填参数；需先通过

SQUARE_LIST_LOCATIONS

获取

仅SCHEDULED（已排期）、UNPAID（未支付）或PARTIALLY_PAID（部分支付）的发票可被取消
```
SQUARE_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
```
参数
持续操作直到
```
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

版本控制:

SQUARE_UPDATE_ORDER

和

SQUARE_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

Powered by Composio

任务	工具标识	关键参数
列出支付记录	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

由 Composio 提供支持