核心用法
squareup 技能提供对 Square 官方 API 的完整代理访问，采用 Maton 托管 OAuth 模式，用户无需自行处理复杂的 OAuth 2.0 授权流程。所有请求通过 https://gateway.maton.ai/squareup/{native-api-path} 转发，自动注入有效的访问令牌。
关键能力覆盖：
- 支付处理：创建、查询、更新、完成及取消付款，支持退款操作
- 客户管理：客户资料的增删改查与高级搜索
- 订单系统：订单创建、更新、批量检索及状态筛选
- 商品目录：商品、分类、变体的批量上下架与搜索
- 库存管理：实时库存查询、批量调整与状态追踪
- 发票服务：发票生成、发布、取消及自动邮件投递
- 商户与门店：多门店位置管理与商户信息获取
认证机制：仅需 Maton API Key（MATON_API_KEY 环境变量），通过 Authorization: Bearer 头部传递。支持多连接管理，可通过 Maton-Connection 头部指定特定 Square 账户。
显著优点
1. 零 OAuth 开发成本：完全托管的 OAuth 生命周期管理，开发者无需维护令牌刷新、权限校验等基础设施
2. 原生 API 透传：路径与请求体保持与 Square 官方 API 100% 一致，可直接参考 Square 官方文档开发
3. 幂等性内置支持：所有写操作原生支持 idempotency_key，天然防止重复扣款或重复创建
4. 多语言示例完备：提供 Bash/Python/JavaScript 三种语言的完整调用示例，降低接入门槛
5. 细粒度权限控制：通过 OAuth Scope 分离权限（CUSTOMERS_READ、ORDERS_WRITE 等），符合最小权限原则
潜在局限与风险
功能边界：
- 依赖 Maton 网关的可用性，存在单点故障风险
- 不支持 Square 的实时 Webhook 推送，需轮询获取状态变更
- 部分高级功能（如分期付款、特定地区的支付方式）受 Square 本身地域限制
使用限制：
- 需要有效的 Square 商户账户并完成 OAuth 授权
- 多连接场景需手动管理
connection_id，缺乏智能路由机制 - 错误码为 Square 原生透传，调试需同时理解 Square 与 Maton 两层错误体系
适合人群
- 中小型企业开发者：需快速集成支付功能但无专职支付安全团队
- SaaS 平台构建者：为多租户提供 Square 支付能力的集成商
- 线下零售数字化：需将传统 POS 数据与线上系统打通的商户
- 财务自动化工具：需批量处理发票、退款、对账的财务软件开发者
常规风险提示
| 风险类型 | 具体表现 | 缓解建议 |
|---------|---------|---------|
| 资金安全 | 支付、退款操作不可逆，误操作可能导致直接财务损失 | 严格测试环境验证；生产环境强制使用幂等键；启用 Square 的邮件确认通知 |
| 数据隐私 | 客户 PII（邮箱、电话）流经第三方网关 | 审查 Maton 数据处理协议；避免在日志中记录敏感字段；定期审计连接权限 |
| 合规风险 | 涉及 PCI-DSS 要求的支付数据处理 | 确认 Maton 网关的 PCI 合规认证；不在自有服务器存储原始卡号 |
| 服务连续性 | Maton 或 Square 服务中断导致支付失败 | 实现降级方案（如离线订单缓存）；监控 API 健康状态；设置超时重试策略 |
| 权限扩散 | OAuth 授权范围过大导致越权操作 | 按需申请最小 Scope；定期审查活跃连接；及时删除废弃连接 |
金额处理特别注意：API 中所有金额单位为最小货币单位（如 USD 的 1000 = $10.00），需在前端/后端进行换算，避免 100 倍金额错误。