腾讯云企业实名 腾讯云国际站代理商系统接入

你有没有过这种体验？刚签完腾讯云国际站代理协议，满心欢喜打开文档，三分钟后盯着满屏的 Authorization: Bearer 和 X-Tencent-Cloud-Region 发呆，手边泡的枸杞茶都凉透了，还没搞懂为啥 403 Forbidden 不是服务器拒绝你，而是你连门牌号都敲错了？别慌——这篇不是官方文档翻译体，也不是PPT式流程图复读机，而是一份带着咖啡渍、改稿痕迹和三次重装SDK血泪史的实战手记。

一、先别急着写代码：搞清你是谁，以及腾讯云想让你是谁

很多同学一上来就猛啃 API 文档，结果测到第7个接口才发现：哦，原来我们压根没开「子账号委派权限」，连最基础的 ListProducts 都返回 UnauthorizedOperation。说白了，接入第一步不是技术，是「身份认证」——但这个认证，不是你身份证复印件+公章，而是三重身份叠buff：

• 腾讯云企业实名 法律身份：得有境外注册公司（香港/新加坡/美国等），且完成腾讯云国际站 KYC 审核（注意！不是国内站那套，国际站要上传公司章程、董事护照页、银行对账单——对，就是那种带SWIFT码的）；
• 平台身份：在 intl.cloud.tencent.com 后台开通「Reseller Portal」，拿到 Reseller ID（形如 reseller-123456789），这玩意儿比你家门禁卡还重要；
• 技术身份：创建「API密钥对」时必须勾选「Reseller API Access」权限组，且密钥状态得是 Active（别信控制台那个灰色「已启用」按钮，点进去看状态栏才是真·启用）。

友情提示：曾有某客户把「Reseller ID」当成「SecretId」填进 SDK 配置，调用 CreateOrder 直接触发风控熔断，账户被临时冻结2小时——腾讯云安全团队以为有人在用ID当密码暴力撞库。

二、接口不是越多越好：盯紧这5个核心接口，其他都是配角

国际站开放API超200个，但代理商日常运营真正高频使用的，就这五个「生存接口」，建议打印贴工位，每天默念三遍：

① DescribeResellerBalance ——你的钱包实时余额

别用 GetAccountBalance！这是给终端客户查余额的，代理商必须用带 Reseller 前缀的专属接口。关键参数只有两个：ResellerId（必须！必须！必须！）和 Region（国际站分 region 极细，ap-singapore ≠ ap-singapore-1）。返回里有个隐藏字段 AvailableCredit，这才是你能花的钱，TotalBalance 包含冻结额度，别拿它算毛利。

② DescribeResellerProducts ——商品目录不是静态HTML

你以为商品列表是后台配置好扔给你一个JSON？错。这个接口每调用一次，都会实时拉取当前 region 下所有可售产品（含新上架的AI算力包），且价格按代理商等级动态浮动。重点：加参数 Filters.ProductType=vm 可过滤云服务器，但 Filters.PriceCurrency=USD 必须显式声明——漏掉它，默认返回 CNY，而国际站账单只认 USD/HKD/SGD。

③ CreateResellerOrder ——下单不是点外卖

参数表长得像《民法典》附则，但生死线就三条：ResellerId（再强调一遍）、ClientUin（客户在腾讯云的唯一标识，不是你给客户起的昵称！）、ProductItems 数组里每个 item 必须带 PriceUnit（hour/month）和 Duration（数字，别传字符串！传 "12" 就报错）。曾有客户把 Duration 写成 "12 months"，错误码返回 InvalidParameterValue.Duration，文档里却没写具体格式要求……我们花了3小时翻SDK源码才定位。

④ DescribeResellerOrders ——查单别只信「Status: success」

订单状态有7种，但只有 Delivered 才算真正生效（资源已分配）。Paid 仅代表客户付款成功，后台可能还在异步调度资源；Processing 更是薛定谔的状态——可能卡在支付网关，也可能卡在新加坡机房的物理上架环节。建议轮询时加个判断：if status == 'Delivered' and resource_id 存在，才算稳了。

⑤ DescribeResellerBillSummary ——账单不是月底才出

国际站支持按天出账单摘要（Day 粒度），参数 StartTime/EndTime 必须是 UTC 时间，且跨度不能超31天。最坑的是：账单里的 RealTotalCost 是扣减代理折扣后的净额，而 Discount 字段藏在 Detail 里——你得先调 DescribeResellerBillDetails 才能算清毛利率。

三、那些文档不会告诉你的「人间真实」

▶ 接口限频不是均摊的

你以为 QPS 限制是全局的？错。腾讯云国际站按「ResellerId + Region + API」三维限频。比如你在 ap-singapore 调 CreateResellerOrder 被限频，切换到 na-toronto 立刻恢复——但别高兴太早，同一 ResellerId 下所有 region 共享日调用量配额（默认5万次/天），超了直接返回 RequestLimitExceeded，且不告诉你哪条超了。

▶ Webhook 通知不是 100% 可靠

订单状态变更会推 Webhook，但网络抖动丢包率约0.3%（我们实测数据）。正确姿势：Webhook 收到后立即返回 HTTP 200，然后异步调用 DescribeResellerOrders 校验最终状态——别让客户等你重试3次才发货。

▶ 沙箱环境？不存在的

国际站没有独立沙箱环境。测试必须走真实账号，但可以申请 test-reseller-xxx 这类特殊前缀账号，配合 TestMode=true 参数模拟下单（不扣款、不发资源）。千万别在生产账号上测！曾有代理误删测试参数，给客户开了100台GPU实例，账单邮件来的时候，他正在会议室讲「降本增效」……

四、最后送你一句保命口诀

「ResellerId 不离身，Region 大小写要分，UTC 时间别本地化，Webhook 收到先回200，账单明细两头查，测试一定用 test 前缀！」

写完这篇，我顺手检查了下自己系统的 DescribeResellerBalance 调用日志——过去24小时共173次，失败0次。窗外广州暴雨如注，而我的咖啡杯底，静静躺着半颗没化的方糖。接入这事，从来不是魔法，只是把每一个「我以为」，换成「我确认过」。