核心用法
Square技能提供完整的Square商业平台API接入能力，通过Maton网关代理访问Square生态。核心架构为：用户→Maton API→自动注入OAuth令牌→Square官方API。支持全量商户运营场景：支付处理（Payments/Refunds/Terminal）、订单管理（Orders/Invoices）、商品目录（Catalog/Inventory）、客户关系（Customers/Loyalty/Cards）、团队协作（Team Members）、财务结算（Payouts/Bank Accounts）及线上收款（Payment Links）。
接入流程：获取Maton API Key → 创建Square OAuth连接 → 浏览器完成授权 → 调用特定端点。所有请求需携带Authorization: Bearer $MATON_API_KEY头部，多账户场景需额外指定Maton-Connection头部。
显著优点
1. OAuth托管零运维：Maton自动处理令牌刷新与存储，开发者无需维护OAuth 2.0基础设施
2. 全功能覆盖：涵盖Square 12+核心API领域，从支付终端（Terminal）到发票系统（Invoices）完整支持
3. 幂等性内置：写入操作强制要求idempotency_key，天然防重复提交
4. 金融级安全设计：明确区分读写权限，所有写操作强制要求显式用户确认、资源预校验、后果说明三重防护
5. 多租户友好：通过Connection ID机制支持同一Maton账户管理多个Square商户
潜在缺点与局限性
- 数据变更风险：具备支付取消、库存调整、客户删除等破坏性操作，误操作可能导致资金损失
- OAuth范围依赖：实际可用功能受授权时勾选的scope限制，创建连接后无法动态扩展权限
- 网关单点：所有流量经Maton中转，存在供应商锁定风险
- 无实时Webhook：文档未提及事件回调能力，需轮询获取状态变更
- 货币单位易错：金额以最小单位（美分）传递，1000=$10.00的换算易引发计算错误
适合人群
- 电商/零售商户：需要程序化库存同步、批量订单处理
- 财务运营团队：自动化发票生成、退款处理、对账报表
- SaaS集成商：为下游客户提供Square支付能力的技术服务商
- 多门店管理者：统一API接口管理分散的Square Location
常规风险
| 风险类型 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 密钥泄露 | MATON_API_KEY硬编码或日志打印 | 严格使用环境变量，异常时立即轮换 |
| 越权操作 | 使用高权限账户执行非必要写操作 | 始终坚持最小权限原则，及时revoke闲置连接 |
| 资金误操作 | 错误金额、错误账户的退款/支付 | 执行前强制二次确认，预展示客户名+金额+位置 |
| 连接混淆 | 多账户场景下请求误发到错误商户 | 强制使用`Maton-Connection`头部显式指定 |
| 幂等键冲突 | 重复使用idempotency_key导致意外行为 | 确保业务键唯一性（UUID+时间戳+业务ID） |
关键红线：任何影响资金的操作（支付、退款、发票发布）必须在执行前向用户完整陈述：操作类型、金额、目标账户/客户、不可逆后果，并获得明确文字确认（非默认同意）。