github/sub2api
1
0
Fork 0
mirror of https://github.com/Wei-Shaw/sub2api.git synced 2026-03-30 16:10:45 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(admin): add create-and-redeem API and payment integration docs

Browse Source
This commit is contained in:
erio
2026-03-01 00:41:38 +08:00
parent 81903e87e3
commit 7af00864b3
1 changed files with 59 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
ADMIN_PAYMENT_INTEGRATION_API.md
View File

@@ -1,159 +1,35 @@
# ADMIN_PAYMENT_INTEGRATION_API
# Sub2API Admin API: Payment Integration
> 单文件中英双语文档 / Single-file bilingual documentation (Chinese + English)
This document describes the minimum Admin API surface for external payment systems (for example, sub2apipay) to complete balance top-up and reconciliation.
---
## Base URL
## 中文
### 目标
本文档用于对接外部支付系统（如 `sub2apipay`）与 Sub2API 的 Admin API，覆盖：
- 支付成功后充值
- 用户查询
- 人工余额修正
- 前端购买页参数透传
### 基础地址
- 生产：`https://<your-domain>`
- Beta：`http://<your-server-ip>:8084`
### 认证
推荐使用：
- `x-api-key: admin-<64hex>`
- `Content-Type: application/json`
- 幂等接口额外传：`Idempotency-Key`
说明：管理员 JWT 也可访问 admin 路由，但服务间调用建议使用 Admin API Key。
### 1) 一步完成创建并兑换
`POST /api/v1/admin/redeem-codes/create-and-redeem`
用途：原子完成“创建兑换码 + 兑换到指定用户”。
请求头：
- `x-api-key`
- `Idempotency-Key`
请求体示例：
```json
{
"code": "s2p_cm1234567890",
"type": "balance",
"value": 100.0,
"user_id": 123,
"notes": "sub2apipay order: cm1234567890"
}
```
幂等语义：
- 同 `code` 且 `used_by` 一致：`200`
- 同 `code` 但 `used_by` 不一致：`409`
- 缺少 `Idempotency-Key`：`400`（`IDEMPOTENCY_KEY_REQUIRED`）
curl 示例：
```bash
curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \
-H "x-api-key: ${KEY}" \
-H "Idempotency-Key: pay-cm1234567890-success" \
-H "Content-Type: application/json" \
-d '{
"code":"s2p_cm1234567890",
"type":"balance",
"value":100.00,
"user_id":123,
"notes":"sub2apipay order: cm1234567890"
}'
```
### 2) 查询用户（可选前置校验）
`GET /api/v1/admin/users/:id`
```bash
curl -s "${BASE}/api/v1/admin/users/123" \
-H "x-api-key: ${KEY}"
```
### 3) 余额调整（已有接口）
`POST /api/v1/admin/users/:id/balance`
用途：人工补偿 / 扣减，支持 `set` / `add` / `subtract`。
请求体示例（扣减）：
```json
{
"balance": 100.0,
"operation": "subtract",
"notes": "manual correction"
}
```
```bash
curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
-H "x-api-key: ${KEY}" \
-H "Idempotency-Key: balance-subtract-cm1234567890" \
-H "Content-Type: application/json" \
-d '{
"balance":100.00,
"operation":"subtract",
"notes":"manual correction"
}'
```
### 4) 购买页 URL Query 透传（iframe / 新窗口一致）
当 Sub2API 打开 `purchase_subscription_url` 时，会统一追加：
- `user_id`
- `token`
- `theme`（`light` / `dark`）
- `ui_mode`（固定 `embedded`）
示例：
```text
https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&ui_mode=embedded
```
### 5) 失败处理建议
- 支付成功与充值成功分状态落库
- 回调验签成功后立即标记“支付成功”
- 支付成功但充值失败的订单允许后续重试
- 重试保持相同 `code`，并使用新的 `Idempotency-Key`
### 6) `doc_url` 配置建议
- 查看链接：`https://github.com/Wei-Shaw/sub2api/blob/main/ADMIN_PAYMENT_INTEGRATION_API.md`
- 下载链接：`https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`
---
## English
### Purpose
This document describes the minimal Sub2API Admin API surface for external payment integrations (for example, `sub2apipay`), including:
- Recharge after payment success
- User lookup
- Manual balance correction
- Purchase page query parameter forwarding
### Base URL
- Production: `https://<your-domain>`
- Beta: `http://<your-server-ip>:8084`
### Authentication
Recommended headers:
- `x-api-key: admin-<64hex>`
- `Content-Type: application/json`
- `Idempotency-Key` for idempotent endpoints
All endpoints below use:
Note: Admin JWT can also access admin routes, but Admin API Key is recommended for server-to-server integration.
- Header: `x-api-key: admin-<64hex>` (recommended for server-to-server)
- Header: `Content-Type: application/json`
Note: Admin JWT is also accepted by admin routes, but machine-to-machine integration should use admin API key.
## 1) Create + Redeem in One Step
### 1) Create and Redeem in one step
`POST /api/v1/admin/redeem-codes/create-and-redeem`
Use case: atomically create a redeem code and redeem it to a target user.
Purpose:
- Atomically create a deterministic redeem code and redeem it to a target user.
- Typical usage: called after payment callback succeeds.
Required headers:
Headers:
- `x-api-key`
- `Idempotency-Key`
Request body:
```json
{
"code": "s2p_cm1234567890",
@@ -164,12 +40,21 @@ Request body:
}
```
Idempotency behavior:
- Same `code` and same `used_by`: `200`
- Same `code` but different `used_by`: `409`
- Missing `Idempotency-Key`: `400` (`IDEMPOTENCY_KEY_REQUIRED`)
Rules:
- `code`: external deterministic order-mapped code.
- `type`: currently recommended `balance`.
- `value`: must be `> 0`.
- `user_id`: target user id.
Idempotency semantics:
- Same `code`, same `used_by` user: return `200` (idempotent replay).
- Same `code`, different `used_by` user: return `409` conflict.
- Missing `Idempotency-Key`: return `400` (`IDEMPOTENCY_KEY_REQUIRED`).
Example:
curl example:
```bash
curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \
-H "x-api-key: ${KEY}" \
@@ -184,20 +69,32 @@ curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \
}'
```
### 2) Query User (optional pre-check)
## 2) Query User (Optional Pre-check)
`GET /api/v1/admin/users/:id`
Purpose:
- Check whether target user exists before payment finalize/retry.
Example:
```bash
curl -s "${BASE}/api/v1/admin/users/123" \
-H "x-api-key: ${KEY}"
```
### 3) Balance Adjustment (existing API)
## 3) Balance Adjustment (Existing Interface)
`POST /api/v1/admin/users/:id/balance`
Use case: manual correction with `set` / `add` / `subtract`.
Purpose:
- Existing reusable admin interface for manual correction.
- Supports `set`, `add`, `subtract`.
Request body example (`subtract`):
```json
{
"balance": 100.0,
@@ -206,6 +103,8 @@ Request body example (`subtract`):
}
```
Example:
```bash
curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
-H "x-api-key: ${KEY}" \
@@ -218,24 +117,18 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
}'
```
### 4) Purchase URL query forwarding (iframe and new tab)
When Sub2API opens `purchase_subscription_url`, it appends:
- `user_id`
- `token`
- `theme` (`light` / `dark`)
- `ui_mode` (fixed: `embedded`)
## 4) Error Handling Recommendations
Example:
```text
https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&ui_mode=embedded
```
- Persist upstream payment result independently from recharge result.
- Mark payment success immediately after callback verification.
- If recharge fails after payment success, keep order retryable by admin operation.
- For retry, always reuse deterministic `code` + new `Idempotency-Key`.
### 5) Failure handling recommendations
- Persist payment success and recharge success as separate states
- Mark payment as successful immediately after verified callback
- Allow retry for orders with payment success but recharge failure
- Keep the same `code` for retry, and use a new `Idempotency-Key`
## 5) Suggested `doc_url` Setting
Sub2API already supports `doc_url` in system settings.
Recommended values:
### 6) Recommended `doc_url`
- View URL: `https://github.com/Wei-Shaw/sub2api/blob/main/ADMIN_PAYMENT_INTEGRATION_API.md`
- Download URL: `https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`
- Direct download URL: `https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`