介绍
# Square
使用托管的 OAuth 身份验证访问 Square API。处理付款、管理客户、订单、目录项目、库存和发票。
## 快速开始
```bash # List locations python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/squareup/v2/locations') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/squareup/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Square API 端点路径。网关会将请求代理到 `connect.squareup.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Square OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=squareup&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'squareup'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "squareup", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Square 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/squareup/v2/locations') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认的（最旧的）活动连接。
## API 参考
### 地点 (Locations)
#### 列出地点
```bash GET /squareup/v2/locations ```
#### 获取地点
```bash GET /squareup/v2/locations/{location_id} ```
#### 创建地点
```bash POST /squareup/v2/locations Content-Type: application/json
{ "location": { "name": "New Location", "address": { "address_line_1": "123 Main St", "locality": "San Francisco", "administrative_district_level_1": "CA", "postal_code": "94102", "country": "US" } } } ```
#### 更新地点
```bash PUT /squareup/v2/locations/{location_id} Content-Type: application/json
{ "location": { "name": "Updated Location Name" } } ```
### 商户 (Merchants)
#### 获取商户
```bash GET /squareup/v2/merchants/me ```
#### 列出商户
```bash GET /squareup/v2/merchants ```
### 支付 (Payments)
#### 列出支付
```bash GET /squareup/v2/payments ```
使用筛选器：
```bash GET /squareup/v2/payments?location_id={location_id}&begin_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z ```
#### 获取支付
```bash GET /squareup/v2/payments/{payment_id} ```
#### 创建支付
```bash POST /squareup/v2/payments Content-Type: application/json
{ "source_id": "cnon:card-nonce-ok", "idempotency_key": "unique-key-12345", "amount_money": { "amount": 1000, "currency": "USD" }, "location_id": "{location_id}" } ```
#### 更新支付
```bash PUT /squareup/v2/payments/{payment_id} Content-Type: application/json
{ "payment": { "tip_money": { "amount": 200, "currency": "USD" } }, "idempotency_key": "unique-key-67890" } ```
#### 完成支付
```bash POST /squareup/v2/payments/{payment_id}/complete Content-Type: application/json
{} ```
#### 取消支付
```bash POST /squareup/v2/payments/{payment_id}/cancel Content-Type: application/json
{} ```
### 退款 (Refunds)
#### 列出退款
```bash GET /squareup/v2/refunds ```
#### 获取退款
```bash GET /squareup/v2/refunds/{refund_id} ```
#### 创建退款
```bash POST /squareup/v2/refunds Content-Type: application/json
{ "idempotency_key": "unique-refund-key", "payment_id": "{payment_id}", "amount_money": { "amount": 500, "currency": "USD" }, "reason": "Customer requested refund" } ```
### 客户 (Customers)
#### 列出客户
```bash GET /squareup/v2/customers ```
#### 获取客户
```bash GET /squareup/v2/customers/{customer_id} ```
#### 创建客户
```bash POST /squareup/v2/customers Content-Type: application/json
{ "given_name": "John", "family_name": "Doe", "email_address": "[email protected]", "phone_number": "+15551234567" } ```
#### 更新客户
```bash PUT /squareup/v2/customers/{customer_id} Content-Type: application/json
{ "email_address": "[email protected]" } ```
#### 删除客户
```bash DELETE /squareup/v2/customers/{customer_id} ```
#### 搜索客户
```bash POST /squareup/v2/customers/search Content-Type: application/json
{ "query": { "filter": { "email_address": { "exact": "[email protected]" } } } } ```
### 订单 (Orders)
#### 创建订单
```bash POST /squareup/v2/orders Content-Type: application/json
{ "order": { "location_id": "{location_id}", "line_items": [ { "name": "Item 1", "quantity": "1", "base_price_money": { "amount": 1000, "currency": "USD" } } ] }, "idempotency_key": "unique-order-key" } ```
#### 获取订单
```bash GET /squareup/v2/orders/{order_id} ```
#### 更新订单
```bash PUT /squareup/v2/orders/{order_id} Content-Type: application/json
{ "order": { "location_id": "{location_id}", "version": 1 }, "fields_to_clear": ["line_items"] } ```
#### 搜索订单
```bash POST /squareup/v2/orders/search Content-Type: application/json
{ "location_ids": ["{location_id}"], "query": { "filter": { "state_filter": { "states": ["OPEN"] } } } } ```
#### 批量检索订单
```bash POST /squareup/v2/orders/batch-retrieve Content-Type: application/json
{ "location_id": "{location_id}", "order_ids": ["{order_id_1}", "{order_id_2}"] } ```
### 目录 (Catalog)
#### 列出目录
```bash GET /squareup/v2/catalog/list ```
使用类型筛选器：
```bash GET /squareup/v2/catalog/list?types=ITEM,CATEGORY ```
#### 获取目录对象
```bash GET /squareup/v2/catalog/object/{object_id} ```
#### 更新或插入目录对象
```bash POST /squareup/v2/catalog/object Content-Type: application/json
{ "idempotency_key": "unique-catalog-key", "object": { "type": "ITEM", "id": "#new-item", "item_data": { "name": "Coffee", "description": "Hot brewed coffee", "variations": [ { "type": "ITEM_VARIATION", "id": "#small-coffee", "item_variation_data": { "name": "Small", "pricing_type": "FIXED_PRICING", "price_money": { "amount": 300, "currency": "USD" } } } ] } } } ```
#### 删除目录对象
```bash DELETE /squareup/v2/catalog/object/{object_id} ```
#### 批量更新或插入目录对象
```bash POST /squareup/v2/catalog/batch-upsert Content-Type: application/json
{ "idempotency_key": "unique-batch-key", "batches": [ { "objects": [...] } ] } ```
#### 搜索目录对象
```bash POST /squareup/v2/catalog/search Content-Type: application/json
{ "object_types": ["ITEM"], "query": { "text_query": { "keywords": ["coffee"] } } } ```
#### 获取目录信息
```bash GET /squareup/v2/catalog/info ```
### 库存 (Inventory)
#### 检索库存计数
```bash GET /squareup/v2/inventory/{catalog_object_id} ```
#### 批量检索库存计数
```bash POST /squareup/v2/inventory/counts/batch-retrieve Content-Type: application/json
{ "catalog_object_ids": ["{object_id_1}", "{object_id_2}"], "location_ids": ["{location_id}"] } ```
#### 批量变更库存
```bash POST /squareup/v2/inventory/changes/batch-create Content-Type: application/json
{ "idempotency_key": "unique-inventory-key", "changes": [ { "type": "ADJUSTMENT", "adjustment": { "catalog_object_id": "{object_id}", "location_id": "{location_id}", "quantity": "10", "from_state": "NONE", "to_state": "IN_STOCK" } } ] } ```
#### 检索库存调整
```bash GET /squareup/v2/inventory/adjustments/{adjustment_id} ```
### 发票 (Invoices)
#### 列出发票
```bash GET /squareup/v2/invoices?location_id={location_id} ```
#### 获取发票
```bash GET /squareup/v2/invoices/{invoice_id} ```
#### 创建发票
```bash POST /squareup/v2/invoices Content-Type: application/json
{ "invoice": { "location_id": "{location_id}", "order_id": "{order_id}", "primary_recipient": { "customer_id": "{customer_id}" }, "payment_requests": [ { "request_type": "BALANCE", "due_date": "2026-02-15" } ], "delivery_method": "EMAIL" }, "idempotency_key": "unique-invoice-key" } ```
#### 更新发票
```bash PUT /squareup/v2/invoices/{invoice_id} Content-Type: application/json
{ "invoice": { "version": 1, "payment_requests": [ { "uid": "{payment_request_uid}", "due_date": "2026-02-20" } ] }, "idempotency_key": "unique-update-key" } ```
#### 发布发票
```bash POST /squareup/v2/invoices/{invoice_id}/publish Content-Type: application/json
{ "version": 1, "idempotency_key": "unique-publish-key" } ```
#### 取消发票
```bash POST /squareup/v2/invoices/{invoice_id}/cancel Content-Type: application/json
{ "version": 1 } ```
#### 删除发票
```bash DELETE /squareup/v2/invoices/{invoice_id}?version=1 ```
#### 搜索发票
```bash POST /squareup/v2/invoices/search Content-Type: application/json
{ "query": { "filter": { "location_ids": ["{location_id}"], "customer_ids": ["{customer_id}"] } } } ```
## 分页
Square 使用基于游标的分页。当存在更多结果时，列表端点会返回一个 `cursor` 字段：
```bash GET /squareup/v2/payments?cursor={cursor_value} ```
响应包含分页信息：
```json { "payments": [...], "cursor": "next_page_cursor_value" } ```
通过在后续请求中传递游标值来继续获取，直到不再返回游标为止。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/squareup/v2/locations', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/squareup/v2/locations', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
## 注意事项
- 所有金额均以最小货币单位为单位（例如，美元为分：1000 = $10.00） - ID 是字母数字字符串 - 时间戳采用 ISO 8601 格式（例如，`2026-02-07T01:59:28.459Z`） - 大多数写入操作需要 `idempotency_key` 以防止重复操作 - 某些端点需要特定的 OAuth 范围（CUSTOMERS_READ, ORDERS_READ, ITEMS_READ, INVOICES_READ 等） - 重要：使用 curl 命令时，如果 URL 包含方括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递到 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Square 连接或请求错误 | | 401 | Maton API 密钥无效或缺失 | | 403 | OAuth 范围不足 | | 404 | 资源未找到 | | 429 | 速率受限 | | 4xx/5xx | 来自 Square API 的透传错误 |
### 错误响应格式
```json { "errors": [ { "category": "INVALID_REQUEST_ERROR", "code": "NOT_FOUND", "detail": "Could not find payment with id: {payment_id}" } ] } ```
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：应用名称无效
1. 确保您的 URL 路径以 `squareup` 开头。例如：
- 正确：`https://gateway.maton.ai/squareup/v2/locations` - 错误：`https://gateway.maton.ai/v2/locations`
### 故障排除：范围不足
如果您收到包含 `INSUFFICIENT_SCOPES` 的 403 错误，则 OAuth 连接没有所需的权限。创建一个新连接，并确保在 OAuth 授权期间授予所有必要的权限。
## 资源
- [Square API 概览](https://developer.squareup.com/docs) - [Square API 参考](https://developer.squareup.com/reference/square) - [支付 API](https://developer.squareup.com/reference/square/payments-api) - [客户 API](https://developer.squareup.com/reference/square/customers-api) - [订单 API](https://developer.squareup.com/reference/square/orders-api) - [目录 API](https://developer.squareup.com/reference/square/catalog-api) - [库存 API](https://developer.squareup.com/reference/square/inventory-api) - [发票 API](https://developer.squareup.com/reference/square/invoices-api) - [地点 API](https://developer.squareup.com/reference/square/locations-api) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])