GenDeploy - AI应用部署

微应用 API 文档

平台为微应用提供的全部运行时 API 参考，包括数据存储、用户管理、商品与支付

概述

平台 API 概述

GenDeploy 为微应用开发者提供了一整套运行时 API，让你的微应用可以轻松实现数据存储、用户登录、商品售卖与支付收款等核心能力，所有对接仅需前端代码，无需自建后端。

基本架构

微应用 HTML/JS
    ↓ 调用 REST API
GenDeploy 平台 API（https://www.gendeploy.top/api）
    ↓
数据存储 / 用户管理 / 支付网关

重要提醒： 本文档所有请求 URL 中的 <你的appId> / YOUR_APP_ID 均为占位符，请替换为你自己的应用 appId（控制台 → 我的微应用 → 应用详情可见）。

认证方式

平台 Runtime API 主要使用 App User Token 认证：

认证方式	Header	适用场景
App User Token	`Authorization: Bearer <token>`	用户登录后访问：用户信息、用户 KV、商品与支付等

通用响应格式

成功响应：

{
  "success": true,
  "data": { ... }
}

错误响应：

{
  "statusCode": 400,
  "message": "错误描述"
}

用户级 KV

用户级 KV（随登录用户）

用户级 KV 是“每个登录用户一份”的数据存储，适合保存用户偏好、配置、草稿等。

前置条件

1. 已在控制台开启用户管理能力

2. 用户已登录并拿到 appUserToken（见「用户管理」里的登录/验证码接口）

3. 请求头携带：Authorization: Bearer <appUserToken>

注意： 用户级 KV 的 value 必须是 扁平对象 且所有字段值都是 string（Record<string,string>）。

API 列表

读取用户 KV

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/kv/{key}

请求头：

Authorization: Bearer <appUserToken>

成功响应（200）：

{ "key": "profile", "value": { "nickname": "张三" }, "updatedAt": "2026-01-01T00:00:00.000Z" }

Key 不存在（200）：

{ "key": "profile", "value": null }

写入/覆盖用户 KV

PUT https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/kv/{key}

请求头：

Authorization: Bearer <appUserToken>
Content-Type: application/json

请求体：

{
  "value": { "nickname": "张三", "theme": "dark" }
}

成功响应（200）：

{ "key": "profile", "value": { "nickname": "张三", "theme": "dark" }, "updatedAt": "2026-01-01T00:00:00.000Z" }

前端实现示例（Fetch）

function getAppUserToken() {
  return localStorage.getItem('appUserToken') || '';
}

async function fetchUserKv(params) {
  const { appId, key } = params;
  const token = getAppUserToken();
  if (!token) throw new Error('未登录：缺少 appUserToken');

  const res = await fetch(`https://www.gendeploy.top/api/runtime/apps/${appId}/me/kv/${encodeURIComponent(key)}`, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!res.ok) throw new Error('读取失败');
  return await res.json();
}

async function saveUserKv(params) {
  const { appId, key, value } = params;
  const token = getAppUserToken();
  if (!token) throw new Error('未登录：缺少 appUserToken');

  const res = await fetch(`https://www.gendeploy.top/api/runtime/apps/${appId}/me/kv/${encodeURIComponent(key)}`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ value }),
  });
  if (!res.ok) throw new Error('保存失败');
  return await res.json();
}

用户管理

用户管理 API

让你的微应用具备用户注册、登录和数据管理能力。

前置条件

1. 在微应用管理后台开启用户管理能力

2. 配置好用户条款（可选）

3. 配置好用户 KV Schema（可选，用于定义用户自有数据结构）

认证说明

- 发送验证码和验证验证码接口无需认证

- 其余接口需要携带 Header：Authorization: Bearer <appUserToken>

- appUserToken 通过验证码验证接口获取

API 列表

发送邮箱验证码

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/auth/email/start

请求体：

{
  "email": "user@example.com"
}

成功响应：

{
  "ok": true,
  "cooldownSeconds": 60
}

验证验证码（登录/注册）

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/auth/email/verify

请求体：

{
  "email": "user@example.com",
  "code": "123456",
  "password": "your-password",
  "nickname": "用户昵称",
  "termsAccepted": true
}

参数	类型	必填	说明
email	string	是	邮箱地址
code	string	是	验证码
password	string	首次注册时必填	密码
nickname	string	否	昵称
termsAccepted	boolean	是	是否同意用户条款

成功响应：

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "isNewUser": true,
  "termsVersion": 1,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "nickname": "用户昵称"
  }
}

密码注册

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/auth/password/register

请求体：

{
  "email": "user@example.com",
  "password": "your-password",
  "nickname": "用户昵称",
  "termsAccepted": true
}

密码登录

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/auth/password/login

请求体：

{
  "email": "user@example.com",
  "password": "your-password"
}

成功响应：

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "nickname": "用户昵称"
  }
}

获取当前用户信息

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/me

请求头： Authorization: Bearer <appUserToken>

成功响应：

{
  "id": "user-uuid",
  "email": "user@example.com",
  "nickname": "用户昵称"
}

退出登录

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/logout

请求头： Authorization: Bearer <appUserToken>

读取用户 KV 数据

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/kv/{key}

请求头： Authorization: Bearer <appUserToken>

成功响应：

{
  "key": "profile",
  "value": { "avatar": "https://...", "bio": "..." }
}

写入用户 KV 数据

PUT https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/kv/{key}

请求头： Authorization: Bearer <appUserToken>

请求体：

{
  "value": { "avatar": "https://...", "bio": "新的个人简介" }
}

注意： value 的类型为 Record<string, string>，即键值对形式，所有值必须为字符串类型。

商品与支付

商品与支付 API

让你的微应用具备商品展示、在线收款和权益管理能力。

前置条件

1. 已开启用户管理能力（收款依赖用户登录）

2. 已配置收款渠道（ZPAY 或 PayPal）

3. 已创建商品（会员套餐或积分包）

商品类型说明

grantType	说明	典型场景
DURATION	有效期型	月度/年度会员、VIP 订阅
CONSUMABLE	可消耗型	积分包、次数包、代币
NON_CONSUMABLE	永久型	一次性购买、永久解锁

API 列表

获取商品列表

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/products

无需认证，返回所有已上架商品。

成功响应：

[
  {
    "productId": "pro_month",
    "name": "月度会员",
    "description": "享受全部高级功能",
    "unitPrice": 29.9,
    "currency": "CNY",
    "grantType": "DURATION",
    "validityMode": "RELATIVE",
    "validityMonths": 1,
    "validityYears": null,
    "grantAmount": null
  },
  {
    "productId": "credits_100",
    "name": "100 积分包",
    "description": null,
    "unitPrice": 9.9,
    "currency": "CNY",
    "grantType": "CONSUMABLE",
    "validityMode": null,
    "validityMonths": null,
    "validityYears": null,
    "grantAmount": 100
  }
]

发起支付

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/payments/initiate

请求头： Authorization: Bearer <appUserToken>

请求体：

{
  "orderId": "order_unique_id",
  "productId": "pro_month",
  "amount": 29.9,
  "currency": "CNY",
  "region": "auto",
  "productType": "one_time",
  "quantity": 1,
  "title": "月度会员",
  "description": "购买月度会员",
  "returnUrl": "https://your-app.com/payment-result"
}

参数	类型	必填	说明
orderId	string	是	自定义唯一订单号
productId	string	是	商品 ID
amount	number	是	支付金额（使用商品的 unitPrice）
currency	string	是	币种（使用商品的 currency）
region	string	否	`domestic` / `international` / `auto`，默认 auto
productType	string	否	`one_time` / `credits`
quantity	number	否	数量，默认 1
title	string	否	订单标题
description	string	否	订单描述
returnUrl	string	否	支付完成后回调地址
cancelUrl	string	否	支付取消后回调地址

成功响应：

{
  "provider": "zpay",
  "merchantOrderId": "mo_abc123",
  "providerPaymentId": "pp_xyz789",
  "payMode": "qrcode",
  "payload": {
    "providerOrderId": "zpay_order_001",
    "qrcodeUrl": "https://...",
    "url": "https://..."
  }
}

payMode 处理方式：

- qrcode：使用 payload.qrcodeUrl 生成二维码供用户扫码

- redirect：使用 payload.url 或 payload.approvalUrl 跳转支付页

查询订单状态

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/payments/orders/merchant/{merchantOrderId}

请求头： Authorization: Bearer <appUserToken>

成功响应：

{
  "merchantOrderId": "mo_abc123",
  "status": "succeeded",
  "provider": "zpay",
  "amount": 29.9,
  "currency": "CNY",
  "productType": "one_time",
  "paidAt": "2025-01-15T10:30:00.000Z"
}

status 可能的值： pending | succeeded | failed | cancelled | expired

建议： 支付后轮询此接口（间隔 2-3 秒），直到 status 变为 succeeded 或终态。

查询用户已购商品

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/products

请求头： Authorization: Bearer <appUserToken>

查询商品权益状态

GET https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/products/{productId}/status

请求头： Authorization: Bearer <appUserToken>

成功响应：

{
  "productId": "pro_month",
  "grantType": "DURATION",
  "hasEntitlement": true,
  "isActive": true,
  "validFrom": "2025-01-15T10:30:00.000Z",
  "validUntil": "2025-02-15T10:30:00.000Z",
  "remaining": null
}

字段	说明
hasEntitlement	是否曾经购买过
isActive	当前是否有效
validFrom / validUntil	有效期（DURATION 类型）
remaining	剩余额度（CONSUMABLE 类型）

消耗积分/次数

POST https://www.gendeploy.top/api/runtime/apps/<你的appId>/me/products/consume

请求头： Authorization: Bearer <appUserToken>

请求体：

{
  "productId": "credits_100",
  "quantity": 10,
  "reason": "generate_image",
  "idempotencyKey": "unique-operation-key"
}

参数	类型	必填	说明
productId	string	是	商品 ID
quantity	number	是	消耗数量
reason	string	否	消耗原因（用于记录）
idempotencyKey	string	否	幂等键，防止重复扣减

成功响应：

{
  "productId": "credits_100",
  "consumed": 10,
  "remaining": 90
}

重要： 务必使用 idempotencyKey！当请求失败但不确定是否已扣减时，使用相同的 key 重试可保证幂等。

认证与 Token

认证与 Token 详解

App User Token

用户通过登录/注册接口获取。用于访问用户相关的 API。

使用方式：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

最佳实践：

- 将 token 存储在 localStorage

- 每次请求在 Header 中携带

- 退出时清除本地存储并调用 logout 接口

典型使用流程

// 1. 用户登录（用于用户相关功能）
const response = await fetch(
  'https://www.gendeploy.top/api/runtime/apps/<你的appId>/auth/email/verify',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email: 'user@example.com',
      code: '123456',
      termsAccepted: true
    })
  }
);
const { token } = await response.json();
localStorage.setItem('appUserToken', token);

// 2. 后续请求携带用户 Token
const userInfo = await fetch(
  'https://www.gendeploy.top/api/runtime/apps/<你的appId>/me',
  {
    headers: {
      'Authorization': `Bearer ${localStorage.getItem('appUserToken')}`
    }
  }
);