核心用法
本Skill提供完整的Square API集成能力，通过Maton API网关实现托管式OAuth认证。用户需先获取Maton API密钥并设置MATON_API_KEY环境变量，然后通过Maton的连接管理接口创建Square OAuth连接。支持的核心功能包括：门店管理（Locations）、支付处理（Payments）、客户管理（Customers）、订单管理（Orders）、商品目录（Catalog）、库存管理（Inventory）、发票管理（Invoices）、会员管理（Loyalty）、在线支付链接（Payment Links）、终端设备（Terminal）等全链路Square生态操作。
使用流程分为三步：首先通过POST /connections创建OAuth连接并浏览器完成授权；然后使用生成的连接ID通过Maton-Connection请求头指定目标账户；最后调用各业务端点执行读写操作。所有请求需携带Bearer Token认证的Maton API密钥，写操作需提供幂等键（idempotency_key）防止重复提交。
显著优点
1. OAuth托管简化：无需自建OAuth服务，Maton统一处理令牌刷新与安全管理
2. 全功能覆盖：支持Square全量核心API，从基础门店查询到复杂支付退款、库存调整、会员积分累积
3. 多账户管理：支持多个Square连接并行，通过请求头灵活切换目标商户
4. 安全设计完善：内置最小权限原则指引、写操作强制二次确认要求、财务操作额外警示
5. 企业级特性：支持终端设备管理、批量操作、分页查询、幂等性保障
潜在缺点与局限性
1. 双重依赖风险：需同时维护Maton与Square两个平台的可用性，任一方服务中断将影响功能
2. 权限配置复杂：Square OAuth scopes粒度较细，初次配置需理解各权限的业务含义
3. 无实时事件：当前为REST API轮询模式，无WebSocket或回调机制支持实时支付状态推送
4. 费率叠加：可能产生Maton网关与Square本身的双重API调用成本
5. 地域限制：Square服务有地域限制，部分功能在特定国家/地区不可用
适合的目标群体
- 中小型商户：需要自动化Square后台管理的电商、零售、餐饮商家
- 财务运营团队：需批量处理退款、发票、对账的财务人员
- SaaS集成商：为客户搭建Square支付能力的ISV或系统集成商
- 开发运维人员：需要程序化管理多门店、库存、会员的技术团队
- 不适合：纯个人消费者、无Square商户账户的用户、仅需简单收款码的场景
常规使用风险
1. 密钥泄露风险：MATON_API_KEY泄露将导致Square数据被非法访问，需严格环境变量管理并定期轮换
2. 资金操作风险：支付、退款、发票发布等操作直接影响资金流，误操作可能导致财务损失
3. 权限过度授予：OAuth授权时若未最小化scope，可能导致数据暴露范围扩大
4. 幂等性误用：idempotency_key重复使用或生成不当可能导致重复扣款或订单创建
5. API限流影响：Square与Maton均有速率限制，高频调用可能触发429错误影响业务连续性
6. 合规责任：处理支付卡行业数据（PCI）时需确保符合Square合规要求，Skill本身不提供合规兜底