调用诊断环境与状态
GoodVision 开放平台

简体中文

English

简体中文

English

外观

开发者后台

经营管理 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。环境明确选择 sandbox|production，内部身份与绑定由平台派生。

调用者需要有效的企业成员关系、应用管理关系，以及对应的公司、商业资料、购买或销售权限。应用所有者使用已有经营权限，其他成员需要被明确分配对应职责。

Scope、能力开通和本人授权需分别满足，不能代替业务权限。此产品仅支持用户 Token。查看管理员销售日志还需要线索和机会管理职责。

产品发布后会出现在目录中，无需手动注册。每个应用仍须配置实际所需的 API 权限，并取得用户本人授权。

方法与 Scope ​

公司与购买记录 ​

方法与路径Scope
GET /open-platform/v1/appmarket/companies:contextoperations.company.read
GET /open-platform/v1/appmarket/companiesoperations.company.read
GET /open-platform/v1/appmarket/companies/{company_id}operations.company.read
POST /open-platform/v1/appmarket/companiesoperations.company.manage
PATCH /open-platform/v1/appmarket/companies/{company_id}operations.company.manage
POST /open-platform/v1/appmarket/companies/{company_id}/{transition}operations.company.manage
GET /open-platform/v1/appmarket/companies/{company_id}/commercial-partiesoperations.company.commercial.read
GET /open-platform/v1/appmarket/companies/{company_id}/commercial-linkoperations.company.commercial.read
POST /open-platform/v1/appmarket/companies/{company_id}/commercial-linkoperations.company.commercial.manage
POST /open-platform/v1/appmarket/companies/{company_id}/commercial-link/unlinkoperations.company.commercial.manage
GET /open-platform/v1/appmarket/companies/{company_id}/purchasesoperations.purchase.read

销售线索 ​

方法与路径Scope
GET /open-platform/v1/appmarket/sales:contextoperations.lead.read
GET /open-platform/v1/appmarket/leadsoperations.lead.read
GET /open-platform/v1/appmarket/leads/{sales_id}operations.lead.read
GET /open-platform/v1/appmarket/leads/{sales_id}/followupsoperations.lead.read
POST /open-platform/v1/appmarket/leadsoperations.lead.manage
PATCH /open-platform/v1/appmarket/leads/{sales_id}operations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/assignoperations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/reopenoperations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/duplicateoperations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/followupoperations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/qualifyoperations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/disqualifyoperations.lead.manage
POST /open-platform/v1/appmarket/leads/{sales_id}/convertoperations.lead.manage

销售机会 ​

方法与路径Scope
GET /open-platform/v1/appmarket/opportunitiesoperations.opportunity.read
GET /open-platform/v1/appmarket/opportunities/{sales_id}operations.opportunity.read
PATCH /open-platform/v1/appmarket/opportunities/{sales_id}operations.opportunity.manage
POST /open-platform/v1/appmarket/opportunities/{sales_id}/assignoperations.opportunity.manage
POST /open-platform/v1/appmarket/opportunities/{sales_id}/stageoperations.opportunity.manage
POST /open-platform/v1/appmarket/opportunities/{sales_id}/reopenoperations.opportunity.manage

销售报告与日志 ​

方法与路径Scope
GET /open-platform/v1/appmarket/sales-reportoperations.sales.report.read
GET /open-platform/v1/appmarket/sales-auditsoperations.sales.audit.read

Webhook 投递记录 ​

方法与路径Scope
GET /open-platform/v1/appmarket/webhook-deliveriesoperations.event.read

客户人员与席位 ​

方法与路径Scope
GET /open-platform/v1/appmarket/companies/{company_id}/usersoperations.user.read
PUT /open-platform/v1/appmarket/companies/{company_id}/users/{membership_id}/assignmentoperations.user.assign

订阅使用 ​

方法与路径Scope
GET /open-platform/v1/appmarket/subscription-usage:contextoperations.usage.read
GET /open-platform/v1/appmarket/subscription-usageoperations.usage.read
POST /open-platform/v1/appmarket/subscription-usageoperations.usage.record

经营任务 ​

方法与路径Scope
GET /open-platform/v1/appmarket/tasksoperations.opportunity.read
GET /open-platform/v1/appmarket/tasks/{sales_id}operations.opportunity.read
GET /open-platform/v1/appmarket/tasks/{sales_id}/historyoperations.opportunity.read
POST /open-platform/v1/appmarket/tasksoperations.opportunity.manage
PATCH /open-platform/v1/appmarket/tasks/{sales_id}operations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/assignoperations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/startoperations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/submitoperations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/reviewoperations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/returnoperations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/canceloperations.opportunity.manage
POST /open-platform/v1/appmarket/tasks/{sales_id}/reopenoperations.opportunity.manage

正式报价 ​

方法与路径Scope
GET /open-platform/v1/appmarket/quotes:contextoperations.opportunity.read
GET /open-platform/v1/appmarket/quotes:optionsoperations.opportunity.read
GET /open-platform/v1/appmarket/quotesoperations.opportunity.read
POST /open-platform/v1/appmarket/quotesoperations.opportunity.manage
GET /open-platform/v1/appmarket/quotes/{sales_id}operations.opportunity.read
PATCH /open-platform/v1/appmarket/quotes/{sales_id}operations.opportunity.manage
GET /open-platform/v1/appmarket/quotes/{sales_id}/historyoperations.opportunity.read
POST /open-platform/v1/appmarket/quotes/{sales_id}/submitoperations.opportunity.manage
POST /open-platform/v1/appmarket/quotes/{sales_id}/approveoperations.opportunity.manage
POST /open-platform/v1/appmarket/quotes/{sales_id}/returnoperations.opportunity.manage
POST /open-platform/v1/appmarket/quotes/{sales_id}/sendoperations.opportunity.manage
POST /open-platform/v1/appmarket/quotes/{sales_id}/withdrawoperations.opportunity.manage
POST /open-platform/v1/appmarket/quotes/{sales_id}/reviseoperations.opportunity.manage
POST /open-platform/v1/appmarket/quotes/{sales_id}/expireoperations.opportunity.manage

写入与重试要求 ​

  • manage Scope 不包含读取 Scope，请分别申请。转化线索还需要机会管理职责。
  • 使用 stage 标记机会赢单或丢单，这只记录销售结果。付款和收入需单独查询。
  • 公司 {transition} 仅支持 archive 和 restore，其他值会被拒绝。
  • 普通写请求（包括 PATCH）携带原 Idempotency-Key，并按接口要求提交当前资源版本和原因。
  • 订阅使用上报通过正文的 event_id 去重，无需额外请求键或资源版本。

网络中断或 503 后，保留原请求键、正文和版本；使用上报保留原事件编号和正文。收到 409 时先核对原记录，再决定下一步，不能自动更换事件编号或版本重试。

查询与统计 ​

创建正式报价 ​

打开「客户经营 → 正式报价」。调用者需要机会查看／管理、公司查看和商业资料查看权限。

创建或编辑时，提交当前机会及版本、公司、销售方案及版本、套餐、数量（1～1000000）、有效期、名称、resource_version 和原因。使用 quotes:options 查询可选方案时，提供 opportunity_id、opportunity_version 和 company_id。

单价、金额、税务规则和完整条款由已发布的固定价方案生成。请求不接受自定义价格、折扣或条款。

报价按 draft → review_pending → approved → sent → accepted/declined 流转，也可进入 withdrawn/expired。

操作说明
submit提交审核
approve审核通过，需提供 approval_evidence_ref
return退回草稿
send允许客户通过客户报价 API查看并决定，不发送邮件
revise对已发送、拒绝、撤回或到期报价创建新修订，清除原审核与发送信息

草稿可编辑，已接受报价不可改写。到期后无法发送或接受新决定，即使尚未执行 expire。客户需本人接受或拒绝；决定仅记录该版本的结果，订单、付款和产品开通另行办理。

结果不明时，使用原 Idempotency-Key、正文和版本恢复，成功后 GET 当前报价。收到 409 时重新读取并确认新请求。

报价目录支持 search/status/limit/cursor，历史支持 limit/cursor，均按编号升序。游标仅用于原范围和父报价。历史保留每次动作的完整报价快照、操作者、原因、修订和审核证据；新草稿不会覆盖已发送条款。

管理经营任务 ​

打开「客户经营 → 经营任务」，需启用线索与机会管理能力，并具有机会查看／管理职责。

创建时提交当前机会 opportunity_id、source_version、任务名称、工作说明、负责人业务引用、UTC 日期 due_date、resource_version: 0 和原因。负责人引用仅记录业务负责人，不绑定平台成员或授予权限。

任务用于记录该机会的经营工作。订单、付款、开通、权益和支持操作需分别办理。

任务状态按 open → working → review_pending → closed 流转：

操作说明
start开始处理
submit提交处理证据 evidence_ref
review复核并关闭
return退回处理中
cancel取消尚未关闭的任务
reopen重开已关闭或取消的任务

仅待处理或处理中任务允许编辑和分派。每次操作提供当前 resource_version、原因和原 Idempotency-Key。收到 409 时，重新读取任务或来源并确认。收到 503 时，使用原正文、版本和键恢复，再 GET 当前任务；恢复回执可能对应较早的状态。

任务目录支持 search、status、limit（1～100，默认 50）和 cursor，按任务编号升序。处理历史使用 limit 和 cursor，按记录编号升序，包含动作、任务版本、操作者引用、原因、证据引用和时间。

保留原筛选，并原样使用游标。游标绑定原应用、产品、环境和父任务，不能解析或跨任务复用。对象不存在或无权时，显示当前范围的错误。此处仅提供机会经营任务及其历史。

查询订阅使用 ​

打开「经营分析 → 订阅使用」，使用当前登录身份和客户经营能力。应用负责人可查看和上报本应用使用记录，协作者需相应的独立职责。接口不提供客户成员或财务资料。

参数或字段必填性说明
from、to🔴 必填RFC3339，含起点、不含终点，最多 366 天
subscription_id、customer_organization_id、metric、status可选省略时不按对应字段筛选
limit可选1～100，省略时 50
offset可选0～1000000，省略时 0
summary、metrics、trend平台返回覆盖全部匹配事件；UTC 每日趋势仅含有使用的日期

也可在「交易 → 购买」、公司购买记录的订阅行或订单详情中点击「查看使用记录」。区块展示对应订阅的统计和明细，无需复制编号。默认查询最近 30 天，可调整日期、客户、指标和结果；订阅编号保持固定。暂停或取消的订阅仍可查询已接收历史。

使用权限单独检查。查询失败时保留原购买或订单页面；403 会清除使用结果，点击「重新核验使用访问」后再查询。刷新原购买或订单会收起使用区块，一次性订单不提供该入口。

查看本月统计 ​

在「经营首页 → 本月订阅使用」点击「读取本月使用统计」。通过使用权限检查后，显示 UTC 本月第一天至今天（含今天）的事件、结果、客户／订阅数、产品上报使用者和每日趋势。

数量按指标和单位分别展示，使用者引用不能用于计算已授权成员数。汇总覆盖整个周期；自建后台可使用 limit=1&offset=0 获取 summary、metrics 和 trend，无需遍历所有事件页。

「刷新本月统计」会重新检查访问权限，并更新到当前 UTC 月份。收到 503 后，点击「重试原统计周期」保持原日期，即使已经跨月。

401/403 会清除结果并停止查询，需点击「重新核验使用访问」恢复。收起区块或切换应用、企业、环境、权限、语言时清除结果。使用查询失败不影响销售概况；「查看全部使用记录」可进入日期与条件筛选页。统计仅描述使用情况，费用、余额和实收需单独查询。

上报使用记录 ​

提交原 event_id、客户企业与订阅编号、occurred_at、metric、unit、实际整数 quantity、status（succeeded|failed|cancelled）和 user_reference。

user_reference 可为空，或使用本产品内由字母、数字、下划线、连字符组成的匿名引用。不要传邮箱、姓名、Token 或正文；该引用不证明平台成员身份。测量了耗时才提交 duration_ms。

平台检查卖方及客户订阅，并保存对应套餐、价格和周期，请求不能覆盖这些信息。首次上报的事件需属于当前可用订阅周期，超周期迟到事件返回 409，暂不支持历史修正。同一事件可在续订或取消后恢复原回执，修改原内容则返回 409。event_id 已提供幂等性，无需资源版本或额外请求键。

数量使用精确整数字符串，按 metric + unit 分组。请勿转成 JavaScript Number、合并不同单位，或将数量作为金额和 Token 余额。上报记录不会直接产生扣费、余额或用户授权。

查询遇到 503 时保持原筛选；上报遇到 503 时重传原事件编号和正文。收到 403 后清除旧记录。

查询客户人员与分配席位 ​

公司需与客户企业有效关联，且客户已明确授权本产品。客户企业所有者或管理员可授权服务商查看人员名称、状态和购买分配；修改席位需另外勾选分配选项。商业关联、付款和应用所有权不能代替人员授权。响应不包含邮箱、电话、账号管理或财务资料。

查询支持 limit（1～100）、offset、名称字面搜索 search 和 assigned_only。can_use 表示当前产品使用资格。

分配时提交当前订阅、版本、明确的 assigned 和原请求键。授权撤销、到期、人员暂停或订阅替换后，后续查询、变更和原键重试都会被拒绝。结果不明时，先保留并恢复原请求，再执行其他操作。

查看公司详情 ​

按需要分别读取 companies/{company_id}、companies/{company_id}/commercial-link 和 companies/{company_id}/purchases。三项各需表中对应 Scope 和职责。

控制台「公司 → 查看详情」在切换页签时读取对应区块。某区块返回 403 时，清除该区块并重新检查公司访问；基础资料可读时保留其他区块，基础资料也被拒绝时返回公司目录。公司刷新返回 503 时撤下旧详情并提供重试。商业写请求结果不明时，先恢复原请求再切换区块。

列表分页 ​

读取下一页时保持原筛选，并原样传回 next_cursor，无需解析游标。公司、线索和机会的已加载条数只表示当前页面数据。切换企业、应用、环境、权限或筛选时，清除旧结果并从第一页开始。

销售报告 ​

提供 YYYY-MM-DD 格式的 from、to，包含 UTC 起止日，最多 366 天。报告统计在该日期窗口创建的全部记录的当前状态；历史阶段变化需另行查询。

as_of 为报告生成时间，source_updated_at 为来源最新更新时间，空报告中该字段为空。未结机会的预计金额按 currency 和 scale 分组，minor_units 为精确整数字符串，请勿转成 JavaScript Number。预计金额仅用于销售预测，收入、实收和订单总额分别查询。

销售操作日志 ​

使用与销售报告相同的日期参数。limit 为 1～100（默认 50），target_type 可选 appmarket_lead、appmarket_opportunity 或 appmarket_lead_followup。

日志按发生时间和 ID 倒序分页，游标绑定应用范围、日期和类型。返回操作者引用、动作、对象引用、结果、请求追踪 ID 和时间，不返回正文或原因。其他业务管理员日志尚未开放。

Webhook 投递历史 ​

使用 webhook-deliveries 查询投递历史。当前应用所有者或管理者需要 webhook.read 动作，无需开通公司或销售能力。

参数必填性说明
limit可选1～200，省略时 50
status、event_type可选状态或精确事件类型；省略时不按对应字段筛选
search可选事件类型、事件 ID 或投递 ID 的子串；省略时不搜索
from、to可选RFC3339，含起点、不含终点；省略时不限对应时间边界
cursor可选首页省略；翻页原样使用 next_cursor

筛选覆盖全部保留历史，在服务端分页前执行。记录按创建时间倒序、同时间投递 ID 升序返回。下一页保持原查询并原样传回 next_cursor，末页省略此字段。新增记录需刷新第一页，状态以本次查询为准。未知或其他应用的游标返回 400。

控制台按 UTC 自然日查询，结束日包含全天。下一页返回 503 时保留已读结果和原游标；403 时清除历史。接口不返回事件正文、请求头或凭据，仅提供投递历史，不提供全部业务事件归档或重放权限。

错误与恢复 ​

响应均使用 Cache-Control: no-store。

状态码处理方式
400/422修正非法或重复参数
401恢复当前用户会话
403清除资料，重新检查能力、Scope、本人授权和职责
404显示当前范围的查询失败，不尝试其他应用标识
409读取最新资源，再确认操作
429按 Retry-After 等待
503显示暂时不可用；不要作为空目录、零统计或写入成功

公司购买关联发生变化时，清除旧页并重新查询。

请求和返回字段见经营管理 OpenAPI。

开发者文档。第三方接入不需要内部运营平台权限。

GoodVision