核心用法
Square 技能通过 Maton 网关代理所有 Square API 请求，开发者无需直接处理 OAuth 令牌刷新与存储。用户需先在 maton.ai 获取 API Key，通过 MATON_API_KEY 环境变量认证，再在 ctrl.maton.ai 完成 Square 账户的 OAuth 授权。所有请求经 https://gateway.maton.ai/squareup/{native-api-path} 转发，网关自动注入有效 OAuth Token。
支持的 API 覆盖 Square 核心商业场景：
- 支付：创建/取消/完成付款、退款处理
- 客户：CRUD 操作与高级搜索
- 订单：创建、更新、批量查询
- 商品目录：ITEM/CATEGORY 等对象管理
- 库存：实时库存查询与批量调整
- 发票：创建、发布、取消及发送
- 门店：多地点管理与商户信息
显著优点
1. 零运维 OAuth：Maton 托管令牌生命周期，开发者无需实现刷新逻辑或安全存储
2. 原生 API 透传：完整支持 Square 官方 API 语义，无功能裁剪，文档可直接复用
3. 多账户支持：通过 Maton-Connection Header 可在同一 API Key 下切换多个 Square 商户账户
4. 幂等性内置：写入操作强制要求 idempotency_key，天然防重放
潜在缺点与局限
- 网络依赖：必须外访 Maton 网关与 Square 服务，无法离线使用
- 速率限制：受 Square API 本身限流策略约束，高频场景需自行实现退避
- 权限粒度：OAuth Scope 需在授权时一次性勾选，后期调整需重新授权
- 数据延迟：库存/支付状态变更存在秒级同步延迟，非实时强一致性
- 地域限制：Square 服务本身在部分国家/地区不可用，需确认商户注册地支持
适合人群
- 快速集成支付能力的 SaaS 创业者与中小商户
- 需要将 Square 数据与内部 ERP/CRM 打通的开发者
- 无专职运维团队、希望外包 OAuth 安全管理的项目
- 多门店/多商户管理的平台型应用
常规风险
| 风险类型 | 说明 | 缓释建议 |
|---------|------|---------|
| 密钥泄露 | `MATON_API_KEY` 泄露可导致 Square 数据被窃取 | 使用环境变量注入，禁止硬编码；定期轮换密钥 |
| 越权访问 | 多账户场景下错误指定 Connection ID 可能操作错误商户 | 调用前显式校验 Connection ID 归属 |
| 重复支付 | 幂等键复用或生成逻辑缺陷导致资金损失 | 使用 UUID 或业务唯一标识生成 idempotency_key |
| 合规风险 | 处理信用卡数据需满足 PCI-DSS 要求 | 确认 Square 托管支付表单，不自行触碰敏感卡数据 |