核心用法
Square Skill 是 Maton 提供的官方 Square API 代理网关，采用托管 OAuth 2.0 认证模式，让开发者无需自建授权服务器即可调用 Square 全栈商业 API。用户通过 gateway.maton.ai 统一入口访问，所有请求自动注入 Square 访问令牌，基础认证仅需 MATON_API_KEY 环境变量。
主要功能模块：
- 支付处理：创建/取消/完成付款、退款管理、小费调整
- 订单管理：订单创建、状态追踪、批量查询、字段更新
- 客户管理：CRUD 操作、邮箱/电话搜索、客户资料维护
- 商品目录：商品/变体/分类的增删改查、批量 upsert
- 库存控制：实时库存计数、批量调整、库存变更记录
- 发票系统：创建账单、设置付款期限、发布/取消/删除发票
- 门店管理：多门店支持、位置信息维护
技术特点：
- 原生兼容 Square API 路径结构，学习成本低
- 支持 cursor 分页，处理大数据集无压力
- 幂等键（idempotency_key）机制防止重复操作
- 多连接管理，支持多商户/多门店场景
显著优点
1. 零 OAuth 运维：连接托管在 ctrl.maton.ai，自动处理令牌刷新与失效，开发者只需关注业务逻辑
2. 统一网关：单一域名访问 Square 全功能，避免直连 connect.squareup.com 的跨区域延迟与 IP 白名单问题
3. 精细权限控制：OAuth scope 粒度匹配 Square 官方标准（CUSTOMERS_READ/WRITE、ORDERS_READ/WRITE 等），最小权限原则
4. 多语言示例完备：bash、Python、JavaScript 代码片段开箱即用
5. 错误透传友好：Square 原生错误格式完整保留，便于调试
潜在缺点与局限性
- 网络依赖强：必须保持外网访问，无法离线使用
- 第三方中间层风险：Maton 网关故障将直接影响 Square 调用，存在单点依赖
- 功能边界限制：仅为代理层，不支持 Square 硬件（读卡器、POS 终端）直连控制
- 费率不透明：文档未说明 Maton 是否收取额外网关费用，需自行确认
- OAuth 授权步骤不可省略：首次使用仍需浏览器跳转完成 Square 授权，无法纯 API 自动化开户
适合人群
- 需要快速集成 Square 支付但不想自建 OAuth 服务的 SaaS 开发者
- 多平台运营、需统一管理 Square/Stripe 等多支付渠道的电商平台
- 使用 AI Agent 或自动化脚本处理发票、库存的后台运营团队
- 中小商户自建会员系统、需要同步 Square 客户与订单数据的技术人员
常规风险
- 密钥泄露风险：
MATON_API_KEY泄露将导致所有 Square 连接被滥用，务必环境变量管理 - 资金操作不可逆：支付、退款、发票发布直接关联真实资金，测试环境务必使用 Square Sandbox
- Scope 权限过大：连接创建时若授权过多 scope，可能暴露敏感商户数据
- 幂等键冲突：生产环境中 idempotency_key 若重复生成，可能导致意料外的幂等拦截