yhlxj/sub2api

# ADMIN_PAYMENT_INTEGRATION_API

单文件中英双语文档 / Single-file bilingual documentation (Chinese + English)

中文

目标

本文档用于对接外部支付系统（如 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

请求体示例：

{
  "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 示例：

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

curl -s "${BASE}/api/v1/admin/users/123" \
  -H "x-api-key: ${KEY}"

3) 余额调整（已有接口）

POST /api/v1/admin/users/:id/balance

用途：人工补偿 / 扣减，支持 set / add / subtract。

请求体示例（扣减）：

{
  "balance": 100.0,
  "operation": "subtract",
  "notes": "manual correction"
}

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 或用户侧自定义页面 iframe URL 时，会统一追加：

user_id
token
theme（light / dark）
lang（例如 zh / en，用于向嵌入页传递当前界面语言）
ui_mode（固定 embedded）

示例：

https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&lang=zh&ui_mode=embedded

5) 失败处理建议

支付成功与充值成功分状态落库
回调验签成功后立即标记“支付成功”
支付成功但充值失败的订单允许后续重试
重试保持相同 code，并使用新的 Idempotency-Key

6) `doc_url` 配置建议

查看链接：https://github.com/Wei-Shaw/sub2api/blob/main/docs/ADMIN_PAYMENT_INTEGRATION_API.md
下载链接：https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/docs/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

Note: Admin JWT can also access admin routes, but Admin API Key is recommended for server-to-server integration.

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.

Headers:

x-api-key
Idempotency-Key

Request body:

{
  "code": "s2p_cm1234567890",
  "type": "balance",
  "value": 100.0,
  "user_id": 123,
  "notes": "sub2apipay order: cm1234567890"
}

Idempotency behavior:

Same code and same used_by: 200
Same code but different used_by: 409
Missing Idempotency-Key: 400 (IDEMPOTENCY_KEY_REQUIRED)

curl example:

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) Query User (optional pre-check)

GET /api/v1/admin/users/:id

curl -s "${BASE}/api/v1/admin/users/123" \
  -H "x-api-key: ${KEY}"

3) Balance Adjustment (existing API)

POST /api/v1/admin/users/:id/balance

Use case: manual correction with set / add / subtract.

Request body example (subtract):

{
  "balance": 100.0,
  "operation": "subtract",
  "notes": "manual correction"
}

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) Purchase / Custom Page URL query forwarding (iframe and new tab)

When Sub2API opens purchase_subscription_url or a user-facing custom page iframe URL, it appends:

user_id
token
theme (light / dark)
lang (for example zh / en, used to pass the current UI language to the embedded page)
ui_mode (fixed: embedded)

Example:

https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&lang=zh&ui_mode=embedded

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

6) Recommended `doc_url`

View URL: https://github.com/Wei-Shaw/sub2api/blob/main/docs/ADMIN_PAYMENT_INTEGRATION_API.md
Download URL: https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/docs/ADMIN_PAYMENT_INTEGRATION_API.md

ADMIN_PAYMENT_INTEGRATION_API.md 6.4 KB Historia Czysty

中文

目标