# SpendPermit 中文完整指南

[返回首页](../README.md) · [English guide](USAGE.en.md) · [打开产品](https://sp.gdlg.ai/individual-card) · [机器合同](../llms.txt)

## 1. 产品模型

SpendPermit 为一笔由人确认的商业采购创建短期、精确限额的虚拟卡。用户不需要注册完整 Card Portal 账户。

AI Agent 可以准备采购，但最终花钱的人仍然负责授权：

1. Agent 获取 SpendPermit 报价，说明金额和卡片策略。
2. 用户确认后，亲自完成 SpendPermit 托管付款。
3. SpendPermit 在服务端核验付款，并记录不可变的采购授权。
4. SpendPermit 发卡，设置精确累计额度和绝对到期时间。
5. Agent 只查询 SpendPermit；用户明确要求时才领取机器可读卡片资料。

Access Key 负责识别客户和订单归属，不能批准一张未付款的正式卡片。
核验成功的人的付款才是这笔采购的授权。

## 2. 适合与不适合

适合：

- AI Agent 已准备好一笔获批准的线上商业采购。
- 知道安全最高预算，但税费、运费、汇率或最终 Capture 还不确定。
- 企业不希望向 Agent 暴露可长期复用的公司卡。
- 金额在 USD 25 至 USD 100，并能在 24 小时内完成。

不适合：

- 个人、家庭或日常消费。
- 订阅、免费试用、周期扣款或多笔采购。
- 酒店、租车、押金、加油站、分批发货和增量授权。
- 选择 `SINGLE_USE`，但商户很可能在失败后重试。
- 任何规避身份、商户、合规或银行控制的用途。

第一次使用前，请阅读[真实场景与反例](SCENARIOS.md)。

## 3. Access Key 与安全

向 SpendPermit 操作人员取得每个客户独立的 `SPENDPERMIT_API_KEY`。它有明确 scope 和额度限制，可以单独限流、轮换、暂停和撤销，只能访问属于该客户的订单。

macOS/Linux：

```bash
export SPENDPERMIT_API_KEY="<issued-access-key>"
```

PowerShell：

```powershell
$env:SPENDPERMIT_API_KEY = "<issued-access-key>"
```

不要把密钥写进源码、Prompt、截图、shell history、日志或公开仓库。本仓库和 CLI 不包含支付、发卡、银行、Webhook、云端、Admin 或内部任务 credential。

## 4. 付款通道与使用模式

只使用产品级通道名称：

- `ALIPAY`：托管支付宝付款。
- `CARD`：托管国际银行卡付款。
- `MOCK`：受控 TEST 专用批准流程。

始终先调用 `capabilities`；文档中的通道也可能暂时不可用。

使用模式：

- `SINGLE_USE`：默认。第一次授权尝试后关闭，包括成功、拒绝或 dropped attempt。
- `SESSION_24H`：只有 capabilities 返回时可用。多次尝试共享一个累计本金上限。

两种模式都不晚于绝对 24 小时到期点关闭。周卡、月卡和持续 Agent Card 仍是路线图，不是当前功能。

## 5. 网页流程

1. 打开 <https://sp.gdlg.ai/individual-card>。
2. 输入私密 SpendPermit Access Key。服务端将其交换为安全浏览器会话，明文密钥不会进入 URL 或 cookie。
3. 选择金额、当前可用的付款通道和模式。
4. 查看本金、应付总额、手续费、使用规则和到期时间。
5. 创建付款并保存订单号。
6. 在托管页面亲自完成付款。
7. 返回状态页。不要因为 callback 延迟而重复付款。
8. 卡片就绪后，通过受保护网页或显式 CLI claim 领取。
9. 完成后结束浏览器访问会话。

如果不再采购，应在付款核验前取消。取消后永远不要再使用旧付款链接。

## 6. CLI 流程

CLI 需要 Node.js 18 或更新版本，可运行在 Windows、macOS 和 Linux。

```bash
node cli/spend-permit.mjs capabilities
node cli/spend-permit.mjs quote 25 --channel alipay --mode single-use
node cli/spend-permit.mjs checkout 25 --channel alipay --mode single-use
```

保存 `order.id`。用户亲自完成 `order.payment.checkoutUrl`，Agent 和 CLI 只查询 SpendPermit：

```bash
node cli/spend-permit.mjs status ORDER_ID
node cli/spend-permit.mjs wait ORDER_ID
```

取消未付款订单：

```bash
node cli/spend-permit.mjs cancel ORDER_ID
```

到达 `CARD_READY` 后，明确领取机器可读资料：

```bash
node cli/spend-permit.mjs claim ORDER_ID --reveal-card
```

claim 命令会先取得短时 capability，再执行带认证的 POST；它不使用永久 claim URL。不要把结果写入日志、Issue、源码仓库或共享聊天。

## 7. 公开 API

所有请求都带：

```http
Authorization: Bearer <SPENDPERMIT_API_KEY>
```

端点：

```text
GET  /api/v1/agent-cards/capabilities
POST /api/v1/agent-cards/quote
POST /api/v1/agent-cards/orders
GET  /api/v1/agent-cards/orders/{orderId}
POST /api/v1/agent-cards/orders/{orderId}/cancel
POST /api/v1/agent-cards/orders/{orderId}/claim
```

创建订单必须提供稳定的 `Idempotency-Key`。请求结果不确定时复用同一个值；在恢复原订单或确认不存在之前，不要生成新 key。

不要调用旧 API、callback、internal、Admin、退款或维护端点。

## 8. 状态

| 状态 | 含义 | 下一步 |
| --- | --- | --- |
| `WAITING_FOR_PAYMENT` | 等待用户付款 | 返回托管链接并等待 |
| `PREPARING_CARD` | 已核验付款，正在准备卡片 | 只查询 SpendPermit |
| `CARD_READY` | 可取得短时 claim capability | 明确同意后领取 |
| `PAYMENT_REVIEW` | 付款证据冲突 | 停止，不要再付，联系客服 |
| `CLOSING` | 卡片不可用，正在清理 | 等待 |
| `CANCELLED` | 未付款订单已取消 | 不再使用旧链接 |
| `CLOSED` / `EXPIRED` / `FAILED` | 已终止 | 不再领卡或使用 |

`quote`、`checkout`、`status` 和 `wait` 都不返回 PAN 或 CVV。

## 9. 退款边界

卡片本金是 maximum purchase budget，并不代表商户必须结算全部金额。一次性卡第一次尝试后，不能把剩余额度用于第二笔消费。

系统会在原始 24 小时审核点核对最终清算、待处理授权、卡片关闭和付款证据。当前标准保留 5% 付款处理费和 USD 2 发卡成本。

例子：本金 USD 100，最终净结算 USD 70，`unusedPrincipalCents` 为 3000；经过证据审核和 Admin 批准后，标准预计退款为 USD 28。退款只原路返回，在审核完成前并不即时或保证到账。

TEST 订单没有外部付款，因此不能退款。

## 10. 错误处理

- `401`：credential 缺失或无效；不要让用户把密钥贴到聊天中。
- `403`：客户暂停、scope 不足、环境不符或动作不允许；停止。
- `404 ORDER_NOT_FOUND`：订单不存在或不属于当前客户。
- `409`：重复请求、订单状态冲突或付款审核；保存 ID，停止危险重试。
- `429`：遵守 `Retry-After`。
- `503`：产品、通道、安全配置或 session 控制尚不可用。

## 11. TEST 流程

测试通道要求 TEST Access Key 具有 `test:bypass` scope，并使用操作人员为该客户和最大金额私下签发的短时一次性 approval code。

```bash
export SPENDPERMIT_TEST_APPROVAL_CODE="<single-use-test-approval>"
node cli/spend-permit.mjs checkout 10 --channel bypass
```

不存在共享 master code。第一次成功创建订单时会原子消耗批准码，重复使用会被拒绝；没有外部付款，也就没有退款。