Zoom Commerce API 端点清单全解析基于 knowledge-work-plugins 的合作伙伴商务自动化接口指南【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-pluginsZoom Commerce API 是 Zoom 为 Partner经销商/分销商/子经销商提供的商务自动化接口域覆盖账户管理、计费、交易登记、订单、报价、产品目录与订阅的全链路操作。本指南以 commerce.md 为骨架结合本仓库rest-apiskill 中的认证、架构与限流资料完整梳理 Commerce API 的 33 个端点操作并给出调用前提、编排建议与排错思路帮助开发者在 Claude Cowork 等知识工作场景中快速定位所需接口并落地集成。Commerce API 概览一份权威端点清单如何组织commerce.md是 Zoom REST API skill 中与官方 Zoom API Hub OpenAPI 文档逐一对齐的领域参考文件之一。它遵循与同目录下其他领域文件如 accounts.md、meetings.md相同的镜像 OpenAPI组织方式所有端点的方法与路径均由官方 Zoom API Hub 的paths对象生成因此本文件适合做端点发现与清单查询而不要把它当作路径拼接的唯一事实来源——真正的编排模式请参考 examples/ 目录中的完整示例。该文档自身声明了三个关键使用前提权威来源Canonical SourceOpenAPI JSON 位于https://developers.zoom.us/api-hub/commerce/methods/endpoints.jsonBase URL 统一为https://api.zoom.us/v2认证细节见 authentication.md。作用域Scope按操作定义每个操作常使用更细粒度的 scope 名称实施前必须到 API Hub 操作页核对准确 scope。用途边界本文件用于端点发现和清单编排模式应参考examples/目录而非以本文件为路径名的唯一依据。覆盖规模指标数值端点操作数Endpoint operations33路径模板数Path templates31标签数Tags8标签索引标签Tag操作数Account Management4Billing3Deal Registration5Order4Platform3Product Catalog3Quote6Subscription5从标签分布可以看出Commerce API 覆盖了一条完整的获客 → 交易 → 履约 → 续订商务链路先管理终端客户账户再登记交易Deal Registration、查产品目录与价目表、创建报价Quote与订单Order最终落到订阅Subscription与账单Billing的管理外加 Platform 类文件上传下载的支撑能力。按标签逐组详解全部 33 个端点操作Account Management账户管理4 个操作该标签面向 Zoom Partner / Sub-Reseller / End Customer 三层账户体系负责终端客户账户的创建与联系人维护MethodEndpoint摘要Operation IDPOST/commerce/account创建终端客户账户createAccountPOST/commerce/account/{accountKey}/contacts向现有终端客户或你自己的账户添加联系人addAccountContactGET/commerce/accounts按账户类型获取与 Zoom Partner/Sub-Reseller 关联的所有账户列表getAllAccountsGET/commerce/accounts/{accountKey}获取 Zoom Partner/Subreseller/End Customer 的账户详情getAccountDetails实践中createAccount是整条商务链路的起点后续的 Deal Registration、Quote、Order 都依赖已存在的客户账户accountKey。addAccountContact支持为已有账户补充联系人或为自身账户维护联系人通常用于报价单Quote收件人、订单确认联系人等场景。Billing计费3 个操作面向经销商与分销商的账单与发票查询MethodEndpoint摘要Operation IDGET/commerce/billing_documents获取分销商或经销商的全部计费文档getAllBillingDocsGET/commerce/billing_documents/{documentNumber}/document按文档 ID 获取计费文档的 PDFdownloadBillingDocGET/commerce/invoices/{invoiceNumber}获取分销商或经销商指定发票的详细信息getInvoiceDetail注意路径中的{documentNumber}与{invoiceNumber}是文档编号/发票编号类标识符与账户的accountKey、交易的dealRegKey不同查询前需从列表接口先取得这些编号。Deal Registration交易登记5 个操作交易登记是 Partner 保护自身交易机会的机制需与 Zoom 官方 Campaign 关联MethodEndpoint摘要Operation IDGET/commerce/campaigns获取可关联交易登记的所有有效 Zoom CampaigngetCampaignsPOST/commerce/deal_registration为 Partner 创建新的交易登记createDealRegGET/commerce/deal_registrations获取 Partner 的全部有效交易登记getAllDealRegsGET/commerce/deal_registrations/{dealRegKey}按登记编号获取交易登记详情getDealRegDetailsPATCH/commerce/deal_registrations/{dealRegKey}更新现有交易登记Updatesanexistingdealregistration标准流程是先用getCampaigns获取有效的 Campaign 标识再用createDealReg创建登记随后可用PATCH在交易推进过程中更新状态如从登记推进到已批准并可上传附件佐证见 Platform 标签的uploadFile。Order订单4 个操作MethodEndpoint摘要Operation IDPOST/commerce/order为 Zoom Partner 创建订阅订单createOrderPOST/commerce/order/preview预览订单中的增量指标与订阅createOrderPreviewGET/commerce/orders获取 Zoom Partner 的全部订单getAllOrdersGET/commerce/orders/{orderReferenceId}按订单引用 ID 获取订单详情getOrderDetailscreateOrderPreview的预览增量delta指标与订阅设计值得注意在真正提交订单前先做一次预览用于核对价格、订阅条目与变更影响避免创建出错后再返工是推荐的前置校验步骤。Platform平台支撑3 个操作MethodEndpoint摘要Operation IDPOST/commerce/file在交易登记或报价的上下文中上传 PDF 附件uploadFileGET/commerce/files/{associatedReferenceId}/details获取与报价或交易登记关联的所有文件详情allFileDetailsGET/commerce/files/{documentReferenceId}下载与报价或交易登记关联的文件downloadFile.该标签为 Deal Registration 与 Quote 提供文件支撑uploadFile明确要求上传 PDFassociatedReferenceId可指向交易登记或报价的引用标识实现业务对象 ↔ 附件的关联管理。Product Catalog产品目录3 个操作MethodEndpoint摘要Operation IDPOST/commerce/catalog获取 Zoom Partner 的 Zoom 产品目录getOffersGET/commerce/catalog/{offerId}获取 Zoom 产品或 Offer 的详情getOfferDetailGET/commerce/pricebooks以可下载文件形式获取价目表downloadPricebook注意getOffers使用POST获取目录可能因目录查询条件复杂而采用请求体传参与常规 GET 列表不同。downloadPricebook返回可下载的价目表文件可作为报价/订单定价计算的离线数据源。Quote报价6 个操作数量最多MethodEndpoint摘要Operation IDPOST/commerce/quote为 Zoom Partner 创建订阅报价createQuotePOST/commerce/quote/preview预览报价中的增量指标与订阅createQuotePreviewGET/commerce/quotes获取 Zoom Partner 的全部报价getAllQuotesGET/commerce/quotes/{quoteReferenceId}按报价引用 ID 获取报价详情getQuoteDetailsPATCH/commerce/quotes/{quoteReferenceId}更新 Zoom Partner 的订阅报价updateQuotePATCH/commerce/quotes/{quoteReferenceId}/fulfillment提交订阅报价以进行资源开通ProvisioningprovisionQuoteQuote 标签是商务流程中承上启下的核心从 Product Catalog 取 Offer 与价目表 →createQuote建议先createQuotePreview预览→ 期间用updateQuote调整 → 客户确认后用provisionQuotePATCH/fulfillment提交履约开通。该操作标志着报价正式转入开通流程属于有状态变更实施时应确保调用顺序正确。Subscription订阅5 个操作MethodEndpoint摘要Operation IDGET/commerce/subscriptions获取 Zoom Partner 的付费订阅getAllSubscriptionsGET/commerce/subscriptions/{subscriptionNumber}按订阅编号获取订阅详情getSubscriptionDetailsGET/commerce/subscriptions/{subscriptionNumber}/versions获取指定订阅编号的变更/版本历史getSubscriptionVersionsGET/commerce/trials获取 Zoom Partner 的试用订阅getAllTrialSubscriptionsGET/commerce/trials/{trialReferenceId}按 Zoom 账户号或试用 ID 获取终端客户的试用详情getTrialDetails订阅是订单/报价履约后的结果形态以subscriptionNumber标识getSubscriptionVersions提供订阅的历史变更记录可用于对账、审计与续订分析。付费订阅/subscriptions与试用/trials分开管理体现了两者在生命周期上的差异。调用前的通用前置条件认证、Base URL 与作用域Commerce API 属于 Zoom REST API v2 体系所有端点均遵循仓库中 authentication.md 与 api-architecture.md 定义的通用规则1. 认证方式。商务自动化属于后端服务场景官方推荐Server-to-Server OAuthJWT 应用类型已弃用。获取令牌的方式curl -X POST https://zoom.us/oauth/token \ -H Authorization: Basic $(echo -n CLIENT_ID:CLIENT_SECRET | base64) \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeaccount_credentialsaccount_idACCOUNT_ID响应中access_token有效期 1 小时expires_in: 3600需缓存并在过期前刷新所有 API 请求在Authorization头携带Bearer {access_token}。2. 区域 Base URL。默认为https://api.zoom.us/v2OAuth 令牌响应中的api_url字段指示用户数据所在区域如https://api-eu.zoom.us出于数据驻留合规要求可使用对应区域 URL但全局 URL 始终可用。3. 作用域。commerce.md特别强调Commerce API 的 scope 是按操作定义的、且多为细粒度命名。实施任何端点前务必在 Zoom API Hub 对应操作页核对精确 scope 并在 App 配置中添加。若令牌缺少 scope会返回4700 Invalid access token, does not contain scopes类错误见 common-errors.md。实操模式建议从端点清单到可运行集成commerce.md的定位是端点发现与清单其自身建议编排模式参考 examples/ 目录例如 meeting-lifecycle.md、user-management.md 展示了完整的请求 → 响应 → 错误处理写法。结合该目录的编排惯例Commerce API 落地时可参考如下模式典型商务自动化流程Quote → Order → ProvisionGET /commerce/campaigns # 获取有效 Campaign POST /commerce/account # 如需创建终端客户账户 POST /commerce/deal_registration # 创建交易登记可带 campaign POST /commerce/file # 上传 PDF 附件关联登记/报价 POST /commerce/quote/preview # 预览增量指标与订阅先行校验 POST /commerce/quote # 创建订阅报价 PATCH /commerce/quotes/{quoteReferenceId} # 按需调整报价 PATCH /commerce/quotes/{quoteReferenceId}/fulfillment # 提交履约开通 GET /commerce/subscriptions/{subscriptionNumber} # 验证开通后的订阅状态分页处理。列表类端点getAllAccounts、getAllOrders、getAllQuotes、getAllSubscriptions等应采用next_page_token分页而非旧式page_number这是本仓库 RUNBOOK.md 中强调的通用约定。错误处理与重试。面对429 Too Many Requests与瞬时5xx应按 rate-limiting-strategy.md 实现指数退避加重试async function callZoomAPI(url, options, maxRetries 5) { for (let attempt 0; attempt maxRetries; attempt) { const response await fetch(url, options); if (response.status 429) { const retryAfter response.headers.get(Retry-After); if (retryAfter) { const waitMs new Date(retryAfter) - Date.now(); if (waitMs 0 waitMs 86400000) { await sleep(waitMs); continue; } throw new Error(Daily rate limit hit. Retry after ${retryAfter}); } const baseDelay Math.pow(2, attempt) * 1000; const jitter baseDelay * 0.2 * Math.random(); await sleep(baseDelay jitter); continue; } return response; } throw new Error(Max retries exceeded for Zoom API); }注意Zoom 的限流按账户共享同一账户下所有应用共享配额Commerce 类批量操作应关注响应头X-RateLimit-Remaining/X-RateLimit-Reset主动降速。通用排错清单源自 RUNBOOK.md 与 common-errors.md症状排查方向401/ invalid tokenOAuth 流程选错、令牌过期或 scope 不匹配403缺少操作所需细粒度 scope或账户权限不足404类行为端点路径/版本错误或accountKey/dealRegKey/orderReferenceId/quoteReferenceId/subscriptionNumber标识符类型用错429突增缺少退避/排队策略或同一账户其他应用消耗了共享配额与其他领域参考文件的边界与协同端点清单的通用约定Commerce 与 accounts.md 等文件共用同一套镜像 OpenAPI结构与 Base URL 约定若需要账户级设置如lock_settings、managed_domains配合商务流程可交叉查询该文件。认证与安全完整 OAuth 实现含 PKCE、刷新令牌、令牌加密存储见 authentication.md涉及文件下载downloadBillingDoc、downloadFile、downloadPricebook时按 api-architecture.md 的Download URLs约定携带 Bearer 令牌并跟随重定向curl -L。限流与错误配额规则、并发限制Lock-Key与响应头说明见 rate-limiting-strategy.mdZoom 错误码表300、4700、1001等见 common-errors.md。快速排错入口集成前先按 RUNBOOK.md 的 5 分钟预检清单确认认证流程、scope、ID 语义与分页/限流四项能大幅降低 Commerce 集成失败率。小结Zoom Commerce API 以 8 个标签、33 个端点操作覆盖了 Zoom 合作伙伴商务闭环的完整生命周期账户Account Management、商机Deal Registration、选品定价Product Catalog、报价Quote、订单Order、履约结果Subscription与财务对账Billing并由 Platform 的文件能力提供附件支撑。使用 commerce.md 时应把它当作端点发现的权威清单先按标签定位操作、到 API Hub 核对细粒度 scope再结合本仓库rest-apiskill 的认证、架构、限流与示例资料完成可运行的集成实现。【免费下载链接】knowledge-work-pluginsOpen source repository of plugins primarily intended for knowledge workers to use in Claude Cowork项目地址: https://gitcode.com/GitHub_Trending/kn/knowledge-work-plugins创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
