{"schema_version":"1","revision":"01896fed8a90d48b30a8acee435a4ac0eace7cabd3cf355730c2f4e139192ed5","pages":[{"path":"/cli/api","title":"发现与调用 API","locale":"zh-CN","markdown_path":"/markdown/cli/api.md","sha256":"2e4402cc1c47a0d21fc9f00806166e3d1195eb573bbf6fd31a175a61e4e864b6","headings":[],"excerpt":"发现与调用 API 以下示例使用 goodvision；项目内安装后使用 npx --no-install goodvision。安装与首次配置见快速开始。 request.json 首次用户空间请求为： 通用输入支持 path、query、headers 和 body，只接受当前 Schema 登记的参数。每项操作显示产品、版本、所需身份与最小 Scope。所需 Application Header 可从当前配置补入，其他授权和领域引用仍按 API 提供。流式 API 加 --stream 输出逐行 JSON。 api list [product] 与 api search <关键词... 可离线运行；搜索同时匹配操作 ID、产品、描述、路径、方法、身份和 Scope，忽略大小写，多个关键词须全部命中。按产品调用可使用 goodvision api <product <operationId。API 调用、事件便捷命令与 SDK 均消费同一 Owner 合同，不开放任意内部 URL。 --dry-run 只做本地校验和脱敏预览，不证明权限、费用或业务准入。普通输出为 {\"ok\":true,\"data\":...}，错误写入 stderr 并返回非零退出码。退出码 3 表示身份或权限拒绝，4 表示版本、幂等或租约冲突，5 表示写入结果未知；输入或依赖错误返回 1。 写操作不自动重试。结果未知时保留原请求和幂等键，先按该 API 的查询／恢复合同确认结果；不得换新键再次提交。详见幂等与重试。 成功状态仍需符合当前 API 合同。未登记的成功状态或 JSON／SSE 响应类型错配会返回错误；写请求已发出时按结果未知处理，并保留允许公开的请求标识。仅支持 SSE 的操作漏加 --stream 会在联网前拒绝，补齐参数后再调用。"},{"path":"/cli/authentication","title":"认证与配置","locale":"zh-CN","markdown_path":"/markdown/cli/authentication.md","sha256":"50ab3943dbbbb5ab56ea99eaaec756cc2545a8eb61d043f11189fd8b13cc23cb","headings":["常用认证与配置命令","授权与恢复"],"excerpt":"认证与配置 以下示例使用 goodvision；项目内安装后使用 npx --no-install goodvision。安装与首次配置见快速开始。 按操作合同选择身份。用户身份访问本人已授权范围；应用服务身份只能调用允许该身份的操作。 常用认证与配置命令 操作目标 对应命令 --- --- 初始化应用配置 goodvision config init --help 查看凭据配置状态 goodvision auth status 检查凭据可读取或获取 goodvision auth check 查看应用与环境 goodvision context 从当前应用取得 API 地址、应用 ID 及已授权的用户 Token，将 Token 保存在自己的受控文件中；文件仅本人可读，不提交到项目。配置只保存文件引用： auth status 离线显示是否配置凭据，不读取 Token，也不判断有效期。auth check 只检查凭据可读取或获取，不代表任何业务权限已通过。服务端接入可改用 --issuer \"$GOODVISION_IDENTITY_ISSUER\" --client-id \"$GOODVISION_SERVICE_CLIENT_ID\" --secret-file ./client-secret --scope openplatform.api.invoke，按需提供当前合同 Scope。此身份只用于应用已开通的能力，不能代替用户授权。 同文件可配置多个 profiles，通过 --profile 显式选择。环境只使用 sandbox 或 production。相对凭据文件按配置文件目录解析；失效、错应用、撤权或依赖故障不会自动切换身份／环境，也不会读取浏览器 Cookie。终端交互式 OAuth 登录不在首期认证合同中。 授权与恢复 用户授权沿用网页授权流程。auth status 不检查 Token 有效期，auth check 不枚举实际已有权限；所需 Scope 由 schema 提供，实际权限按 API 拒绝结果处理。终端 auth login/logout 和按业务域自动申请授权尚未实现。 移除 Profile 只删除本地配置引用，不等同于登出或撤销委托。通过现有授权入口撤销，再在同一有效身份和范围恢复原任务，写入需要显式重新执行。"},{"path":"/cli/capabilities","title":"GoodVision CLI 能力地图","locale":"zh-CN","markdown_path":"/markdown/cli/capabilities.md","sha256":"1b8f92ad016db04299544c80f4c9c69efad388aa8bcf733136bbfd26eb14d7c0","headings":["业务能力地图","在终端中探索"],"excerpt":"GoodVision CLI 能力地图 先了解 Agent 可以调用哪些能力，再选择具体操作。 业务能力地图 以下为公开合同已登记的能力，不表示当前应用已开通、目标环境可用或当前用户有权执行。用 goodvision api products 获取随本地工具版本交付的完整清单、产品版本、操作数量、身份、Scope 和文档入口；用 api list <product 展开具体操作。 业务域 能做什么 产品与接入指引 --- --- --- 模型与 Token 查询符合条件的可用模型、余额和用量；按公开合同调用 Chat Completions、Messages、Responses；查询套餐、订单及原支付结果 token-multimodal · Token API 客户经营 管理当前应用的公司资料与商业引用、产品使用者分配；处理线索、商机、报价、任务；查询报表与审计、上报订阅实际用量 appmarket-operations · 客户经营 API 订阅与商业化 查询商品、套餐、客户报价和订阅；接受或拒绝报价、确认免费套餐、变更或取消订阅、创建与查询原支付操作；读取已发布公开价格 commerce-checkout、public-pricing · SaaS 商业化 API 订单与支付 查询卖方订单、订单上下文与支付状态、按合同取消订单；接受当前一次性报价并创建或恢复原订单支付 appmarket-orders、order-payment · 卖方订单、订单支付 用户空间与委托 解析当前应用的用户／客户空间；查询授权选项，创建、判定、查询和撤销本人委托 customer-user-context、delegated-grants · 用户与事件、用户授权 应用目录 读取当前用户可见的应用发布信息 application-listings · 应用目录 事件与诊断 流式接收和确认原事件租约；查询原事件的访问快照与集成能力、提交履约结果；由当前用户上报受控客户端诊断 application-event-connection、application-event-processing、client-diagnostics · 应用用户与事件 在终端中探索 产品总览与 SDK 共用生成合同，不另行维护权限目录。凭据、交互与执行三层组合见 Agent 全局能力概述。"},{"path":"/cli/commands","title":"命令参考","locale":"zh-CN","markdown_path":"/markdown/cli/commands.md","sha256":"c6172882d1809def455e03c2ea4901c1293302e6ae73083cac0ae865d3bdfeb1","headings":["读取公开文档","全局参数"],"excerpt":"命令参考 以下示例使用 goodvision；项目内安装后使用 npx --no-install goodvision。安装与首次配置见快速开始。 目标 命令 --- --- 创建新配置 goodvision config init --help 查看当前身份配置 goodvision auth status 检查凭据获取 goodvision auth check 多应用管理 goodvision profile --help 发现 API／查看合同 goodvision api search <关键词／goodvision schema <operationId 读取公开指南 goodvision docs --help 调试事件 goodvision events --help 生成项目 goodvision init --help 读取公开文档 公开站点同时提供 llms.txt、版本化索引 和 /markdown/ 下的公开 Markdown。CLI 校验索引与正文摘要，可供脚本和 Codex 按需读取；不包含登录后的应用资料。英文使用 --lang en-US，页面路径以索引返回为准。 全局参数 --config <文件 指定配置，--profile <名称 固定单次上下文。--help 和 help <command 离线可用；--version 输出包版本和目录版本。发现、Schema 和预览均不读取凭据。API 调用支持 --input <文件-、--dry-run、--stream；事件 ACK 需要 --processed。"},{"path":"/cli/events","title":"接收与确认事件","locale":"zh-CN","markdown_path":"/markdown/cli/events.md","sha256":"11d8c515b16adb697fe4f7e5016c6613bfc182e4743e327b3cb908cf3f4ee087","headings":[],"excerpt":"接收与确认事件 以下示例使用 goodvision；项目内安装后使用 npx --no-install goodvision。安装与首次配置见快速开始。 events watch 需要当前应用的服务身份和 openplatform.api.invoke，收到事件不自动 ACK。业务已持久完成后，以当前租约的 delivery_id、lease_receipt 组成 ack.json，显式确认；过期租约不能反复重放。持续业务接收使用 event-receiver 模板，按事件 ID 幂等持久处理后 ACK。 持久接收或 HTTPS Webhook 项目见接入模板。"},{"path":"/cli/faq","title":"常见问题","locale":"zh-CN","markdown_path":"/markdown/cli/faq.md","sha256":"ef84d4a0ded2054a3f7366a3c8f4a94ddc095e3ac64da4361ff86ac9b65310d7","headings":[],"excerpt":"常见问题 - 找不到命令：先执行 npm install @goodvision/cli @goodvision/sdk，再使用 npx --no-install goodvision；确认项目的 node_modules/.bin 可用。 - 缺少配置：传入 --config ./goodvision.json，或在默认位置创建配置；配置不会自动覆盖。 - 退出码 3：核对当前应用、环境、身份类型和 Schema Scope；按用户授权恢复授权，再显式执行原任务。 - 退出码 4：回读当前资源版本、原幂等操作或事件租约，不盲目重复提交。 - 退出码 5：结果未知，保留原请求和幂等键并查询原结果。130 表示主动取消；写请求取消后同样需核对原结果。 在 Codex 中可直接要求：“使用 GoodVision CLI 查找当前应用可接入的公开 API，读取 Schema，先预览请求，确认后执行。”目录登记、凭据获取与真实业务授权分别检查。CLI 不自动安装 Agent 配置或 Skills，不包含扫码建应用、终端 auth login/logout 或第三方应用业务工作流。"},{"path":"/cli/profiles","title":"多应用与 Profile","locale":"zh-CN","markdown_path":"/markdown/cli/profiles.md","sha256":"bdf2dd0e177d7f735a80684e10a49399bbe9a30deb3112a6ca1533a972a81ee4","headings":["重命名或移除 Profile"],"excerpt":"多应用与 Profile 以下示例使用 goodvision；项目内安装后使用 npx --no-install goodvision。安装与首次配置见快速开始。 已有配置中添加另一个应用，不改变默认应用；config init --name <名称 可指定首个 profile 名称： profile list 展示应用、环境、凭据类型及默认标记，不读取或输出凭据。profile add 遇到重名拒绝覆盖；profile use 才会持久修改默认项。并发脚本使用每次调用的 --profile，不修改默认值。并发编辑失败时保留原配置；若遗留 .lock，先确认没有编辑进程，再处理该文件。 重命名或移除 Profile rename 保留应用、环境与凭据引用，重命名默认项时同步默认名称。remove 必须带 --yes，且拒绝移除默认项；先切换到其他项，最后一项不能移除。私有凭据文件可能供其他应用使用，移除配置不会删除它，也不会撤销服务端授权。 命令 说明 --- --- profile list 查看所有应用上下文 profile add --name <名称 ... 添加，不覆盖、不切默认 profile use <名称 持久切换默认项 profile rename <旧名称 <新名称 重命名，身份保持原样 profile remove <名称 --yes 移除非默认配置 --profile <名称 <命令 单次选择，并发场景使用"},{"path":"/cli/quick-start","title":"快速开始","locale":"zh-CN","markdown_path":"/markdown/cli/quick-start.md","sha256":"f3e16a46728ead61b973bed88f95b6399ae741ad90a115034be1255c38278cb0","headings":["1. 安装 CLI","2. 配置应用","3. 开始第一个任务"],"excerpt":"快速开始 1. 安装 CLI 需要 Node.js 22.22 或更高版本。产品名为 GoodVision CLI，命令为 goodvision（简写 gv）。客户端包名为 @goodvision/cli、@goodvision/sdk，与 @goodvision/ui 使用同一 npm scope，可直接从 NPM 安装，也可以从源码构建。 在接入项目中安装公开包： 持有源码交付物时，在源码根目录运行： 源码或离线 .tgz 制品只用于本地开发、验收或无网络环境。使用源码时，在源码根目录运行上面的构建门禁；使用离线制品时，将制品路径传给 npm install。 后续示例用 goodvision 表示命令入口；项目安装后可使用 npx --no-install goodvision，源码模式使用 node packages/cli/bin/gv.mjs。它只消费公开 API，操作列表不表示当前身份已获得授权或目标环境已开放。 2. 配置应用 从当前应用取得 API 地址、应用 ID 及已授权的用户 Token，将 Token 保存在自己的受控文件中；文件仅本人可读，不提交到项目。配置只保存文件引用： auth status 离线显示是否配置凭据，不读取 Token，也不判断有效期。auth check 只检查凭据可读取或获取，不代表任何业务权限已通过。服务端接入可改用 --issuer \"$GOODVISION_IDENTITY_ISSUER\" --client-id \"$GOODVISION_SERVICE_CLIENT_ID\" --secret-file ./client-secret --scope openplatform.api.invoke，按需提供当前合同 Scope。此身份只用于应用已开通的能力，不能代替用户授权。 同文件可配置多个 profiles，通过 --profile 显式选择。环境只使用 sandbox 或 production。相对凭据文件按配置文件目录解析；失效、错应用、撤权或依赖故障不会自动切换身份／环境，也不会读取浏览器 Cookie。终端交互式 OAuth 登录不在首期认证合同中。 3. 开始第一个任务 在 Codex 中输入： 本次请求的 request.json 为 {\"body\":{}}。核对预览后，去掉 --dry-run 显式执行；此 API 需要当前用户 Token。详见 API 调用和认证与配置。"},{"path":"/document/console/","title":"开发者后台","locale":"zh-CN","markdown_path":"/markdown/document/console/index.md","sha256":"fb7346a7e6df0f82764f20eb6281e6385b703cef046be31b5b6d678721e7d521","headings":["管理应用","配置 API 权限","获取凭据","查看调用诊断"],"excerpt":"开发者后台 开发者后台用于创建应用、配置认证和 API 权限、接收事件以及完成接入验收。使用本人账号登录，首次没有企业时自动准备个人空间；创建者自动成为应用所有者。普通成员按当前权限协作，无需先配置业务角色才能开始。 开发配置无需人工审核。正式上线时创建版本并提交审核，审核通过后发布。 进入开发者后台 管理应用 应用中心支持网格和列表视图，可按名称、Slug、环境、状态和类型搜索筛选。选择应用后，通过左侧目录进入对应页面。 应用内保留工作台、商业管理、应用管理、开发接入四个工作区，侧栏只显示当前工作区。创建普通 Sandbox 应用只需名称，代码自动生成；高级项按需展开。 页面 主要功能 --- --- 概览 查看当前应用信息和接入进度 凭证与基础信息 查看应用标识，获取或轮换应用身份凭据 OAuth/OIDC 配置 配置用户身份、回调地址和登录参数 收费与履约 按需配置收费方式、套餐和交付方式 API 与权限 自助配置 API 权限，获取调用配置和代码模板 事件与 Webhook 推荐长连接；按需配置 HTTPS、同步回调及独立测试结果 Sandbox 与上线 确认适用测试，准备独立的正式运行配置 版本管理与发布 创建版本、提交审核并发布；新草稿不影响已发布版本 应用协作者、应用设置 管理协作者、双语资料、所有权与删除 测试环境与人员 准备真人成员与 Sandbox 名单 安全设置 限制 OAuth 调用来源 IP 服务端日志、质量概览、客户端日志 筛选七日记录与完整窗口统计 支持与反馈 提交、跟踪并显式转交平台客服 应用中心的 应用开发流程 按创建、开发测试、版本发布提供对应指南。 配置 API 权限 在 API 与权限 中选择 应用身份权限 或 用户身份权限，再选择所需 API 产品和 Scope。点击 开通权限 后，平台自动校验配置并启用权限。每次配置针对一种身份。 产品名称、产品说明和 Scope 说明支持中文、英文。缺少当前语言的说明时，页面使用默认说明并显示提示。Scope、Audience、版本和路径使用产品提供的固定标识。 登录和 Token 由 GoodVision 统一身份服务提供，应用的组织范围和 API 权限由平台统一校验。开发者只需使用控制台展示的 Client、Issuer、Audience、Scope 和 API 地址，不需要接触平台管理接口。 保存后平台自动校验并完成 OAuth Client 和权限配置，成功即启用。接入无需通过管理接口自行注册或修改平台凭证。 选择身份后，可以复制非敏感的环境变量，以及获取服务 Token、调用 API 和用户 PKCE 登录的代码模板。模板使用占位值，不包含有效 Token、Client Secret 或 Webhook Secret。TypeScript/Node.js 项目可安装官方"},{"path":"/document/","title":"GoodVision 开发文档","locale":"zh-CN","markdown_path":"/markdown/document/index.md","sha256":"808b8bb38391daabdca317baa827ef6b26d0820f8fb4fadb92287bfb0f5b9381","headings":["新手入门","开放接口一览","开发与接入","参考资料","帮助与支持","开发者后台"],"excerpt":"GoodVision 开发文档 常见接入问题 如何获取 API 调用凭证？ 如何配置用户授权？ 如何接收事件通知？ API 调用失败，如何排查？ 查询环境、接口版本与调用限制，查看 环境与地址 · API 产品 新手入门 1. 了解基本流程 自建应用接入流程 介绍 创建应用、配置身份与权限，完成第一次 API 调用。 PC 网页应用接入 介绍 选择跳转或内置，完成开发测试、审核与发布。 2. 体验开放能力 服务端 API 教程 查看 API 产品、调用身份、版本和权限范围。 模型与 Token 教程 接入模型目录、文本推理、额度与用量查询。 用户登录 教程 通过 OAuth 2.0 与 PKCE 接入统一登录。 事件接收 教程 通过长连接快速接收事件，按需使用 HTTPS Webhook。 3. 接入产品与经营能力 订阅与支付 指南 接入订阅套餐、购买流程与支付恢复。 订单管理 指南 查询订单详情、查看付款状态和取消订单。 客户经营 指南 接入客户、团队与经营管理能力。 线索与机会 指南 登记销售线索、创建机会并记录跟进结果。 4. 开始开发 第三方接入代码示例 示例 参考身份认证、API 调用和 Webhook 接收代码。 开放接口一览 身份认证 获取令牌与用户登录 用户授权 创建、核验和撤销授权 API 产品 查看产品与申请权限 模型与 Token 购买套餐与调用模型 应用目录 查询客户可见应用 应用配置 选择和启用应用能力 订阅与支付 查询套餐与管理订阅 订阅生命周期 处理订阅状态变化 订单管理 查询和取消订单 独立订单支付 创建订单与恢复付款 客户经营 管理客户与经营数据 线索与机会 登记线索与跟进机会 事件目录 查看事件类型与字段 Webhook 验证签名与处理投递 账务参考 查看账务资源与规则 幂等与重试 避免重复操作与恢复请求 错误处理 查看错误码与处理建议 环境与地址 获取测试和生产配置 查看 API 产品与权限 GoodVision 开放平台 开发与接入 开始接入 应用配置 SaaS 接入案例 参考资料 API 产品 事件目录 接入代码示例 帮助与支持 环境与地址 错误处理 联系支持 开发者后台 管理我的应用 创建应用与开发测试 GoodVision 简体中文 ｜ English 请勿使用内部账号或他人凭证。Sandbox Token、Secret 和 Application 不得复制到 Production。"},{"path":"/en/cli/api","title":"Discover and call APIs","locale":"en-US","markdown_path":"/markdown/en/cli/api.md","sha256":"9802d57568e97877100ebd7c5dcdd1bf019a9e3c8df4d168e93af741bbd0e615","headings":[],"excerpt":"Discover and call APIs Examples use goodvision. After a project installation, use npx --no-install goodvision. See quick start for installation and first configuration. For the first user-space request, request.json is: Generic input accepts path, query, headers and body, limited to registered Schema parameters. Each operation includes its product, version, identity requirements and minimum Scopes. The current Application Header may be filled from configuration; other context and authorization references follow the API contract. Add --stream for newline-delimited JSON from streaming APIs. api list [product] and api search <terms... work offline. Search covers operation IDs, products, descriptions, paths, methods, identity types and Scopes; matching is case-insensitive and every term must match. Product calls also accept goodvision api <product <operationId. API calls, event shortcuts and the SDK share Owner contracts; arbitrary internal URLs are unavailable. --dry-run validates and redacts a local request preview; it does not establish permission, cost or business eligibility. Success is {\"ok\":true,\"data\":...}. Errors go to stderr with nonzero exits: 3 for authentication or permiss"},{"path":"/en/cli/authentication","title":"Authentication and configuration","locale":"en-US","markdown_path":"/markdown/en/cli/authentication.md","sha256":"4c37e397c673d5bdc24c9e1703054d9fcc6ff60e7b439587e96d16805fca6f76","headings":["Authentication commands","Authorization and recovery"],"excerpt":"Authentication and configuration Examples use goodvision. After a project installation, use npx --no-install goodvision. See quick start for installation and first configuration. Choose the identity required by each operation. User identity accesses authorized user context; application service identity only calls operations that permit it. Authentication commands Goal Command --- --- Create configuration goodvision config init --help Inspect credential configuration goodvision auth status Check credential acquisition goodvision auth check Inspect application and environment goodvision context Get the current API address, application ID and authorized user Token from your application. Keep the Token in a private credential file owned by your user; never commit it. Configuration stores the file reference: auth status shows credential configuration offline, without reading credentials or evaluating expiry. auth check proves only that credentials can be read or obtained. For application service access, replace the Token file option with --issuer \"$GOODVISION_IDENTITY_ISSUER\" --client-id \"$GOODVISION_SERVICE_CLIENT_ID\" --secret-file ./client-secret --scope openplatform.api.invoke, reque"},{"path":"/en/cli/capabilities","title":"GoodVision CLI capability map","locale":"en-US","markdown_path":"/markdown/en/cli/capabilities.md","sha256":"9415c7bb1bd77b413182962d2dfb573faacd4b37ea772c68fbe1fd884544adbe","headings":["Business capability map","Explore from your terminal"],"excerpt":"GoodVision CLI capability map Discover what your Agent can call before choosing an operation. Business capability map These capabilities are registered in public contracts. Registration does not establish application enablement, environment availability or user permission. Run goodvision api products for the full catalog shipped with your tool version, including product versions, operation counts, identity, Scopes and documentation. Expand operations with api list <product. Domain What you can do Products and guides --- --- --- Models and Token Query eligible models, balance and usage; call Chat Completions, Messages and Responses; inspect packages, orders and original payment results token-multimodal · Token API Customer operations Manage application company records and commercial references, allocate authorized product users, work with leads, opportunities, quotes and tasks, query reports and audits, and report actual subscription usage appmarket-operations · Customer operations API Subscriptions and commerce Read products, plans, customer quotes and subscriptions; accept or decline quotes, confirm free plans, change or cancel subscriptions, create and query original checkout ope"},{"path":"/en/cli/commands","title":"Command reference","locale":"en-US","markdown_path":"/markdown/en/cli/commands.md","sha256":"b6df7fa9f4700edbd0abfc5788d31888d7a1a8307d79b7a942f9945935e98d5a","headings":["Read public documentation","Global options"],"excerpt":"Command reference Examples use goodvision. After a project installation, use npx --no-install goodvision. See quick start for installation and first configuration. Goal Command --- --- Create configuration goodvision config init --help Inspect credential configuration goodvision auth status Check credential acquisition goodvision auth check Manage applications goodvision profile --help Discover APIs and contracts goodvision api search <terms / goodvision schema <operationId Read public guides goodvision docs --help Debug events goodvision events --help Scaffold a project goodvision init --help Read public documentation The public site provides llms.txt, a versioned index and public Markdown under /markdown/. The CLI checks index and body hashes for scripts and Codex. Authenticated application data is excluded. Select English with --lang en-US and use the page paths returned by the index. Global options --config <file selects configuration; --profile <name fixes the invocation context. --help and help <command work offline. --version reports the package version and catalog revision. Discovery, Schema and previews require no credential reads. API commands accept --input <file-, --dry"},{"path":"/en/cli/events","title":"Receive and acknowledge events","locale":"en-US","markdown_path":"/markdown/en/cli/events.md","sha256":"0d191a19818dc3ee3562720ff4636597fbb5729ef085b658ae72c5f131930068","headings":[],"excerpt":"Receive and acknowledge events Examples use goodvision. After a project installation, use npx --no-install goodvision. See quick start for installation and first configuration. events watch requires the current application's service identity and openplatform.api.invoke. It never ACKs automatically. After durable business processing, create ack.json from the current delivery_id and lease_receipt and acknowledge explicitly. Do not replay expired receipts. Use event-receiver for continuous consumption with durable, idempotent processing before ACK. Use integration templates for persistent reception or HTTPS Webhooks."},{"path":"/en/cli/faq","title":"Frequently asked questions","locale":"en-US","markdown_path":"/markdown/en/cli/faq.md","sha256":"006e29e12ae7cb603e2f95a0950898d63d65fff2e62d05157a6157308f95e08a","headings":[],"excerpt":"Frequently asked questions - Command unavailable: run npm install @goodvision/cli @goodvision/sdk, then use npx --no-install goodvision; confirm that the project's node_modules/.bin is available. - Configuration missing: pass --config ./goodvision.json or create configuration at the default location. Existing files are never overwritten by initialization. - Exit 3: check the application, environment, identity type and Schema Scopes. Restore user authorization, then explicitly invoke the original task. - Exit 4: read the current revision, original idempotent operation or lease before submitting again. - Exit 5: preserve the original request and idempotency key and query the unknown outcome. Exit 130 means cancellation; a cancelled write also requires checking the original result. In Codex, ask: “Use GoodVision CLI to discover public APIs for this application, inspect the Schema, preview the request, then execute after confirmation.” Check catalog registration, credential acquisition and business authorization separately. The CLI does not install Agent configuration or Skills and does not provide QR application creation, terminal auth login/logout or third-party business workflows."},{"path":"/en/cli/profiles","title":"Multiple applications and Profiles","locale":"en-US","markdown_path":"/markdown/en/cli/profiles.md","sha256":"30761de720c1ba3d968c88efe7ea5deaa93b2c2ff872b176e05fd713a1acd71c","headings":["Rename or remove a Profile"],"excerpt":"Multiple applications and Profiles Examples use goodvision. After a project installation, use npx --no-install goodvision. See quick start for installation and first configuration. Add an application to an existing configuration without changing the default. For the first profile, config init --name <name selects its name: profile list reports applications, environments, credential kinds and the default marker without reading or exposing credentials. profile add rejects duplicate names. Only profile use persists a new default. Concurrent scripts should select --profile per invocation. Concurrent edits fail without changing the original configuration; investigate a leftover .lock only after confirming no editor is active. Rename or remove a Profile rename preserves the application, environment and credential references; renaming the active entry updates its name. remove requires --yes and rejects the active Profile. Select another Profile first; the last entry cannot be removed. Credential files remain available to other applications, and server authorization is unchanged. Command Purpose --- --- profile list List application contexts profile add --name <name ... Add without overwri"},{"path":"/en/cli/quick-start","title":"Quick start","locale":"en-US","markdown_path":"/markdown/en/cli/quick-start.md","sha256":"b8277188be85d30c680e6b0049095b9cf3e5a6cd11f0720b132531b8399ac9f1","headings":["1. Install the CLI","2. Configure your application","3. Run your first task"],"excerpt":"Quick start 1. Install the CLI Use Node.js 22.22 or later. The product is GoodVision CLI, invoked as goodvision (shorthand: gv). Packages @goodvision/cli and @goodvision/sdk share the @goodvision npm scope with @goodvision/ui; install them from npm or build from source. Install the public packages in your integration project: With the source distribution, run from its root: Source checkouts and offline .tgz artifacts are for local development, acceptance, or environments without registry access. For a source checkout, run the build gate above; for offline artifacts, pass their paths to npm install. Examples below use goodvision. After a project installation, use npx --no-install goodvision; for a source checkout, use node packages/cli/bin/gv.mjs. The CLI consumes public APIs; listing an operation grants no permissions and does not establish target-environment availability. 2. Configure your application Get the current API address, application ID and authorized user Token from your application. Keep the Token in a private credential file owned by your user; never commit it. Configuration stores the file reference: auth status shows credential configuration offline, without reading c"},{"path":"/en/document/console/","title":"Developer Console","locale":"en-US","markdown_path":"/markdown/en/document/console/index.md","sha256":"0823d1e50185ef9e996f756371f925960e72bc5db230481137af24d725bff3cb","headings":["Manage Applications","Configure API access","Get credentials","View call diagnostics"],"excerpt":"Developer Console The Developer Console lets you create Applications, configure authentication and API access, receive events and complete integration acceptance. Use your own account; an account with no enterprise gets a personal space automatically. The creator becomes the Application owner. Ordinary members collaborate with current access without preparing business roles first. Development configuration needs no human review. To launch, create a version, submit it for review and publish after approval. Open Developer Console Manage Applications The application center supports grid and list views, with search and filters for name, Slug, environment, status, and type. Select an Application, then open the required page from the sidebar. The Workbench, Commerce, Application and Developer integration workspaces remain, with the sidebar showing only the current workspace. Creating an ordinary Sandbox Application requires a name; its code is generated and advanced fields are optional. Page Main functions --- --- Overview View Application information and integration progress Credentials and basic information View identifiers and retrieve or rotate application credentials OAuth/OIDC conf"},{"path":"/en/document/","title":"GoodVision Developer Documentation","locale":"en-US","markdown_path":"/markdown/en/document/index.md","sha256":"b81514a036f1a8429ef781599b9b7e8799d6d0320e90fd7373e7f1c920905a6c","headings":["Getting started","Explore open APIs","Build & integrate","Resources","Help & support","Developer console"],"excerpt":"GoodVision Developer Documentation Common integration questions How do I get API credentials? How do I configure user consent? How do I receive event notifications? How do I diagnose a failed API call? For environments, versions, and calling limits, see environments and URLs · API products Getting started 1. Understand the basics Custom application integration Overview Create an application, configure identity and permissions, and make your first API call. PC web application integration Overview Choose redirect or embedding, test, obtain review, and publish. 2. Explore platform capabilities Server APIs Tutorial Explore API products, calling identities, versions, and scopes. Models & tokens Tutorial Integrate model discovery, text inference, balance, and usage queries. User sign-in Tutorial Connect user sign-in with OAuth 2.0 and PKCE. Receive events Tutorial Start with a long connection, or use HTTPS webhooks when needed. 3. Build and operate your product Subscriptions & payments Guide Integrate plans, purchases, and payment recovery. Order management Guide Query order details, check payment status, and cancel orders. Customer operations Guide Integrate customer, team, and business"},{"path":"/en/getting-started/","title":"Application integration workflow","locale":"en-US","markdown_path":"/markdown/en/getting-started/index.md","sha256":"dccbe6956b8d1ff15f3c201f9b78d5b36a5240156fea4e32e8ac9b80f250c9d8","headings":["Before you start","Integrate user login in three steps","Step 1: Create an Application","Step 2: Enter the callback and copy configuration","Step 3: Implement the callback and verify login","Add APIs as needed (optional)","Receive business events (optional)","Add subscriptions and payments (optional)","Sandbox acceptance checklist","Prepare Production and launch"],"excerpt":"Application integration workflow This guide explains how to integrate GoodVision login, then add APIs, events and commerce as needed. For login only, create an Application, enter the callback and copy configuration, then verify login. Before you start Sign in to the Developer Console for the current environment. An account with no enterprise gets a personal space automatically and can create an Application there. Its creator becomes the Application owner without preparing business roles. Join an existing enterprise and obtain Application access when collaborating on its Applications. Prepare a product name and an implemented login callback such as https://app.example.test/auth/callback. One independent product in one environment uses one Application. User login and backend calls use two identities within that Application. Sandbox and Production use separate Applications. To correlate users across products, see Applications, users and events. Integrate user login in three steps Step 1: Create an Application Enter the Application name and create it. Sandbox is the default and the application code is generated automatically; expand advanced settings only to customize it. Check the env"},{"path":"/en/getting-started/sandbox-access","title":"Create and test an application","locale":"en-US","markdown_path":"/markdown/en/getting-started/sandbox-access.md","sha256":"3555c37f599fdf8f426a099cec6e0d4a46ec91b7614db3cab0052fb95ef97b6b","headings":["Prepare the configuration you need","Create and test the application","Prepare test enterprises and members","Confirm applicable tests","Get integration configuration","Common states"],"excerpt":"Create and test an application Sandbox supports application development and testing. Use your own account in the Developer Console for the current deployment environment. An account without an enterprise gets a personal space automatically, and the Application creator becomes its owner. After saving, the platform checks the application, OAuth identity, API access grants and Webhook and enables them without human review. Correct reported errors and retry. Contact support to recover historical applications without a responsible owner. One independent product uses one Application, with application identity, user identity, or both. Each has separate OAuth client and API permission configuration. The Application Owner can reveal or rotate the application Secret according to the current credentials page. User identity uses PKCE and requires no Client Secret. For login only, create the Application, enter its callback and copy configuration, then verify login. See Application integration workflow. APIs, events and commerce are optional; unselected capabilities do not block login. The platform resolves the user and customer space, with no fixed customer organization ID; the contract must be"},{"path":"/en/guides/access-and-permissions","title":"Integration entry points and permissions","locale":"en-US","markdown_path":"/markdown/en/guides/access-and-permissions.md","sha256":"db2ca8f263ac55e8464ef243d0b3e16b63f2605af2f71f9414d74b9f7945613b","headings":["Choose a calling identity","Basic concepts","Complete setup on the current page","View and manage API permissions","Close permissions","Import and export permissions","Unified entry points","Test entry points for a Sandbox Application","Production environment (Production)","Configuration entry points","API authorization requirements","Request and configuration flow","Troubleshoot 401 and 403 responses","Integration boundary","Customer space after login"],"excerpt":"Integration entry points and permissions Use application permissions for background automation and user permissions when acting for the signed-in user. One Application can enable both identities, each with separate credentials and permissions. This guide describes calling identities, entry points, and authorization requirements. After sign-in, each API request still checks the Application, identity, API access, organization, and resource permissions. The Developer Console shows Application permissions and User permissions. Protocol names such as identity_type and OAuth Profile in API and diagnostic details refer to these identity configurations. Choose a calling identity Your scenario Choose Client Secret The request represents --- --- --- --- Scheduled jobs, background sync, service-to-service calls Application permissions Required; store it server-side only The Application A signed-in user views or changes their own data User permissions None; PKCE is required The Application and current user A product has both foreground and background work Enable both and request API permissions separately Separate configuration Exactly one identity per request Application permissions never inh"},{"path":"/en/guides/agent-integration","title":"Agent integration overview","locale":"en-US","markdown_path":"/markdown/en/guides/agent-integration.md","sha256":"df5a7ef8ca7b46fa32ab19a6b8b31494931293dae75a08414ef569815a9dfe0b","headings":["Capabilities at a glance","Choose your integration path","Business capability map","Shortest path to a first call","SDK and events","Availability and next steps"],"excerpt":"Agent integration overview GoodVision offers three composable capabilities for Agent developers: choose an identity, receive business changes, and execute business actions. Applications and credentials establish the application, user or service identity, and environment. Event SDK receives subscribed events over a long connection or Webhook and acknowledges them after durable processing. GoodVision CLI lets Codex discover APIs, inspect parameters, preview requests, and call public model, customer, subscription and order operations. Use the same TypeScript SDK in application code. Capabilities at a glance GoodVision Agent capability layers and three integration paths Combine layers as needed. Calling an API requires its identity but does not require an event connection. The interaction layer here receives business events; a conversational Channel SDK with streaming messages or cards is unavailable. Capability When to use it Form Integration guide --- --- --- --- Applications and credentials · Identity layer Establish identity, consent, Scopes and sandbox or production context. Goal: obtain the identity required for this task. Developer console, web OAuth/PKCE, application service cr"},{"path":"/en/guides/application-diagnostics","title":"Query call logs and quality","locale":"en-US","markdown_path":"/markdown/en/guides/application-diagnostics.md","sha256":"a75e921107bbcf009d22eb17509a7dafa572f6a5613435b22c65e51f0c40a98f","headings":["Query server logs","View quality","Query client logs","Link technical feedback"],"excerpt":"Query call logs and quality Use server logs to locate API requests and Quality overview to inspect metrics for the entire selected window. Client logs show diagnostics explicitly reported by your application and do not prove server execution. Query server logs 1. Open the current Application → Developer integration → Server logs. 2. Select a start and end within the last seven days, or use the 1-, 3- or 7-day options. 3. Enter a Request ID or other known filters and select Search. Filter Description --- --- Request ID Exact request lookup URL path and request method Use a public route template such as /open-platform/v1/token-orders/{id}, without a hostname, query parameters or actual customer ID User OpenID The current Application user's open_id; do not use an identifier from another Application API Product and operation Match the configured product and operation OAuth profile ID and calling identity Distinguish user and application calling configuration Call result, reason code and HTTP Filter structured results Error message Case-insensitive search within fixed explanations; request bodies are not searched Records include time, Request ID, HTTP status, duration and collected safe"},{"path":"/en/guides/application-directory","title":"Application directory","locale":"en-US","markdown_path":"/markdown/en/guides/application-directory.md","sha256":"efca4dd5fea80239b47e5cbb2edf8bb63070c083c046664fcb06e6735c62bce1","headings":["1. Prepare the current user identity","2. Read visible applications","3. Errors and retries","Directory entry and login configuration","Embed in Console"],"excerpt":"Application directory The application directory queries published Applications visible to the current customer organization, allowing you to display them in your own product. Querying the directory does not purchase products, create subscriptions, or grant access. 1. Prepare the current user identity Complete user authentication to obtain a user Access Token for the current environment, and select an Organization where the user is a member. This shared endpoint checks the current user and Organization relationship; it does not require a separate commerce API product. A service identity cannot replace the customer user. 2. Read visible applications GET /open-platform/v1/application-listings returns {\"items\": [...]}. The array is empty when no applications are visible. Each item includes current publication data: id, application_id, environment, resource_version and OpenAPI-defined display fields. The platform filters public and organization-specific publications for the current customer. sales_offer_refs contains available offer references. Query purchase eligibility, amounts and product activation separately. Display the current response. Clear previous data and read again after an"},{"path":"/en/guides/application-management","title":"Manage application details, collaborators and versions","locale":"en-US","markdown_path":"/markdown/en/guides/application-management.md","sha256":"0ec3d3b07153c192276698caab5e90602b27b0c66287bca74d2fa1b2b6e83746","headings":["Configure each feature","Update Chinese and English details","Add or revoke collaborators","Transfer ownership","Review and publish an application version","Delete an application"],"excerpt":"Manage application details, collaborators and versions Use the Application workspace to maintain Chinese and English details, collaborators and ownership, and record validated configuration versions. Application collaborators manage the Developer Console; customer product access and commercial subscriptions are configured separately. Configure each feature Delivered development and operations features are available in your own application scope after creation. Development opens API and permissions by default. Configure login under OAuth/OIDC or identity settings, APIs under API and permissions, and receivers under Events and Webhooks. Saving each resource automatically associates and validates its configuration; no aggregate form or second enable step is required. Use Commerce → Billing and fulfillment only for billing methods, one-time products, subscriptions, fulfillment, and product access. Select real authorized resources and save once. You can skip commerce when testing login, APIs, or events. Save customer information and the entry URL under Application publication. Ordinary draft changes preserve the published version. For production, complete applicable testing, create a ve"},{"path":"/en/guides/application-security","title":"Configure application security and credentials","locale":"en-US","markdown_path":"/markdown/en/guides/application-security.md","sha256":"4455207982559b5ff0a430618eeb5c5ad814dace5ee4432550cd6776df73a433","headings":["Retrieve current credentials","Restrict source IP addresses","Recover from a source restriction"],"excerpt":"Configure application security and credentials Retrieve the credentials required by the current Application and optionally restrict OAuth API calls by source IP. User sign-in, application backend calls and HTTPS event receivers use different credentials. Retrieve current credentials Open “Application → Credentials and basics” and check the Application, environment, integration status and corresponding Client ID. Purpose Credentials How to obtain them --- --- --- User sign-in User Client ID; no Client Secret Enable user identity and register an exact callback in OAuth/OIDC configuration Backend APIs or long connection Application Client ID and Client Secret Temporarily reveal or rotate through the credentials page with current permission, or use its approved delivery channel HTTPS events or synchronous callbacks HMAC Secret; Verification Token and Encrypt Key when configured Use the dedicated receiver settings in the event page, or its current delivery channel Secrets are masked by default. After explicit retrieval, store them in the corresponding server. Leaving the page, changing enterprise or Application, expired sign-in or access changes clears temporary values. Ordinary configu"},{"path":"/en/guides/application-users-and-events","title":"Applications, users and event correlation","locale":"en-US","markdown_path":"/markdown/en/guides/application-users-and-events.md","sha256":"bd1182547fdb4e85b602df33b74ce0157da82d7e22f274365f39e65061db6218","headings":["1. How many Applications do you need?","2. Configure only what you use","3. Resolve the user and customer space after login","4. Correlate events with business records","5. Minimal integration checks","6. Report client diagnostics","7. Receive events over a persistent connection","8. Process received fulfillment and membership events"],"excerpt":"Applications, users and event correlation This guide covers login, customer relationships and events when one developer business owns multiple Applications. Application A and Application B are fictional examples. 1. How many Applications do you need? Product setup Configuration --- --- Two independent products Two Applications with separate login, API grants, webhooks and subscription plans One product needs login and background calls Enable user and service identities in one Application; these identities do not require two Applications Sandbox and Production for one product Independent Applications; Production references an accepted Sandbox The business at the top of Developer Console manages your Applications. Common ownership does not share Clients, Secrets, API grants, user consent or paid access. Two Applications may use the same server code, but requests and events must use their own Application, environment and credentials. Do not use Application A's Client for Application B or combine their subscription records. Applications and customer spaces View the full relationship diagram 2. Configure only what you use User login alone does not require a service Secret. A product tha"},{"path":"/en/guides/appmarket-operations","title":"Business operations API","locale":"en-US","markdown_path":"/markdown/en/guides/appmarket-operations.md","sha256":"edbab7850f89f99f8e41cc7c3befee3308923dfffa3bea929db1108d6ed600a6","headings":["Setup","Operations and scopes","Companies and purchases","Sales leads","Sales opportunities","Sales reports and logs","Webhook deliveries","Customer personnel and seats","Subscription usage","Commercial tasks","Quotations","Write requests and retries","Queries and operations","Create quotations","Manage commercial tasks","Query subscription usage","View monthly statistics","Report usage","Read customer personnel and assign seats","View company details","Paginate lists","Sales reports","Sales operation logs","Webhook delivery history","Errors and recovery"],"excerpt":"Business operations API The business operations API provides companies, commercial links, purchases, personnel assignments, leads, opportunities, tasks, usage records, sales reports, and audit summaries for building your own back office. Enable the required permissions under APIs and permissions → User identity → AppMarket Business Operations. For order endpoints, see Order management. Setup 1. Delivered company and sales features are available in your own application scope. Your current duties and data scope are checked on every request. 2. Configure the required Scopes. Copy the Base URL, Application ID and API Product ID, and explicitly select the environment. The platform derives the Client and Audience from the effective configuration. 3. Sign in with this application’s user OAuth authorization code + PKCE. Follow user authorization to confirm consent bound to the same application, environment, API product and Scopes. Use {\"resource_type\":\"appmarket_product\",\"resource_ids\":[\"your-product\"]}. 4. Call from your own server. Each request supplies one Authorization: Bearer <userToken, X-GV-Organization-ID (provider organization), X-GV-Application-ID, X-GV-Environment, X-GV-API-Prod"},{"path":"/en/guides/appmarket-orders","title":"Order Management","locale":"en-US","markdown_path":"/markdown/en/guides/appmarket-orders.md","sha256":"cb8133bd1b87441808deb8e364f76a3ad2313b4132ee326c5ebe82e19de7064f","headings":["Enable and authorize","Public endpoints","Filters and meaning","Cancellation and recovery","Errors","Display names","Payment evidence inside an order"],"excerpt":"Order Management Order management supports order queries, cancellation, and payment status checks. Use Developer Console → Commerce → Orders or build your own back office with the public API. Both follow the same business rules. Orders are isolated by provider organization, Application, product, and environment. No customer company selection is required. Enable and authorize 1. Order management is available in your own application scope without a separate enable step. Open Commerce → Orders. If access is denied or disabled, check your current duties and application state. 2. Under API and permissions, select the user identity and Order Management. Configure the required Scopes. Copy the Application ID, API Product ID and Base URL, and select the sandboxproduction environment. The platform derives the Client and Audience from the effective configuration. 3. Sign in using that application's user OAuth authorization code with PKCE. The token must be issued for that user client and include the required Audience and Scope. Your own backend may keep its own user session and call this API. 4. Select the provider enterprise and confirm person consent for {\"resource_type\":\"appmarket_product"},{"path":"/en/guides/authentication","title":"Authentication and authorization","locale":"en-US","markdown_path":"/markdown/en/guides/authentication.md","sha256":"d6a202eb1f8e8f4f2aa7f2e68bbe790b45b01829244cde37bb2d262e587aa659","headings":["Developer Console sign-in","Recover expired sign-in","Verify sensitive actions","Choose an OAuth flow","Configure an OAuth client","Obtain a Sandbox Application backend service token","User sign-in","Authorization checks","Security notes","User and customer space after login"],"excerpt":"Authentication and authorization GoodVision provides identity authentication through OAuth 2.0 and OpenID Connect. This guide explains how to choose an authentication flow, obtain an access token, and integrate user sign-in. One Application supports application and user identities, each with a separate OAuth client, API grant, and status. After authentication, business APIs still check audience, scopes, organization, ProductAccess, and resource ownership. Developer Console sign-in The Developer Console uses GoodVision's managed identity service for sign-in. The process is: 1. Use your own account to complete Authorization Code + PKCE sign-in with the managed identity service. 2. The platform reads available enterprises. An account with no enterprise gets a personal space automatically, followed by a current access check. 3. Enter the selected valid enterprise or explicitly choose an available one. The Application creator automatically becomes its owner without preparing business roles. 4. Ordinary members collaborate according to current Application access. Revoked enterprise or Application access stops operations in that scope rather than silently switching to another enterprise. "},{"path":"/en/guides/callbacks","title":"Handle synchronous callbacks","locale":"en-US","markdown_path":"/markdown/en/guides/callbacks.md","sha256":"212486ea834edb6ec25d64cc690fae0a7fd4bec4a02bfcd1775329955de3dfa0","headings":["Configure and test","Receive the request","Return a result","Timeouts and unknown results"],"excerpt":"Handle synchronous callbacks A synchronous callback requires the receiver to return a structured result within one HTTPS request. Configure it separately from asynchronous events. Selecting a long connection for events does not change synchronous callback transport. You can configure token.agent.action.v1 and send synthetic Sandbox tests. Actual TOKEN business calls are not available yet. Saved configuration or a successful test does not prove production use. Configure and test 1. Select the callback type under the current Sandbox Application → Developer integration → Events and webhooks → Callback configuration. 2. Configure a public HTTPS receiver, complete endpoint verification, and prepare signature validation, Verification Token and decryption according to current settings. 3. Save, send one synthetic test and inspect the separate callback result and receiver records. If saving fails, follow configuration recovery. Recover configuration separately from checking an already sent test; recovery does not automatically send another test. Asynchronous event and synchronous callback sets are saved independently; preserve the other complete set when changing one. A changed URL require"},{"path":"/en/guides/code-examples","title":"Integration code examples","locale":"en-US","markdown_path":"/markdown/en/guides/code-examples.md","sha256":"51ab404aae28469462409838a1beec3ef3f1661da36379910cd87ea23b0a38b5","headings":["1. Choose the caller identity","2. Copy values from the Console","3. Server environment template","4. Application identity: obtain a token","5. Call an API","6. User sign-in: PKCE","7. Receive Webhooks","8. Node.js, Go, and Python examples","Node.js (built-in `fetch`)","Go (standard library)","Python (standard library)","SDK support","Notes","User and space after login"],"excerpt":"Integration code examples This guide provides code examples for access tokens, API calls, PKCE sign-in, and webhooks. Create an Application and enable the required API access in the Developer Console before integration. Examples use placeholders. Copy the issuer, Client ID, API address, audience, and scopes from the current Application into your server configuration. 1. Choose the caller identity Need Choose Token flow Secret --- --- --- --- Background jobs, scheduled sync, service-to-service calls Application identity permissions Client Credentials Client Secret on the server only User sign-in and calls on behalf of that user User identity permissions Authorization Code + PKCE (S256) No Client Secret If both are needed, enable and request them separately in the same Application. The identities must not share Clients, scopes, or tokens. 2. Copy values from the Console Console page Copy Used for --- --- --- OAuth/OIDC Issuer, Client ID, callback URLs Sign-in and token requests APIs and permissions API Base, audience, approved scopes, paths Backend API calls Events and Webhooks Webhook URL, event types, secret delivery status Receiving events Copy only values approved for the current"},{"path":"/en/guides/developer-tooling","title":"GoodVision CLI","locale":"en-US","markdown_path":"/markdown/en/guides/developer-tooling.md","sha256":"75f6fb58a7dd74a0bf6864b9888c0ed5b1405d026b50b69fa3704e780dd9076f","headings":["Quick start","Use cases","Capability map","Documentation"],"excerpt":"GoodVision CLI GoodVision CLI lets Codex discover and call GoodVision public APIs from your terminal. Inspect a capability and its parameters, preview the request, then execute authorized model, customer, subscription or order operations with structured results. The product is GoodVision CLI; run goodvision or its shorthand gv. Package @goodvision/cli uses the same @goodvision npm scope and maintaining team as @goodvision/ui. The CLI and SDK are available from npm and can also be built from source. Quick start 1. Install the CLI from npm or build it from source. 2. Configure identity for your application and environment. Choose user or service credentials according to the operation. 3. Discover, preview and call your first API. Use cases Task Ask Codex Capabilities --- --- --- First application integration Find the user-context API, inspect its required Scopes and preview my sandbox request. Discovery, Schema, request preview Model integration Inspect available model APIs and build code to query models and usage for my authorized context. Token APIs, SDK types Customer operations Find company, lead and quote operations. Show me the required references and a preview before changing "},{"path":"/en/guides/event-connection","title":"Receive events over a long connection","locale":"en-US","markdown_path":"/markdown/en/guides/event-connection.md","sha256":"618e888ae16b5a6a238ff5859adb8eda74435fc63829a986ca0c77088a194873","headings":["1. Select events","2. Configure and run the example","3. Send a test and integrate your business handler","Connection and recovery contract"],"excerpt":"Receive events over a long connection Start with the recommended long connection. Your server opens it; no public receiver URL, challenge, HMAC Secret, Verification Token or Encrypt Key is needed. Use the application's service identity and Client Credentials. User login credentials cannot receive this connection. This is a runnable Node.js 22 example with no dependencies, not an SDK. You can also use HTTPS Webhooks with an existing public receiver. Synchronous callbacks continue to use HTTPS separately. Event reception choices and independent synchronous callback diagram Diagram: choose long connection or HTTPS for asynchronous events; configure synchronous callbacks separately. This illustrates a flow rather than a Console screenshot. 1. Select events Open the current application → Events and webhooks and keep the recommended long connection. If no service identity is available, select “Enable application identity” on this event page and wait for the platform to confirm the current state before continuing. Enabling identity does not grant business API permissions. Add at least one event and save. No events can be received with zero selections or an inactive configuration. This pag"},{"path":"/en/guides/idempotency","title":"Idempotency and retries","locale":"en-US","markdown_path":"/markdown/en/guides/idempotency.md","sha256":"43f717a2d88760581892133a4f96b7b3c50077ccecd89e089be39c7a9e671431","headings":["Generate one key per logical operation","Recover after a timeout","Retry decisions","Webhooks are idempotent too"],"excerpt":"Idempotency and retries Idempotency prevents a business operation from running twice during retries. GoodVision write requests use a stable Idempotency-Key; repeating the same request does not create duplicate results. After a network timeout, the server may already have completed the operation. Retain the original request content and key, then follow the recovery steps below. Generate one key per logical operation Generate an unpredictable key when the user begins an operation. Persist it with the local command record and reuse it for every retry of the exact same payload. Never reuse a key for a different payload. The service can return 409 Conflict when the key is already bound to another request fingerprint. Recover after a timeout 1. Retry the exact payload with the original key. 2. Query the asynchronous operation when an operation_id is available. 3. Read the current resource state to determine whether the original command completed. 4. Generate a new key only when the user intentionally starts a new logical operation. Do not switch keys after a timeout and accidentally duplicate an order, cancellation, payment, or refund operation. Retry decisions Condition Caller action --"},{"path":"/en/guides/integration-templates","title":"Integration templates","locale":"en-US","markdown_path":"/markdown/en/guides/integration-templates.md","sha256":"b0f2d0092297092993a981f154e3f7c080ed5f48d6aba278b6d601f327251313","headings":[],"excerpt":"Integration templates Use GoodVision CLI to create a minimal project after installation. Template Purpose --- --- api First API request pkce-web Web user consent with PKCE event-receiver Durable SSE reception and explicit ACK webhook HTTPS event reception and signature checks The four templates provide a first API call, web PKCE, persistent long-connection reception and plaintext HTTPS Webhook reception. Scaffolding creates a new directory without installing packages or executing scripts. Follow its README. Event templates do not fulfill customer purchases or payments; implement business processing against each event Schema and resource version."},{"path":"/en/guides/order-payment","title":"Independent order payment","locale":"en-US","markdown_path":"/markdown/en/guides/order-payment.md","sha256":"4cbee496cf71ee6bcea009132bd838508d4df1c033f76bf7d03b0baf3c3fbfc9","headings":["Prerequisites","API permissions","Create an order and payment","Errors and recovery"],"excerpt":"Independent order payment Independent order payment supports one-time product purchases. This guide covers offer queries, order creation, payment pages, and recovery of the original order's payment. Prerequisites Development configuration and testing do not require manual review. Delivered operations features are available in your own application scope. Configure one-time products only when needed; they are not required for login, API, or event testing. In Developer Console, open the current application's Commerce → Billing and fulfillment page. Select the one-time product and its approved offer, then save for automatic validation. The offer pins a product, price and terms revision. Customer payer eligibility is approved separately; application management or company directory access does not authorize customer payments. API permissions Sign in using the application's user OAuth profile and request the independent payment API scopes: Scope Purpose --- --- commerce.order_payment.catalog.read Read the approved one-time offer commerce.order_payment.order.read Read original orders and payment state commerce.order_payment.checkout.create Accept an offer and recover original checkout When"},{"path":"/en/guides/product-access-snapshot","title":"Product access snapshot","locale":"en-US","markdown_path":"/markdown/en/guides/product-access-snapshot.md","sha256":"344b2496eed5852b52cce2ede72804151f1c8a9816b4d473ff6ce5c1ee5cb58e","headings":["Request","Apply the result","Failure and recovery"],"excerpt":"Product access snapshot After receiving oem.access_context.changed.v1, query current member permissions with the application service identity. Request POST /open-platform/v1/applications/{id}/events/{event_id}/access-snapshot Use GOODVISION_API_BASE, a Bearer Token issued to the current application service Client, scope openplatform.api.invoke, and an empty JSON object {}. Enable the member-access feature for the application. Ordinary users need no operations role or service permission. id selects the current application; event_id selects an original access event recorded for it. The original event determines the customer space, product and member. Additional customer, organization, Profile or environment selectors are rejected. This endpoint does not list customers or all members. Credentials from another application cannot read the event. Apply the result The response contains application_id, environment, product_code, audience, organization, product_access, exactly one members entry, entitlements, capabilities, and generated_at, with Cache-Control: no-store. The member identifier membership_id matches space.membership_id in the user context. It is not interchangeable with open_i"},{"path":"/en/guides/saas-commerce-api","title":"SaaS subscription and payment API","locale":"en-US","markdown_path":"/markdown/en/guides/saas-commerce-api.md","sha256":"1fc16d37e94206135f089daeffbaacf97a40da67627ca9965ee70a6f8e501522","headings":["1. Prepare permissions","2. Read plans and create a checkout","Read public prices anonymously","Find quotations for an opportunity","View received quotations","3. Read, cancel and change subscriptions","Activate a free plan","Upgrade a free subscription","Read subscriptions","Cancel or change a plan","4. Errors and recovery","5. Configure subscription plans and Credits","Enable free activation","Configure Credits","Configure a first-month offer","Personal, business and SaaSdemo reference plans","Publish plans before configuring the product address","Independent pricing page and URL selectors","Configure one-time Credits add-ons"],"excerpt":"SaaS subscription and payment API The SaaS subscription and payment API provides plan queries, payment creation, and subscription management. For integration with the platform's ready-made pages, see Third-party SaaS billing. Enable the corresponding API product for the current Application and use its specified environment and version. Production is not open; product registration does not activate it. 1. Prepare permissions Configure API permissions for the current application in Developer Console, then call the API as the customer user. The customer also needs valid organization membership, commercial details and payment authority. Send the following headers with each request: Endpoint Minimum Scope --- --- GET /open-platform/v1/products commerce.catalog.read POST /open-platform/v1/checkout-sessions commerce.checkout.create POST /open-platform/v1/free-activations commerce.checkout.create GET /open-platform/v1/operations/{id} commerce.checkout.read GET /open-platform/v1/subscriptions commerce.subscription.read GET /open-platform/v1/subscriptions/{id} commerce.subscription.read POST /open-platform/v1/subscriptions/{id}:cancel commerce.subscription.manage POST /open-platform/v1/subsc"},{"path":"/en/guides/saasdemo","title":"SaaSdemo: a minimal third-party SaaS integration","locale":"en-US","markdown_path":"/markdown/en/guides/saasdemo.md","sha256":"2d4ead4f49335b161859db2bf6a4b60402b82388578aa4b53410421cefcfc1d9","headings":["Page functions","Account header and current-user information","OIDC configuration","Get integration settings from Developer Console","Demo BFF routes","Configure subscription and billing links","Minimal implementation flow","Webhook receiver reference implementation","Optional fulfillment integration","Plans and Credits reference","Acceptance checklist","Customer space in the reference example"],"excerpt":"SaaSdemo: a minimal third-party SaaS integration SaaSdemo demonstrates GoodVision sign-in, subscription, and payment integration for third-party SaaS products. The example provides its own business pages and sign-in session. GoodVision's customer workspace provides plan, subscription, payment, billing, and entitlement management. SaaSdemo displays currently published free or paid plans with monthly/yearly selection, Credits, seats, FAQs and original order recovery. It queries free activation, payment, allowance and product access separately and keeps no independent balance or eligibility table. Store upgrade state separately by subscription ID. Check current member access after the old free subscription ends. Example boundary SaaSdemo is an independent reference integration for third-party SaaS teams, not a GoodVision internal micro-application, service, or operations demo. It demonstrates published OIDC integration and page functions. Before calling commercial APIs, confirm the application’s SaaS Billing API Product in Developer Console and use its paths, scopes, audiences and event schemas. Page functions Capability SaaSdemo GoodVision platform --- --- --- Registration, sign-in, "},{"path":"/en/guides/sales-operations","title":"Lead and opportunity operations","locale":"en-US","markdown_path":"/markdown/en/guides/sales-operations.md","sha256":"e0ccc74582986bb67a8abc933dc8581c820124d2a0a393fbde7312617377b20c","headings":["Enable the capability","Register and convert a lead","Opportunity stages and outcomes","Search and recover","Defaults and automatic recovery"],"excerpt":"Lead and opportunity operations Lead and opportunity management lets you register leads, record follow-ups, convert qualified leads into opportunities, and update sales stages and outcomes. Data is isolated by organization, Application, product, and environment. Delivered sales features are available in your own application scope without a separate capability request. Application owners and collaborators use their current duties and data scope. Enable the capability In Developer Console, select your organization and application, then open Customer operations → Leads or Opportunities. The platform checks your current application access and duties before reading records. No aggregate configuration or second enable step is required. If a menu is missing, check the current application's capability state and your sales permissions. Records remain closed when the capability is inactive or suspended, read permission is absent, or permission cannot be confirmed. Lead read, manage and convert, and opportunity read, manage and reopen are separate permissions. Company access does not grant sales access. Sandbox and Production are configured separately and do not share sales records. Register "},{"path":"/en/guides/sdk","title":"GoodVision TypeScript SDK","locale":"en-US","markdown_path":"/markdown/en/guides/sdk.md","sha256":"7edab2dfb74b77d0ba37f0af3f8c33a7ed9b1f56880dbeb426701cd9ea35426d","headings":["Global capabilities"],"excerpt":"GoodVision TypeScript SDK After installing the SDK from npm as described in quick start, call the same operation ID: The integrator keeps the Token file private. discoverOperations searches only the generated local catalog. Owner contracts define types, parameters, responses and Scopes; APIs enforce authorization. consumeEvents ACKs only after durable, idempotent processing completes, and never ACKs a failed callback. Global capabilities capabilityOverview includes product versions, counts, identity types, Scopes and bilingual guides from the local public contracts. Live availability and authorization remain unevaluated."},{"path":"/en/guides/subscription-lifecycle","title":"Subscription lifecycle","locale":"en-US","markdown_path":"/markdown/en/guides/subscription-lifecycle.md","sha256":"3a4e77ba6f96a7a57f44f2c3f76f9e292c5258b685da389528358beb5088c6bb","headings":["State handling","Scenario 1: activation → scheduled cancellation → cancellation effective","Complete scheduled-cancellation event","Complete effective-cancellation event","Scenario 2: scheduled plan change → new plan effective","Scenario 3: renewal failure → grace → expiry","Update subscription state","Handle member access after subscription changes","Subscriptions and users"],"excerpt":"Subscription lifecycle This guide describes SaaS subscription states and handling for renewal, cancellation, plan changes, and expiry events. Commercial SaaS subscriptions and Application API access grants are independent. Cancelling either does not automatically cancel the other or issue a refund. State handling Free plans require explicit activation on a published offer. They return billing_mode: free without payment, so active can also describe a free subscription. Upgrade summaries include upgrade_from_subscription_id. The original free subscription remains active until payment is confirmed. Update each (subscription_id, resource_version) separately. An old subscription's termination cannot overwrite its replacement. After out-of-order events, query current subscriptions and member access again. Closing new free activation preserves historical orders. Subscription events omit payment references, renewal processing and scheduling fields. Query amounts and payment outcomes through authorized order APIs. Subscription event data contains the current commercial subscription summary. Use it to update your local subscription record. It is not a list of changed fields and does not incl"},{"path":"/en/guides/third-party-saas-billing","title":"Integrate Third-party SaaS Billing","locale":"en-US","markdown_path":"/markdown/en/guides/third-party-saas-billing.md","sha256":"8e31ef3fa10f816b40b886a1f72f49f0d587f08b4be063a15ba8d1c109372c83","headings":["Integration approach","Open the customer workspace","Return according to the application opening mode","Platform-side commercial flow","Third-party server responsibilities","Optional APIs and events","Plan and VIP access changes","Go-live acceptance"],"excerpt":"Integrate Third-party SaaS Billing GoodVision's customer workspace provides plan selection, subscriptions, payments, and billing management for third-party SaaS products. This guide covers platform entry points, sign-in and payment redirects, and subscription status updates. The current plan supports fixed monthly or yearly SaaS fees, monthly plan Credits and published one-time add-ons. Credits are usage allowances, not withdrawable stored value. Undeclared overage charges are never enabled automatically. Current availability GoodVision's customer workspace provides plan, subscription, payment and billing pages. The Commerce Checkout Sandbox API Product is implemented. The current application must receive its matching API configuration in Developer Console before calling it. Production routes are not open. You can first implement platform navigation, the OIDC BFF and page integration, then receive redacted subscription, payment and refund events under enabled scopes. The API uses billing_interval=monthyear for monthly or annual billing. Integration approach Scenario Third-party product GoodVision platform --- --- --- Product features Renders the partner's own business pages Does no"},{"path":"/en/guides/token-api","title":"Token packages and multimodal API","locale":"en-US","markdown_path":"/markdown/en/guides/token-api.md","sha256":"41bd8bb3cf72d443a84db05c58f8542068b2a8ed79a8eeee01199cab14f0e95b","headings":["User authorization","Purchase and original checkout recovery","Credits add-on policies","Models and inference","Balance, usage and recovery","Allowance batches","Read usage records","Filter and summarize usage","Customer space and model privileges"],"excerpt":"Token packages and multimodal API The Token API provides package queries and purchases, payment recovery, allowance and usage queries, and multimodal model calls. White-label customers can complete these operations in their own products without first visiting the platform Console. User authorization Request the published Token API Product under API and permissions → User identity. Configure login callbacks and use Authorization Code with PKCE and current user consent. The user access token must belong to that application's user OAuth Client. Operation Minimum Scope Customer authority --- --- --- Catalog commerce.catalog.read Current commercial read access Orders commerce.order.read Current commercial read access Purchase and checkout commerce.checkout.create Current payer authority Models inference.models.read Current product consent Inference inference.invoke Current product consent and eligible allowance Balance inference.balance.read Current account billing read access Usage inference.usage.read Current account billing read access After automatic configuration, confirm that the actual binding is bound, then obtain a fresh PKCE user token with the minimum scopes needed for the op"},{"path":"/en/guides/user-authorization","title":"User authorization","locale":"en-US","markdown_path":"/markdown/en/guides/user-authorization.md","sha256":"45f7175030b28594063091d6ad3872a17a0fbb18e7723e17c05c20b043fb17c7","headings":["Prerequisites","Endpoint list","Query options and create a grant","Query, check, and revoke a grant","Errors and recovery","User correlation and consent"],"excerpt":"User authorization User authorization lets a user specify the business resources an Application may operate on and how long access remains valid. This guide covers querying options, creating grants, checking access, and revoking grants. API permissions, user consent, and resource access are checked separately. Creating a grant does not purchase a product or increase allowance. Prerequisites Before creating, renewing or checking a grant, configure the application's user identity and required API Scopes as described in Entry points and permissions, then sign in with authorization code + PKCE. Listing and revocation require only a valid person session and current organization membership; they remain available when business Scopes are withdrawn or the application is unavailable. Send the user Bearer and X-GV-Organization-ID on every request. The user must belong to the selected customer Organization. Do not use a service Token or supply a different user or Organization in the body. Endpoint list Endpoint Description --- --- GET /open-platform/v1/delegated-grant-options Read available options for the current application's user OAuth Client GET /open-platform/v1/delegated-grants Read you"},{"path":"/en/guides/web-apps/develop","title":"Develop and configure","locale":"en-US","markdown_path":"/markdown/en/guides/web-apps/develop.md","sha256":"65cb5b17a802527a140b11a2831348c4f731beb0b532092f50a8594b89dd7f26","headings":["Configure the application entry","Integrate each opening mode","Prepare embedded artifacts","Adapt the lifecycle and interface","Configure security and sign-in","Handle subscription checkout and return"],"excerpt":"Develop and configure Confirm that the application works independently before connecting it to Console. All adaptation uses public platform contracts and lives in your application's repository. <DocsWebAppSteps / Configure the application entry Under “Application management → Application listing”, fill in these fields and save a draft. Field Description --- --- Application URL Your HTTPS business entry; retained for redirect and embedded modes Opening mode Redirect by default; choose isolated iframe or trusted qiankun after adaptation Manifest URL Required for embedding; an anonymously readable HTTPS JSON URL on the same origin as the application URL Redirect mode needs no container SDK. Saving an embedded draft automatically queues public Manifest and asset digest checks. The page updates with the result; failure preserves the draft and allows another check. Integrate each opening mode Mode Application work Configuration and runtime --- --- --- Redirect Independent pages, sign-in, and business routes Set the application URL; customers use the application's own page Isolated iframe Also deliver the Manifest, container, and lifecycle below Select isolated iframe; business code runs "},{"path":"/en/guides/web-apps/","title":"Web application overview","locale":"en-US","markdown_path":"/markdown/en/guides/web-apps/index.md","sha256":"6dc3a63cc57223229a99380e7a58f3391c5238c45fc7a8f0284b12c7ed8480e1","headings":["Choose an opening mode","Integration workflow","Add capabilities when needed"],"excerpt":"Web application overview Connect an independently deployed PC web application so customers can open it from Console. You own its build, deployment, authentication, and maintenance; integration requires no changes to Console or another application's source code. <DocsWebAppSteps / Choose an opening mode Mode Customer experience Requirements --- --- --- Redirect (default) Use the application on its own page Configure the existing HTTPS application URL Isolated iframe Use the application inside the Console workspace Adapt to the public container protocol; recommended for third-party embedding Trusted qiankun mount Mount the business interface directly in the workspace Adapt the public lifecycle; obtain independent security approval and explicitly publish Both embedded modes retain the independent URL, with retry and open-in-new-window recovery. An iframe provides cross-origin isolation. Directly mounted code shares the host page's permissions; the qiankun sandbox is not a third-party security boundary. Follow the steps for each opening mode. Embedding your application in Console and embedding a platform commercial page inside your application are separate directions. Subscription inte"},{"path":"/en/guides/web-apps/publish","title":"Review and publish","locale":"en-US","markdown_path":"/markdown/en/guides/web-apps/publish.md","sha256":"78114b248af207a642396592df2d6288bab6d41d4d89762ac85c56ea1fe15e6b","headings":["Prepare a release","Review security and availability","Publish and verify","Maintain the application"],"excerpt":"Review and publish Production customers use the published version. After development testing, create a Production release, obtain independent review, and explicitly publish it. <DocsWebAppSteps / Prepare a release 1. Prepare separate Production configuration under “Development integration → Sandbox and launch”. 2. Check application details, availability, URL, and opening mode. Embedded artifacts need checks for the current draft and real PC testing. 3. Under “Application management → Versions and releases”, create a version draft with a version number, change description, and test evidence references. 4. Explicitly submit for review. Applicants cannot approve their own release. After rejection, correct the configuration and create a new version. See application management for version operations and collaborator permissions. Review security and availability Mode Review focus --- --- Redirect Independent URL, sign-in, application details, and availability scope Isolated iframe Public artifacts, exact host origins, message validation, sign-in window, and isolation Trusted qiankun mount Exact artifact code, dependencies and supply chain, shared host page permissions, and explicit appro"},{"path":"/en/guides/web-apps/test","title":"Development testing","locale":"en-US","markdown_path":"/markdown/en/guides/web-apps/test.md","sha256":"d72a02ae1468fb4c1ffc548d8c5590957a3d202b861b4dc4267595a6a3789bc5","headings":["Review artifact checks","Complete a PC test installation","Troubleshooting"],"excerpt":"Development testing After saving an embedded draft, review automatic artifact checks and then verify real customer operations in a test installation. <DocsWebAppSteps / Review artifact checks The platform asynchronously reads the public Manifest and assets to check format, URL restrictions, and SHA-256. It does not execute third-party scripts or prove that browser mounting, sign-in, or business features work. Status Action --- --- Queued / running Wait for the page to update; avoid repeated saves Passed Complete the real PC browser checks below Failed Correct URLs, the Manifest, or asset digests; save or check again Service unavailable Keep the draft and check again when the service recovers Stale Read the current draft and check its current URL, mode, and artifacts Changes to the application URL, Manifest, or opening mode invalidate the previous result for the new draft. Failed or unavailable checks preserve the existing published version. Complete a PC test installation Use test accounts and installations for the selected environment. Do not copy Sandbox credentials, customer data, or approvals to Production. A trusted-mode Sandbox draft must not run directly in a customer's prod"},{"path":"/en/guides/webhooks","title":"Receive webhooks","locale":"en-US","markdown_path":"/markdown/en/guides/webhooks.md","sha256":"a086d79d86260b1b13eff1d93f640f3bfcf820fba3e3e02c5285f06c23ae48ca","headings":["Integration steps","Recover a configuration save","Verify the endpoint","Test complete events in the Console","Complete example: subscription activated","Request headers and signature","Process in the correct order","Plaintext and encrypted bodies","Recompute a signature locally","Duplicates and ordering","Failure and recovery","Synchronous callback availability","Signing Secret and rotation","Obtain the signing key securely from the console","Correlate membership events with signed-in users"],"excerpt":"Receive webhooks For first-time integration, use the recommended Node.js long-connection example. It needs no public receiver URL or webhook encryption setup. The steps below apply when you choose HTTPS Webhooks. Webhooks provide notifications for subscription activation, plan changes, cancellation, and other events. GoodVision sends events to the Application's configured HTTPS endpoint. Validate and persist each event before acknowledging it, then process business work asynchronously. Delivery is at least once, so duplicates and out-of-order events are possible. HTTP 2xx acknowledges durable receipt: persist the event before returning it. A lost response or consumer crash can cause retries, so deduplicate business work by event_id. If automatic retries are exhausted, review the failed delivery in the Console and request recovery using the original event_id. Integration steps 1. Configure delivery: open the current application → Events and webhooks → Add event. Enter a public HTTPS callback URL, test the connection, then select events and save. The platform generates the signing key and token and enables delivery automatically. 2. Configure your receiver: open Receiver configuratio"},{"path":"/en/","title":"TOKEN Model Open Platform","locale":"en-US","markdown_path":"/markdown/en/index.md","sha256":"abd31fc82859790f1562c479d7e34ec315808a6a4609ab1fd03ba59931741cc5","headings":["Get started","Capabilities and tools","Developer Console","Tools and support"],"excerpt":"TOKEN Model Open Platform Build with versioned APIs, OAuth 2.0 and signed Webhooks. Get started Create an application, configure OAuth sign-in and add APIs and events as needed. Follow the integration guides and validate your application before release. Quickstart Developer documentation Capabilities and tools Explore model APIs, identity and permissions, orders and payments, subscriptions, signed Webhook delivery, code templates and GoodVision CLI. API products GoodVision CLI Receive events Developer Console Open Developer Console Tools and support Code examples Technical support"},{"path":"/en/reference/api-products","title":"API products","locale":"en-US","markdown_path":"/markdown/en/reference/api-products.md","sha256":"e46aab05ab897d56012bb0a434db4640133ad55c0fb88f35cf033626bd5eddf7","headings":["Basic concepts","Request API access","Map scopes to APIs, events and resources","Get call configuration","Integration guides","Shared endpoints and unavailable capabilities","Capability catalog","Call requirements","Product status and environment"],"excerpt":"API products An API product groups related open APIs. Once access is enabled, an Application can call those APIs at the specified version. Each product provides a Base URL, audience, scopes, schemas, quotas, and support information. Open APIs and permissions in the Developer Console to view products and request access. Product names and descriptions are available in Chinese and English; scope, audience, and route identifiers remain fixed. Basic concepts Name Description Example --- --- --- Application Integration configuration for a product in one environment Sandbox Application for acme-workflow API product A group of APIs with versions, addresses, and call requirements OEM Core API API access grant Operations, data range, and quota available to the current identity Read-only billing access for application identity After creating an Application, request API access separately. Each request also checks the access token, organization, and resource permissions. One Application supports application (service/confidential) and user (public + PKCE) identities. Each has a separate OAuth client and API access grant. Their permission states and revocation actions are independent. Request API"},{"path":"/en/reference/environments","title":"Environments","locale":"en-US","markdown_path":"/markdown/en/reference/environments.md","sha256":"60fed2b9c5234793cb8fee79114f4d1fa64351eb4aab8a561d61f25f91cdcadc","headings":["Two environment dimensions","Deployment environments and availability","Get entry-point addresses","Identity Issuer","Move from Sandbox to Production","Isolation checklist"],"excerpt":"Environments This reference describes Sandbox and Production availability and the addresses used for documentation, authentication, APIs, and webhooks. Applications, credentials, audiences, scopes, data, webhooks, and quotas are isolated by Application environment. Two environment dimensions Environment type Values Description --- --- --- Deployment environment development, test-us, production Entry points and availability for developer documentation, the Console, authentication, and APIs Application environment sandbox, production Application, identity-specific OAuth clients and API access grants, webhooks, quotas, and acceptance lifecycle Application environment supports only sandbox and production. You can test a sandbox application in Development or test-us. Do not put development, test-us or release parameters in that field. Deployment environments and availability Deployment environment Application use Address source Status --- --- --- --- development Sandbox development and integration Current environment’s entry-point settings Development only; no Production Applications or production data test-us Invited Sandbox acceptance testing Entry-point settings supplied for the invi"},{"path":"/en/reference/errors","title":"Errors","locale":"en-US","markdown_path":"/markdown/en/reference/errors.md","sha256":"6b3be1be46760ee16577cccd8783138a98223928f8156a7d34bad3355ac6c566","headings":["Common responses","Recover Developer Console operations","Safe diagnostic fields","Valid token returns 403","Space resolution fails after login"],"excerpt":"Errors When an API call fails, GoodVision returns an HTTP status code and Problem Details. Handle failures using the status and error code. The detail field provides additional context and should not drive program logic. Common responses Status Meaning Caller action --- --- --- 400 Malformed request or missing field Correct the input; do not retry unchanged 401 Missing authentication or invalid token Obtain a token for the correct issuer and audience 403 Authenticated but unauthorized Check scopes, organization, ProductAccess, and resource ownership 404 Resource absent or not visible Verify the ID and authorized tenant context 409 State, version, or idempotency conflict Read current state before deciding the next action 422 Business rule validation failed Correct the business input using the error code 429 Quota exceeded Respect Retry-After and back off 5xx Service temporarily unavailable Retry transient failures only as specified by the API Recover Developer Console operations Expired sign-in, insufficient recent verification and revoked access require different actions. Follow the displayed error to recover the original scope instead of changing accounts or enterprises to bypass "},{"path":"/en/reference/events","title":"Event catalog","locale":"en-US","markdown_path":"/markdown/en/reference/events.md","sha256":"5e7a5e9e44861dae3242d54c9bdf16b6659427cdb616c9d676b43304fc934ac8","headings":["Complete subscription envelope","Required subscription data fields","Integration scope and state-specific fields","Complete subscription event table","Event families","Consumer requirements","Effective access changes","Product access activated","User and event correlation keys"],"excerpt":"Event catalog This catalog lists GoodVision event types, triggers, and fields. Events use versioned names and are delivered through approved, active Webhook subscriptions. For signature verification, token validation, deduplication, and acknowledgements, see Receive webhooks. Fields, enums, and permissions follow the event schema provided by the current Application's API product. Complete subscription envelope This complete business event represents activation and contains every required field. Plaintext HTTP delivery adds a top-level verification_token: validate and remove it to obtain this envelope. Encrypted delivery requires signature verification, decryption, and Token validation first. All IDs, plans, and reason codes are synthetic. producer: \"opaque\" is a display placeholder for an opaque source; use the issued schema for actual source enums. Do not hard-code the placeholder or example reason codes. Download JSON or see the complete HTTP request with headers, Token, and reproducible signature. Every top-level field below is required for subscription events: Field Type Meaning and validation --- --- --- event_id string Stable business event ID; Inbox unique key event_type str"},{"path":"/en/reference/saas-billing","title":"SaaS Billing Reference","locale":"en-US","markdown_path":"/markdown/en/reference/saas-billing.md","sha256":"643fe8e0d9770338e31fed118bbfc9ff5c083d13006fb8b24231b5e1fb209ed1","headings":["Current capability status","Resources and usage","Public fields","Request requirements","Expected API Product composition after publication","Safe browser fields"],"excerpt":"SaaS Billing Reference This reference describes billing resources, fields, and handling rules for monthly or yearly SaaS integrations. Use the paths, schemas, and scopes provided by the current Application's API product when making calls. Current capability status Capability Status --- --- Fixed monthly/yearly SaaS plan rules Defined Application, API access, and Webhook requests Available through the Developer Console Commerce Checkout Sandbox API Product Implemented; callable after it is issued to the Application Production API Product Not available Stored value, usage, and overage billing Not supported by the current commercial plan Resources and usage Resource Entry point or method Integration usage --- --- --- Application, API product, API access grant, Webhook subscription Developer Console Request access and get version-specific API configuration Product/Plan/PriceVersion, Order, SaaSSubscription Customer workspace View and manage commercial resources; third parties query necessary state through authorized APIs Payment, refund, and payment status Customer workspace Complete payment or refunds; third parties query redacted state through authorized APIs ProductAccess, Entitleme"},{"path":"/en/reference/user-context","title":"Users and customer spaces","locale":"en-US","markdown_path":"/markdown/en/reference/user-context.md","sha256":"f7120a628ea2ab6164c95fa175beca0df42f7e1471d974db8eaafa62da24546b","headings":["Request","Response","open_id and union_id","Recovery"],"excerpt":"Users and customer spaces After login, read open_id, union_id and the customer space. The platform generates identifiers and a default personal space automatically. No user group or additional API Subscription is needed. Request POST ${GOODVISION_API_BASE}/open-platform/v1/user-context:resolve Call from your server with the current Application's user Access Token. Send {} at first entry: Parameter Location Required Description --- --- --- --- Authorization Header 🔴 Required Bearer <USER_ACCESS_TOKEN from the current user Client, not an application identity Token Content-Type Header 🔴 Required application/json JSON request body Body 🔴 Required Send {} at first entry; no user or space ID is needed organization_id Body Optional Omit to prepare or reuse the personal space; send only when the user explicitly selects an existing customer space, with membership checked again For an explicit existing space selection, send {\"organization_id\":\"<SELECTED_CUSTOMER_SPACE_UUID\"}. Do not send Application, user or permission fields, organization Headers or Query parameters. Response These fields are generated and returned by the platform, not request parameters that developers must fill in. Fie"},{"path":"/en/support","title":"Support and diagnostics","locale":"en-US","markdown_path":"/markdown/en/support.md","sha256":"f8c5565907dfe69703c4885a1d8df4ddb240ebb4d7719980accb2dc1189321e9","headings":["Submit application technical feedback","Forward to platform support","Reply and track status","Issue details","Sensitive information","Check before escalation"],"excerpt":"Support and diagnostics For integration or API issues, open the current Application → Developer integration → Support and feedback to submit technical feedback, link diagnostics, read the timeline and reply. Explicitly forward a ticket when platform assistance is needed; existing private feedback is never forwarded automatically. Use the relevant product channels for commercial, payment or customer support. Submit application technical feedback 1. Check the Application and environment, then enter a short subject and plain-text issue description. 2. Optionally select a diagnostic from call logs or a Webhook delivery from the last seven days. References include necessary summaries without request or customer bodies. 3. Submit explicitly and retain the ticket reference. Open its timeline for messages and status; read a message body only when needed. Bodies must not include credentials, sensitive headers, JWTs or HTML. Directory access, body access and actions are authorized separately: a visible ticket reference does not grant permission to read or reply. Contact the current Application owner when required access is absent. Forward to platform support 1. Select Forward to platform sup"},{"path":"/getting-started/","title":"应用接入流程","locale":"zh-CN","markdown_path":"/markdown/getting-started/index.md","sha256":"deb2ba30f8c3d552f941236cb8bf6d617adfd5e7c70534deca884a95bcead6bd","headings":["接入前准备","仅接入用户登录（3 步）","第 1 步：创建应用","第 2 步：填写回调并复制配置","第 3 步：实现回调并验证登录","按需增加 API 能力（可选）","接收业务事件（可选）","接入订阅与支付（可选）","Sandbox 验收清单","准备 Production 与上线"],"excerpt":"应用接入流程 本文介绍如何为产品接入 GoodVision 登录，再按需增加 API、事件和商业能力。仅接登录时，创建应用、填写回调并复制配置、验证登录三个步骤即可开始联调。 接入前准备 登录当前环境的开发者后台。首次没有企业的账号会自动准备个人空间，可在其中创建应用；创建者自动成为该应用所有者，无需先配置业务角色。协作已有企业的应用时，再加入该企业并取得对应应用权限。准备产品名称和应用实际实现的登录回调，例如 https://app.example.test/auth/callback。 一个独立产品、一个环境对应一个应用（Application）。同一产品的用户登录与后台调用使用同一应用中的两种身份；Sandbox 与 Production 分开。多个产品如何关联用户，请参见多应用、用户与事件接入。 仅接入用户登录（3 步） 第 1 步：创建应用 在应用中心填写应用名称并创建，默认使用 Sandbox，应用代码自动生成；需要自定义代码时再展开高级设置。保存后在凭证页核对环境和接入状态。自动配置成功时状态为 active；依赖失败时按提示恢复原请求，不重复创建。 第 2 步：填写回调并复制配置 进入“开发接入 → OAuth/OIDC 配置 → 用户身份”，确认用户身份已启用，填写精确的登录回调。平台生成并校验当前应用的登录配置，保存后复制非敏感配置。 配置 必填性 说明 --- --- --- 登录回调（Callback URL） 🔴 必填 精确填写应用已实现的授权码接收路由 退出地址（Logout URL） 可选 核对自动建议值；不需要退出后跳转时可不配置 网站来源（Web Origin） 可选 仅协议、主机和端口；需要浏览器跨来源请求时配置 Issuer、Client ID 平台提供 接入必需，从当前应用复制 Client Secret 用户身份不需要 后台应用身份调用时必需 例如，回调为 https://app.example.test/auth/callback 时，网站来源为 https://app.example.test，退出后可返回 https://app.example.test/。产品访问地址和登录回调用途不同。 第 3 步：实现回调并验证登录 应用服务端实现授权码 + PKCE、回调核验和自己的会话。确认精确回调成功、会话可刷新及退出，并验证错误 Token 和错应用被拒绝。具体操作见认证与授权。 登录后调用用户与客户空间，首次发送 {}。平台自动准备或复用个人空间，返回当前用户、空间与成员；开发者不用填写 Group 或固定客户企业 ID。暂不可用时保留登录并提供重新读取入口。 仅接登录不要求业务 API Subscription、Webhook 或订阅套餐。登录和成员关系不会授予付费权益或产品权限。 按需增加 API 能力（可"},{"path":"/getting-started/sandbox-access","title":"创建应用与开发测试","locale":"zh-CN","markdown_path":"/markdown/getting-started/sandbox-access.md","sha256":"058325913ce66f1ace7dc202b9cf356cc71b8dcd9dbf9528025a8113514cd351","headings":["按需准备配置","创建应用并测试","准备测试企业和人员","确认适用测试","获取接入配置","常见状态"],"excerpt":"创建应用与开发测试 Sandbox 用于应用开发和联调。在当前部署环境的开发者后台，使用本人账号创建应用。首次没有企业时自动准备个人空间，应用创建者自动成为所有者。 保存配置后，平台会自动检查应用、OAuth 身份、API 调用权限和 Webhook，通过后立即启用，无需人工审核。失败时按页面提示修正并重试。找回历史无负责人的应用需通过人工支持处理。 一个独立产品使用一个应用，可以启用应用身份、用户身份或两者。两种身份分别配置 OAuth Client 和 API 权限。应用 Owner 可按凭证页当前状态查看或轮换应用身份 Secret；用户身份使用 PKCE，无需 Client Secret。 仅接登录时，创建应用、填写实际回调并复制配置、验证登录即可，见应用接入流程。API、事件和商业按需配置，未选能力不是登录前置。登录后由平台解析用户与客户空间，无需填写固定企业 ID；需目标环境完成合同启用。 Sandbox 是应用环境，与 GoodVision 的部署环境不同。配置成功不替代企业成员关系、用户同意（Consent）、资源 ACL、付款资格或 Webhook 端点安全校验。重复提交不会重复创建，未完成配置的资源不会显示为 active。 按需准备配置 创建应用只需填写名称，其他配置在使用对应功能时补充。不要在普通表单中填写 Secret、Token、私钥或客户数据。 字段 示例 要求 --- --- --- 应用名称 Acme Workflow Connector 便于识别产品和用途 Application Code 自动生成 可选；需要自定义时展开高级设置，仅小写字母、数字和连字符 运行范围 测试（sandbox） 创建时默认为测试范围；正式上线使用独立资源 应用身份权限 需要 / 不需要 用于服务端任务和后端调用 用户身份权限 需要 / 不需要 用于用户登录后的操作；需要精确 Callback URL API Product 控制台中的已发布产品 使用业务 API 时选择 Scope 最小权限集合 使用业务 API 时按应用和环境配置并自动校验 Webhook Endpoint https://sandbox.example.com/goodvision/events 仅选择 HTTPS 接收或同步回调时需要；长连接无需公网地址 事件类型 oem.subscription.expired.v1 接收事件时只选实际消费的类型 联系人 技术、安全、Support 用于故障、轮换和弃用通知 创建应用并测试 1. 打开当前部署环境的开发者后台，使用本人账号登录。 2. 核对企业或个人空间。首次初始化暂不可用时重试；已选企业无权时不静默切换。 3. 填写名称创建 Sandbox 应用，平台自动生成代码并授予创建者应用所有权，保存返回的 Applicatio"},{"path":"/guides/access-and-permissions","title":"接入入口与权限","locale":"zh-CN","markdown_path":"/markdown/guides/access-and-permissions.md","sha256":"b968d80bca8fad684506932b77363b64408a04809ecaa47bccebb58601b44b07","headings":["选择调用身份","基本概念","在当前页面完成配置","查看和管理 API 权限","关闭权限","批量导入和导出","统一入口","Sandbox Application 的测试入口","正式环境（Production）","配置入口","API 授权条件","配置与启用步骤","401 与 403 排查","接入方边界","登录后的客户空间"],"excerpt":"接入入口与权限 后台自动运行的任务选择应用身份权限；代表当前登录用户操作时选择用户身份权限。同一应用可以启用两种身份，分别配置凭证和权限。 本文介绍两种调用身份的适用场景、接入地址和授权条件。登录成功后，API 仍会校验当前应用、调用身份、API 权限、企业范围和资源权限。 开发者后台显示 应用身份权限 和 用户身份权限；接口和诊断信息中的 identity_type、OAuth Profile 对应这两种身份的配置。 选择调用身份 场景 调用身份 是否需要 Client Secret 调用主体 --- --- --- --- 定时任务、后台同步、服务间调用 应用身份权限 需要，只保存在服务端 当前 Application 用户登录后查看或操作自己的数据 用户身份权限 不需要，使用 PKCE 当前 Application + 当前用户 产品同时有前台用户操作和后台任务 两种都启用并分别申请 API 权限 两套配置分开 每个请求只选择其中一种 应用身份不能借用用户权限，用户 Token 也不能用于无人值守任务。Sandbox 与 Production 中的两种身份都分别配置和启用，不会跨环境复制。 已开通应用身份权限时，仍可切换到“用户身份权限”为同一 API 产品单独申请；反向操作同样适用。调整已有授权会保留当前勾选的权限，确认后更新该身份的授权，不影响另一种身份。 基本概念 名称 说明 --- --- 应用（Application） 产品在某个环境中的接入配置 API 权限 允许调用哪些操作、访问多大数据范围；协议配置中会映射为 Scope 访问令牌（Token） 调用 API 时携带的短期身份证明，不是长期密码 目标 API（Audience） 访问令牌允许使用的目标 API OAuth Client 平台为一种调用身份签发的认证配置；由平台创建，开发者不手工管理 配置和接口使用括号内的协议标识，可用于核对参数和排查错误。 部署环境（developmenttest-usproduction）决定接入地址和服务可用性；Application 环境（sandboxproduction）决定应用资源用于测试还是生产。 在当前页面完成配置 应用本身显示待配置时，先在当前页面点击“完成配置并启用”，无需补填信息。读取到应用已启用后，再配置调用身份；不要重复创建应用。 后台任务选择“应用身份权限”，点击“启用应用身份”，无需填写登录回调，也不必另建应用。已有应用身份显示待配置时，仍在这里启用，平台沿用已有身份；API 权限按需另选，不会复制用户权限。 启用配置已保存但页面尚未更新时，点击“重新读取当前应用”。该操作只读取状态，无需再次创建或启用。结果尚未确认时，点击“恢复原启用请求”；原请求确认前不另开一个创建操作。 应用身份无回调启用与读取恢复操作示意 进入应用的"},{"path":"/guides/agent-integration","title":"Agent 接入能力概述","locale":"zh-CN","markdown_path":"/markdown/guides/agent-integration.md","sha256":"723e1d5fe8794434a7e1e4bcf303e443e1bee630fe0204fb768a3cd423464b6c","headings":["能力一览","如何组合这些能力","业务能力地图","最短开始路径","SDK 与事件能力","能力状态与后续接入"],"excerpt":"Agent 接入能力概述 GoodVision 面向 Agent 开发者提供三类可组合能力，分别解决“用谁的身份接入”“如何接收变化”“如何执行业务动作”三个问题。 应用与凭据：创建应用，选择用户授权或应用服务身份，固定应用和环境。 事件 SDK：通过长连接或 Webhook 接收已订阅事件，持久处理后确认。 GoodVision CLI：让 Codex 发现 API、读取参数、预览请求并调用模型、客户经营、订阅和订单等公开能力；代码集成使用同一套 TypeScript SDK。 能力一览 GoodVision Agent 全局能力与三种组合路径 三层按需组合。只调用 API 时，先取得所需身份即可，不必建立事件连接。下面的“交互层”指业务事件输入；聊天会话、流式消息和卡片 Channel SDK 尚未提供。 能力 什么时候使用 形态 接入指引 --- --- --- --- 应用与凭据 · 凭据层 为应用确定身份、用户授权、Scope 和 sandbox／production 上下文。目标：取得本次任务所需的身份。 开发者后台、网页 OAuth／PKCE、应用服务凭据；CLI 引用私有文件 创建应用与开发测试、用户授权、服务身份 事件 SDK · 交互层 接收应用已订阅的事件，按事件 ID 幂等处理并在持久完成后确认。目标：让自动化响应业务变化。 TypeScript／Node.js SDK、SSE、HTTPS Webhook、接收模板 长连接、Webhook、应用用户与事件 GoodVision CLI · 执行层 搜索公开能力、读取 Schema、调用 API、组合脚本。目标：让 Agent 执行已获准的业务动作。 goodvision／gv CLI、@goodvision/sdk、JSON／JSONL；npm 包和源码均可用 GoodVision CLI、API 产品、接入模板 如何组合这些能力 路径 适合什么场景 使用组合 第一个可执行任务 --- --- --- --- A · IDE 中直接执行 在 Codex 中查能力、调试 API、生成接入代码 应用与凭据 → CLI 找到用户空间 API，查看参数，用 sandbox 预览首次请求 B · 服务端业务集成 在自己的应用或脚本中调用公开业务 API 应用与凭据 → TypeScript SDK 按当前身份查询可用模型、客户资料或订单，按 Schema 处理结果 C · 事件驱动自动化 订阅状态变化后持续处理业务 应用服务身份 → 事件 SDK／Webhook → 业务 API 持久接收事件，读取原事件对应的当前状态，完成幂等处理后 ACK 应用服务身份适用于合同明确支持的操作。需要当前用户、客户授权或产品策略的操作仍须逐次授权，不能因为已经连上事件通道而获得业务权限。 业务能力地图 Good"},{"path":"/guides/application-diagnostics","title":"查询调用日志与质量","locale":"zh-CN","markdown_path":"/markdown/guides/application-diagnostics.md","sha256":"6235835c4d55b54ae2b0caccc8f960fbccd34a8e547a4f347fcf2e9791d1dbf1","headings":["查询服务端日志","查看质量概览","查询客户端日志","关联技术反馈"],"excerpt":"查询调用日志与质量 使用服务端日志查找实际 API 请求，使用质量概览查看完整时间窗口的统计。客户端日志单独显示应用主动上报的诊断，不能代替服务端执行结果。 查询服务端日志 1. 打开当前应用 → 开发接入 → 服务端日志。 2. 选择最近七天内的起止时间，或使用最近 1、3、7 天快捷选项。 3. 按请求 ID 或其他已知条件筛选，点击“查询”。 筛选项 说明 --- --- Request ID 精确查找一次请求 URL 路径、请求方法 使用公开路由模板，如 /open-platform/v1/token-orders/{id}，不要填写域名、查询参数或实际客户 ID 用户 OpenID 当前应用用户的 open_id；不能使用其他应用的用户标识 API Product、操作 对应已配置产品和操作 OAuth 配置 ID、调用身份 区分用户身份与应用身份的调用配置 调用结果、原因码、HTTP 按结构化结果筛选 错误信息 在固定错误说明中检索，忽略大小写；不查询请求正文 记录包含请求时间、Request ID、HTTP 状态、耗时和已采集的安全维度。URL 只显示路由模板；旧记录没有采集的字段显示为未知，不根据当前配置补填。查询只包含当前有权访问的应用和环境。 日志表最多显示前 100 条匹配记录，不能用表格行数估算完整调用量。没有记录不表示所有请求成功；检查查询窗口、筛选条件和实际采集状态。 查看质量概览 打开“开发接入 → 质量概览”，使用相同的时间和筛选条件查看调用次数、成功率、错误数、P95 延迟及操作统计。统计覆盖完整查询窗口，不从当前展示的日志行计算。 日志与统计可能分别暂不可用。页面会说明失败项，保留仍可读取的结果；点击重新读取恢复。统计不可用不会显示为零或成功，客户端上报也不计作可信服务端成功证明。 查询客户端日志 打开“开发接入 → 客户端日志”，按 Request ID、操作、原因码及最近 24 小时、3 天、7 天查询。记录保留七天，并标记为客户端上报。 没有匹配记录时，页面显示空列表，并提供“查看日志接入文档”入口。功能暂不可用与没有访问权限会分别提示；登录过期时，页面清除旧日志并提供“重新登录”，完成登录后继续查看当前应用。功能暂不可用时可联系平台支持，恢复后点击“刷新日志”。 客户端上报由你的应用主动执行，平台不会自动安装 SDK 或采集浏览器请求。使用当前应用用户的 OAuth Bearer 调用 POST /open-platform/v1/client-diagnostics，并携带独立的 Idempotency-Key。 名称 类型 必填 说明 --- --- --- --- request_id string 🔴 必填 非敏感请求标识，1～100 字符；符合 ^[A-Za-z0-9][A-Za-z0-9._:/-]$"},{"path":"/guides/application-directory","title":"应用目录","locale":"zh-CN","markdown_path":"/markdown/guides/application-directory.md","sha256":"96bf8766883d6c86da594e2d780a8cfcdbb67a207cf7659d53c063ad44a51f1c","headings":["1. 准备当前用户身份","2. 读取可见应用","3. 错误与重试","目录入口与登录配置","Console 内置接入"],"excerpt":"应用目录 通过应用目录接口，可以查询当前客户企业可见的已发布应用，用于在自己的产品中展示应用列表。 查询目录不会购买产品、创建订阅或授予使用权限。 1. 准备当前用户身份 使用用户身份认证取得当前环境的用户 Access Token，并选择用户所属的客户企业。这个共享接口依据当前用户和企业关系读取目录，无需另申请商业 API 产品；应用身份 Token 不能代替客户用户。 2. 读取可见应用 GET /open-platform/v1/application-listings 返回 {\"items\": [...]}。没有可见应用时，items 为空数组。 每项包含当前发布信息：id、application_id、environment、resource_version 和 OpenAPI 定义的展示字段。平台按当前客户范围筛选公开或企业定向发布项。 sales_offer_refs 提供当前可用销售方案的引用。购买资格、金额和产品开通状态需另行查询。 使用本次响应展示应用。用户切换企业或环境后，清除旧数据并重新查询；应用访问状态以最新响应为准。 3. 错误与重试 状态码 处理方式 --- --- 401 重新登录 403 检查当前企业成员关系，不修改企业请求头绕过限制 503 显示暂时不可用并提供重试，不展示上一范围的目录 此接口只读，无需 Idempotency-Key。 下一步：第三方 SaaS 订阅与支付 · API 产品 目录入口与登录配置 目录入口是客户打开产品的网址，登录回调接收授权码，两者分别配置。每个产品创建一个应用；用户登录与后台 API 使用同一应用的不同身份。登录后的客户范围见用户与客户空间。 Console 内置接入 应用默认跳转，也支持隔离 iframe 与受信 qiankun 直挂。内置适配均在应用自己的仓库中完成。完整步骤见PC 网页应用，依次完成开发配置、开发测试和审核发布。"},{"path":"/guides/application-management","title":"管理应用资料、协作者与版本","locale":"zh-CN","markdown_path":"/markdown/guides/application-management.md","sha256":"1ae044f7f846e82d6d019c57a2f9c1265755ad8bbf809e290b17e31a580922b4","headings":["按功能配置应用","修改中英文资料","添加或撤销协作者","转移所有权","统一审核与发布版本","删除应用"],"excerpt":"管理应用资料、协作者与版本 在“应用管理”中维护应用的中英文资料、协作者和所有权，并记录已校验的配置版本。应用协作者管理开发者后台；客户使用产品的权限和商业订阅分别配置。 按功能配置应用 创建应用后，已提供的开发与自有范围经营功能默认可用。开发接入默认进入 API 与权限；按需在所属页面配置，无需总表单或资源保存后的再次启用。 任务 页面 保存后的行为 --- --- --- 登录与调用身份 OAuth/OIDC 或 API 与权限 自动关联当前身份及地址，复制参数后联调 API 权限 API 与权限 批量配置必要权限，测试免人工审核 接收事件 事件与 Webhook 选择方式和事件，完成连接／Challenge 后测试 收费、订阅、履约、产品访问 商业管理 → 收费与履约 选择真实资源并保存，自动核验；无商业需求可跳过 客户资料与地址 应用发布信息 保存草稿并关联当前配置，旧正式版本继续服务 正式运营 Sandbox 与上线 完成适用测试，创建版本，提交一次审核，批准后显式发布 主动关闭或暂停立即收紧当前运行。重新开启不会恢复旧正式批准，需新版本审核并发布；开发功能可用也不代表用户同意、客户数据、付款或使用权益已经获得授权。 修改中英文资料 1. 打开当前应用 → 应用管理 → 应用设置。 2. 选择默认语言，填写该语言的应用名称，按需填写说明。 3. 需要另一种语言时，启用对应译文并填写名称和说明，保存资料。 配置 要求 保存后的结果 --- --- --- 默认语言 🔴 必填；zh-CN 或 en-US 决定应用的默认名称 默认语言名称 🔴 必填 更新应用名称 另一语言名称 🔴 条件必填；启用该语言时填写 该语言下显示译名；未提供时使用默认名称 各语言说明 可选；可以为空 对应语言下显示说明 切换后台语言只改变展示，不保存应用资料。旧应用未配置译文时保留原名称，不会自动翻译。移除非默认语言时，该译文会从当前资料中移除。 保存后更新开发配置；正式客户资料随获批版本发布，修改语言、名称或说明都会产生新的应用配置版本。结果未知时使用“恢复原资料更新”，不要另建更新；版本冲突时先读取当前资料，核对后再次保存。 添加或撤销协作者 当前应用所有者和应用管理员可在“应用管理 → 应用协作者”向同企业的有效成员分配职责。企业成员尚未加入时，先通过“本企业团队”完成邀请与接受，再回到应用协作者页面。 1. 从当前企业目录选择成员，读取该成员当前的应用关系。 2. 选择管理员、开发或运营职责；“操作原因”可留空，平台自动记录操作说明，也可填写简短补充。 3. 提交后查看当前关系。已有协作者可按同样步骤改变职责；撤销时先勾选明确的撤销确认，再提交。 职责 默认范围 --- --- 所有者 全部应用管理；转移和删除需要独立确认 管理员 资料、协作者、技术配置、测试和版本"},{"path":"/guides/application-security","title":"配置应用安全与凭据","locale":"zh-CN","markdown_path":"/markdown/guides/application-security.md","sha256":"f34621070248b4b617f8ae8557be70e8b7b3b3bcfb7330ae254295cb45a118f7","headings":["取得当前应用凭据","限制调用来源 IP","修复来源限制"],"excerpt":"配置应用安全与凭据 在当前应用中取得所需凭据，并按需限制 OAuth API 调用的来源 IP。用户登录、应用后台调用和 HTTPS 事件接收使用不同凭据，不能互换。 取得当前应用凭据 进入“应用管理 → 凭证与基础信息”，核对应用、环境、接入状态和对应 Client ID。 用途 凭据 取得方式 --- --- --- 用户登录 用户身份 Client ID；无需 Client Secret 在 OAuth/OIDC 配置中启用用户身份并登记精确回调 后台 API 或长连接 应用身份 Client ID 和 Client Secret 在凭证页按当前权限临时查看或轮换，或使用页面指定的安全交付渠道 HTTPS 事件或同步回调 HMAC Secret；按当前配置使用 Verification Token、Encrypt Key 在事件页的专用接收端配置中查看或轮换，或使用当前交付渠道 Secret 默认遮罩。主动查看后，将其保存到对应服务端；离页、切换企业或应用、登录失效或权限变化会清除临时值。普通配置复制、导出、文档、日志和工单不包含 Secret。应用管理员身份不会自动取得所有者专用凭据权限。 OAuth Client Secret 轮换成功后旧值立即失效，需更新应用服务端并重新获取 Token。Webhook 签名密钥按轮换规则切换；凭据交付成功不等于接收端已使用新值。轮换或查看要求验证身份时，完成验证后再明确操作。 限制调用来源 IP 只有需要固定网络来源的应用才启用 IP 白名单。先确认应用请求到达平台时的实际出口地址；使用长连接时，连接和 ACK 的出口也须符合策略。 1. 打开“应用管理 → 安全设置”。 2. 勾选“启用 IP 白名单”，每行填写一个允许的 IPv4、IPv6 地址或 CIDR。 3. 保存后核对返回的地址集合，在允许与未允许的网络分别验证请求。 配置 要求 说明 --- --- --- 启用 IP 白名单 可选；未配置时关闭 限制当前应用的应用身份和用户身份 OAuth API 请求 IP 或 CIDR 🔴 条件必填；启用时至少一项，最多 100 项 如 203.0.113.10、203.0.113.0/24、2001:db8::/32；示例不是你的实际出口 保存会规范化、去重并排序地址集合。请求来自未允许地址时被拒绝；伪造来源请求头不能取得访问权。策略不授予 API Scope、客户资源或产品权限。 修复来源限制 开发者后台保持可访问，可用于恢复应用的来源策略。当前有修改权限的用户可登录后台，更新允许地址或关闭限制后保存，再验证应用请求。 情况 处理方式 --- --- 新网络请求被拒绝 核对实际出口、当前应用和环境，更新策略后再试 保存结果未知 点击“重试原请求”，保持原地址集合、版本和操作编号 IP 或 CIDR 格"},{"path":"/guides/application-users-and-events","title":"多应用、用户与事件接入","locale":"zh-CN","markdown_path":"/markdown/guides/application-users-and-events.md","sha256":"95a6ec89e3a3ba6ad99e79f77ec8adcdc21b1cf1e5d18b9fbe4cb0cef37e1775","headings":["1. 需要几个应用","2. 按用途完成最少配置","3. 登录后取得用户与客户空间","4. 事件怎样关联业务记录","5. 最小联调清单","6. 上报客户端诊断","7. 长连接接收事件","8. 处理已收到的履约和成员事件"],"excerpt":"多应用、用户与事件接入 本文说明同一家开发者企业有多个应用时，怎样配置登录、关联客户和处理事件。应用 A、应用 B 是通用示例，不代表真实客户。 1. 需要几个应用 产品情况 配置方式 --- --- 两个独立产品 创建两个应用，分别配置登录、API 权限、Webhook 和订阅套餐 一个产品同时需要用户登录和后台调用 在一个应用中启用用户身份和应用身份，无需因此创建两个应用 同一产品的 Sandbox 与 Production 使用独立应用；Production 关联已验收的 Sandbox 开发者后台顶部的企业是应用管理方。一家企业可以管理多个应用；共同归属不会让应用共享 Client、Secret、API 权限、用户授权或付费权益。 两个应用可以使用同一套服务端代码，但请求和事件必须按各自应用、环境及凭据处理。不要用应用 A 的 Client 调用应用 B，也不要合并两个应用的订阅记录。 多应用与客户空间关系 查看完整关系图 2. 按用途完成最少配置 只配置产品实际使用的能力。仅接用户登录无需取得应用身份 Secret；不通过平台收费无需先准备订阅套餐。 用途 开发者提供 后台入口 联调前确认 --- --- --- --- 用户登录 应用已实现的登录回调；按需调整自动补全的退出地址与网站来源 开发接入 → OAuth/OIDC 配置 → 用户身份 身份已启用，当前 Client ID 与精确回调一致；无需 Client Secret 后台 API 所需 API 与权限 凭证与基础信息；开发接入 → API 与权限 → 应用身份 身份已启用，API 权限已启用且绑定成功，Secret 保存在服务端 订阅与支付 套餐、平台管理的购买入口、所需接入能力 商业管理 → 订阅套餐／收费与履约 套餐可售、能力已生效，客户购买页面能读取当前应用和环境的目录 业务事件 事件类型；长连接使用应用身份，HTTPS 接收才需公网地址 开发接入 → 事件与 Webhook 订阅已启用，实际处理后 ACK 或安全接收后返回 2xx 应用目录导流 公共 HTTPS 首页或登录页 应用管理 → 应用发布信息 发布信息已生效；发布不授予客户产品访问权 登录回调接收授权码，客户访问地址打开产品，两者用途不同。网站来源只有协议、主机和端口，没有回调路径。 例如，回调为 https://app.example.test/auth/callback 时，网站来源为 https://app.example.test；退出后可返回 https://app.example.test/。应用必须实际实现回调，平台不会替第三方创建路由。 Issuer、Client ID 和已绑定权限从当前应用页面取得，不从另一应用或其他环境复制。详见认证与授权和接收 Webhook。 3. 登录后取得用户与客户空间"},{"path":"/guides/appmarket-operations","title":"经营管理 API","locale":"zh-CN","markdown_path":"/markdown/guides/appmarket-operations.md","sha256":"d7f6ba30c6f40eba0ee0c22887ad95a0865b36fe06af57c0ca5a1748542aec41","headings":["接入","方法与 Scope","公司与购买记录","销售线索","销售机会","销售报告与日志","Webhook 投递记录","客户人员与席位","订阅使用","经营任务","正式报价","写入与重试要求","查询与统计","创建正式报价","管理经营任务","查询订阅使用","查看本月统计","上报使用记录","查询客户人员与分配席位","查看公司详情","列表分页","销售报告","销售操作日志","Webhook 投递历史","错误与恢复"],"excerpt":"经营管理 API 经营管理 API 提供公司、商业档案关联、购买记录、人员分配、线索、机会、经营任务、使用记录、销售报告和销售日志等接口，可用于开发自己的经营后台。 在当前应用的 API 与权限 → 用户身份 → 接入方经营管理 中开通所需权限。订单接口请参见订单管理。 接入 1. 已提供的自有范围公司和销售功能默认可用；平台仍逐次核验本人职责与数据范围。 2. 配置需要的 API Scope，复制 Base URL、Application ID 和 API Product ID，明确本次使用的环境。Audience 与 Client 由有效配置派生。 3. 使用本应用用户 OAuth 授权码 + PKCE 登录；沿用户授权确认本人授权，绑定同一应用、环境、API 产品与 Scope。资源范围为 {\"resource_type\":\"appmarket_product\",\"resource_ids\":[\"your-product\"]}。 4. 自建后台通过自己的服务端调用。每次请求提供单个 Authorization: Bearer <用户Token、X-GV-Organization-ID（接入方企业）、X-GV-Application-ID、X-GV-Environment、X-GV-API-Product-ID、X-GV-Delegated-Grant-ID、X-GV-Product-Code。环境明确选择 sandboxproduction，内部身份与绑定由平台派生。 调用者需要有效的企业成员关系、应用管理关系，以及对应的公司、商业资料、购买或销售权限。应用所有者使用已有经营权限，其他成员需要被明确分配对应职责。 Scope、能力开通和本人授权需分别满足，不能代替业务权限。此产品仅支持用户 Token。查看管理员销售日志还需要线索和机会管理职责。 产品发布后会出现在目录中，无需手动注册。每个应用仍须配置实际所需的 API 权限，并取得用户本人授权。 方法与 Scope 公司与购买记录 方法与路径 Scope --- --- GET /open-platform/v1/appmarket/companies:context operations.company.read GET /open-platform/v1/appmarket/companies operations.company.read GET /open-platform/v1/appmarket/companies/{company_id} operations.company.read POST /open-platform/v1/appmarket/companies operations.company.manage PATCH /open-platform/v1/appmarke"},{"path":"/guides/appmarket-orders","title":"订单管理","locale":"zh-CN","markdown_path":"/markdown/guides/appmarket-orders.md","sha256":"ab32b778dfbef2acf4e99159d1302fd190812d52c5d72aa031e72753fbbff69e","headings":["开通与授权","公开接口","查询与结果说明","取消与原请求恢复","错误处理","名称展示","订单内的付款证据"],"excerpt":"订单管理 订单管理支持查询订单、取消订单和查看付款状态。可以使用开发者后台的 交易 → 订单 页面，也可以通过公开 API 开发自己的后台，两者使用相同业务规则。 订单按当前接入方企业、应用、产品和环境隔离，无需先选择客户公司。 开通与授权 1. 订单管理默认可用于当前应用自有范围，无需额外开通。进入「商业管理 → 订单」；无权或已关闭时按页面说明核对本人职责及当前应用状态。 2. 在“API 与权限”的用户身份中选择“订单管理”，配置需要的 Scope，记录 Application ID、API Product ID 和 Base URL，明确本次使用的 sandboxproduction 环境；Client 与 Audience 由有效配置派生。 3. 使用该应用的用户 OAuth 授权码 + PKCE 登录。Token 必须由该用户 Client 签发，包含所需 Audience 和 Scope。自建后台可保存自己的用户会话，浏览器通过自己的服务端请求 API。 4. 操作者使用当前接入方企业，并确认本人授权：resource_scope 为 {\"resource_type\":\"appmarket_product\",\"resource_ids\":[\"your-product\"]}。授权必须绑定同一 Application、环境、API Product 和 Scope，并且未过期或撤销。操作流程见用户授权。 此 API 仅支持用户 Token。调用者需要有效的企业成员关系和应用管理关系。应用所有者可查看本应用订单，并取消符合条件的订单；其他成员需单独获得订单查看或取消职责。 能力配置和 API 权限不会授予其他企业订单或财务执行权限。 Scope 操作 --- --- operations.order.read 查看可用状态、订单列表和详情 operations.order.cancel 取消允许取消的订单；不包含查看 Scope operations.payment.read 查看原订单的付款证据；独立核验付款查看职责 公开接口 方法与路径 Scope 返回 --- --- --- GET /open-platform/v1/appmarket/orders:context operations.order.read 当前能力是否启用、产品、允许动作及原因 GET /open-platform/v1/appmarket/orders operations.order.read 有界订单列表和下一页游标 GET /open-platform/v1/appmarket/orders/{order_id} operations.order.read 当前订单及允许动作 POST /open-platform/v1/appmarket/orders/{orde"},{"path":"/guides/authentication","title":"认证与授权","locale":"zh-CN","markdown_path":"/markdown/guides/authentication.md","sha256":"a1d14e19d40321f65773fdaf3ef7a0e5417392268d41eb462812a45e13f37090","headings":["开发者后台登录","登录过期后的恢复","敏感操作验证","选择认证方式","配置 OAuth Client","获取 Sandbox Application 后台服务 Token","用户登录","授权检查","安全说明","登录后的用户与客户空间"],"excerpt":"认证与授权 GoodVision 通过 OAuth 2.0 和 OpenID Connect 提供身份认证。本文介绍如何选择认证方式、获取 Access Token 并接入用户登录。 同一应用支持应用身份和用户身份，两者使用独立的 OAuth Client、API 调用授权和状态。认证成功后，业务 API 仍会校验 Audience、Scope、企业（Organization）、产品访问权限（ProductAccess）和资源归属。 开发者后台登录 开发者后台使用 GoodVision 统一身份服务完成登录。登录过程如下： 1. 使用自己的账号通过统一身份服务完成 Authorization Code + PKCE 登录。 2. 平台查询当前可访问的企业；首次没有企业时自动准备个人空间，再读取当前访问权限。 3. 进入已选择的有效企业，或在可用企业中明确选择。创建应用后，创建者自动成为应用所有者，无需先配置业务角色。 4. 普通成员按当前应用权限协作。已有企业或应用权限被撤销时，停止原范围操作，不静默切换到另一企业。 如果是 Partner 代 Customer 调用，服务端还可以提交 acting_organization_id。它只表示“以哪个 Partner 身份行动”，必须由平台根据已批准的委托关系验证；前端或请求 Header 不能自行授予跨组织权限。 Token、Refresh Token 和 ID Token 保存在加密的服务端 Session 中。浏览器仅接收非敏感的用户信息、企业信息和权限摘要。 登录过期后的恢复 后台提示登录过期时，在原页点击重新登录。验证成功后重新检查当前账号和权限：同一账号、同一有效范围可以保留普通草稿，临时 Secret 和删除、所有权等敏感确认会清除。后台不会自动重放创建、保存、付款或转交操作；回到原页核对后明确提交。 补登录后若提示暂时无法核验当前登录与工作区，先点击“重新核验工作区”读取当前状态，无需重复打开登录窗口。仅在登录确实失效时重新登录；重新核验不会自动提交原操作。 首次提交被明确要求重新登录或验证时，返回后仅重新读取当前权限和配置版本。核对保留的草稿，再次确认后才发起新的操作。 已提交但结果未知的请求单独保留原内容、版本和操作编号。同一账号、同一有效范围完成登录或验证后，使用“恢复原请求”确认结果；不要改写原内容或另建操作。新的敏感操作仍需重新确认。 换账号、退出、企业或应用权限失效时，旧资料和操作会清除。依赖暂不可用时按提示重新读取；不要把故障当成没有企业，也不要换用他人账号。 敏感操作验证 原页登录恢复与按需验证图示 图示：重新验证后仍需核对原操作并明确提交；此图不表示实际验证码验证已经完成。 普通登录和日常接入不要求先设置第二因素。所有权转移、向平台客服转交等敏感操作可能要求近期身份验证；按页面"},{"path":"/guides/callbacks","title":"处理同步回调","locale":"zh-CN","markdown_path":"/markdown/guides/callbacks.md","sha256":"21fa10a2483792913abea014bf71a58b3d5915484a8e1ab836f61b021fd206ed","headings":["配置与测试","接收请求","返回结果","超时与结果未知"],"excerpt":"处理同步回调 同步回调要求接收端在一次 HTTPS 请求内返回结构化结果。它与异步事件分别配置；选择长连接接收事件，不会将同步回调改为长连接。 当前可配置 token.agent.action.v1 并在 Sandbox 发送合成测试。真实 TOKEN 业务调用尚未开放；保存配置或测试成功，不代表生产业务已经使用该回调。 配置与测试 1. 在当前 Sandbox 应用的“开发接入 → 事件与 Webhook → 回调配置”选择回调类型。 2. 配置公网 HTTPS 接收地址，通过地址校验，按当前配置准备验签、Verification Token 和解密。 3. 保存后发送一次合成测试，查看独立的回调结果及接收端记录。 配置保存失败时，按配置恢复处理。配置保存的恢复与已发送测试的结果核对分别进行，不会自动再次发送测试。 异步事件集合和同步回调集合独立保存，修改一个集合时保留另一个完整集合。URL 变化后须重新校验。测试可能执行接收端逻辑，须使用明确隔离的测试处理；测试请求会标记 X-GV-Test-Delivery: true。 接收请求 先按当前配置验证签名、Token 和加密 Body，再验证请求 Schema、当前应用及环境。移除传输安全字段后，请求信封示例如下；所有标识均为合成值。 名称 类型 必填 说明 --- --- --- --- schema_version string 🔴 必填 当前固定为 \"1\" request_id string 🔴 必填 原样返回，用于接收端防重复 callback_type string 🔴 必填 token.agent.action.v1 application_id、environment string 🔴 必填 核对接收端应用和环境 data object 🔴 必填 应用约定的 JSON，最多 64 KiB 不要用异步事件的 event_id 或租约 ACK 替代同步请求标识。签名、加密和凭据取得方式见接收 Webhook。 返回结果 在 5 秒内返回 application/json，完整响应最多 64 KiB。信封只能包含下列五个字段；重复字段、未知字段、错误请求标识或非对象结果会被拒绝。 名称 类型 必填 说明 --- --- --- --- schema_version string 🔴 必填 固定为 \"1\" request_id string 🔴 必填 与请求完全一致 callback_type string 🔴 必填 与请求完全一致 status string 🔴 必填 completed 或 rejected result object 🔴 必填 应用约定的 JSON 对象 仅返回 2xx 而没有合法结果，不表示回调完成。 超时与结果未知 每个请求标识只尝试一次，平台不会自动重"},{"path":"/guides/code-examples","title":"第三方接入代码示例","locale":"zh-CN","markdown_path":"/markdown/guides/code-examples.md","sha256":"a1670925bd190a666c8a63e5d4185869d2b76b36ca3826b96c85c028e1df97be","headings":["一、选择调用身份","二、从控制台复制配置","三、服务端配置示例","四、应用身份：获取 Token","五、调用 API","六、用户登录：PKCE","七、接收 Webhook","八、Node.js、Go、Python 示例","Node.js （内置 `fetch`）","Go（标准库）","Python（标准库）","SDK 支持说明","注意事项","登录后的用户与空间"],"excerpt":"第三方接入代码示例 本文提供获取 Access Token、调用 API、接入 PKCE 登录和接收 Webhook 的代码示例。接入前，请在开发者后台创建应用并开通所需 API 权限。 示例使用占位值。请从当前应用复制 Issuer、Client ID、API 地址、Audience 和 Scope，并填入服务端配置。 一、选择调用身份 场景 调用身份 认证方式 Client Secret --- --- --- --- 后台任务、定时同步、服务间调用 应用身份权限 Client Credentials 仅服务端保存 Client Secret 用户登录后代表用户调用 用户身份权限 Authorization Code + PKCE（S256） 无 Client Secret 如果两种场景都需要，就在同一个 Application 中分别启用、分别申请权限。两种身份的 Client、Scope 和 Token 不能混用。 二、从控制台复制配置 控制台页面 配置项 用途 --- --- --- OAuth/OIDC 配置 Issuer、Client ID、回调地址 登录和获取 Token API 与权限 API Base、Audience、已批准 Scope、接口路径 服务端调用 API 事件与 Webhook Webhook 地址、事件类型、密钥交付状态 接收订阅和支付事件 只复制当前环境、当前身份已经批准的内容。用户身份不需要 Client Secret；应用身份的 Secret 只能放在服务端的 Secret Manager 中。 三、服务端配置示例 使用用户身份时，改为配置 GOODVISION_USER_CLIENT_ID、已经登记的 GOODVISION_REDIRECT_URI 和 GOODVISION_POST_LOGOUT_URI，不填写 Client Secret。 用精确 GOODVISION_IDENTITY_ISSUER 加 /.well-known/openid-configuration 读取 Discovery，核对 issuer，使用返回的 token_endpoint、authorization_endpoint 及按需使用的 end_session_endpoint。上面的 Endpoint 变量保存这些返回地址，不猜固定路径。 推荐事件接收可直接运行Node.js 22 长连接示例；HTTPS 接收与同步回调分别配置。 四、应用身份：获取 Token 这一步只能在第三方后端执行。浏览器不能执行 Client Credentials，也不能接收 Client Secret。 服务端使用返回的短期 Token 调用 API；同时检查签发方、目标 API、有效期和 Scope。Token 过期后重新获取，不要自行延长有效期。"},{"path":"/guides/developer-tooling","title":"GoodVision CLI","locale":"zh-CN","markdown_path":"/markdown/guides/developer-tooling.md","sha256":"995cde2fc4ec10a7a3e4b69fcbf231049c7f7d3f3cd58d0fc8caf01eab11b682","headings":["快速开始","使用场景","能力地图","文档导航"],"excerpt":"GoodVision CLI GoodVision CLI 让 Codex 在终端中发现并调用 GoodVision 的公开 API。先找到能力、理解参数、预览请求，再执行已获准的模型、客户经营、订阅和订单操作，结果可直接交给代码或脚本处理。 产品名为 GoodVision CLI，命令为 goodvision（简写 gv），包名 @goodvision/cli。与 @goodvision/ui 使用同一 @goodvision npm scope 和维护团队；CLI 与 SDK 已通过 npm 提供，也支持源码构建。 快速开始 1. 安装 CLI：从 npm 安装公开包，或使用源码构建。 2. 配置身份：固定应用与环境，按操作选择用户身份或应用服务身份。 3. 发现能力、预览请求，完成第一次 API 调用。 使用场景 任务 可以这样告诉 Codex 使用能力 --- --- --- 首次接入应用 找到用户空间 API，读取所需 Scope，用我的 sandbox 配置预览首次请求。 能力发现、Schema、请求预览 接入模型 查看模型 API，生成按当前授权上下文查询可用模型和用量的代码。 Token API、SDK 类型 客户经营 找到公司、线索和报价操作，先列出必需的领域引用和请求预览，再执行修改。 客户经营 API、产品策略、幂等 事件自动化 生成事件接收项目，持久保存已订阅事件，幂等处理完成后再确认。 事件 SDK、SSE、Webhook 模板 能力地图 业务能力地图按业务域列出已登记的公开能力、产品 ID 和接入指引。Agent 能力概述说明凭据、交互、执行三层及其组合路径。 文档导航 目标 独立指南 --- --- 安装和第一个任务 快速开始 选择身份和检查凭据 认证与配置 同时管理多个应用 多应用与 Profile API 发现、预览和执行 发现与调用 API 事件调试与确认 接收与确认事件 命令和机器可读文档 命令参考 错误与恢复 常见问题 在应用代码中调用 TypeScript SDK 创建接入项目 接入模板 目录登记、凭据获取和业务授权分别核验。扫码创建应用、终端 OAuth 登录／登出和聊天 Channel SDK 尚未提供。"},{"path":"/guides/event-connection","title":"长连接接收事件","locale":"zh-CN","markdown_path":"/markdown/guides/event-connection.md","sha256":"8c69ad8bb93fdf111839e8a1a2bdd39282f9a958f22ed97d3c4fd00b94bd8623","headings":["1. 选择事件","2. 配置并运行示例","3. 发送测试并接入业务","连接与恢复合同"],"excerpt":"长连接接收事件 推荐从长连接开始：应用服务端主动建立连接，不需要公网接收地址、Challenge、HMAC Secret、Verification Token 或 Encrypt Key。使用应用身份的 Client Credentials；用户登录凭据不能接收这条连接。 本文提供 Node.js 22、零依赖的可运行示例，不是 SDK。已有公网接收服务时也可以选择 HTTPS Webhook，同步回调继续单独使用 HTTPS。 事件接收方式与独立同步回调图示 图示：异步事件选择长连接或 HTTPS；同步回调独立配置。此图用于解释流程，不是后台截图。 1. 选择事件 进入当前应用 → 事件与 Webhook，使用推荐的“长连接”。没有可用应用身份时，在当前事件页点击“启用应用身份”，等平台回读确认后继续；启用身份不会授予业务 API 权限。添加至少一个事件并保存。零事件或配置未生效时没有事件可接收；页面不会替你的服务建立连接。 2. 配置并运行示例 下载 event-connection.mjs，复制事件页的“当前应用参数”到服务端 .env。模板包含精确的 Application ID、环境和应用身份 OAuth Client ID；补入当前环境提供的 API Base 和该 Client 的 Secret，Identity Issuer 若未提供也须补齐。不要使用用户身份 Client 或其他应用／环境的凭据。 保护 .env，不提交到源码或发给浏览器。运行： 示例从精确的 Issuer Discovery 读取 Token Endpoint，以 client_credentials 获取包含 openplatform.api.invoke 的 Bearer。Token 只在内存和 Authorization 请求头中使用，不进入 URL、Inbox 或日志。连接和 ACK 均受当前应用权限与来源限制控制，示例不绕过限制。 原事件保存在服务端 event-inbox/，示例结果在 event-inbox/results/。可用 GOODVISION_EVENT_INBOX 指定持久目录；每个应用／环境使用独立目录，仅运行一个接收进程。保留这些文件用于重启恢复，不把目录当作可随时清空的缓存。 3. 发送测试并接入业务 在 Sandbox 的“事件调试”发送已订阅事件，查看示例状态和“投递日志”。connected 只说明连接已建立；delivery_processed 表示本次示例处理与 ACK 已成功。测试入队不等于接收完成。 示例的 onEvent 只持久保存示例结果，不执行开通、支付或权限变更。接入业务时替换该独立回调：按当前事件 Schema 校验客户、资源与环境，在业务事务内使用 event_id 幂等处理，成功后才返回。Sandbox 合成事件"},{"path":"/guides/idempotency","title":"幂等与重试","locale":"zh-CN","markdown_path":"/markdown/guides/idempotency.md","sha256":"68ba02e781bc2fd264dcf373e34efdf13dc5dc619aff46589b4471c4c159ff60","headings":["一个业务操作只生成一次 Key","超时后的处理顺序","哪些错误可以重试","Webhook 也需要幂等"],"excerpt":"幂等与重试 幂等用于避免同一业务操作在重试时重复执行。GoodVision 写请求使用稳定的 Idempotency-Key，重复提交相同请求时不会产生重复结果。 网络超时后，服务端可能已经完成操作。请保留原请求内容和幂等键，按以下步骤恢复。 一个业务操作只生成一次 Key 用户发起操作时生成一个不可预测的 Key，将它和本地业务记录一起持久化。相同请求的所有重试必须复用这个 Key。 同一个 Key 不能用于不同 Payload。Key 已绑定其他请求内容时，服务端可返回 409 Conflict。 超时后的处理顺序 1. 使用原 Key 和完全相同的 Payload 重试。 2. 如果已获得 operation_id，查询该异步操作。 3. 查询当前资源状态，确认原操作是否已经生效。 4. 只有用户明确发起一个新的业务操作时，才生成新 Key。 不要因为超时就换 Key 重复创建订单、取消请求或支付/退款操作。 哪些错误可以重试 情况 处理方式 --- --- 网络错误或超时 原 Key、原 Payload，有界指数退避 429 遵守 Retry-After，增加随机抖动 契约明确可重试的 5xx 有界重试，之后查询操作或资源状态 400 / 422 修正输入后作为新操作提交 401 / 403 修复认证或授权，不要原样重试 409 读取当前状态，处理版本或幂等冲突 Webhook 也需要幂等 Webhook 按“至少一次”投递，同一事件可能出现多个 Delivery。使用 event_id 去重，使用 resource_version 防止旧事件覆盖新状态；delivery_id 只标识一次投递尝试。"},{"path":"/guides/integration-templates","title":"接入模板","locale":"zh-CN","markdown_path":"/markdown/guides/integration-templates.md","sha256":"a68d8b43275499f71030ab33f55baba8f3c899d8e82c3f54d65bca495eb0a638","headings":[],"excerpt":"接入模板 安装 GoodVision CLI后，创建最小接入项目。 模板 用途 --- --- api 首次 API 请求 pkce-web PKCE 网页用户授权 event-receiver SSE 持久接收与显式 ACK webhook HTTPS 事件接收与签名校验 四类模板分别提供 API 首次调用、网页 PKCE、长连接持久接收和明文 HTTPS Webhook 接收。模板只写入新目录，不执行安装或脚本；按生成目录中的 README 配置并运行。事件模板不替应用执行开通或支付，接入真实业务前按事件 Schema 和资源版本完成自己的业务处理。"},{"path":"/guides/order-payment","title":"独立订单支付","locale":"zh-CN","markdown_path":"/markdown/guides/order-payment.md","sha256":"4c58ebea2567355434dbbf6e4b28d33c124ce7deafb8b5da7972c3561050ecd5","headings":["前提条件","调用权限","创建订单与付款","错误与恢复"],"excerpt":"独立订单支付 独立订单支付支持一次性商品购买。本文介绍如何查询报价、创建订单、打开付款页面，以及恢复原订单的付款。 前提条件 开发配置与测试无需人工审批。已提供的自有范围经营功能默认可用；一次性商品按真实需要配置，不是登录、API 或事件联调的前置。 在 Developer Console 的当前应用「商业管理 → 收费与履约」中选择一次性商品及已批准报价，保存后平台自动核验。报价包含确定的商品、价格和条款版本。客户的付款资格须独立批准；能管理应用或客户公司资料不能直接获得客户付款权限。 调用权限 使用当前应用的用户 OAuth 登录，并申请独立支付 API 的用户权限： Scope 用途 --- --- commerce.order_payment.catalog.read 读取获批的一次性报价 commerce.order_payment.order.read 读取原订单和付款状态 commerce.order_payment.checkout.create 接受报价及恢复原订单付款 API 权限配置就绪后，还须取得当前用户对 order_payment_product 资源范围的本人同意。资源编号是当前商品的 Product Code。Token 商品的本人授权不能用于独立订单支付；应用服务身份不能代替用户身份。 每次调用以下接口时，携带用户 Bearer，以及当前企业、应用、环境、API 产品、本人授权和商品的选择头：X-GV-Organization-ID、X-GV-Application-ID、X-GV-Environment、X-GV-API-Product-ID、X-GV-Delegated-Grant-ID、X-GV-Product-Code。每个头只允许一个值。使用公开配置的 GOODVISION_API_BASE，明确选择 sandboxproduction，平台派生对应 Client 与环境绑定。 创建订单与付款 1. 调用 GET /open-platform/v1/order-payment-offers，读取当前获批报价的 id、resource_version、价格、条款正文和 terms_sha256。用户确认正文后，提交接受请求。 2. 调用 POST /open-platform/v1/order-payment-orders，携带原 Idempotency-Key 和如下内容。金额由报价计算，正文不接受金额、收款账户或环境覆盖。 3. 保存返回的原订单 id。此步骤只接受订单。调用 POST /open-platform/v1/order-payment-orders/{id}:checkout，携带原请求键及空对象 {}，创建或恢复该订单的付款。取得有效 checkout.checkout_url 后跳转。 4. 回"},{"path":"/guides/product-access-snapshot","title":"产品权限快照回查","locale":"zh-CN","markdown_path":"/markdown/guides/product-access-snapshot.md","sha256":"51265c0b3a39cb9d69dbbf0e3d315c82d58829fc6f742a0b999dd1e79481f1f0","headings":["请求","使用结果","失败与恢复"],"excerpt":"产品权限快照回查 收到 oem.access_context.changed.v1 后，使用本应用服务身份查询事件目标成员的当前权限。 请求 POST /open-platform/v1/applications/{id}/events/{event_id}/access-snapshot 以 GOODVISION_API_BASE 为入口，使用当前应用服务 Client 取得的 Bearer Token，Scope 为 openplatform.api.invoke，JSON 正文为 {}。应用需已启用成员权限能力；不要求给普通用户增加运营角色或机器权限。 id 是当前应用，event_id 是本应用已收到的原权限事件。平台从原事件确定客户空间、产品和成员；不接受额外客户、企业、Profile 或环境选择，也不提供客户或全体成员列表。另一应用的凭据不能查询该事件。 使用结果 响应包含 application_id、environment、product_code、audience、organization、product_access、单个 members、entitlements、capabilities 和 generated_at，并设置 Cache-Control: no-store。 成员 membership_id 对应用户上下文的 space.membership_id，不能与 open_id、union_id 或登录身份标识互换。只有 product_access_allowed 明确为 true、身份和成员均为 active、产品访问为 trial 或 active，且 access_revision 不低于原事件时，才应用当前权限。未分类许可不返回 product_license_kind，不能推断为构建许可。 同一用户在两个应用中的权限、产品与订阅分别核验；union_id 相同不产生跨应用授权。支付成功、订阅激活或履约成功事件均不能替代本次回查。 失败与恢复 收到事件先持久化并限制旧权限。401 时重新取得当前应用服务 Token；403／404 时核验应用、原事件及能力是否仍有效；503 时保留事件进行有界重试。响应缺字段、成员不匹配或版本不足时继续限制访问，不沿用旧权限。 相关文档：订阅生命周期 · 事件目录 · API 产品"},{"path":"/guides/saas-commerce-api","title":"SaaS 订阅与支付 API","locale":"zh-CN","markdown_path":"/markdown/guides/saas-commerce-api.md","sha256":"0807cd1cffefbd8f4c9818c32e48c4ebe26e1e670947837ebdb5d880a4456332","headings":["1. 准备调用权限","2. 查询套餐并创建付款","匿名读取公开套餐","查询机会关联的报价","查看客户收到的报价","3. 查询、取消与变更订阅","激活免费套餐","升级免费订阅","查询订阅","取消或变更套餐","4. 错误与恢复","5. 配置订阅套餐和 Credits","开启免费激活","配置 Credits","配置首月优惠","个人版、企业版与 SaaSdemo 演示","先发布套餐，稍后配置访问地址","独立定价页与 URL 参数","配置一次性Credits加量包"],"excerpt":"SaaS 订阅与支付 API SaaS 订阅与支付 API 提供套餐查询、付款创建和订阅管理等接口。使用平台现成页面的接入方式，请参见第三方 SaaS 订阅与支付。 调用前，请确认当前应用已开通对应 API 产品，并使用指定环境和版本。Production 尚未开放，产品登记不会自动开通正式环境。 1. 准备调用权限 在开发者控制台中为当前应用配置所需的 API 权限，然后使用客户用户的身份调用接口。客户还需要有效的企业成员关系、商业资料和付款资格。 每次请求携带以下请求头： Endpoint 最小 Scope --- --- GET /open-platform/v1/products commerce.catalog.read POST /open-platform/v1/checkout-sessions commerce.checkout.create POST /open-platform/v1/free-activations commerce.checkout.create GET /open-platform/v1/operations/{id} commerce.checkout.read GET /open-platform/v1/subscriptions commerce.subscription.read GET /open-platform/v1/subscriptions/{id} commerce.subscription.read POST /open-platform/v1/subscriptions/{id}:cancel commerce.subscription.manage POST /open-platform/v1/subscriptions/{id}:change-plan commerce.subscription.manage POST /open-platform/v1/subscriptions/{id}:change-pricing commerce.subscription.manage GET /open-platform/v1/customer-quotes/{id} commerce.catalog.read GET /open-platform/v1/customer-quotes commerce.catalog.read POST /open-platform/v1/customer-quotes/{id}/accept commerce.checkout.create POST /open-platform/v1/customer-quotes/{id}/decline commerce.checkout.create 2. 查询套餐并创建付款 匿名读取公开套餐 GET /open-"},{"path":"/guides/saasdemo","title":"SaaSdemo：最小第三方 SaaS 接入","locale":"zh-CN","markdown_path":"/markdown/guides/saasdemo.md","sha256":"8e3594384283f9b67ea2aaa47ee72dde04b494c20fb3aa7fe03103f0227c8291","headings":["页面功能","顶部账号入口与用户信息","OIDC 配置","从 Developer Console 获取接入配置","Demo BFF 路由","配置订阅与账单入口","最小实现流程","Webhook Receiver 参考实现","自动履约接入（可选）","套餐与Credits参考","验收清单","参考案例中的客户空间"],"excerpt":"SaaSdemo：最小第三方 SaaS 接入 SaaSdemo 演示第三方 SaaS 如何接入 GoodVision 登录、订阅和支付。示例应用提供自己的业务页面和登录会话，套餐、订阅、支付、账单和权益管理由 GoodVision 客户工作区提供。 SaaSdemo 的订阅页展示当前已发布的免费或付费套餐，支持月／年切换、Credits、席位、FAQ 和原订单恢复。应用分别查询免费激活、付款、额度和产品开通状态，不维护独立的余额或资格表。 升级时按订阅 ID 分别保存状态。旧免费订阅终止后，仍需检查当前成员权限。 示例边界 SaaSdemo 是给第三方 SaaS 团队参考的独立接入样例，不是 GoodVision 内部微应用或内部服务 Demo。它演示已发布的 OIDC 接入和页面功能。使用商业 API 前，请在开发者控制台确认当前应用已开通 SaaS Billing API Product，并使用产品提供的路径、Scope、Audience 和事件 Schema。 页面功能 能力 SaaSdemo GoodVision 平台 --- --- --- 注册、登录、退出 提供入口和同源 BFF Session GoodVision 统一身份服务处理身份、凭证和 OIDC Session 合作方业务页面 展示第三方产品自己的功能 不托管第三方业务功能 套餐、订阅、支付、账单 只提供平台入口 客户工作区展示并执行商业操作 Application、API Product、Webhook 只提供开发者平台入口 Developer Console 管理技术接入 API 参数和错误码 使用当前版本说明 API Product 提供对应 OpenAPI/AsyncAPI 套餐、订单、支付、账单和使用权限由平台管理。第三方页面不能维护另一套结果，也不能用 localStorage 模拟这些状态。 顶部账号入口与用户信息 示例顶部提供开发者后台、应用入口和登录按钮；登录后显示账号头像、姓名与邮箱，可读取用户信息、切换语言、登录其他账号或退出。切换应用只打开服务端登记的独立入口，不转移当前应用的会话或权限。 以下路径属于 SaaSdemo 自己的同源 BFF，供第三方参考实现，不是平台新增的业务 API： 接口 用途 --- --- GET /auth/session 检查是否登录，读取当前用户投影和本应用 CSRF 信息 GET /api/me 重新核验当前会话和应用范围，读取姓名、邮箱、本地用户 ID、open_id 与 union_id GET /auth/login?switch_account=true 通过统一登录确认其他账号；登录后返回原页面 POST /auth/logout 携带本应用的 CSRF 校验，退出并清理当前会话 接口只读取当前登录用户，不接受用户、企"},{"path":"/guides/sales-operations","title":"线索与机会经营","locale":"zh-CN","markdown_path":"/markdown/guides/sales-operations.md","sha256":"6fef14b6a785c6c4bdf96e076a67dde4a4dde5dc740df7c2eb92961d6e7dd7f3","headings":["启用与入口","线索登记和转换","机会阶段和结果","查询与恢复","默认权限与自动恢复"],"excerpt":"线索与机会经营 通过线索与机会管理，可以登记销售线索、记录跟进、将符合条件的线索转为机会，并更新销售阶段和结果。数据按当前企业、应用、产品和环境隔离。 已提供的自有范围销售功能默认可用，无需逐项申请或额外开通。应用所有者及协作者按当前职责和数据范围使用。 启用与入口 在 Developer Console 选择当前企业和应用，进入「客户经营 → 线索／机会」。平台核验当前应用和本人职责后读取记录，不要求总配置或重复启用。 如果没有菜单，先检查当前应用的能力状态和本人的销售权限。未启用、已暂停、无读取权限或暂时无法确认权限时，资料保持关闭。线索读取、管理、转换，以及机会读取、管理、重开分别授权；公司查看权不能代替销售权。Sandbox 和 Production 分别配置，不共享销售记录。 线索登记和转换 1. 在「线索」选择「新建线索」，填写来源系统、来源对象引用、公司名称、联系人和负责人引用、合法收集依据及其引用、操作原因。 2. 来源系统和对象引用用于识别同一条线索。相同范围内重复登记会发生冲突；先查询已有记录，不通过变更来源创建重复线索。 3. 在详情中选择获授权操作，编辑资料、分派负责人、添加跟进或判定资格。跟进一经记录不能覆盖；补充说明应新增跟进。 4. 显式标记重复时，查询并选择当前应用的目标线索。标记只保存重复关系，保留原记录。 5. qualified 线索可「转为机会」，填写机会名称、需求、负责人、预计金额及币种、预计日期和原因。转换成功后原线索只读，并保留机会引用。 联系人、负责人和收集依据引用应来自你方合法的售前流程。填写这些引用不会验证客户身份，也不会授予客户人员数据或营销权限。 转换会同时保存线索和机会，客户公司、付款主体和产品使用资格需另行建立。 机会阶段和结果 机会详情允许按当前权限编辑需求、精确预计金额、日期、负责人和销售阶段。金额是销售预估；赢单或丢单须记录原因，赢单不确认订单、付款、开通或收入。 终态机会只读。有独立重开权限时可以提交重开原因，恢复售前阶段并保留历史赢单／丢单结果。报价关联和客户公司摘要尚未开放，不能用机会作为正式报价或交易条件。 查询与恢复 搜索和状态筛选针对当前范围的全部记录；「加载更多」读取下一页，目录会随记录变更更新，不是固定快照。下一页失败时保留已加载资料，再次加载沿用原游标。 结果不明时，页面保留并锁定原输入。按情况处理： 情况 操作 --- --- 超时或暂时不可用 点击「恢复原请求」，发送相同内容、版本和请求键，避免重复登记线索 版本冲突 保留草稿，读取当前记录，核对变更后确认新版本提交 成功 重新查询当前状态；原回执可能对应较早的状态 撤权或切换企业、应用、环境会清理旧资料和未完成表单。持续无法读取时先确认当前能力与权限，再联系支持。 默认权限与自动恢复 应用所有者开通公司、线索与机会管理后"},{"path":"/guides/sdk","title":"GoodVision TypeScript SDK","locale":"zh-CN","markdown_path":"/markdown/guides/sdk.md","sha256":"4739dd9e833c16a18b8c70e112dce836e1ad09a177629e6b0947ce4ac8e4caea","headings":["全局能力发现"],"excerpt":"GoodVision TypeScript SDK 按快速开始从 npm 安装 SDK 后，以同一操作 ID 调用： Token 文件由接入方按前述私有权限保管。discoverOperations 只搜索本地生成目录；类型、参数、响应、Scope 来自 Owner，实际授权由 API 执行。事件接收可使用 consumeEvents：持久且幂等完成回调后才 ACK，回调失败不 ACK。 全局能力发现 capabilityOverview 从本地公开合同汇总产品版本、操作数量、身份、Scope 和双语文档入口，不判断目标可用性或当前授权。"},{"path":"/guides/subscription-lifecycle","title":"订阅生命周期","locale":"zh-CN","markdown_path":"/markdown/guides/subscription-lifecycle.md","sha256":"897769b6bbfc54c83ff7fe131b69e6c4cf67aeb88992ad9b1941822cc08bfd1d","headings":["状态处理","场景一：激活 → 预约取消 → 取消生效","预约取消的完整事件","取消生效的完整事件","场景二：预约套餐变更 → 新套餐生效","场景三：续费失败 → 宽限期 → 到期","更新订阅状态","订阅变化后如何处理成员权限","订阅与用户的关系"],"excerpt":"订阅生命周期 本文介绍 SaaS 订阅的状态变化，以及如何处理续费、取消、套餐变更和到期事件。 商业 SaaS 订阅与应用的 API 调用授权相互独立。取消其中一项不会自动取消另一项，也不会自动退款。 状态处理 免费套餐需在已发布方案中明确启用后才能激活。响应包含 billing_mode: free，无需付款，因此 active 也可能表示免费订阅。 升级后的摘要包含 upgrade_from_subscription_id。付款确认前，原免费订阅继续有效。分别按 (subscription_id, resource_version) 更新两份订阅记录；旧订阅的终止事件不能覆盖新订阅。遇到乱序时，重新查询当前订阅和成员访问权限。 付费升级确认后，原免费订阅已分配的成员及用户组来源会转到新订阅，重叠来源仍按成员去重计席位。产品开通与当前成员访问检查仍须成功；升级后被明确撤销的来源不会因后续订阅修订而恢复。 关闭新免费激活不会修改历史订单。订阅事件不提供付款引用、续费处理信息或调度字段；金额和付款结果请通过已授权的订单接口查询。 订阅事件的 data 包含当前商业订阅摘要。接收后更新本地订阅记录；它不是变化字段列表，也不提供成员权限。开放产品功能前，另行检查当前成员的访问权限。 商业状态 含义 接入方行为 --- --- --- draft / pending_payment 草稿或等待支付 展示准备/支付状态，不据此开放功能 trialing / trial_ending 试用中或即将结束 展示 trial_end，访问按授权回查结果执行 active 商业订阅已生效 展示当前套餐与周期，单独核对成员权限 renewal_pending 进入续费窗口 展示续费提示，不自行延长当前周期 payment_failed / past_due / grace_period 支付失败、逾期或宽限期 引导恢复支付，不自行延长 grace_deadline plan_change_pending 套餐变更尚未生效 展示当前套餐与预约套餐，不提前套用新权益 pause_pending / paused 已预约暂停或已暂停 区分预约与生效时间，按当前访问结果限制操作 cancellation_pending 取消已预约 展示 cancel_at，不能当作已经取消 cancelled / expired 取消已生效或订阅到期 收紧访问并回查，提供重新订阅入口，保留历史 suspended 商业订阅被限制 收紧访问，只允许获批的恢复和 Support 操作 terminated 该订阅被终止 停止依据该来源放行，回查当前成员权限和替代订阅，保留历史 所有事件名称、触发条件、允许的 data.status 和相关字段见完整订阅事件表。只有已获批并勾选的事件才会投递；事件目录不代表你"},{"path":"/guides/third-party-saas-billing","title":"接入第三方 SaaS 订阅与支付","locale":"zh-CN","markdown_path":"/markdown/guides/third-party-saas-billing.md","sha256":"d345e04af4a659e693127420964ac9b87038bce9f38bc9e546f1892090793b9c","headings":["接入方式","跳转到客户工作区","按应用打开方式返回","平台侧商业流程","第三方服务端职责","可选 API 与事件接入","套餐/VIP 权限变更","上线验收"],"excerpt":"接入第三方 SaaS 订阅与支付 通过 GoodVision 客户工作区，第三方 SaaS 可以接入套餐选择、订阅、支付和账单管理。本文介绍如何配置平台入口、处理登录和支付跳转，并同步订阅状态。 当前方案支持固定月付或年付 SaaS 使用费、套餐月度 Credits 和已发布的一次性加量包。Credits 表示使用额度，不是可提现储值余额；未声明的超额扣费不会自动启用。 接口使用 billing_interval=monthyear 指定月付或年付周期。 当前可用性 客户的套餐、订阅、支付和账单页面由 GoodVision 客户工作区提供。Commerce Checkout Sandbox API Product 已实现，当前应用在开发者控制台获得对应调用配置后才能使用；Production 路径尚未开放。 可先完成平台跳转、OIDC BFF 和页面接入，再按已开通的 Scope 接收脱敏的订阅、支付和退款事件。 接入方式 场景 第三方产品 GoodVision 平台 --- --- --- 产品功能 展示合作方自己的业务页面 不复制第三方业务功能 定价、比较、FAQ 用独立页面承载平台 iframe，并提供独立打开入口 /console/pricing 提供个人／企业及月／年套餐 订阅、支付、账单、权益管理 在弹窗中嵌入平台管理页，或独立打开 /console/subscription 与 /console/billing 提供管理操作 Application、API Product、Webhook 只显示 Developer Console 入口 Developer Console 管理技术接入 产品权限判断 按已开通接口查询必要状态 根据订单、付款和权限检查返回当前结果 第三方不需要实现第二套本地套餐目录、订单或支付状态机。SaaSdemo 的 /app/pricing 在工作区中保留左侧导航并嵌入平台定价 iframe；/pricing 提供带官网顶栏的独立宿主页。两个入口的“我的订阅”都打开管理弹窗；平台价格页与管理页分别承载不同任务。侧栏在定价、订阅和账单之间保留所选 product，独立链接保留同一应用／环境／产品。第三方可以承接平台已冻结的支付返回导航，但价格、订单、支付、账单和使用权限仍由平台管理。 跳转到客户工作区 在第三方服务端配置当前环境的客户工作区 URL。定价入口为 /console/pricing，订阅管理为 /console/subscription，账单为 /console/billing。配置示例请参见 SaaSdemo 的 platform.subscriptionUrl 和 platform.billingUrl。 可独立打开，也可在已登记的 Origin 下通过 iframe 嵌入。仅支持已公布的范围选择和展示参数："},{"path":"/guides/token-api","title":"Token 套餐与多模态 API","locale":"zh-CN","markdown_path":"/markdown/guides/token-api.md","sha256":"3720f35e217cfb9b74553b77115242e5a4366b12f53fd3241a91dbbdf74d73ed","headings":["1. 配置用户身份权限","2. 查询、购买与恢复","Credits加量包政策","3. 模型与调用","4. 额度、用量与拒绝处理","额度批次","查询使用记录","筛选与统计","用户空间与模型权限"],"excerpt":"Token 套餐与多模态 API Token API 提供套餐查询与购买、付款恢复、额度与用量查询，以及多模态模型调用。白牌客户可以在自己的产品中完成这些操作，无需先进入平台控制台。 1. 配置用户身份权限 在当前应用的“API 与权限 → 用户身份权限”申请已发布的 Token API 产品。配置用户登录回调，使用授权码 + PKCE，让用户确认操作范围。用户 Access Token 属于当前应用的用户 OAuth Client；不能用模型节点的 API Key 或应用身份 Token 替代。 操作 最小 Scope 客户权限 --- --- --- 读取套餐 commerce.catalog.read 当前客户的商业读取权 读取原订单 commerce.order.read 当前客户的商业读取权 创建订单／恢复付款 commerce.checkout.create 当前付款主体的付款操作权 读取模型 inference.models.read 当前用户的产品调用授权 调用模型 inference.invoke 当前用户的产品调用授权及可用额度 读取额度 inference.balance.read 当前客户账务账户读取权 读取用量 inference.usage.read 当前客户账务账户读取权 自动配置成功后确认“API 与权限”中的实际绑定状态为已绑定，再通过 PKCE 重新获取包含本次最小 Scope 的用户 Token。Audience 由当前启用的产品及权限签发，客户无需手工添加；配置漂移或更新前的旧 Token 可能被拒绝。 API 权限配置、用户同意和客户自身权限都需要当前有效。模型调用用户无需付款人权限；套餐付款成功也不会自动授予用户权限。 完成用户身份认证后，使用当前应用的用户 OAuth Client Token 调用 /open-platform/v1/delegated-grants，保存当前用户的产品授权。 - application_id、environment 和 api_product_id：使用当前应用的稳定 ID、明确的 sandboxproduction 环境及 API 产品。 - scopes：仅填写本次需要的权限。 - 资源范围：使用 {\"resource_type\":\"token_product\",\"resource_ids\":[\"<product_code\"]}。 保存响应中的 Grant ID，供后续调用使用。授权撤销或到期后，调用会被拒绝。创建与撤销参数请参见用户授权。 使用当前环境提供的 GOODVISION_API_BASE，并在每次请求中携带以下请求头。环境明确选择 sandboxproduction；Client、绑定和 Scope 由平台派生，请求不接受价格、账务账户或执行节点地址。 平台会核"},{"path":"/guides/user-authorization","title":"用户授权","locale":"zh-CN","markdown_path":"/markdown/guides/user-authorization.md","sha256":"0addeeb7fe149ac6f588c60c5219267413bf33060be3652c445a4dbc11b3fdc0","headings":["前提条件","接口列表","查询选项并创建授权","查询、核验与撤销授权","错误与恢复","用户关联与用户授权"],"excerpt":"用户授权 通过用户授权，用户可以指定应用允许操作的业务资源和有效期限。本文介绍如何查询授权选项、创建授权、核验授权范围和撤销授权。 API 调用权限、用户同意和资源权限分别校验。创建授权不会购买商品或增加额度。 前提条件 创建、续期及核验前，先按接入入口与权限配置当前应用的用户身份与所需 API Scope，再完成授权码 + PKCE 登录。列表和撤销只要求有效的本人登录与当前企业关系，不要求管理权限、业务 Scope 或应用可用状态。每次调用携带用户 Bearer 和 X-GV-Organization-ID。用户必须属于当前客户企业；不使用应用身份 Token，也不在正文传入另一个用户或企业。 接口列表 接口 说明 --- --- GET /open-platform/v1/delegated-grant-options 读取当前应用、当前用户 OAuth Client 可用的授权选项 GET /open-platform/v1/delegated-grants 读取本人的授权；可按 status=active\\revoked\\expired 筛选 POST /open-platform/v1/delegated-grants 创建或按版本更新本人授权 POST /open-platform/v1/delegated-grants/{id}:revoke 使用当前版本撤销本人授权 POST /open-platform/v1/delegated-grants:authorize 核验当前请求是否在有效授权范围内 这些共享接口不单独申请一个 API 产品。创建及核验授权时，Token、应用用户身份与 API 调用权限必须共同包含请求的业务 Scope。 查询选项并创建授权 响应的 items 包含可用的 application_id、application_name、environment、environment_binding_id、api_product_id、scopes 和 product_codes。选项来自当前应用、环境和 API 产品的有效权限。product_codes 只在存在真实商业资源时提供候选；空数组不代表用户已经授权，创建授权时仍须使用业务 Owner 确认的精确资源。 Client 与环境绑定由平台根据当前来源派生；创建和核验请求只提交应用、环境与 API 产品，不提交 OAuth Profile、订阅或环境绑定 ID。其他产品请使用对应说明中的资源类型与范围。 向用户展示用途、Scope、资源和到期时间，确认后调用创建接口，携带稳定的 Idempotency-Key。以下为 Token 产品示例，替换所有占位值： 创建成功返回 201，更新成功返回 200。保存 id、application_id、environment、en"},{"path":"/guides/web-apps/develop","title":"开发与配置","locale":"zh-CN","markdown_path":"/markdown/guides/web-apps/develop.md","sha256":"b6d587ac920caff8f8d0cde11efd2f20dd5f7a6da57b88442527b44e5508eadb","headings":["配置应用入口","按打开方式接入","准备内置制品","适配生命周期与业务界面","配置安全与登录","处理订阅付款与回跳"],"excerpt":"开发与配置 先确认应用可独立访问，再按选定方式接入 Console。本文使用平台公开协议，所有适配代码均在应用自己的仓库中实现。 <DocsWebAppSteps / 配置应用入口 进入“应用管理 → 应用发布信息”，填写以下内容并保存草稿。 字段 填写说明 --- --- 访问地址 应用自己的 HTTPS 业务入口，跳转和内置均须保留 打开方式 默认跳转；完成适配后选择隔离 iframe 或受信 qiankun 直挂 Manifest 地址 内置必填；与访问地址同 Origin，匿名可读的 HTTPS JSON 地址 跳转方式无需容器 SDK。选择内置后，保存会自动排队检查公开 Manifest 和资源摘要；页面显示结果，失败时保留草稿并可重新检查。 按打开方式接入 方式 应用需要实现 配置与运行结果 --- --- --- 跳转 独立网页、自有登录与业务路由 配置访问地址；客户在应用自己的页面使用 隔离 iframe 独立网页之外，再交付下方 Manifest、容器与生命周期 选择隔离 iframe；业务代码在应用自己的 Origin 内运行 受信 qiankun 直挂 复用内置制品与生命周期；API、会话和资源显式指向应用自己的 Origin 选择受信直挂；经独立审核并正式发布后，业务 DOM 直接挂载到 Console iframe 和直挂共用公开协议，但安全边界、审核条件与验收分别处理。第三方无需接入内部微应用 Registry，也不向 Console 提交业务代码或应用专属路由。 准备内置制品 下载公开 Manifest Schema、TypeScript 协议与容器 SDK。将两个 TypeScript 文件加入应用自己的构建，使用 qiankun@2.10.16。 assets 须完整列出实际运行制品，包括脚本、样式和容器。示例摘要是占位值，发布前按实际响应字节计算。路径必须为同 Origin 的绝对路径，不带参数或片段。使用不可变版本地址；字节变化后重新检查并发布。 在应用自己的 Origin 容器中调用 startThirdPartyContainer，传入本应用身份、环境、已登记宿主、Manifest 路径／摘要、挂载 ID 和 DOM 容器；参数类型以下载的 SDK 为准。应用身份与允许的宿主来源由应用自己的服务端配置提供。 适配生命周期与业务界面 生命周期 应用职责 --- --- bootstrap 初始化独立应用资源 mount 直接显示业务界面；已有会话时进入业务页 update 接收主题和语言变化，更新展示 unmount 清理 DOM、监听器、定时器及其他资源 生命周期返回 Promise。HTML 声明 UTF-8。使用 host.path 作为站内路径，使用 host.applicationOrigin 构造应用自己的"},{"path":"/guides/web-apps/","title":"网页应用概述","locale":"zh-CN","markdown_path":"/markdown/guides/web-apps/index.md","sha256":"ac4572ef6bded87fa7d9ca8e73ef41211dac0c36bb0091eaf10c627df65d2b31","headings":["选择打开方式","接入流程","按需接入其他能力"],"excerpt":"网页应用概述 将独立部署的 PC 网页应用接入 GoodVision，让客户从 Console 打开并使用。应用由开发者自行构建、部署和维护，无需修改 Console 或其他应用的代码。 <DocsWebAppSteps / 选择打开方式 方式 客户体验 适用条件 --- --- --- 跳转（默认） 在独立页面使用应用 已有 HTTPS 网页，配置访问地址即可 隔离 iframe 内置 在 Console 工作区使用应用 按公开容器协议适配；推荐的第三方内置方式 受信 qiankun 直挂 业务界面直接挂载到 Console 工作区 按公开生命周期适配；通过独立安全审核并获准正式发布 两种内置都保留独立访问地址，加载失败时可以重试或在新窗口打开。iframe 提供跨来源隔离；直挂代码与宿主共享页面权限，qiankun 的沙箱不构成第三方安全隔离。 三种方式的实现步骤见按打开方式接入。应用内置到 Console 与应用内嵌入平台商业页是两个方向；接入订阅时另须处理付款与回跳。 接入范围 当前面向 PC 浏览器，不要求移动端、小程序包或专用客户端。内置应用需适配公开的 Manifest、容器 SDK 和 qiankun 生命周期；普通网页仅填写 URL 后可使用跳转方式。 接入流程 1. 在开发者后台创建应用，默认从 Sandbox 开始。详见创建应用与开发测试。 2. 在“应用管理 → 应用发布信息”配置独立访问地址与打开方式。内置模式增加公开 Manifest。 3. 保存草稿，等待自动制品检查，再用真实 PC 浏览器完成开发测试。 4. 准备独立的 Production 配置，创建版本、提交审核，并显式发布获批版本。 保存、检查和审核各自有独立结果。新草稿不替换客户正在使用的正式版本。 按需接入其他能力 需求 文档 --- --- 用户登录与客户空间 认证与授权、用户与客户空间 安全、凭据和协作者 应用安全、应用管理 API 与事件 API 产品、事件接入 套餐、订阅与支付 第三方 SaaS 订阅与支付 应用展示、用户登录、API 权限和付费权益分别配置与核验。选择内置方式不会自动授予其他能力。"},{"path":"/guides/web-apps/publish","title":"审核与发布","locale":"zh-CN","markdown_path":"/markdown/guides/web-apps/publish.md","sha256":"fa770985edba227bee5642b90b464a3c4af205dd01cdf83ed9d8da68ab3d5923","headings":["准备上线版本","审核安全与使用范围","发布并核验","上线后的维护"],"excerpt":"审核与发布 正式客户使用已发布版本。完成开发测试后，创建 Production 版本并提交独立审核，获批后显式发布。 <DocsWebAppSteps / 准备上线版本 1. 在“开发接入 → Sandbox 与上线”准备独立的 Production 配置。 2. 核对应用资料、可用范围、访问地址和打开方式。内置制品须完成当前草稿的制品检查与真实 PC 测试。 3. 在“应用管理 → 版本管理与发布”创建版本草稿，填写版本号、变更说明和测试证据引用。 4. 显式提交上线审核。申请人不能自审；退回后修正配置并创建新版本。 配置版本的完整操作及协作者权限见应用管理。 审核安全与使用范围 方式 重点检查 --- --- 跳转 独立访问地址、登录、应用资料及发布范围 隔离 iframe 公开制品、精确宿主来源、消息校验、登录窗口及隔离边界 受信 qiankun 直挂 精确制品代码、依赖与供应链、共享宿主页面权限的风险及明确批准 直挂需要独立批准 制品检查只证明公开资源与登记内容一致。受信直挂须由独立平台审核人核查代码与供应链，并明确确认共享页面权限风险；自动检查通过不能代替批准。 发布版本、制品、应用与环境必须一致。更换制品或打开方式后，重新检查、测试并提交新版本。 发布并核验 审核通过后，显式发布获批版本。发布时平台重新核验当前权限、资源与已发布版本，成功后更新正式入口；批准本身不改变客户使用方式。 用目标客户身份从 Console 打开，确认显示的版本和打开方式正确，再核验已选业务能力。仅开放给指定客户的应用，无需扩大为公开分发。 新草稿和审核过程保留旧正式版本。操作结果未知时恢复原请求；版本冲突时先回读当前版本与正式状态，登录恢复后不自动提交或发布。 上线后的维护 在调用日志与质量排查问题。需要停用或退役时，按应用管理执行对应流程。密钥轮换与敏感操作见应用安全。"},{"path":"/guides/web-apps/test","title":"开发测试","locale":"zh-CN","markdown_path":"/markdown/guides/web-apps/test.md","sha256":"abf33e8094cfd91af26a9fad7fd916ea730774a8462f712372479f4e0a1b28f9","headings":["查看制品检查","完成 PC 测试安装","常见问题"],"excerpt":"开发测试 保存内置草稿后，先查看自动制品检查结果，再在测试安装中验证真实客户操作。 <DocsWebAppSteps / 查看制品检查 平台异步读取公开 Manifest 和资源，检查格式、地址限制与 SHA-256。检查不执行第三方脚本，也不证明浏览器挂载、登录或业务功能已通过。 状态 处理方式 --- --- 排队中／检查中 等待页面自动更新；不必重复保存 通过 用真实 PC 浏览器完成下方检查项 失败 按错误修正地址、Manifest 或资源摘要，再保存或重新检查 服务暂不可用 保留草稿，服务恢复后点击重新检查 已过期 回读当前草稿，按新的地址、模式和制品重新检查 修改访问地址、Manifest 或打开方式后，旧结果不能用于新草稿。检查失败或不可用时，现有正式版本继续服务客户。 完成 PC 测试安装 使用当前环境的测试账号与测试安装，不把 Sandbox 凭据、客户数据或批准结论复制到 Production。受信模式的 Sandbox 草稿不得直接运行在客户正式工作区。 检查项 预期结果 --- --- 首次打开与刷新 从 Console 进入实际业务页，刷新和深层路由正常 现有会话 已登录时直接进入业务，不重复展示宣传页或登录页 首次授权与失效 必要授权由一次明确交互打开登录窗口；取消、过期可恢复 明暗主题与语言 初次展示和上下文变化均正确，无宿主导航叠加 客户与环境切换 清除旧范围数据；错应用、错环境和无权限访问被拒绝 卸载与重开 清理资源；旧挂载消息无效；未保存内容有提示 加载失败 提示错误，可重试或在新窗口打开独立应用 套餐与业务能力 若接入商业化，另行测试套餐选择、购买及权益生效 付款成功／取消 使用支付服务商测试模式；内置返回原 Console 应用订阅页，独立访问返回独立页；回读原订单／订阅，不仅检查 URL 付款窗口异常 验证拦截后继续原付款、手动关闭、窗口通信中断与延迟到账；保持原订单，不重建购买 付款回执安全 拒绝伪造 Origin／Window／关联值、错应用／环境及卸载后的回执；回执不能授予权益 iframe 与受信直挂分别验收。准备上线版本时记录测试环境、制品版本、测试结果和可追溯证据引用。 常见问题 现象 检查方向 --- --- iframe 被拒绝 容器响应的 CSP frame-ancestors、X-Frame-Options 和 Console Origin 登记 资源检查失败 匿名可读性、同 Origin、完整 assets 清单与实际字节摘要 API 请求到了 Console 是否使用 host.applicationOrigin 构造请求地址 检查通过仍打不开 浏览器生命周期、握手、容器响应及真实登录流程；静态检查不能代替这些测试 选择直挂仍不能启动 Production、独立审核、明确风险批准和显式发布是否"},{"path":"/guides/webhooks","title":"接收 Webhook","locale":"zh-CN","markdown_path":"/markdown/guides/webhooks.md","sha256":"a34689e9b6d3d0d0e79bb9d56cab7e26007a82d9dd78acde3cec7ed405d28edc","headings":["接入步骤","保存配置失败后的恢复","验证接收地址","在控制台调试完整事件","完整示例：订阅已激活","请求头与签名","接收端校验顺序","明文与加密 Body","本地复算签名","去重与乱序","签名密钥与轮换","失败与恢复","同步回调可用性","从控制台安全取得签名密钥","成员事件与登录用户关联"],"excerpt":"接收 Webhook 首次接入推荐长连接 Node.js 示例：无需公网接收地址或 Webhook 加密配置。以下步骤适用于主动选择的 HTTPS Webhook。 Webhook 用于接收订阅激活、套餐变更和取消生效等事件通知。GoodVision 将事件发送到应用配置的 HTTPS 接收地址，接收端验证并持久化事件后返回成功，再异步处理业务。 事件采用“至少一次”投递，同一事件可能重复或乱序到达。 HTTP 2xx 是接收 ACK，接收端必须在返回前持久化事件。响应丢失或消费者崩溃会触发重试，接收端按 event_id 业务去重。自动重试耗尽后，在控制台查看失败投递并申请恢复，恢复仍使用原 event_id。 接入步骤 1. 配置推送：进入当前应用 → 事件与 Webhook → 添加事件，填写公网 HTTPS 回调地址，测试连接后选择事件并保存。平台自动生成签名密钥和 Token，并启用推送。 2. 配置接收端：打开「接收端配置」，主动查看 HMAC Secret 和 Verification Token，将两项保存到服务端。接收端按下文处理连接校验、验签与可靠应答。 3. 联调：在 Sandbox 的「事件调试」中选择已订阅事件并发送，进入「投递日志」确认接收端返回 2xx。入队不表示接收成功。 配置 必填性 如何处理 --- --- --- 回调地址 🔴 必填 开发者填写；公网 HTTPS，可响应连接校验 订阅事件 🔴 必填 至少选择一个，按业务需要添加 HMAC Secret、Verification Token 平台生成 无需填写或自定义；查看后保存到接收端 Encrypt Key 可选 默认不加密正文；仅启用消息加密时配置接收端解密 同步回调 可选 事件推送无需配置；同步请求与响应使用独立 HTTPS 配置 多应用分别配置回调地址和事件；可以使用同一接收服务，但每个应用使用各自的凭据。接收端按应用隔离验签、消息与业务处理。事件清单见事件目录。 每个应用仅支持一个未撤销的 Webhook 接收地址。异步事件 event_types[] 和同步回调 callback_types[] 分别配置，修改其中一项时保留另一项的完整配置。 商业订阅、API 调用授权和 Webhook Subscription 分别管理。取消商业订阅不会撤销 API 授权或停止 Webhook。 保存配置失败后的恢复 事件、接收地址或安全配置保存结果未知时，配置窗口保留原内容、版本和操作编号，并暂停编辑和关闭窗口。使用“恢复原请求”确认结果，不重新创建一次保存或轮换。 恢复时若要求登录或身份验证，完成后回到同一应用，再明确恢复原请求。验证不会自动提交，临时显示的凭据会清除。若页面明确提示凭据无法再次交付，读取当前凭据版本，核对后重新确认凭据操作；不要索取旧明文。 若页面"},{"path":"/","title":"TOKEN 大模型开放平台","locale":"zh-CN","markdown_path":"/markdown/index.md","sha256":"56cabc9c10c1e83e0b1c9ad98daa71adf72d19ceebd5bd049fdd7eb5f99ade26","headings":["开始接入","开放能力与开发工具","开发者后台","工具与支持"],"excerpt":"TOKEN 大模型开放平台 使用版本化 API、OAuth 2.0 和签名 Webhook，构建专属 AI 应用与工作平台。 开始接入 创建应用、配置 OAuth 用户登录，按需增加 API、模型调用和事件接收。沿接入指南完成开发与测试，再创建版本并发布。 快速开始 开发文档 开放能力与开发工具 了解模型 API、身份与权限、订单支付、订阅管理与签名 Webhook，使用接入模板、SDK 和 GoodVision CLI 连接你的业务。 API 产品 GoodVision CLI 事件接收 开发者后台 打开开发者后台 工具与支持 开发教程与代码示例 技术支持"},{"path":"/reference/api-products","title":"API 产品","locale":"zh-CN","markdown_path":"/markdown/reference/api-products.md","sha256":"18dfb6ac7c84274c7bf4ab9bc39c12fc1e0522e9216773e110d7b8612e89ff35","headings":["基本概念","申请 API 权限","查看 Scope 对应的 API、事件和资源","获取调用配置","接入指南","共享接口与待开放能力","能力目录","调用要求","产品状态与环境"],"excerpt":"API 产品 API 产品是一组相关的开放接口。开通产品权限后，应用可以按指定版本调用接口。每个产品提供 API 地址（Base URL）、目标 API（Audience）、权限（Scope）、数据格式（Schema）、调用配额和支持说明。 在开发者后台进入应用的 API 与权限 页面，可以查看可用产品并申请权限。产品名称和说明支持中文、英文；Scope、Audience 和接口路径使用固定标识。 基本概念 名称 说明 示例 --- --- --- 应用（Application） 产品在某个环境中的接入配置 acme-workflow 的 Sandbox 应用 API 产品 可申请的一组接口，包含版本、地址和调用要求 OEM Core API API 调用权限 当前调用身份可以使用的操作、数据范围和配额 应用身份的账单只读权限 创建应用后，需要单独申请 API 调用权限。每次请求还会校验访问令牌（Token）、企业和资源权限。 同一应用支持应用身份（service/confidential）和用户身份（user/public + PKCE）。两种身份分别配置 OAuth Client 和 API 调用授权，权限状态及撤销操作相互独立。 申请 API 权限 1. 登录开发者后台，打开目标应用的 API 与权限 页面。 2. 根据调用场景选择 应用身份权限 或 用户身份权限。 3. 选择 API 产品，查看权限说明、版本和环境。 4. 点击 开通权限，选择所需 Scope 并提交。自动校验成功后，权限立即启用。 权限状态的含义如下： 状态 含义 下一步 --- --- --- 可申请 当前 Application 尚未订阅该 API Product 点击“开通权限”，选择一个或多个公开 Scope 并提交申请 待配置 历史申请尚未完成实际权限配置 核对后点击“完成配置并启用” 已启用 Scope 已批准，可在当前环境使用 按产品提供的 Audience 和接口路径调用 已暂停 / 已撤销 当前 API 调用授权已暂停或撤销 联系产品支持人员处理 未包含 已开通该产品，但未获批此 Scope 当前后台不支持追加 Scope，请通过支持渠道申请新的产品授权 申请绑定当前应用、环境、调用身份和 API 产品，可重试但不会重复创建。已有申请时，页面显示当前状态和可执行操作。 平台自动将本次申请的 Scope 和 Audience 绑定到当前身份的 OAuth Client。状态为 已绑定 时可以开始联调；显示 配置漂移 或 暂不可核验 时，请先核对配置或稍后重试。 查看 Scope 对应的 API、事件和资源 1. 在“API 与权限”中按身份、产品、状态或敏感级别筛选 Scope。 2. 查看每项权限的关联 API、关联事件和资源授权范围，选择实际需要的最小集合。批量"},{"path":"/reference/environments","title":"环境与地址","locale":"zh-CN","markdown_path":"/markdown/reference/environments.md","sha256":"d31b4d1751533a8aa99b1a5c601f96577843bde32ae2e4afec330610d8c2ff41","headings":["两层环境模型","部署环境与可用性","获取接入地址","Identity Issuer","从 Sandbox 进入 Production","环境隔离检查"],"excerpt":"环境与地址 本文介绍 Sandbox 和 Production 的使用范围，以及文档、身份认证、API 和 Webhook 的地址配置。应用、凭证、Audience、Scope、数据、Webhook 和配额按应用环境隔离。 两层环境模型 环境类型 可选值 说明 --- --- --- 部署环境 development、test-us、production 开发者文档、后台、身份认证和 API 的接入地址与可用性 Application 环境 sandbox、production Application、两类身份的 OAuth Client 与 API 调用权限、Webhook、配额和验收生命周期 应用的 environment 仅支持 sandbox 和 production。sandbox 应用可在 Development 或 test-us 联调；development、test-us 和发布参数不能填入该字段。 部署环境与可用性 部署环境 Application 用途 地址来源 状态 --- --- --- --- development Sandbox 开发与联调 当前环境提供的一组接入地址 用于开发联调，不承载 Production Application 或生产数据 test-us Sandbox 受邀实机验收 受邀测试提供的一组接入地址 仅限受邀测试，不能作为通用公开入口 production 独立 Production Application 正式接入提供的一组地址 尚未确定业务发布目标，当前为 disabled 获取接入地址 配置项 用途 获取方式 --- --- --- GOODVISION_DEVELOPER_DOCS_ORIGIN 开发者文档；同源 /console/ 为当前环境开发者后台 当前环境接入配置 GOODVISION_IDENTITY_ISSUER 完整 OAuth/OIDC Issuer 当前环境身份认证配置 GOODVISION_API_BASE 当前应用已开通 API 产品的 Base URL API 产品调用配置 GOODVISION_WEBHOOK_ORIGIN 当前应用的 Webhook 地址范围 Webhook 接入配置 使用同一部署环境提供的四项配置，不能根据域名后缀推导或混用其他环境。 GOODVISION_DEVELOPER_DOCS_ORIGIN 用于文档和控制台，不能作为 API Base、OIDC Issuer 或 Webhook Origin。调用 API 时，使用当前应用产品配置中的 GOODVISION_API_BASE、版本化路径、Audience 和 Scope。地址可达后，仍需检查对应接口权限。 请使用当前环境提供的接入配置，无需自行配置平台的网关、证书或安全防护。 Identity "},{"path":"/reference/errors","title":"错误处理","locale":"zh-CN","markdown_path":"/markdown/reference/errors.md","sha256":"dc1c0afb2534055cd7856e9085a461eb15b341cc221acf911be19128278a1256","headings":["常见响应","开发者后台恢复","建议保留的诊断信息","有效 Token 返回 403","登录后的空间解析失败"],"excerpt":"错误处理 API 调用失败时，GoodVision 返回 HTTP 状态码和 Problem Details 错误信息。请根据状态码和错误码处理失败；detail 用于补充说明，不应用于程序判断。 常见响应 状态码 含义 调用方处理 --- --- --- 400 请求格式或必填字段错误 修正输入，不要原样重试 401 缺少认证或 Token 无效 获取 Issuer/Audience 正确的新 Token 403 已认证但无权访问 检查 Scope、Organization、ProductAccess 和资源归属 404 资源不存在或对当前调用方不可见 核对 ID 和授权租户上下文 409 状态、版本或幂等冲突 读取最新状态后再决策 422 业务规则校验失败 根据错误码修正业务输入 429 超出配额 遵守 Retry-After 并退避 5xx 服务端暂时不可用 仅按接口说明重试临时故障 开发者后台恢复 后台登录过期、近期验证不足和权限撤销需要不同处理。按页面的错误提示恢复原范围，不要通过切换账号或企业绕过拒绝。 情况 处理方式 --- --- 401，登录已过期 在原页重新登录；同一账号、同一有效范围可保留普通草稿，Secret 和敏感确认清除 403，明确提示需要近期身份验证 完成敏感操作验证，回到原页核对并再次明确提交 403，企业或应用权限撤销 停止原范围操作并清除旧资料；联系当前所有者或管理员核对权限 409，版本或状态冲突 读取最新状态，再核对操作；不要继续提交旧配置 超时或写入结果未知 保留原内容和操作编号，使用页面的“恢复原请求”或“重试原请求”；不要另建一次操作 依赖暂不可用 保留已验证登录并重新读取；故障不代表没有企业或没有权限 验证成功不会自动重放创建、保存、删除、付款、回复或转交。换账号、退出或原范围失效会清除旧草稿。普通 API 的 401 仍按上表获取正确 Token；后台 Session 恢复不能替代业务 API 授权。 原未知请求恢复时若遇到登录过期或近期验证要求，先完成验证，再明确恢复同一请求。原内容、版本和操作编号保持；验证成功不表示此前写入失败。页面明确指出输入无效时，修正对应字段后再提交新请求。 需要协助时，在当前应用提交技术反馈，附上安全诊断信息。平台客服只有在明确转交后才能参与。 建议保留的诊断信息 - request_id 或 correlation_id； - operation_id、delivery_id 或 event_id； - HTTP 状态码和机器错误码； - Endpoint 名称和 UTC 时间； - Application ID 和环境。 日志和支持请求中不得包含 Access Token、Client Secret、Webhook Secret、私钥或完整客户 Payload。 有效 To"},{"path":"/reference/events","title":"事件目录","locale":"zh-CN","markdown_path":"/markdown/reference/events.md","sha256":"69ea121ed2dfcbf7c4360cb068080d5f2445ce8c9d98f5fc614e180a2f42d4c4","headings":["订阅事件结构","订阅 data 的必需字段","接入范围与状态相关字段","完整订阅事件表","事件分类","接收端要求","有效权限变更","产品访问已开通","用户与事件的关联键"],"excerpt":"事件目录 本文列出 GoodVision 事件类型、触发时机和字段说明。事件使用带版本的名称，通过已批准且已启用的 Webhook 订阅投递。 接收端的签名验证、Token 校验、去重和应答方式，请参见接收 Webhook。实际字段、枚举和权限以当前应用 API 产品提供的事件 Schema 为准。 订阅事件结构 下面是订阅激活的完整业务事件，包含全部必需字段。HTTP 明文投递还会增加顶层 verification_token，校验并移除后才得到这里的信封；加密投递先验签、解密和核验 Token。 所有 ID、套餐和原因码都是合成值，producer: \"opaque\" 是不透明来源的展示占位，实际来源枚举以已签发 Schema 为准。不要按占位来源或示例原因码硬编码。可下载 JSON，或查看含 Header、Token 和可复算签名的完整 HTTP 请求。 以下顶层字段在订阅事件中全部必需： 字段 类型 含义与校验 --- --- --- event_id string 稳定业务事件 ID，用于持久化和去重 event_type string 下表列出的完整、带版本事件名；与 Header 一致 schema_version string 当前为 \"1\"，不是整数 1 occurred_at RFC3339 string 事件发生时间；不是用于验签的投递时间戳 producer string 不透明来源，按已签发 Schema 校验 tenant_id string 购买方客户 Organization，等于 data.organization_id；不是应用所属企业 resource_id string SaaS 订阅 ID，等于 data.id resource_version integer ≥ 1 订阅版本，与 data.resource_version 一致 correlation_id string 关联排障，不用作去重键 data object 当前订阅摘要，见下面的字段定义 按当前事件 Schema 验证字段。开放对象可忽略受支持主版本内新增的字段；设置 additionalProperties: false 的封闭对象需拒绝或隔离未知字段。不支持的主版本也需拒绝或隔离，避免按旧格式解析。 订阅 data 的必需字段 所有 19 种订阅事件共用此摘要；不能只发送或只按 {id, status} 处理。字段组合需与事件及当前状态一致。 字段 类型 含义 --- --- --- id string 订阅 ID，与顶层 resource_id 一致 organization_id string 购买方客户 Organization，与顶层 tenant_id 一致 party_id string 商业客户档案标识，不是用户或 Membershi"},{"path":"/reference/saas-billing","title":"SaaS 账务参考","locale":"zh-CN","markdown_path":"/markdown/reference/saas-billing.md","sha256":"6ad7854168b9576b86770c7d7333041daae919e8577e8044d908fc5b332d3ff4","headings":["当前能力状态","资源与使用方式","公共字段","调用要求","发布后预期的 API Product 组成","安全返回字段"],"excerpt":"SaaS 账务参考 本文介绍月付、年付 SaaS 接入中的账务资源、字段和处理规则。调用时，请使用当前应用 API 产品提供的接口路径、Schema 和 Scope。 当前能力状态 能力 状态 --- --- 固定月付/年付 SaaS 套餐规则 已确定 Application、API 调用权限、Webhook 申请 可通过开发者控制台申请 Commerce Checkout Sandbox API Product 已实现，可按 Application 签发后调用 Production API Product 尚未开放 储值余额、按量和超额扣费 当前商业方案不支持 资源与使用方式 资源 管理入口或方式 接入方用法 --- --- --- Application、API 产品、API 调用权限、Webhook 订阅 开发者控制台 申请接入并获取对应版本的调用配置 Product/Plan/PriceVersion、Order、SaaSSubscription 客户工作区 展示和操作商业资源；第三方按已授权接口查询必要状态 支付、退款和支付状态 客户工作区 完成付款和退款；第三方按已授权接口查询脱敏状态 ProductAccess、Entitlement 产品权限快照尚未开放 按已发布合同处理事件；不使用内部回查接口 支付/退款证据 已授权的支付状态接口 查询脱敏状态和证据引用 卡片或钱包凭证 支付服务商 只通过 Hosted Checkout/Tokenization 处理 公共字段 以下字段只适用于未来签发的服务端 API/Event 契约，不是客户工作区跳转参数。当前商业页面入口不接受第三方拼接的业务 Query 参数。 字段 约束 --- --- application_code 由 Application 和服务端会话确定，浏览器不能覆盖 plan_code / plan_version 指向已批准套餐和不可变版本 price_version_ref 指向不可变价格快照，不由浏览器生成 billing_interval 仅允许 month 或 year amount_scaled / amount_scale 整数金额和精度；由服务端价格快照产生 currency 大写 ISO 4217 代码；由套餐/订单确定 operation_id 不可猜测的异步操作标识，不是支付凭证 resource_version 同一资源单调递增，用于事件乱序保护 金额按 amount_scaled × 10^-amount_scale 解释。例如 2900 和 2 表示 29.00。不要使用浮点数计算或传输金额。 调用要求 1. 浏览器不持有服务端 OAuth Client Secret、Webhook Secret 或支付凭证。 2. 第三方浏览器只打开平台客户工作区，不"},{"path":"/reference/user-context","title":"用户与客户空间","locale":"zh-CN","markdown_path":"/markdown/reference/user-context.md","sha256":"fe4a9db92c17bdb9eb131efa6155b71e275f364d67552d368efc9e342258a336","headings":["请求","响应","open_id 与 union_id","故障恢复"],"excerpt":"用户与客户空间 登录后读取 open_id、union_id 和客户空间。平台自动生成标识和默认个人空间，无需配置用户组或额外申请 API Subscription。 请求 POST ${GOODVISION_API_BASE}/open-platform/v1/user-context:resolve 应用服务端使用当前应用的用户 Access Token 调用，首次请求发送 {}： 参数 位置 必填性 说明 --- --- --- --- Authorization Header 🔴 必填 Bearer <USER_ACCESS_TOKEN；当前应用的用户 Token，不能使用应用身份 Token Content-Type Header 🔴 必填 application/json JSON 请求体 Body 🔴 必填 首次进入发送 {}，无需填写用户或空间 ID organization_id Body 可选 省略时自动准备或复用个人空间；只在用户主动选择已有客户空间时传入，平台重新核验成员关系 选择已有空间时发送 {\"organization_id\":\"<SELECTED_CUSTOMER_SPACE_UUID\"}。不传应用、用户或权限字段，也不添加组织 Header 或 Query 参数。 响应 下表均为平台返回的字段，不是开发者需要填写的请求参数。 字段 用途 --- --- application_id、environment 核对是否属于当前应用及环境 user.open_id 当前应用内的用户关联；可以作为应用自己的用户键 user.union_id 同开发者、同环境多个应用中的同一用户关联 space.organization_id 当前客户空间；用于后续业务范围，用户不用填写 space.membership_id 当前用户在该空间的成员关联 space.display_name 空间展示名称；不能按名称判断权限 space.kind personal 为默认个人入口；selected 表示显式选择，不是团队分类 resolved_at、expires_at 解析时间和失效时间，最长五分钟 下载响应 JSON Schema。服务端核对响应的应用、环境、当前空间及有效时间，按业务需要重新读取。响应为 no-store；普通输出不包含内部身份 ID 或任何 Secret。 open_id 与 union_id 平台自动生成 OpenID（open_id）与 UnionID（union_id），从响应的 user 中读取： 同一用户进入 open_id union_id --- --- --- 同开发者、同环境的应用 A 与 B 不同 相同 同一应用，切换客户空间 不变 不变 不同开发者或环境 隔离 隔离 应用转移后不自动合并历史用户。用"},{"path":"/support","title":"支持与问题诊断","locale":"zh-CN","markdown_path":"/markdown/support.md","sha256":"47784fc3936ecfe5bc1b49c2a4b1ea2d09d79e77f606ef754c3b3565dd9dec3e","headings":["提交应用技术反馈","转交平台客服","回复与跟踪状态","问题描述","敏感信息","提交前检查"],"excerpt":"支持与问题诊断 遇到接入或调用问题时，可在当前应用“开发接入 → 支持与反馈”提交技术反馈、关联诊断、查看时间线并追加回复。需要平台客服参与时，再明确转交；旧反馈不会自动公开。商业、付款和客户支持按对应产品渠道处理。 提交应用技术反馈 1. 核对当前应用和环境，填写简短标题及纯文本问题说明。 2. 可从调用日志或最近七天的 Webhook 投递记录选择诊断引用。引用只带必要摘要，不提交请求或客户正文。 3. 明确提交后，保存工单编号；打开时间线查看消息和状态，需要正文时再主动读取。 正文不得包含凭据、敏感请求头、JWT 或 HTML。工单目录、正文和操作分别检查权限：能看到编号不表示可以读取正文或回复。没有所需权限时联系当前应用负责人。 转交平台客服 1. 在当前工单点击“转交平台客服”，阅读确认信息。 2. 要求验证时，按敏感操作验证完成最近 5 分钟内的身份验证，返回后明确确认转交。 3. 在时间线核对转交结果；平台回复和状态随后在原应用工单中回读。 转交对象由平台固定，不需要填写客服账号或目标企业。未转交的应用反馈保持私有；关闭的工单不能直接转交。成功转交不表示已经回复或解决，也不保证立即受理。 验证、取消、重新读取或选择日志都不会自动转交、创建工单或重发回复。结果未知时，当前页面锁定编辑和返回列表，保留原内容、工单版本和操作编号。即使恢复时再次要求登录或验证，也不能据此认定首次提交没有执行。同一用户完成验证后，先重新检查当前应用权限及工单，再点击“恢复原请求”；版本冲突时读取最新时间线，核对后重新确认。登录失效时会收起已读取的正文；恢复后如需查看，请再次主动读取。切换用户、应用或企业会清除旧范围内容。 回复与跟踪状态 在工单时间线追加回复或按当前可执行操作更新状态。open、pending、resolved、closed 分别表示打开、等待、已解决、关闭；以当前工单状态为准，不把配置或付款成功当作问题解决。 情况 处理方式 --- --- 需要近期身份验证 完成验证后返回原工单，明确提交；不自动重放 创建、回复、状态更新或转交结果未知 恢复原请求，保持原内容和操作编号 工单版本变化 读取最新时间线后核对并重新确认 无权读取正文或已撤权 停止旧范围操作，联系应用负责人 查询暂不可用 重试读取，不显示为无反馈或已解决 问题描述 - Application ID 和环境； - request_id 或 correlation_id； - 相关 operation_id、delivery_id 或 event_id； - UTC 时间和受影响的 Endpoint / Event Type； - HTTP 状态码和机器错误码； - 最小复现步骤、期望结果和实际结果。 敏感信息 提交问题前，请移除以下信息： - Client Secret、私钥、Access T"}]}