square-automation

Rube MCP による Square の自動化

Rube MCP 経由で Composio の Square ツールキットを使用し、Square の決済処理、注文管理、請求書発行を自動化します。

ツールキットのドキュメント： composio.dev/toolkits/square

前提条件

• Rube MCP が接続されていること（RUBE_SEARCH_TOOLS が利用可能）
• square ツールキットを指定した RUBE_MANAGE_CONNECTIONS による有効な Square 接続
• 現在のツールスキーマを取得するため、必ず最初に RUBE_SEARCH_TOOLS を呼び出してください

セットアップ

Rube MCP の入手：クライアント設定で https://rube.app/mcp を MCP サーバーとして追加してください。API キーは不要です。エンドポイントを追加するだけで動作します。

1. RUBE_SEARCH_TOOLS が応答することを確認し、Rube MCP が利用可能であることを確認します
2. square ツールキットを指定して RUBE_MANAGE_CONNECTIONS を呼び出します
3. 接続が ACTIVE でない場合は、返された認証リンクに従って Square OAuth を完了します
4. ワークフローを実行する前に、接続ステータスが ACTIVE であることを確認します

主なワークフロー

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 - 絞り込みに使用するロケーション ID を取得します［前提条件］
2. SQUARE_LIST_INVOICES - ロケーションの請求書を一覧表示します［必須］
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 の解決

ロケーション名 -> ロケーション 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 の形式：

• ロケーション ID は英数字の文字列です（例：'L1234ABCD'）
• 支払い ID と注文 ID は、より長い英数字の文字列です
• 他の操作を行う前に、必ずロケーション名を 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
ロケーションの一覧表示	SQUARE_LIST_LOCATIONS	(なし)
請求書の一覧表示	SQUARE_LIST_INVOICES	location_id, cursor
請求書の取得	SQUARE_GET_INVOICE	invoice_id
請求書のキャンセル	SQUARE_CANCEL_INVOICE	invoice_id, version

---

Composio により提供