Square

简介

Square 的 API 覆盖实体和线上商户的支付、订单、库存、客户等。认证是个人访问令牌（第三方应用用 OAuth）——无令牌请求返回 401（已实测）。

快速开始

目录列表（替换 YOUR_TOKEN）：

curl "https://connect.squareup.com/v2/catalog/list" \
  -H "Authorization: Bearer YOUR_TOKEN"

{ "objects": [], "cursor": "..." }

创建订单：

curl -X POST "https://connect.squareup.com/v2/orders" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Square-Version: 2026-08-19" \
  -d '{"idempotency_key": "unique-key", "order": {"location_id": "LOCATION_ID"}}'

认证方式

• 个人访问令牌：开发者控制台 → Applications → Access Tokens（生产）。
• 第三方应用走 OAuth 流程（Authorization Code + PKCE）。
• 通过 Authorization: Bearer YOUR_TOKEN 携带（缺失 → 401，已实测）。
• 始终设置 Square-Version 请求头为带日期的 API 版本。

速率限制与注意事项

• 限流按应用和端点类别（见文档）。
• 端点：/v2/catalog、/v2/orders、/v2/payments、/v2/customers、/v2/inventory、/v2/locations。
• 沙盒模式：connect.squareupsandbox.com + 沙盒令牌做测试。
• 写端点必须带 idempotency_key。

常见问题

Square API 免费吗？ 无月费；按交易抽成。API 访问免费。

如何获取令牌？ 开发者控制台 → Applications → Access Tokens。

沙盒是什么？ connect.squareupsandbox.com + 沙盒令牌，测试不产生真实扣款。