Square

Square API 与托管 OAuth 集成。处理付款、管理客户、订单、目录、库存、发票、忠诚度计划、团队成员等。 当用户想要接受付款、管理销售点操作、跟踪库存、处理发票、管理忠诚度计划或通过 Square 创建付款链接时，请使用此技能。 对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。 需要网络访问和有效的 Maton API 密钥。

## 概述（中文）

Square API 与托管 OAuth 集成。处理付款、管理客户、订单、目录、库存、发票、忠诚度计划、团队成员等。
当用户想要接受付款、管理销售点操作、跟踪库存、处理发票、管理忠诚度计划或通过 Square 创建付款链接时，请使用此技能。
对于其他第三方应用程序，请使用 api-gateway 技能 (https://clawhub.ai/byungkyu/api-gateway)。
需要网络访问和有效的 Maton API 密钥。

## 原文

# Square

Access the Square API with managed OAuth authentication. Process payments, manage customers, orders, catalog items, inventory, and invoices.

## Quick Start

```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
```

## Base URL

```
https://gateway.maton.ai/squareup/{native-api-path}
```

Replace `{native-api-path}` with the actual Square API endpoint path. The gateway proxies requests to `connect.squareup.com` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Square OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```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
```

### Create Connection

```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
```

### Get Connection

```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
```

**Response:**
```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": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```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
```

### Specifying Connection

If you have multiple Square connections, specify which one to use with the `Maton-Connection` header:

```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
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

### Locations

#### List Locations

```bash
GET /squareup/v2/locations
```

#### Get Location

```bash
GET /squareup/v2/locations/{location_id}
```

#### Create Location

```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"
    }
  }
}
```

#### Update Location

```bash
PUT /squareup/v2/locations/{location_id}
Content-Type: application/json

{
  "location": {
    "name": "Updated Location Name"
  }
}
```

### Merchants

#### Get Merchant

```bash
GET /squareup/v2/merchants/me
```

#### List Merchants

```bash
GET /squareup/v2/merchants
```

### Payments

#### List Payments

```bash
GET /squareup/v2/payments
```

With filters:

```bash
GET /squareup/v2/payments?location_id={location_id}&begin_time=2026-01-01T00:00:00Z&end_time=2026-02-01T00:00:00Z
```

#### Get Payment

```bash
GET /squareup/v2/payments/{payment_id}
```

#### Create Payment

```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}"
}
```

#### Update Payment

```bash
PUT /squareup/v2/payments/{payment_id}
Content-Type: application/json

{
  "payment": {
    "tip_money": {
      "amount": 200,
      "currency": "USD"
    }
  },
  "idempotency_key": "unique-key-67890"
}
```

#### Complete Payment

```bash
POST /squareup/v2/payments/{payment_id}/complete
Content-Type: application/json

{}
```

#### Cancel Payment

```bash
POST /squareup/v2/payments/{payment_id}/cancel
Content-Type: application/json

{}
```

### Refunds

#### List Refunds

```bash
GET /squareup/v2/refunds
```

#### Get Refund

```bash
GET /squareup/v2/refunds/{refund_id}
```

#### Create Refund

```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

#### List Customers

```bash
GET /squareup/v2/customers
```

#### Get Customer

```bash
GET /squareup/v2/customers/{customer_id}
```

#### Create Customer

```bash
POST /squareup/v2/customers
Content-Type: application/json

{
  "given_name": "John",
  "family_name": "Doe",
  "email_address": "john.doe@example.com",
  "phone_number": "+15551234567"
}
```

#### Update Customer

```bash
PUT /squareup/v2/customers/{customer_id}
Content-Type: application/json

{
  "email_address": "john.updated@example.com"
}
```

#### Delete Customer

```bash
DELETE /squareup/v2/customers/{customer_id}
```

#### Search Customers

```bash
POST /squareup/v2/customers/search
Content-Type: application/json

{
  "query": {
    "filter": {
      "email_address": {
        "exact": "john.doe@example.com"
      }
    }
  }
}
```

### Orders

#### Create Order

```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"
}
```

#### Get Order

```bash
GET /squareup/v2/orders/{order_id}
```

#### Update Order

```bash
PUT /squareup/v2/orders/{order_id}
Content-Type: application/json

{
  "order": {
    "location_id": "{location_id}",
    "version": 1
  },
  "fields_to_clear": ["line_items"]
}
```

#### Search Orders

```bash
POST /squareup/v2/orders/search
Content-Type: application/json

{
  "location_ids": ["{location_id}"],
  "query": {
    "filter": {
      "state_filter": {
        "states": ["OPEN"]
      }
    }
  }
}
```

#### Batch Retrieve Orders

```bash
POST /squareup/v2/orders/batch-retrieve
Content-Type: application/json

{
  "location_id": "{location_id}",
  "order_ids": ["{order_id_1}", "{order_id_2}"]
}
```

#### P