--- name: "square-japan" description: "Square日本向け決済・POS管理エージェント — Square Connect v2 APIを活用し、決済処理、POS管理、在庫管理、顧客管理、ロイヤリティプログラム、インボイス発行、eコマースをClaude Codeから統合操作。日本市場に最適化されたキャッシュレス決済・店舗運営スキル。" version: "1.0.0" author: "hanabi-jpn" tags: - square - payment - pos - japan - cashless - ecommerce - loyalty - invoice - inventory - retail --- ``` ┌──────────────────────────────────────────────────────────────┐ │ ╔═╗╔═╗ ╦ ╦╔═╗╦═╗╔═╗ │ │ ╚═╗║═╬╗║ ║╠═╣╠╦╝║╣ Japan Agent │ │ ╚═╝╚═╝╚╚═╝╩ ╩╩╚═╚═╝ │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │PAY │─│ POS │─│ INV │─│ CRM │─│LOYAL │─│ONLINE│ │ │ │決済 │ │レジ │ │在庫 │ │顧客 │ │特典 │ │EC │ │ │ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ │ │ └────────┴────────┴────────┴────────┴────────┘ │ │ Square Connect v2 API │ │ Claude Code × 日本向けオムニチャネル決済 │ └──────────────────────────────────────────────────────────────┘ ``` `claude-code` `square` `payment` `pos` `japan` [![Version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/hanabi-jpn/clawhub-skills) [![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/hanabi-jpn/clawhub-skills/blob/main/LICENSE) [![Platform](https://img.shields.io/badge/platform-Square_Connect_v2-00cc00)](https://developer.squareup.com/) [![Language](https://img.shields.io/badge/language-Japanese-red)](https://github.com/hanabi-jpn/clawhub-skills) [![Status](https://img.shields.io/badge/status-stable-brightgreen)](https://github.com/hanabi-jpn/clawhub-skills) > **Square日本向け決済・POS管理エージェント** — グローバルNo.1の決済プラットフォームSquareの全機能をClaude Codeから操作。対面決済からeコマース、ロイヤリティプログラム、インボイス発行まで、オムニチャネル店舗運営を日本市場に最適化してワンコマンドで実現するスキル。 --- ## Overview Square Japan Agentは、Squareが提供するConnect v2 APIをClaude Codeから直接操作し、日本市場向けに最適化された決済・店舗運営を実現するスキルです。Squareは対面決済（Square Reader / Square Terminal / Square Stand）、オンライン決済（Square Online）、請求書発行（Square Invoices）、ロイヤリティプログラム、在庫管理、顧客管理を統合プラットフォームで提供しています。本スキルはこれらの機能すべてをコマンドラインから操作可能にし、特に日本のインボイス制度、軽減税率、日本の商慣習に対応した運用を実現します。Squareの翌営業日入金（三井住友銀行・みずほ銀行）は、日本の中小事業者にとって大きなキャッシュフロー改善をもたらします。 ### アーキテクチャ概要 ``` ┌────────────────────────────────────────────────────────────────────┐ │ Claude Code Terminal │ │ ┌──────────────────────────────────────────────────────────────┐ │ │ │ square payment / pos / inventory / customer / loyalty │ │ │ └───────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────▼──────────────────────────────────┐ │ │ │ Square Japan Agent Core │ │ │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │Payment │ │POS │ │Inventory │ │Customer │ │ │ │ │ │Gateway │ │Manager │ │System │ │Directory │ │ │ │ │ │(決済) │ │(レジ) │ │(在庫) │ │(顧客) │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ │ │ │ │ ┌────┴─────┐ ┌────┴─────┐ ┌────┴─────┐ ┌────┴─────┐ │ │ │ │ │Loyalty │ │Invoice │ │Online │ │Analytics │ │ │ │ │ │Program │ │Generator │ │Store │ │Engine │ │ │ │ │ │(特典) │ │(請求書) │ │(EC) │ │(分析) │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ └────────────┴────────────┴────────────┘ │ │ │ └───────────────────────────┬──────────────────────────────────┘ │ │ │ HTTPS / REST API (v2) │ │ ┌───────────────────────────▼──────────────────────────────────┐ │ │ │ Square Connect v2 API │ │ │ │ payments / orders / catalog / customers / loyalty / │ │ │ │ invoices / inventory / team / locations │ │ │ └───────────────────────────┬──────────────────────────────────┘ │ │ │ │ │ ┌───────────────────────────▼──────────────────────────────────┐ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ │ │ Square │ │ Square │ │ Square │ │ │ │ │ │ Reader │ │ Terminal │ │ Online │ │ │ │ │ │ (対面IC/磁気)│ │ (据置端末) │ │ (EC) │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ VISA / Mastercard / JCB / AMEX / Diners / Discover │ │ │ │ Suica / PASMO / iD / QUICPay / PayPay │ │ │ └──────────────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────────┘ ``` ### 処理フロー ``` 商品カタログ登録 ──→ 注文作成 ──→ 決済処理 ──→ レシート発行 ──→ 入金 │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ 在庫反映 ロイヤリティ カード/QR/ 電子/紙 翌営業日 カテゴリ管理 ポイント加算 電子マネー インボイス 自動入金 タッチ決済 対応レシート ``` --- ## System Prompt（行動指針） Square Japan Agentとして動作する際、以下のガイドラインに厳密に従うこと。 1. **すべてのAPI呼び出しはSquare Connect v2エンドポイントを使用する。** 旧v1エンドポイントは使用しない。APIバージョンは `2026-02-20` 以降を指定する。 2. **金額はすべて日本円（JPY）の最小単位（1円）で扱う。** Square APIはcents単位を要求するが、日本円は小数点がないため、amount = 表示金額そのままとする。 3. **インボイス制度（適格請求書等保存方式）に完全準拠する。** レシートおよび請求書に登録番号（T+13桁）、税率ごとの区分記載を必須とする。 4. **軽減税率8%と標準税率10%をカタログアイテムのカテゴリに基づいて自動適用する。** フード（テイクアウト）は8%、フード（イートイン）は10%、その他は10%をデフォルトとする。 5. **決済処理では冪等性キー（idempotency_key）を必ず付与する。** 重複決済を防止し、ネットワークエラー時の安全なリトライを保証する。 6. **顧客データはSquare Customer Directoryを正として管理する。** ローカルキャッシュは参照用とし、更新時は必ずAPIを通じて同期する。 7. **ロイヤリティプログラムのポイント計算は、税抜金額ベースで行う。** 100円につき1ポイントをデフォルトとし、プログラム設定に従って調整する。 8. **Square Onlineとの在庫同期は双方向で行う。** 対面販売とオンライン販売の在庫を統合管理し、在庫切れによる機会損失を防ぐ。 9. **入金スケジュールは銀行ごとのSquare規定に従う。** 三井住友銀行・みずほ銀行は翌営業日入金、その他銀行は週1回（金曜日）入金を正確に追跡する。 10. **Webhookイベントはすべて検証する。** Square署名ヘッダーを検証し、不正なWebhookリクエストを拒否する。 11. **複数ロケーション（店舗）の管理に対応する。** ロケーションごとに独立した売上集計、在庫管理、スタッフ管理を行う。 12. **チーム管理（Square Team）と連携する。** スタッフの勤怠管理、権限設定、売上紐づけを一元化する。 13. **エラーハンドリングはSquare APIのエラーカテゴリに基づいて分類する。** RATE_LIMIT、AUTHENTICATION、INVALID_REQUEST、PAYMENT_METHOD、INTERNAL_SERVERのカテゴリ別に適切な対処を行う。 14. **Sandbox環境とProduction環境を明確に分離する。** SQUARE_ENVIRONMENT変数で切り替え、テスト用のカードナンバーはSandboxのみで使用する。 15. **日次のレジ締め処理を自動化する。** 現金・カード・電子マネー・QRの各決済手段ごとに集計し、不一致がある場合はアラートする。 16. **PCI DSS準拠を維持する。** カード番号の生データを一切保持せず、Squareのトークン化されたnonce・カードIDのみを扱う。 17. **定期的なAPIトークンのローテーションを推奨する。** アクセストークンの有効期限を監視し、期限30日前に更新を促す。 --- ## Environment Variables | 変数名 | 必須 | 説明 | 例 | |--------|------|------|-----| | `SQUARE_ACCESS_TOKEN` | Yes | Square APIアクセストークン | `(Square Developer Dashboardで取得)` | | `SQUARE_LOCATION_ID` | Yes | デフォルトロケーション（店舗）ID | `L0CATION1D2E3F4G5H6I` | | `SQUARE_ENVIRONMENT` | Yes | 実行環境（sandbox / production） | `production` | | `SQUARE_APPLICATION_ID` | No | SquareアプリケーションID | `sq0idp-WxYzAbCdEfGhIjKlMnOp` | | `SQUARE_WEBHOOK_SECRET` | No | Webhook署名検証シークレット | `sq0whk-secret-key-here-1234` | | `SQUARE_CURRENCY` | No | 通貨コード（デフォルト: JPY） | `JPY` | | `SQUARE_TAX_REGISTRATION` | No | 適格請求書発行事業者登録番号 | `T9876543210123` | | `SQUARE_LOYALTY_PROGRAM_ID` | No | ロイヤリティプログラムID | `loy_pg_1a2b3c4d5e` | | `SQUARE_BANK_ACCOUNT` | No | 入金先銀行口座情報 | `三井住友銀行 渋谷支店` | | `SQUARE_ONLINE_SITE_ID` | No | Square OnlineサイトID | `site_jp_hanabi_001` | | `SQUARE_TEAM_ENABLED` | No | チーム管理機能有効化 | `true` | | `SQUARE_STORAGE_DIR` | No | ローカルデータ保存先 | `~/.square-japan/data` | --- ## Commands ### 1. `square payment` — 決済処理 決済の実行、照会、返金処理を行います。 ```bash square payment list --date 2026-03-01 --location L0CATION1D2E3F4G5H6I ``` **出力例:** ``` ╔═══════════════════════════════════════════════════════════════════╗ ║ 決済一覧（2026-03-01 / 渋谷本店） ║ ╠═══════════════════════════════════════════════════════════════════╣ ║ ║ ║ 本日の決済: 62件 / 合計: ¥485,200 ║ ║ ║ ║ ┌──────┬────────────┬──────────┬──────────┬───────┬──────────┐ ║ ║ │ 時刻 │ 決済ID │ 手段 │ 金額 │手数料 │ 状態 │ ║ ║ ├──────┼────────────┼──────────┼──────────┼───────┼──────────┤ ║ ║ │09:15 │ SQ-PY-0001 │ VISA TC │ 4,200 │ 136│ 完了 │ ║ ║ │09:32 │ SQ-PY-0002 │ Suica │ 680 │ 22│ 完了 │ ║ ║ │10:05 │ SQ-PY-0003 │ Master TC│ 12,800 │ 415│ 完了 │ ║ ║ │10:18 │ SQ-PY-0004 │ 現金 │ 3,500 │ 0│ 完了 │ ║ ║ │10:45 │ SQ-PY-0005 │ iD │ 1,980 │ 64│ 完了 │ ║ ║ │11:02 │ SQ-PY-0006 │ JCB TC │ 8,900 │ 295│ 完了 │ ║ ║ │11:20 │ SQ-PY-0007 │ PayPay │ 2,400 │ 79│ 完了 │ ║ ║ │... │ ... │ ... │ ... │ ...│ ... │ ║ ║ ├──────┼────────────┼──────────┼──────────┼───────┼──────────┤ ║ ║ │ │ 合計(62件) │ │ 485,200 │15,724│ │ ║ ║ └──────┴────────────┴──────────┴──────────┴───────┴──────────┘ ║ ║ ║ ║ TC = タッチ決済（NFC/コンタクトレス） ║ ║ 手数料率: 3.25%（VISA/Master/AMEX） / 3.95%（JCB） ║ ║ 翌営業日入金予定: ¥469,476 ║ ╚═══════════════════════════════════════════════════════════════════╝ ``` ### 2. `square pos` — POS管理 注文の作成、管理、レジ操作を行います。 ```bash square pos order create --items "抹茶ラテ:2:580:8" "クロワッサン:1:320:8" \ --customer CUS-00123 --loyalty-add ``` **出力例:** ``` 注文作成完了 注文ID: ORD-2026-0301-0048 ロケーション: 渋谷本店 明細: 1. 抹茶ラテ 2点 × ¥580 = ¥1,160 (税8%) 2. クロワッサン 1点 × ¥320 = ¥320 (税8%) 小計: ¥1,480 消費税(8%): ¥118 合計: ¥1,598 顧客: CUS-00123（田中美咲様） ロイヤリティ: +14ポイント加算（税抜¥1,480 → 14pt） 累計ポイント: 284pt（次回特典まで16pt） 決済待ち... 端末で決済を完了してください。 ``` ### 3. `square inventory` — 在庫管理 カタログアイテムの在庫状況を管理します。 ```bash square inventory status --category "コーヒー豆" --low-stock ``` **出力例:** ``` 在庫アラート（カテゴリ: コーヒー豆） ┌────────────┬───────────────────┬──────┬──────┬────────┬─────────┐ │ SKU │ 商品名 │ 在庫 │ 閾値 │ 状態 │ 消化日数│ ├────────────┼───────────────────┼──────┼──────┼────────┼─────────┤ │ CB-ETH-001 │ エチオピア イルガチェフェ│ 2kg│ 5kg│ 要発注 │ 2.1日 │ │ CB-COL-002 │ コロンビア スプレモ │ 3kg│ 5kg│ 要発注 │ 3.5日 │ │ CB-GUA-003 │ グアテマラ アンティグア│ 1kg│ 5kg│ 緊急 │ 0.8日 │ └────────────┴───────────────────┴──────┴──────┴────────┴─────────┘ 全店舗在庫合計: 渋谷本店: 6kg 新宿店: 12kg → 新宿店から渋谷本店への在庫移動を推奨（グアテマラ 5kg） 消化日数は過去30日間の平均販売量から算出 ``` ### 4. `square customer` — 顧客管理 Square Customer Directoryの顧客データを管理します。 ```bash square customer search --query "田中" --sort spending-desc ``` **出力例:** ``` 顧客検索結果（"田中" / 利用額順） ┌──────────┬──────────┬────────────┬──────────┬──────┬───────────┐ │ 顧客ID │ 氏名 │ メール │ 累計利用 │来店数│ 会員区分 │ ├──────────┼──────────┼────────────┼──────────┼──────┼───────────┤ │CUS-00123 │田中美咲 │m.tanaka@jpn│ 284,500│ 42│ ゴールド │ │CUS-00456 │田中健一 │k.tanaka@jpn│ 156,200│ 28│ シルバー │ │CUS-00789 │田中由美 │y.tanaka@jpn│ 62,300│ 11│ レギュラー│ └──────────┴──────────┴────────────┴──────────┴──────┴───────────┘ CUS-00123 田中美咲 詳細: 初回来店: 2025-06-15 最終来店: 2026-02-28 平均客単価: ¥6,773 お気に入り: 抹茶ラテ（18回）、クロワッサン（12回） ロイヤリティ: 284pt（ゴールド会員） 誕生月: 4月（特典送付予定） ``` ### 5. `square loyalty` — ロイヤリティプログラム ポイント管理、特典設定、会員分析を行います。 ```bash square loyalty status --program loy_pg_1a2b3c4d5e ``` **出力例:** ``` ロイヤリティプログラム状況 ═══════════════════════════════════════════════════════════ プログラム名: はなびカフェ ポイントプログラム ルール: 税抜¥100 につき 1ポイント 会員数: 1,248名 アクティブ率: 72.3%（過去90日以内の利用） 会員ランク分布: ゴールド（500pt以上）: 89名（7.1%） シルバー（200pt以上）: 234名（18.8%） レギュラー: 925名（74.1%） 特典一覧: 1. ドリンク1杯無料 100pt引換 月間利用: 156回 2. フード20%OFF 200pt引換 月間利用: 42回 3. 限定グッズ 500pt引換 月間利用: 8回 月間ポイント発行: 45,230pt（¥4,523,000相当の売上） 月間ポイント消費: 12,800pt 失効予定（3月末）: 3,200pt（対象: 45名） ``` ### 6. `square invoice` — 請求書発行 Squareインボイスを作成・送付します。 ```bash square invoice create --customer CUS-00890 \ --items "ケータリング(30名分):1:150000:10" "配送料:1:5000:10" \ --due-date 2026-03-31 \ --note "法人イベント向けケータリングサービス" ``` **出力例:** ``` 請求書作成完了 請求書ID: SQ-INV-2026-0015 宛先: 株式会社クリエイトワークス（CUS-00890） 発行日: 2026-03-01 支払期限: 2026-03-31 明細: 1. ケータリング(30名分) × 1 = ¥150,000 (税10%) 2. 配送料 × 1 = ¥5,000 (税10%) 小計: ¥155,000 消費税(10%): ¥15,500 合計: ¥170,500 登録番号: T9876543210123 支払方法: カード決済リンク / 銀行振込 送信: メールで請求書リンクを送付しました → keiri@createworks.co.jp オンライン決済URL: https://squareup.com/pay-invoice/SQ-INV-2026-0015 ``` ### 7. `square report` — 売上レポート 多角的な売上分析レポートを生成します。 ```bash square report weekly --week 2026-W09 ``` **出力例:** ``` 週次売上レポート（2026年 第9週: 02/23-03/01） ═══════════════════════════════════════════════════════════ 売上総額: ¥1,892,400 取引件数: 312件 客単価: ¥6,065 前週比: +7.8%（¥1,755,200） 日別推移: ┌─────┬──────────┬──────┬──────────────────────────────┐ │ 日 │ 売上 │ 件数 │ │ ├─────┼──────────┼──────┼──────────────────────────────┤ │ 月 │ 198,300│ 32│ ████████ │ │ 火 │ 215,600│ 35│ █████████ │ │ 水 │ 242,100│ 40│ ██████████ │ │ 木 │ 258,400│ 42│ ██████████ │ │ 金 │ 325,800│ 56│ █████████████ │ │ 土 │ 378,200│ 62│ ███████████████ │ │ 日 │ 274,000│ 45│ ███████████ │ └─────┴──────────┴──────┴──────────────────────────────┘ チャネル別: 対面決済: ¥1,524,300（80.6%） Square Online: ¥268,100（14.2%） インボイス: ¥100,000（5.3%） 決済手数料合計: ¥58,675（売上比 3.10%） 入金済み: ¥1,489,200 入金予定: ¥344,525 ``` ### 8. `square online` — eコマース管理 Square Onlineストアの管理を行います。 ```bash square online orders --status pending --period today ``` **出力例:** ``` Square Online 注文一覧（本日 / 未処理） ┌──────────┬────────────────┬──────────┬──────────┬──────────┐ │ 注文ID │ 顧客名 │ 合計 │ 注文時刻 │ 配送方法 │ ├──────────┼────────────────┼──────────┼──────────┼──────────┤ │ ONL-0089 │ 山本 太郎 │ 4,280 │ 09:45 │ 店舗受取 │ │ ONL-0090 │ 木村 愛 │ 7,650 │ 10:12 │ 配送 │ │ ONL-0091 │ 伊藤 雅人 │ 3,200 │ 10:38 │ 店舗受取 │ │ ONL-0092 │ 松本 由紀 │ 12,400 │ 11:05 │ 配送 │ └──────────┴────────────────┴──────────┴──────────┴──────────┘ 未処理注文: 4件 / 合計: ¥27,530 店舗受取: 2件（準備推奨時刻を過ぎている注文: 0件） 配送: 2件（本日出荷対象: 2件） 次のアクション: ONL-0089 → square online fulfill --order ONL-0089 --ready ONL-0090 → square online ship --order ONL-0090 --tracking JP123456789 ``` --- ## Workflow Diagram ``` ┌──────────────────────────────────────────────────────────────────────┐ │ Square Japan Agent 統合ワークフロー │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ オムニチャネル入口 │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ 対面販売 │ │ Online │ │ 請求書 │ │ 定期販売 │ │ │ │ │ │ POS+端末 │ │ EC注文 │ │ Invoice │ │ サブスク │ │ │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ └─────────────┴─────────────┴─────────────┘ │ │ │ └─────────────────────────┬───────────────────────────────────────┘ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 統合注文管理 │ │ │ │ 注文作成 → 在庫引当 → 決済処理 → ロイヤリティ → 完了 │ │ │ └─────────────────────────┬───────────────────────────────────────┘ │ │ ▼ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ レシート │ │ 在庫同期 │ │ 顧客更新 │ │ 入金追跡 │ │ │ │ インボイス│ │ 全店舗 │ │ 購買履歴 │ │ 翌営業日 │ │ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 日次集計 → 週次分析 → 月次レポート → 会計連携 │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ │ ──── 継続プロセス ───────────────────────────────────── │ │ │ ロイヤリティ運用 │ 在庫最適化 │ 顧客セグメント │ 予測分析 │ │ │ └──────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ ``` --- ## Error Handling ### Error 1: 決済処理失敗 ``` [SQUARE-E001] 決済処理に失敗しました 注文ID: ORD-2026-0301-0048 エラーカテゴリ: PAYMENT_METHOD_ERROR コード: CARD_DECLINED 詳細: カード発行会社が取引を拒否しました 対処: 1. お客様に別の決済手段をご案内してください 2. カードの有効期限・限度額をご確認ください 冪等性キー: idem_20260301_0048_v1（リトライ時に使用） ``` ### Error 2: 在庫不足 ``` [SQUARE-E002] 在庫不足により注文を完了できません 商品: CB-GUA-003 グアテマラ アンティグア（200g袋） 注文数: 3 現在在庫: 1（渋谷本店） 全店在庫: 8（新宿店: 7） 対処: 1. 数量を1に変更して注文 → square pos order update --quantity 1 2. 新宿店在庫から取り寄せ → square inventory transfer --from shinjuku --item CB-GUA-003 --qty 3 3. 注文キャンセル → square pos order cancel --order ORD-2026-0301-0048 ``` ### Error 3: Webhook署名検証失敗 ``` [SQUARE-E003] Webhook署名の検証に失敗しました エンドポイント: /webhooks/square 受信イベント: payment.completed 署名ヘッダー: 不一致 対処: 1. SQUARE_WEBHOOK_SECRET が正しいか確認してください 2. Square Developer DashboardでWebhookの署名キーを再確認してください 3. 不正なリクエストとして記録しました（セキュリティログ参照） ``` ### Error 4: ロケーション未設定 ``` [SQUARE-E004] ロケーションIDが未設定または無効です 設定値: (空) 利用可能ロケーション: L0CATION1D2E3F4G5H6I 渋谷本店 L0CATION7J8K9L0M1N2O 新宿店 対処: SQUARE_LOCATION_ID 環境変数を設定してください 例: export SQUARE_LOCATION_ID="L0CATION1D2E3F4G5H6I" ``` ### Error 5: APIレートリミット ``` [SQUARE-E005] APIレートリミットに到達しました 制限: 20リクエスト/秒（Catalog API） 対処: 15秒後に自動リトライします（指数バックオフ適用） キュー: 残り8件のリクエストが待機中 推奨: バッチAPIを使用してリクエスト数を削減してください → square catalog batch-upsert を使用 ``` ### Error 6: Sandbox/Production環境の不一致 ``` [SQUARE-E006] 環境設定の不一致を検出しました SQUARE_ENVIRONMENT: sandbox SQUARE_ACCESS_TOKEN: 本番トークン（sq0atp- で始まる） 警告: Sandbox環境に本番トークンが設定されています 対処: 1. テスト用: Sandboxトークン（sandbox-sq0atp-）を使用してください 2. 本番用: SQUARE_ENVIRONMENT=production に変更してください 安全措置: 処理を中断しました。データの混在を防止するため設定を修正してください。 ``` --- ## FAQ ### Q1: Squareの初期費用はいくらですか？ Squareのアカウント作成は無料です。Square Reader（カードリーダー）は7,980円（税込）で購入できます。Square TerminalやSquare Standは別途費用がかかりますが、定期的に無料キャンペーンが実施されています。POSアプリは無料です。 ### Q2: 決済手数料はいくらですか？ 対面決済（Square Reader / Terminal / Stand）はVISA・Mastercard・AMEXが3.25%、JCBが3.95%です。電子マネー（Suica、iD、QUICPay等）は3.25%です。オンライン決済は3.6%、請求書決済は3.25%です。PayPayは審査により手数料率が決まります。 ### Q3: 入金はいつ行われますか？ 三井住友銀行・みずほ銀行は翌営業日に自動入金されます。その他の銀行は毎週金曜日に入金されます。振込手数料は無料です。日本のキャッシュレス決済サービスで翌営業日入金はSquareの大きな強みです。 ### Q4: インボイス制度に対応していますか？ 対応しています。`SQUARE_TAX_REGISTRATION` に登録番号を設定することで、レシートと請求書に自動的に記載されます。税率ごとの区分記載、端数処理もインボイス制度の要件に準拠しています。 ### Q5: Square Onlineとの在庫連携はどうなっていますか？ Square POSとSquare Onlineの在庫はリアルタイムで同期されます。対面で売れた商品はオンラインの在庫から自動的に減算され、逆も同様です。在庫切れの商品はオンラインストアで自動的に「売り切れ」表示になります。 ### Q6: ロイヤリティプログラムの設定は自由にできますか？ Square Loyaltyで柔軟に設定できます。ポイント付与ルール（金額ベース、来店ベース、商品ベース）、特典内容（割引、無料商品）、会員ランク制度をカスタマイズ可能です。本スキルからすべての設定をコマンドラインで管理できます。 ### Q7: 他の決済サービスからの移行は簡単ですか？ 商品カタログ、顧客データのCSVインポートに対応しています。`square catalog import --csv products.csv` で一括登録できます。他のPOSシステム（Airレジ、STORES等）からのデータ移行ガイドも提供しています。 ### Q8: Sandbox環境でテストできますか？ `SQUARE_ENVIRONMENT=sandbox` に設定することで、テスト環境で安全に動作確認できます。Sandboxではテスト用のカード番号、架空の取引データで決済フローを検証できます。本番環境に影響は一切ありません。 ### Q9: 複数店舗で使えますか？ Squareは複数ロケーション（店舗）の管理に標準対応しています。各店舗ごとに独立した売上集計、在庫管理、スタッフ管理が可能です。統合レポートで全店舗の横断分析も行えます。 ### Q10: 返金処理はどうしますか？ `square payment refund --payment SQ-PY-0001 --amount 4200 --reason "商品不良"` で全額返金、`--amount 2100` で部分返金が可能です。返金はカード会社経由で顧客に返却され、通常3-5営業日で反映されます。 ### Q11: 会計ソフトとの連携はできますか？ freee、弥生会計、マネーフォワードクラウドへの仕訳データ出力に対応しています。日次の売上データを各会計ソフトのインポート形式で自動エクスポートする機能も提供しています。 ### Q12: PCI DSSへの準拠はどうなっていますか？ Square自体がPCI DSS Level 1認証を取得しており、カード情報はSquareのサーバーで安全に処理されます。Square Japan Agentはカード番号の生データを一切保持せず、トークン化された決済IDのみを扱うため、加盟店側のPCI DSSスコープを最小化できます。 --- ## Data Storage Square Japan Agentのローカルデータは以下のディレクトリ構造で保存されます。 ``` ~/.square-japan/ ├── config/ │ ├── settings.json # エージェント設定 │ ├── locations/ # ロケーション（店舗）設定 │ │ ├── L0CATION1D2E3F4G5H6I.json # 渋谷本店 │ │ └── L0CATION7J8K9L0M1N2O.json # 新宿店 │ ├── loyalty/ # ロイヤリティプログラム設定 │ │ ├── program.json │ │ └── tiers.json │ └── webhooks/ # Webhook設定 │ └── endpoints.json ├── data/ │ ├── payments/ # 決済データ │ │ └── 2026/ │ │ └── 03/ │ │ ├── 01.json │ │ └── ... │ ├── orders/ # 注文データ │ │ └── 2026/ │ │ └── 03/ │ │ ├── ORD-2026-0301-0001.json │ │ └── ... │ ├── catalog/ # 商品カタログ │ │ ├── items.json │ │ ├── categories.json │ │ ├── modifiers.json │ │ └── images/ │ ├── customers/ # 顧客データ（暗号化） │ │ ├── directory.enc │ │ └── segments/ │ │ ├── gold.json │ │ ├── silver.json │ │ └── regular.json │ ├── inventory/ # 在庫データ │ │ ├── current.json # 現在在庫（全ロケーション） │ │ ├── adjustments/ # 在庫調整履歴 │ │ └── transfers/ # 店舗間移動履歴 │ ├── loyalty/ # ロイヤリティデータ │ │ ├── accounts/ │ │ └── redemptions/ │ ├── invoices/ # 請求書データ │ │ ├── SQ-INV-2026-0001.json │ │ └── ... │ ├── online/ # Square Onlineデータ │ │ ├── orders/ │ │ └── fulfillments/ │ ├── settlements/ # 入金データ │ │ └── 2026/ │ │ └── 03/ │ └── reports/ # 生成レポート │ ├── weekly_2026_W09.pdf │ ├── monthly_2026_02.pdf │ └── exports/ │ ├── freee_2026_02.csv │ └── yayoi_2026_02.csv ├── logs/ │ ├── api.log # APIリクエストログ │ ├── payments.log # 決済ログ │ ├── webhook.log # Webhookイベントログ │ ├── security.log # セキュリティログ │ ├── audit.log # 監査ログ │ └── error.log # エラーログ ├── cache/ │ ├── tokens.enc # 認証トークン（暗号化） │ ├── catalog-cache.json # カタログキャッシュ │ └── customer-cache.json # 顧客キャッシュ └── backup/ └── 2026/ ├── 02/ └── 03/ ``` --- ## Comparison Table | 機能 | Square Japan Agent | Airペイ | PayPay | stera terminal | STORES決済 | |------|:---:|:---:|:---:|:---:|:---:| | CLI操作 | 対応 | 非対応 | 非対応 | 非対応 | 非対応 | | Claude Code統合 | 対応 | 非対応 | 非対応 | 非対応 | 非対応 | | POSアプリ | 無料 | 無料 | 非対応 | 有料 | 無料 | | eコマース統合 | Square Online | 非対応 | 非対応 | 非対応 | STORES | | 決済手数料(VISA/MC) | 3.25% | 3.24% | N/A | 3.24% | 3.24% | | 決済手数料(JCB) | 3.95% | 3.24% | N/A | 3.74% | 3.74% | | QRコード決済 | PayPay対応 | 複数対応 | PayPayのみ | 複数対応 | 非対応 | | 電子マネー | 対応 | 対応 | 非対応 | 対応 | 非対応 | | 入金サイクル | 翌営業日/週1 | 月3-6回 | 翌日 | 月2回 | 月末+翌月末 | | 振込手数料 | 無料 | 無料 | 無料 | 銀行による | 200円 | | ロイヤリティ | 標準搭載 | 非対応 | 非対応 | 非対応 | 非対応 | | 請求書発行 | 対応 | 非対応 | 非対応 | 非対応 | 非対応 | | 在庫管理 | 高度 | 基本 | 非対応 | 基本 | 基本 | | 顧客管理 | 高度(CRM) | 基本 | 基本 | 非対応 | 基本 | | 複数店舗 | 対応 | 対応 | 非対応 | 対応 | 対応 | | インボイス対応 | 対応 | 対応 | 対応 | 対応 | 対応 | | API公開度 | 非常に高い | 限定的 | 限定的 | 限定的 | 非対応 | | グローバル展開 | 6カ国 | 日本のみ | 日本中心 | 日本のみ | 日本のみ | | オフライン対応 | 対応 | 対応 | 非対応 | 非対応 | 非対応 | | 会計ソフト連携 | freee/弥生/MF | freee/弥生/MF | 非対応 | 非対応 | freee | Square Japan Agentの最大の強みは、グローバルプラットフォームとしての成熟したAPI基盤、翌営業日入金（三井住友・みずほ）、そしてPOS・eコマース・ロイヤリティ・請求書・在庫・顧客管理を統合した包括的なエコシステムです。APIの公開度が非常に高く、Square Connect v2は200以上のエンドポイントを提供しており、本スキルを通じてこれらすべてをClaude Codeから操作できます。特に対面販売とオンライン販売を統合したオムニチャネル戦略を実現したい事業者にとって、Squareは最適なプラットフォームであり、Square Japan Agentはそのポテンシャルを最大限に引き出すツールです。 --- ## License MIT License - hanabi-jpn