核心用法
Square技能通过Maton API网关提供托管式OAuth接入，开发者仅需配置MATON_API_KEY环境变量即可调用Square完整生态API。支持支付处理（Payments）、客户管理（Customers）、订单系统（Orders）、商品目录（Catalog）、库存追踪（Inventory）、发票管理（Invoices）、团队权限（Team Members）、会员忠诚计划（Loyalty）、在线支付链接（Payment Links）及终端设备（Terminal）等全链路功能。
典型工作流
1. 连接配置：通过Maton连接管理界面完成Square OAuth授权，获取connection_id
2. 业务调用：在请求头中携带Authorization: Bearer $MATON_API_KEY，多账户场景追加Maton-Connection头部指定目标商户
3. 数据交互：所有金额以最小货币单位传输（如USD的cents），时间戳采用ISO 8601格式
显著优点
- 零OAuth开发成本：Maton托管令牌生命周期，免除开发者处理授权码交换、令牌刷新及密钥存储的安全负担
- 统一网关接入：单一API密钥对接Square全量API，支持多商户账户灵活切换
- 完备业务覆盖：从支付收款、退款、发票到库存调整、会员积分累积，覆盖零售/餐饮/服务业核心场景
- 幂等性保障：关键写操作（支付、订单、退款）强制要求
idempotency_key，天然防重放攻击 - 标准化错误体系：400-429状态码分层提示连接缺失、密钥失效、权限不足、限流等状态
潜在局限
- 网络依赖性强：必须实时连通
api.maton.ai，无法离线或私有化部署 - 功能代理延迟：请求经Maton转发至Square，理论延迟高于直连Square官方API
- 权限粒度受限：实际权限取决于OAuth授权时用户勾选范围，存在
INSUFFICIENT_SCOPES风险 - 货币单位易错：金额需手动转换（如$10→1000），缺乏高层级货币对象封装
适合人群
- 中小商户技术团队：无专职支付开发资源，需快速上线收款、发票、库存系统
- SaaS服务商：为下游商户提供多租户 Square 集成能力
- 自动化财务工作流：需批量处理退款、生成发票、同步库存数据的后台作业
- 线下+线上融合场景：同时使用Square Terminal硬件与自建在线支付链接的混合业态
常规风险
| 风险类型 | 说明 | 缓释建议 |
|---------|------|---------|
| **密钥泄露** | `MATON_API_KEY`泄露可导致账户被滥用 | 禁止硬编码，使用密钥管理服务或环境变量注入 |
| **误操作支付** | 写操作需人工复核，但自动化脚本可能绕过确认 | 生产环境配置操作审计日志，敏感操作启用双人复核 |
| **多账户混淆** | 未指定`Maton-Connection`时行为未明确定义 | 始终显式传递连接ID，禁止依赖默认行为 |
| **OAuth令牌失效** | 用户撤销授权或令牌过期导致服务中断 | 建立连接状态监控告警，前置重授权流程 |
| **金额换算错误** | 小数点处理失误造成资损（如传入100而非10000） | 封装货币转换层，单元测试覆盖边界值 |
架构示意图
[用户应用] → HTTPS → api.maton.ai/squareup/v2/*
↓
[Maton网关: OAuth注入]
↓
connect.squareup.com该技能本质上是Square生态的安全代理层，在降低集成门槛的同时，要求使用者理解支付系统的幂等性、货币精度及OAuth授权边界等核心概念。