核心用法
Square技能通过Maton代理服务接入Square官方API，提供完整的商户管理能力。用户需先在Maton平台获取API密钥，创建OAuth连接完成授权，随后即可通过统一端点https://api.maton.ai/squareup/{path}调用Square原生API。
技能采用双重认证架构：Maton API Key作为服务层凭证，Square OAuth Token作为资源层凭证，由代理自动注入。支持多连接管理，可通过Maton-Connection头指定目标商户账户。
覆盖业务范围
- 核心交易：支付处理、退款、发票管理、在线收款链接
- 商品运营：目录管理、库存调整、定价配置
- 客户关系：客户档案、会员卡、积分累积
- 组织管理：门店位置、团队成员权限
- 财务结算：提现记录、银行账户、终端设备
显著优点
1. 托管OAuth简化授权：无需自行搭建OAuth流程，Maton处理令牌生命周期
2. 原生API完整透传：保留Square官方端点结构与响应格式，文档可直接复用
3. 多账户灵活切换：单API Key管理多商户连接，适合代运营场景
4. 幂等性内置支持：所有写操作支持idempotency_key，防止重复提交
潜在缺点与局限性
1. 网络依赖单点：完全依赖Maton代理服务可用性，无直连Square的降级方案
2. 权限粒度受限：OAuth scope由Square授权页面控制，Maton侧无法动态调整
3. 延迟与限速叠加：Maton层+Square层双重限速，高频场景需特别注意
4. 服务商锁定风险：业务数据流经Maton中转，长期绑定增加迁移成本
适合人群
- Square商户的技术管理员或代运营服务商
- 需要自动化报表、批量库存调整、订单同步的中小企业
- 构建内部BI工具或财务对账系统的开发者
常规风险
- 财务操作不可逆：支付、退款、发票发布等动作直接影响资金流动，误操作可能导致实际损失
- OAuth令牌泄露：连接URL包含会话令牌，浏览器历史或日志泄露可导致账户接管
- 权限膨胀：Square授权页默认勾选较多权限，用户可能过度授权
- 环境变量暴露：脚本示例中
MATON_API_KEY若写入代码仓库存在泄露风险
安全设计要点
技能文档反复强调最小权限原则：建议默认只读操作、写操作前展示目标资源详情、获取用户显式确认。支付等敏感操作需额外说明金额、账户、影响范围。