3 步快速接入
步骤 1
🔑
获取 API Key
填写下方申请表，我们会为你创建专属 Key
步骤 2
📡
发送请求
向接口传入邮箱，获取订阅链接
步骤 3
✅
交付用户
将返回的订阅链接发给你的用户
示例 — 创建一个订阅
curl -s -X POST https://univista.me/openapi/v1/subscriptions \
-H 'X-Api-Key: uk_live_your_key_here' \
-H 'Content-Type: application/json' \
-d '{"email":"[email protected]","plan_id":"30d"}'
# Response 201
{
"data": {
"subscription_url": "https://univista.me/sub?token=abc123...",
"email": "[email protected]",
"plan_id": "30d",
"expires_at": "2026-05-29T00:00:00Z"
}
}
鉴权方式
所有请求需在 Header 中携带 API Key： X-Api-Key
X-Api-Key: uk_live_a1b2c3d4e5f6...
安全提示：
API Key 仅在创建时显示一次，请立即存入环境变量，切勿写入代码仓库。建议每 90 天轮换一次。
Base URL
https://univista.me/openapi/v1/
API 端点详情
POST
/openapi/v1/subscriptions
创建订阅
为指定邮箱创建订阅，返回可直接交付用户的订阅链接。
请求体 (JSON)
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| string | required | 订阅归属邮箱（唯一标识） | |
| plan_id | string | optional | 套餐：7d / 30d / 90d / 365d，默认 30d |
| memo | string | optional | 备注（不对用户展示，记入审计日志） |
请求示例
curl -X POST https://univista.me/openapi/v1/subscriptions \
-H "X-Api-Key: uk_live_..." \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","plan_id":"30d","memo":"order #123"}'
响应 201
{
"data": {
"subscription_token": "abc123...",
"subscription_url": "https://univista.me/sub?token=abc123...",
"email": "[email protected]",
"plan_id": "30d",
"expires_at": "2026-05-29T00:00:00Z",
"created_at": "2026-04-29T10:00:00Z",
"memo": "order #123"
}
}
若该邮箱已有有效订阅，返回 409，使用 /renew 续期。
GET
/openapi/v1/subscriptions/{email}
查询订阅
查询指定邮箱的订阅状态（只返回当前 Key 创建的订阅）。
curl https://univista.me/openapi/v1/subscriptions/[email protected] \
-H "X-Api-Key: uk_live_..."
响应 200
{
"data": {
"email": "[email protected]",
"status": "active", // active | expired | rate_limited
"plan_id": "30d",
"expires_at": "2026-05-29T00:00:00Z",
"days_remaining": 30,
"subscription_url": "https://univista.me/sub?token=..."
}
}
POST
/openapi/v1/subscriptions/{email}/renew
续期订阅
为已有订阅续期。 extend （在当前到期时间上叠加天数）或 reset （从今天重新计算）。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| plan_id | string | required | 续期套餐 |
| mode | string | optional | extend（默认，叠加）或 reset（重置） |
curl -X POST https://univista.me/openapi/v1/subscriptions/[email protected]/renew \
-H "X-Api-Key: uk_live_..." \
-H "Content-Type: application/json" \
-d '{"plan_id":"30d","mode":"extend"}'
响应 200
{
"data": {
"email": "[email protected]",
"new_expires_at": "2026-06-29T00:00:00Z",
"subscription_url": "https://univista.me/sub?token=..."
}
}
DELETE
/openapi/v1/subscriptions/{email}
撤销订阅
停用（软撤销）该邮箱的订阅。订阅记录会保留，但状态变为 revoked，并在下次同步时移除访问权限。仅对本 API Key 创建的订阅生效。
curl -X DELETE https://univista.me/openapi/v1/subscriptions/[email protected] \
-H "X-Api-Key: uk_live_..."
响应 200
{
"data": {
"email": "[email protected]",
"status": "revoked",
"revoked_at": "2026-06-22T10:00:00Z"
}
}
GET
/openapi/v1/subscriptions
订阅列表
分页列出本 API Key 创建的订阅。只返回属于你的订阅——其他租户的数据绝不会暴露。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| page | int | optional | 页码，从 1 开始，默认 1。 |
| per_page | int | optional | 每页条数，默认 20，最大 100（超出按 100 截断）。 |
| status | string | optional | 过滤： active / expired / all （默认 all）。 |
curl "https://univista.me/openapi/v1/subscriptions?page=1&per_page=20" \
-H "X-Api-Key: uk_live_..."
响应 200
{
"data": [
{
"email": "[email protected]",
"status": "active",
"plan_id": "30d",
"expires_at": "2026-07-22T00:00:00Z",
"days_remaining": 30,
"subscription_url": "https://univista.me/sub?token=..."
}
],
"meta": {
"page": 1,
"per_page": 20,
"total": 156,
"total_pages": 8
}
}
GET
/openapi/v1/me
Key 信息与用量
查看当前 API Key 的详情及今日用量。
curl https://univista.me/openapi/v1/me \
-H "X-Api-Key: uk_live_..."
{
"data": {
"name": "Partner A",
"owner_email": "[email protected]",
"created_at": "2026-04-01T00:00:00Z",
"rate_limit": {
"per_minute": 60,
"per_day": 1000,
"remaining_today": 847
}
}
}
错误码规范
所有错误响应统一格式：
{ "error": { "code": "invalid_email", "message": "..." } }
| HTTP | error.code | 说明 |
|---|---|---|
| 400 | invalid_email | 邮箱格式不合法 |
| 400 | invalid_plan_id | plan_id 不存在 |
| 401 | missing_api_key | 未提供 X-Api-Key |
| 401 | invalid_api_key | API Key 无效或已撤销 |
| 403 | ip_not_whitelisted | 来源 IP 不在白名单 |
| 404 | subscription_not_found | 邮箱无订阅记录 |
| 409 | email_already_exists | 邮箱已有有效订阅，请用续期接口 |
| 429 | rate_limit_exceeded | 超出频率限制，查看 Retry-After 响应头 |
| 500 | internal_error | 服务端内部错误 |
频率限制
60
req/min
每个 Key 每分钟
1,000
req/day
每个 Key 每日
超限时返回 429 ， Retry-After 响应头指示等待秒数。如需提升配额，请联系我们。
申请 API 接入
填写下方申请表提交申请。我们审核后会与你联系并交付 API Key。
已有 Key？直接参考上方快速开始。 联系支持