PPanel Edgeredeem
由 openapi.json 自动生成的 5 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/growth/redeem-batches
GET /api/v1/admin/growth/redeem-batches
List redeem batches without secret codes
{
"parameters": [
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"maxLength": 2048,
"type": "string"
}
},
{
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"default": 20,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"has_more": {
"type": "boolean"
},
"items": {
"items": {
"properties": {
"created_at": {
"type": "string"
},
"created_by": {
"format": "uuid",
"type": "string"
},
"effect": {
"properties": {
"kind": {
"type": "string"
},
"params": {
"additionalProperties": {},
"type": "object"
},
"snapshot": {},
"term": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"perpetual": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"perpetual"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 1200,
"minimum": 1,
"type": "integer"
},
"perpetual": {
"enum": [
false
],
"type": "boolean"
},
"unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"perpetual",
"unit",
"count"
],
"type": "object"
}
]
}
},
"required": [
"kind",
"params"
],
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"exported_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"void_reason": {
"type": [
"string",
"null"
]
},
"voided_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"quantity",
"effect",
"starts_at",
"ends_at",
"created_by",
"created_at",
"exported_at",
"voided_at",
"void_reason"
],
"type": "object"
},
"type": "array"
},
"next_cursor": {
"type": [
"string",
"null"
]
}
},
"required": [
"items",
"next_cursor",
"has_more"
],
"type": "object"
}
}
},
"description": "Success"
}
},
"summary": "List redeem batches without secret codes",
"tags": [
"redeem"
],
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "growth.redeem.manage",
"x-rate-limit": "growth.redeem.admin",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/growth/redeem-batches
POST /api/v1/admin/growth/redeem-batches
Create a redeem batch for one-time export
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"effect": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"activate_plan"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
},
"term": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"perpetual": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"perpetual"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 1200,
"minimum": 1,
"type": "integer"
},
"perpetual": {
"enum": [
false
],
"type": "boolean"
},
"unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"perpetual",
"unit",
"count"
],
"type": "object"
}
]
}
},
"required": [
"kind",
"plan_id",
"term"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"plan_switch"
],
"type": "string"
},
"plan_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"kind",
"plan_id"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"term_extend"
],
"type": "string"
},
"term": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"perpetual": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"perpetual"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 1200,
"minimum": 1,
"type": "integer"
},
"perpetual": {
"enum": [
false
],
"type": "boolean"
},
"unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"perpetual",
"unit",
"count"
],
"type": "object"
}
]
}
},
"required": [
"kind",
"term"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"traffic_bonus"
],
"type": "string"
},
"traffic_bytes": {
"pattern": "^[1-9][0-9]{0,17}$",
"type": "string"
}
},
"required": [
"kind",
"traffic_bytes"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"device_delta": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"expires_at": {
"format": "date-time",
"type": "string"
},
"kind": {
"enum": [
"device_bonus"
],
"type": "string"
}
},
"required": [
"kind",
"device_delta"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"kind": {
"enum": [
"usage_reset"
],
"type": "string"
}
},
"required": [
"kind"
],
"type": "object"
}
]
},
"ends_at": {
"format": "date-time",
"type": "string"
},
"name": {
"maxLength": 64,
"minLength": 1,
"type": "string"
},
"quantity": {
"maximum": 1000,
"minimum": 1,
"type": "integer"
},
"starts_at": {
"format": "date-time",
"type": "string"
}
},
"required": [
"name",
"quantity",
"effect"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"properties": {
"created_at": {
"type": "string"
},
"created_by": {
"format": "uuid",
"type": "string"
},
"effect": {
"properties": {
"kind": {
"type": "string"
},
"params": {
"additionalProperties": {},
"type": "object"
},
"snapshot": {},
"term": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"perpetual": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"perpetual"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 1200,
"minimum": 1,
"type": "integer"
},
"perpetual": {
"enum": [
false
],
"type": "boolean"
},
"unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"perpetual",
"unit",
"count"
],
"type": "object"
}
]
}
},
"required": [
"kind",
"params"
],
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"exported_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"void_reason": {
"type": [
"string",
"null"
]
},
"voided_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"quantity",
"effect",
"starts_at",
"ends_at",
"created_by",
"created_at",
"exported_at",
"voided_at",
"void_reason"
],
"type": "object"
}
}
},
"description": "Success"
}
},
"summary": "Create a redeem batch for one-time export",
"tags": [
"redeem"
],
"x-audit": "growth.redeem.generate",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "growth.redeem.manage",
"x-rate-limit": "growth.redeem.admin",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/growth/redeem-batches/{id}/export
POST /api/v1/admin/growth/redeem-batches/{id}/export
Export redeem codes exactly once; response cannot be replayed
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"batch_id": {
"format": "uuid",
"type": "string"
},
"codes": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"batch_id",
"codes"
],
"type": "object"
}
}
},
"description": "Success"
}
},
"summary": "Export redeem codes exactly once; response cannot be replayed",
"tags": [
"redeem"
],
"x-audit": "growth.redeem.export",
"x-body": "none",
"x-body-limit": 0,
"x-idempotency": "none",
"x-permission": "growth.redeem.manage",
"x-rate-limit": "growth.redeem.admin",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/admin/growth/redeem-batches/{id}/void
POST /api/v1/admin/growth/redeem-batches/{id}/void
Void all unredeemed codes in a batch
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"reason"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"created_at": {
"type": "string"
},
"created_by": {
"format": "uuid",
"type": "string"
},
"effect": {
"properties": {
"kind": {
"type": "string"
},
"params": {
"additionalProperties": {},
"type": "object"
},
"snapshot": {},
"term": {
"oneOf": [
{
"additionalProperties": false,
"properties": {
"perpetual": {
"enum": [
true
],
"type": "boolean"
}
},
"required": [
"perpetual"
],
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"count": {
"maximum": 1200,
"minimum": 1,
"type": "integer"
},
"perpetual": {
"enum": [
false
],
"type": "boolean"
},
"unit": {
"enum": [
"hour",
"day",
"month",
"year"
],
"type": "string"
}
},
"required": [
"perpetual",
"unit",
"count"
],
"type": "object"
}
]
}
},
"required": [
"kind",
"params"
],
"type": "object"
},
"ends_at": {
"type": [
"string",
"null"
]
},
"exported_at": {
"type": [
"string",
"null"
]
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"type": "string"
},
"quantity": {
"type": "integer"
},
"starts_at": {
"type": [
"string",
"null"
]
},
"void_reason": {
"type": [
"string",
"null"
]
},
"voided_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"quantity",
"effect",
"starts_at",
"ends_at",
"created_by",
"created_at",
"exported_at",
"voided_at",
"void_reason"
],
"type": "object"
}
}
},
"description": "Success"
}
},
"summary": "Void all unredeemed codes in a batch",
"tags": [
"redeem"
],
"x-audit": "growth.redeem.void",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "growth.redeem.manage",
"x-rate-limit": "growth.redeem.admin",
"x-reauth": false,
"effectiveSecurity": []
}POST /api/v1/me/redeem
POST /api/v1/me/redeem
Redeem a single-use entitlement code
{
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"code": {
"description": "R- plus 40 Crockford base32 characters; lowercase, spaces, missing hyphen and I/L/O aliases are accepted.",
"maxLength": 128,
"type": "string"
},
"subscription_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"properties": {
"grant_id": {
"format": "uuid",
"type": "string"
},
"replayed": {
"type": "boolean"
},
"subscription_id": {
"format": "uuid",
"type": "string"
}
},
"required": [
"subscription_id",
"grant_id",
"replayed"
],
"type": "object"
}
}
},
"description": "Success"
}
},
"summary": "Redeem a single-use entitlement code",
"tags": [
"redeem"
],
"x-audit": "growth.redeem.use",
"x-body": "json",
"x-body-limit": 65536,
"x-capability": "me.redeem.use",
"x-idempotency": "required",
"x-rate-limit": "growth.code.user",
"x-reauth": false,
"effectiveSecurity": []
}