portaly-overview

Portaly 概览

使用此技能可帮助人类用户（或其 Agent）了解 Portaly 的开放 API 能做什么，以及 接下来该查看哪个技能或文档。这是一个用于引导和导航的技能，不是集成工作流——它不会创建结账会话、签署回调，也不会自行调用任何 API。用户明确需求后，请转交给 portaly-payment 或 portaly-product，以了解实际实现步骤。

Portaly 环境

API 主机（可通过 PORTALY_API_HOST 覆盖）：

const PORTALY_API_HOST = process.env.PORTALY_API_HOST || 'https://portaly.ai'

portaly-payment 和 portaly-product 共用同一个 API 主机和同一个 Creator Subscription API Key（pcs_live_* / pcs_test_*）。portaly-email 使用同一个主机，但有自己的邮件 API 密钥（pem_*）。

快速开始

1. 询问人类用户想构建什么。将需求与下方的功能和映射表进行匹配。
2. 指引用户前往相应的 API 文档位置（见下文）查看完整详情。
3. 建议用户安装涵盖该工作流的特定技能；如果用户提出要求，也可以协助安装——不要在此处尝试复现 portaly-payment 或 portaly-product 的工作流步骤。
4. 如果需求不符合任何一行（例如仅限管理员使用的功能，或尚不存在的功能），请直接说明，不要猜测 API 端点。

功能概览

Portaly 当前开放的（面向第三方）API 涵盖：

• 订阅付款 — 月付和年付的循环方案、一次性和动态（由买家／系统指定金额）定价、托管结账会话、循环续订回调、取消／恢复生命周期管理，以及订阅者自助服务门户。
• 折扣码 — 结账时可使用的固定金额／百分比／免费折扣，支持重复或永久有效。
• 数字产品 — 为创作者现有的数字产品（课程、模板、下载内容）提供单件或自定义捆绑结账、托管付款 + 邮件，以及签名 Webhook 事件。
• 订单和发票 — 查询付款／订单记录和发票状态，以便进行对账。
• 买家推广 — 允许创作者自己的买家通过推荐其他买家购买一次性方案来赚取佣金。Portaly 会在托管的购买完成页面上生成推荐链接，并负责账本、结算和付款；创作者的网站只需记住买家通过哪个链接到达。仅限台湾账户。
• 邮件（仅限受邀者参与的 Beta 版）— 从创作者已验证的域名发送应用自己的收据、登录码、通知和新闻简报；提供按收件人查询的投递状态和剩余额度。

付款、产品和推广功能使用两种 API 密钥前缀（pcs_live_* / pcs_test_*）开放——一个密钥即可调用所有这些功能。邮件功能使用独立的邮件 API 密钥（pem_*），无法调用付款端点；付款密钥也无法发送邮件。

API 目录

按分组列出的开放 API。此处列出的端点仅为示例，并不完整——完整列表请参阅下表后的获取说明。

分组	功能	示例端点
商家配置	托管结账页面上显示的商家名称 / 徽标	GET/PUT /api/creator-subscription/config
订阅方案	创建和管理月度 / 年度 / 一次性方案	GET/POST /api/creator-subscription/plans、PUT .../plans/{planId}
折扣码	固定金额 / 百分比 / 免费折扣	GET/POST /api/creator-subscription/discount-codes、GET .../discount-codes/lookup
结账会话	为方案启动托管结账；列出尚未完成的结账（放弃的购物车 / 首次扣款失败），用于对账和后续跟进	POST /api/creator-subscription/checkout-sessions、GET .../checkout-sessions、GET .../checkout-sessions/{sessionId}
订阅	查询和管理有效订阅	GET /api/creator-subscription/subscriptions、POST .../subscriptions/{subscriptionId}/cancel、.../resume
订单和发票	对账和电子发票状态	GET /api/creator-subscription/orders、GET .../invoices
订阅者门户	供订阅者自助使用的门户	POST /api/creator-subscription/portal-sessions
数字产品	列出产品、结账购买单件产品 / 套装	GET /api/digital-products、POST /api/digital-products/checkout-sessions
Webhook	支付 / 订阅 / 产品事件的签名回调	8 种事件类型（creator_subscription.*、digital_product.*）
评价	嵌入已验证买家的评价组件（托管 iframe，而非 JSON API）	https://portaly.ai/embed/reviews/{slug}（iframe 嵌入，无需 API 密钥）
买家推广	为产品开启买家推广，并设置所有符合条件的一次性方案共用的佣金比例	GET/PUT /api/creator-subscription/promotion
电子邮件（仅限邀请的 Beta 版，使用 pem_* 密钥）	从创作者的域名发送电子邮件、跟踪送达情况、查询配额	POST /api/email/emails、POST /api/email/batches、GET /api/email/emails/{id}、GET /api/email/quota

请勿将此表视为完整的接口规范。 当用户需要完整且始终最新的端点列表时，请实时获取，而非依赖此文件：

• 获取 https://portaly.ai/llms.txt——精简的端点索引，可先快速查阅。
• 获取 https://portaly.ai/openapi.json——包含所有端点和 Webhook 负载的完整请求 / 响应架构。

常见产品功能 → API / 技能映射

我想构建……	使用此技能	主要 API
付费会员 / 订阅网站（月付或年付）	portaly-payment	POST /api/creator-subscription/plans、POST /api/creator-subscription/checkout-sessions
一次性购买、捐赠或“随心付”流程	portaly-payment	动态定价计划（pricingType: dynamic）+ POST /api/creator-subscription/checkout-sessions
促销 / 优惠码 / 推荐折扣	portaly-payment	POST /api/creator-subscription/discount-codes、GET /api/creator-subscription/discount-codes/lookup
让订阅者取消、恢复或管理自己的计划	portaly-payment	POST /api/creator-subscription/portal-sessions
商家发起的订阅生命周期管理	portaly-payment	POST /api/creator-subscription/subscriptions/{id}/cancel、.../resume
将支付事件同步到自己的数据库	portaly-payment 或 portaly-product	已签名的回调 / webhook（x-portaly-signature）
在自己的网站上销售创作者的课程、模板或下载内容	portaly-product	GET /api/digital-products、POST /api/digital-products/checkout-sessions
自定义多商品组合结账	portaly-product	POST /api/digital-products/checkout-sessions，包含多个 items[]
对账 / “我的购买”或“我的订单”面板	portaly-payment 或 portaly-product	GET /api/creator-subscription/orders、GET /api/digital-products/orders
发票 / 电子发票状态查询	portaly-payment	GET /api/creator-subscription/invoices
在自己的网站上展示已验证的评分 / 社会认同	portaly-review	托管的 iframe 嵌入（无需 API 密钥）
让自己的买家推荐他人并赚取佣金	portaly-affiliate	PUT /api/creator-subscription/promotion + 创建结账会话时设置 profitSharingId
从自己的域名发送应用收据、登录验证码或通知	portaly-email	POST /api/email/emails

如果某个需求涉及多行（例如，会员网站还销售一次性购买的模板），请同时安装 portaly-payment 和 portaly-product——它们共用同一个 API 密钥。

API 文档

除了这套技能之外，Portaly 还发布了独立的 API 文档：

• https://portaly.ai/docs — 可交互、供人浏览的 API 文档。最适合手动探索 API 功能的人。
• https://portaly.ai/openapi.json — 机器可读的 OpenAPI 规范。最适合生成客户端、提供给 API 工具，或让 Agent 以编程方式检查完整的请求 / 响应架构。
• https://portaly.ai/llms.txt — 精简、面向大模型的 API 索引。最适合希望在决定接下来阅读什么之前，快速了解可用端点的 Agent。

如果此技能的摘要与这些文档存在冲突，应以 https://portaly.ai/docs 中的文档为准——此技能只是指南，而非权威信息来源。

路由到正确的技能

• portaly-payment — 涉及定期订阅、一次性／动态定价、折扣码、订阅生命周期（取消／恢复）或订阅者自助服务门户时安装。

  npx skills add portaly-ai/portaly-skills --skill portaly-payment
  

• portaly-product — 涉及商品上架和销售创作者现有的数字产品（包括捆绑结账）时安装。

  npx skills add portaly-ai/portaly-skills --skill portaly-product
  

• portaly-review — 需要在用户自己的网站中嵌入 Portaly 托管的已验证买家评价组件（Trustpilot 风格的评分徽章）时安装。无需 API 密钥。

  npx skills add portaly-ai/portaly-skills --skill portaly-review
  

• portaly-affiliate — 需要让创作者自己的买家通过推荐其他买家赚取佣金时安装。需要已有 Portaly Payment 设置；仅适用于一次性、固定价格的方案，且仅限位于台湾的 Portaly 账户（推广者的佣金将打入台湾银行账户）。

  npx skills add portaly-ai/portaly-skills --skill portaly-affiliate
  

• portaly-email — 需要从创作者的域名发送应用自身的邮件（收据、验证码、通知、新闻简报）时安装。仅限受邀用户参加的 Beta 版：只有 Portaly 邀请的账户才能使用。

  npx skills add portaly-ai/portaly-skills --skill portaly-email
  

• 如果用户还没有 Portaly 账户或 API 密钥：请前往 https://portaly.cc/payment 注册，并在 https://portaly.cc/admin/creator-subscription 创建 API 密钥；若要使用邮件功能，则在 https://portaly.cc/admin/email/api-keys 创建邮件 API 密钥（这些页面都需要人工操作，请在浏览器中为用户打开；对应技能的工作流会详细介绍这一步）。
• 安装后，按照该技能自身的工作流部分完成实际集成步骤（API 密钥设置、会话创建、回调／Webhook 验证等）。本技能不会重复说明这些步骤，只会告诉你应加载哪个技能。

报告已安装的技能版本

向 Portaly 报告此技能的版本，以便商家的仪表板能够标记已安装的技能是否过期。这是一次性、非阻塞的版本检查——请求正文仅包含技能名称和版本，不包含任何用户项目或数据的信息。向用户提及一次（例如：“正在报告已安装的 Portaly 技能版本，以便您的仪表板检测过期技能”）——无需暂停等待批准，但也不要隐瞒。

发送时机——每个会话发送一次，只要 process.env.PORTALY_API_KEY 已设置，就在以下时机中最先发生的那个时发送：

1. 安装或更新此技能后立即发送，前提是环境中已存在密钥。
2. 否则，首次调用任何 Portaly API 时发送——版本报告会随首次实际 API 使用一并发送。

• 如果环境中尚未设置 PORTALY_API_KEY，暂时跳过报告。绝不要仅为了发送报告而向用户索要密钥——这个技能尤其可能在用户还没有密钥时使用，因为它往往是用户加载的第一个技能。
• 请求：

  POST https://portaly.ai/api/creator-subscription/skill-version
  Authorization: Bearer {PORTALY_API_KEY}
  Content-Type: application/json
  
  { "skillName": "portaly-overview", "version": "0.3.1" }
  

• version 是本文件顶部 frontmatter 中此技能的 version——请使用当前正在运行的 SKILL.md 中的实际值，以确保报告反映已安装的版本。
• 请求正文仅包含 skillName 和 version。如果调用失败，请忽略并继续——它绝不会阻塞任何操作。
• 成功后，检查响应中的 data.available 数组——其中列出此商家账号从未报告过版本的技能，每项的格式为 { id, installPackage, latestVersion, description }。这不代表技能尚未安装：只有当技能自身的版本报告触发时，服务器才会知道此处存在该技能；这会发生在首次实际使用时，而不是运行 npx skills add 时。因此，已经存在于此项目中、只是尚未使用的技能，仍会出现在此列表中。提及任何内容之前，请先根据实际项目自行筛选：移除技能目录或文件已在本地存在的条目——服务器看不到项目目录树，只有你看得到。筛选后若没有剩余条目，则不必提及任何内容。对于剩余条目，在本会话中只向用户提及一次，说明他们可以添加这些技能（npx skills add ...），绝不要说他们缺少这些技能——列出每个技能的名称和一行说明。这仅用于发现技能——除非用户要求，否则不要自行运行 npx skills add。
• 如果此项目中安装了多个 Portaly 技能，每个技能都会发送各自的版本报告，并收到相同的 available 列表——每个会话只展示一次，而不是每个技能展示一次。如果你（或另一个 Portaly 技能）已在本会话中展示过 available 列表，则跳过此步骤。
• 如果 data.available 缺失、为空，或响应格式不符，则不执行任何操作——与调用失败时一样，忽略并继续；绝不能让此步骤阻塞任何操作。

护栏

• 此技能不会代表用户调用任何 Portaly API，上述版本报告除外（该报告为条件性操作——仅当 PORTALY_API_KEY 已存在时才会按所述时机发送；这不是提供给用户的选项）。此处仅用于说明方向——不要在这里尝试创建结账会话、创建套餐或处理回调；请转交给 portaly-payment / portaly-product。
• 切勿将用户引导至仅供管理员使用的端点或内部管理后台 API。 https://portaly.cc/admin/creator-subscription 是供人工操作的仪表板，不属于面向第三方的 API；只能提及这是人工创建 API 密钥的地方，不要将其作为可调用的接口。
• 不要在此处重复或另行编写 portaly-payment 或 portaly-product 中的详细工作流步骤。 如果用户需要实现细节，请引导他们使用相应的技能，而不要自行发挥。
• 如果本文档与 https://portaly.ai/docs 不一致，以文档为准。 将此技能中的映射表视为指引，而非约定。
• 不要臆造端点。 上文提及的每条路径都必须存在于 portaly-payment、portaly-product 或 portaly-email 的 references/api-contract.md 中，或存在于已发布的 /openapi.json 中。如果用户询问的功能未被映射表中的任何一行涵盖，请说明它目前不属于开放 API，而不要猜测一个听起来合理的端点。

资源

• ../portaly-payment/SKILL.md 和 ../portaly-payment/references/api-contract.md — 完整的订阅/支付约定。
• ../portaly-product/SKILL.md 和 ../portaly-product/references/api-contract.md — 完整的数字产品约定。
• ../portaly-email/SKILL.md 和 ../portaly-email/references/api-contract.md — 完整的邮件约定。
• https://portaly.ai/docs、https://portaly.ai/openapi.json、https://portaly.ai/llms.txt — 规范的 API 文档。