PPanel Edgewallet
由 openapi.json 自动生成的 10 个端点及其请求、响应和权限元数据。
此参考由已发布 API 契约生成。字段、请求头和权限要求如下。
下载完整 OpenAPI 文档 · SHA-256: ccaa20cec11fad96e369b88073ce3608a5b071ce55d6dc03fa31df7b0f08c525
标识符和数据结构与公开契约一致，说明直接给出调用规则。共享模型见 数据模型.
GET /api/v1/admin/users/{id}/wallet
GET /api/v1/admin/users/{id}/wallet
A user's balances (ETag: wallet version)
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Wallet"
}
}
},
"description": "The wallet",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No wallet for this user"
}
},
"summary": "A user's balances (ETag: wallet version)",
"tags": [
"wallet"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "ledger.entry.read",
"effectiveSecurity": []
}GET /api/v1/admin/wallet-adjustments
GET /api/v1/admin/wallet-adjustments
Adjustment approval queue
{
"parameters": [
{
"in": "query",
"name": "status",
"required": false,
"schema": {
"enum": [
"pending",
"approved",
"rejected",
"withdrawn",
"expired"
],
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"format": "uuid",
"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": {
"$ref": "#/components/schemas/WalletAdjustmentReview"
},
"type": "array"
},
"next_cursor": {
"format": "uuid",
"type": [
"string",
"null"
]
},
"policy": {
"properties": {
"adjustment_approval_threshold_units": {
"type": "string"
},
"adjustment_request_ttl_days": {
"type": "integer"
}
},
"required": [
"adjustment_approval_threshold_units",
"adjustment_request_ttl_days"
],
"type": "object"
}
},
"required": [
"items",
"has_more",
"next_cursor",
"policy"
],
"type": "object"
}
}
},
"description": "Review requests"
}
},
"summary": "Adjustment approval queue",
"tags": [
"wallet"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ledger.entry.read",
"effectiveSecurity": []
}POST /api/v1/admin/wallet-adjustments
POST /api/v1/admin/wallet-adjustments
Adjust the cash or gift balance of a user (reason required)
{
"parameters": [
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletAdjustmentRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletAdjustment"
}
}
},
"description": "Posted below threshold, otherwise pending independent review"
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "auth.reauth_required"
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "No such user"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "ledger.insufficient_balance: a debit would overdraw the bucket"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "ledger.amount_invalid (currency other than the wallet’s) or common.validation_failed"
}
},
"summary": "Adjust the cash or gift balance of a user (reason required)",
"tags": [
"wallet"
],
"x-audit": "ledger.adjustment.create",
"x-body": "json",
"x-body-limit": 65536,
"x-idempotency": "required",
"x-permission": "ledger.adjustment.create",
"x-reauth": true,
"effectiveSecurity": []
}GET /api/v1/admin/wallet-adjustments/{id}
GET /api/v1/admin/wallet-adjustments/{id}
Adjustment review request
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletAdjustmentReview"
}
}
},
"description": "Request",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Not found"
}
},
"summary": "Adjustment review request",
"tags": [
"wallet"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"x-permission": "ledger.entry.read",
"effectiveSecurity": []
}POST /api/v1/admin/wallet-adjustments/{id}/approve
POST /api/v1/admin/wallet-adjustments/{id}/approve
approve an adjustment request
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
},
{
"in": "header",
"name": "if-match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletAdjustmentReview"
}
}
},
"description": "Decision",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Independent reviewer required"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Stale, expired, decided or insufficient balance"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match required"
}
},
"summary": "approve an adjustment request",
"tags": [
"wallet"
],
"x-audit": "ledger.adjustment.approve",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "ledger.adjustment.approve",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/wallet-adjustments/{id}/reject
POST /api/v1/admin/wallet-adjustments/{id}/reject
reject an adjustment request
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
},
{
"in": "header",
"name": "if-match",
"required": true,
"schema": {
"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": {
"$ref": "#/components/schemas/WalletAdjustmentReview"
}
}
},
"description": "Decision",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Independent reviewer required"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Stale, expired, decided or insufficient balance"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match required"
}
},
"summary": "reject an adjustment request",
"tags": [
"wallet"
],
"x-audit": "ledger.adjustment.reject",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "ledger.adjustment.approve",
"x-reauth": true,
"effectiveSecurity": []
}POST /api/v1/admin/wallet-adjustments/{id}/withdraw
POST /api/v1/admin/wallet-adjustments/{id}/withdraw
withdraw an adjustment request
{
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"in": "header",
"name": "idempotency-key",
"required": true,
"schema": {
"description": "Idempotency-Key: 16–128 visible ASCII characters",
"pattern": "^[\\x21-\\x7e]{16,128}$",
"type": "string"
}
},
{
"in": "header",
"name": "if-match",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"reason": {
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"type": "object"
}
}
},
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletAdjustmentReview"
}
}
},
"description": "Decision",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Independent reviewer required"
},
"409": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Stale, expired, decided or insufficient balance"
},
"428": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "If-Match required"
}
},
"summary": "withdraw an adjustment request",
"tags": [
"wallet"
],
"x-audit": "ledger.adjustment.withdraw",
"x-body": "json",
"x-body-limit": 65536,
"x-concurrency": {
"etag": true,
"ifMatch": true
},
"x-idempotency": "required",
"x-permission": "ledger.adjustment.create",
"x-reauth": false,
"effectiveSecurity": []
}GET /api/v1/admin/wallet-entries
GET /api/v1/admin/wallet-entries
Wallet entries of all users, newest first (keyset pages)
{
"parameters": [
{
"in": "query",
"name": "user_id",
"required": false,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "reference_type",
"required": false,
"schema": {
"maxLength": 64,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "reference_id",
"required": false,
"schema": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"in": "query",
"name": "operation_key",
"required": false,
"schema": {
"maxLength": 200,
"minLength": 1,
"type": "string"
}
},
{
"description": "Bucket; repeat the parameter for several values",
"in": "query",
"name": "bucket",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"cash",
"gift",
"commission_pending",
"commission"
],
"type": "string"
},
{
"items": {
"enum": [
"cash",
"gift",
"commission_pending",
"commission"
],
"type": "string"
},
"type": "array"
}
],
"description": "Bucket; repeat the parameter for several values"
}
},
{
"description": "Entry kind; repeat the parameter for several values",
"in": "query",
"name": "kind",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"top_up",
"order_apply",
"order_release",
"order_reapply",
"order_payment",
"refund",
"admin_adjust",
"gift_grant",
"commission_accrue",
"commission_release",
"commission_reverse",
"commission_to_cash",
"withdraw_hold",
"withdraw_release",
"commission_withdraw_hold",
"commission_withdraw_release",
"commission_withdraw_settle",
"correction"
],
"type": "string"
},
{
"items": {
"enum": [
"top_up",
"order_apply",
"order_release",
"order_reapply",
"order_payment",
"refund",
"admin_adjust",
"gift_grant",
"commission_accrue",
"commission_release",
"commission_reverse",
"commission_to_cash",
"withdraw_hold",
"withdraw_release",
"commission_withdraw_hold",
"commission_withdraw_release",
"commission_withdraw_settle",
"correction"
],
"type": "string"
},
"type": "array"
}
],
"description": "Entry kind; repeat the parameter for several values"
}
},
{
"description": "Inclusive lower bound (ISO-8601)",
"in": "query",
"name": "created_from",
"required": false,
"schema": {
"description": "Inclusive lower bound (ISO-8601)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Exclusive upper bound (ISO-8601)",
"in": "query",
"name": "created_to",
"required": false,
"schema": {
"description": "Exclusive upper bound (ISO-8601)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdminWalletEntryPage"
}
}
},
"description": "A page of entries"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "Wallet entries of all users, newest first (keyset pages)",
"tags": [
"wallet"
],
"x-body": "none",
"x-body-limit": 0,
"x-permission": "ledger.entry.read",
"effectiveSecurity": []
}GET /api/v1/me/wallet
GET /api/v1/me/wallet
My balances: cash, gift, pending and available commission (ETag: wallet version)
{
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Wallet"
}
}
},
"description": "My wallet",
"headers": {
"ETag": {
"description": "Current resource version for If-Match.",
"schema": {
"type": "string"
}
}
}
}
},
"summary": "My balances: cash, gift, pending and available commission (ETag: wallet version)",
"tags": [
"wallet"
],
"x-body": "none",
"x-body-limit": 0,
"x-concurrency": {
"etag": true
},
"effectiveSecurity": []
}GET /api/v1/me/wallet/entries
GET /api/v1/me/wallet/entries
My wallet entries, newest first (keyset pages)
{
"parameters": [
{
"description": "Bucket; repeat the parameter for several values",
"in": "query",
"name": "bucket",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"cash",
"gift",
"commission_pending",
"commission"
],
"type": "string"
},
{
"items": {
"enum": [
"cash",
"gift",
"commission_pending",
"commission"
],
"type": "string"
},
"type": "array"
}
],
"description": "Bucket; repeat the parameter for several values"
}
},
{
"description": "Entry kind; repeat the parameter for several values",
"in": "query",
"name": "kind",
"required": false,
"schema": {
"anyOf": [
{
"enum": [
"top_up",
"order_apply",
"order_release",
"order_reapply",
"order_payment",
"refund",
"admin_adjust",
"gift_grant",
"commission_accrue",
"commission_release",
"commission_reverse",
"commission_to_cash",
"withdraw_hold",
"withdraw_release",
"commission_withdraw_hold",
"commission_withdraw_release",
"commission_withdraw_settle",
"correction"
],
"type": "string"
},
{
"items": {
"enum": [
"top_up",
"order_apply",
"order_release",
"order_reapply",
"order_payment",
"refund",
"admin_adjust",
"gift_grant",
"commission_accrue",
"commission_release",
"commission_reverse",
"commission_to_cash",
"withdraw_hold",
"withdraw_release",
"commission_withdraw_hold",
"commission_withdraw_release",
"commission_withdraw_settle",
"correction"
],
"type": "string"
},
"type": "array"
}
],
"description": "Entry kind; repeat the parameter for several values"
}
},
{
"description": "Inclusive lower bound (ISO-8601)",
"in": "query",
"name": "created_from",
"required": false,
"schema": {
"description": "Inclusive lower bound (ISO-8601)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Exclusive upper bound (ISO-8601)",
"in": "query",
"name": "created_to",
"required": false,
"schema": {
"description": "Exclusive upper bound (ISO-8601)",
"format": "date-time",
"type": "string"
}
},
{
"description": "Default 20, at most 100",
"in": "query",
"name": "page_size",
"required": false,
"schema": {
"description": "Default 20, at most 100",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "`next_cursor` of the previous page",
"in": "query",
"name": "cursor",
"required": false,
"schema": {
"description": "`next_cursor` of the previous page",
"maxLength": 512,
"minLength": 1,
"type": "string"
}
},
{
"description": "Return `total` (first page only)",
"in": "query",
"name": "include_total",
"required": false,
"schema": {
"description": "Return `total` (first page only)",
"enum": [
"true",
"false"
],
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WalletEntryPage"
}
}
},
"description": "A page of my entries"
},
"422": {
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"description": "Invalid filter or cursor"
}
},
"summary": "My wallet entries, newest first (keyset pages)",
"tags": [
"wallet"
],
"x-body": "none",
"x-body-limit": 0,
"effectiveSecurity": []
}