worldmonitor/docs/zh/api-commerce.mdx

---
title: "商务端点"
description: "World Monitor 计费与商业化 API 完整参考：涵盖结账流程、客户门户、产品目录、优惠券与推荐奖励端点，基于 Convex 数据库与 Dodo Payments 构建的轻量边缘代理层，为 Pro 订阅、API 密钥额度、团队席位与年度计划提供安全的支付集成。"
---

WorldMonitor 使用 [Dodo Payments](https://dodopayments.com) 处理 PRO 订阅，并使用 [Convex](https://convex.dev) 作为权益的事实来源。这些边缘端点是轻量的认证代理 —— 它们验证 Clerk JWT，然后通过 `RELAY_SHARED_SECRET` 转发到 Convex HTTP actions。

## 结账

### `POST /api/create-checkout`

创建 Dodo 结账会话并返回托管结账 URL。

- **认证**：Clerk bearer（必需）
- **请求体**：
  ```json
  { "productId": "pro-monthly", "returnUrl": "https://www.worldmonitor.app/pro/success" }
  ```
- **响应**：`{ "checkoutUrl": "https://checkout.dodopayments.com/..." }`
- **幂等性**：支持可选的 `Idempotency-Key`，在成功响应后 10 分钟内有效。使用相同键重试并附带相同请求体会重放原始结账响应，而非创建另一次结账尝试。
- **returnUrl** 会在 Convex 侧根据白名单进行验证。

### `POST /api/customer-portal`

为现有订阅者创建 Dodo 客户门户会话（更新卡片、取消、查看发票）。

- **认证**：Clerk bearer + 活跃权益
- **响应**：`{ "portalUrl": "..." }`
- **幂等性**：支持可选的 `Idempotency-Key`。使用相同键重试会重放原始门户响应，而非创建另一次门户尝试。

## 产品目录

### `GET /api/product-catalog`

返回 `/pro` 定价页使用的分层视图模型。在 Redis 中以 `product-catalog:v3` 为键缓存 1 小时；缓存未命中时，从 Dodo Payments 获取实时价格，若 Dodo 不可达则回退到 `_product-fallback-prices.js`。响应携带 `X-Product-Catalog-Source` 头，以便探针区分缓存命中与实时获取。

**响应**（分层顺序为 `free`、`pro`、`pro_business`、`api_starter`、`api_business`、`enterprise`）：

```json
{
  "tiers": [
    {
      "name": "Free",
      "localeKey": "free",
      "description": "Get started with the essentials",
      "features": ["Core dashboard panels", "..."],
      "cta": "Get Started",
      "href": "https://worldmonitor.app",
      "highlighted": false,
      "price": 0,
      "period": "forever"
    },
    {
      "name": "Pro",
      "localeKey": "pro",
      "description": "Full intelligence dashboard",
      "features": ["..."],
      "highlighted": true,
      "monthlyPrice": 39.99,
      "monthlyProductId": "pdt_0Nbtt71uObulf7fGXhQup",
      "annualPrice": 359.99,
      "annualProductId": "pdt_0NbttMIfjLWC10jHQWYgJ"
    },
    {
      "name": "Pro Business",
      "localeKey": "proBusiness",
      "description": "The Pro dashboard, licensed for work",
      "features": ["..."],
      "highlightFeatures": ["Commercial license included"],
      "highlighted": false,
      "monthlyPrice": 49.99,
      "monthlyProductId": "pdt_...",
      "annualPrice": 449.99,
      "annualProductId": "pdt_..."
    },
    {
      "name": "API Starter",
      "localeKey": "api",
      "description": "Build internal tools on live intelligence data",
      "features": ["..."],
      "highlighted": false,
      "monthlyPrice": 99.99,
      "monthlyProductId": "pdt_0NbttVmG1SERrxhygbbUq",
      "annualPrice": 899.99,
      "annualProductId": "pdt_0Nbu2lawHYE3dv2THgSEV"
    },
    {
      "name": "API Business",
      "localeKey": "apiBusiness",
      "description": "Launch your own product on WorldMonitor data",
      "features": ["..."],
      "highlighted": false,
      "monthlyPrice": 299.99,
      "monthlyProductId": "pdt_0Nbttg7NuOJrhbyBGCius"
    },
    {
      "name": "Enterprise",
      "localeKey": "enterprise",
      "description": "Custom solutions for organizations",
      "features": ["..."],
      "cta": "Contact Sales",
      "href": "mailto:enterprise@worldmonitor.app",
      "highlighted": false,
      "price": null
    }
  ],
  "fetchedAt": 1751799600000,
  "cachedUntil": 1751803200000,
  "priceSource": "dodo"
}
```

说明：

- 价格字段直接放在分层对象上。付费分层始终暴露 `monthlyPrice` / `monthlyProductId`，仅当存在年度变体时才添加 `annualPrice` / `annualProductId` —— API Business 仅为月度，因此这些字段在其上不存在。Free 使用 `price: 0, period: "forever"`；Enterprise 使用 `price: null`。
- `highlightFeatures` 是可选数组，用于许可 / 商用说明，在定价页上与 `features` 分开渲染。没有此类说明的分层会省略该字段。
- 价格单位为美元（Dodo 返回分；处理程序除以 100）。已发布目录的货币隐式为 USD。

### `DELETE /api/product-catalog`

清除缓存的目录。需要 `Authorization: Bearer $RELAY_SHARED_SECRET`。内部使用。

## 推荐

### `GET /api/referral/me`

返回调用者的确定性推荐码（Clerk userId 的 8 字符 HMAC，在账户生命周期内保持稳定）和预构建的分享 URL。需要 Clerk bearer。处理程序还会触发一个尽力而为的 `ctx.waitUntil` Convex 绑定，以便未来的 `/pro?ref=<code>` 注册可以归因 —— 这绝不会阻塞响应。

```json
{
  "code": "a1b2c3d4",
  "shareUrl": "https://worldmonitor.app/pro?ref=a1b2c3d4"
}
```

错误：

- `401 UNAUTHENTICATED` —— 缺少或无效的 Clerk JWT。
- `503 service_unavailable` —— 未配置 `BRIEF_URL_SIGNING_SECRET`（推荐码 HMAC 复用该密钥）。

目前不返回 `referrals` 计数或 `rewardMonths` —— Dodo 的 `affonso_referral` 归因尚未流入 Convex，且仅暴露候补名单侧的计数会造成误导。

`affonso_referral` 是 Dodo 转发给 Affonso 推荐追踪 webhook 的供应商契约元数据键。该键名是承载性的 —— 重命名它（为 `wm_referral`、`ref` 等）会静默破坏 Dodo→Affonso 归因。写入/读取调用点见 `convex/payments/checkout.ts` 和 `convex/payments/subscriptionHelpers.ts`。

## 候补名单

### `POST /api/leads/v1/register-interest`

将邮箱捕获到 Convex 候补名单表中。经 Turnstile 验证（桌面来源绕过），按 IP 限速。属于 `LeadsService` 的一部分；请求结构见[平台端点](/zh/api-platform)。