---
title: API 设置 + 自动化订单管理 (AOM) + 自动化使用情况报告
slug: zh/api-aom
icon: {"faIcon":"fa-brands fa-wordpress"}
createdAt: 2026-03-10T18:19:01.825Z
---

# 第 0 部分：设置

WeTransact 会将事件发送到您在 WeTransact Portal 的 **事件网格主题终结点** 中配置的 **设置**。

### 3.1 API 访问

:::BlockQuote
📖 API 参考：https\://apidocs.wetransact.io/openapi/subscriptions
:::

如果您想以编程方式控制激活，则需要一个 API 密钥。

**生成密钥：**

1. 前往您的 WeTransact 门户：yourcompany.wetransact.io
2. 前往 **设置** → **集成&#x20;**→ 滚动到 **API 访问** 部分
3. 点击 **生成**
4. 立即复制该密钥并将其存储在 secrets manager 中

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/2N4POKUZ-0O8BJSNQvqtP_fig4-api-key-created.png)

:::BlockQuote
⚠️ **该密钥仅显示一次。** 离开页面后将不会再次显示。如果密钥已泄露，请生成新的密钥以使旧密钥失效
:::

# <font color="#4338CA">第 1 部分：自动化订单管理 (AOM)</font>

## 1. 简介

📖 API 参考：https\://apidocs.wetransact.io/openapi/subscriptions

当 Marketplace 发布商拥有自动化预配流程时，大多数发布商都希望将 Marketplace 购买渠道接入该流程。通过 WeTransact Platform，您可以按照本指南实现这一点。

## 2. 订单流程

通过 Microsoft Marketplace 销售时，Microsoft 会规定订单流程。启用 AOM 后，WeTransact 将充当 Microsoft Marketplace 与您的订单管理系统之间的中间件。

**工作原理：**

1. 客户完成购买 → 被重定向到 WeTransact Landing Page
2. 购买者点击 **确认购买** → 订单发送到 WeTransact Portal
3. WeTransact 向您的 Event Grid endpoint 发送 CreateSubscription 事件
4. 您的系统预配并激活订阅
5. WeTransact 通知 Microsoft Marketplace 以确认激活

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/fBzcvZrJQXXciFY4G1O9u_fig1-order-flow.png)

**后续生命周期事件** — 激活后，WeTransact 还会转发以下事件：

| 事件     | 说明                             |
| ------ | ------------------------------ |
| 取消     | 客户取消订阅；服务将在承诺期限结束时终止           |
| 暂停     | Microsoft 无法收取付款；请考虑暂停服务       |
| 恢复     | 暂停后已收取付款；恢复服务                  |
| 续订     | 订阅已手动续订或通过自动续订完成续订             |
| 套餐变更   | 客户更改了套餐层级（例如：Basic → Standard） |
| 席位数量变更 | 客户更改了用户数量（仅适用于 Per-User 套餐）    |

##

### 3 订阅激活

发布者必须在 **30 天内** 激活订阅，否则 Microsoft 将自动取消该订阅。

:::BlockQuote
🚨 **30 天窗口期。** 请在您的订单队列上设置监控和警报，以避免错过此截止时间。
:::

共有三种激活方式：

**方式 1 — 手动（门户）** 前往 **订单** → 点击 **采取行动** → 批准或拒绝。

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/DJKA9SwNjidNaZTqNGKNu_fig5-manual-activation.png)

**方式 2 — 自动批准** 前往 **产品列表 → 定价方案** → 启用 **自动批准新订单**（适用于所有计划或特定计划）。

适用于所有计划

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/j6bnG7ZRhf8FZrsaVWxso_image.png)

适用于特定计划

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/GZAvJSjulWzSK7JD4mrgP_image.png)

**方式 3 — 通过 API** *（推荐用于 AOM）* 接收 CreateSubscription 事件，完成配置，然后调用 API 进行激活。

### 3.2 通过 API 激活

| &#x20;  |                                                                                                     |
| ------- | --------------------------------------------------------------------------------------------------- |
| **方法**  | POST                                                                                                |
| **URL** | https\://\[YOUR-SUBDOMAIN].wetransact.io/api/v1.0/subscriptions/\[SUBSCRIPTION-ID]/actions/activate |
| **请求头** | x-api-key: \[YOUR API KEY]                                                                          |

**响应：**

- 200 OK — 处理成功
- 500 — 失败，请联系 WeTransact Support

:::BlockQuote
ℹ️ 返回 200 并不保证激活成功。如果下游处理失败，WeTransact 将异步发送 ActivateSubscriptionFailed 事件。如果发生这种情况，请联系支持团队。
:::

## 4. 事件与消息

### 4.1 CreateSubscription

在创建订阅时发送。包含进行配置和激活所需的所有内容。

| 字段                        | 类型            | 说明                             |
| ------------------------- | ------------- | ------------------------------ |
| MarketplaceSubscriptionId | GUID          | Microsoft 分配的 ID。将其用作您的唯一标识符。  |
| Created                   | DATETIME      | 订阅创建时间戳                        |
| CompanyName               | STRING        | 购买公司的名称                        |
| MarketplaceOfferId        | STRING        | Partner Center 中的产品 ID         |
| MarketplacePlanId         | STRING        | Partner Center 中的计划（SKU）ID     |
| SeatQuantity              | STRING *（可选）* | 席位数量——仅适用于 Per-User 计划         |
| TermUnit                  | STRING        | P1M / P1Y / P2Y / P3Y          |
| InitialUserEmail          | STRING        | 购买者的电子邮件                       |
| AdditionalDetails         | STRING *（可选）* | 额外的 Landing Page 字段，采用 JSON 格式 |
| Channel                   | STRING        | Direct 或 Indirect（CSP）         |
| BeneficiaryEmail          | STRING *（可选）* | 最终用户电子邮件——通过 CSP 时与购买者不同       |

json

:::BlockQuote
\{  "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0",  "Created": "2025-03-07T12:34:56.7892",  "CompanyName": "EndCustomer",  "MarketplaceOfferId": "offer-123",  "MarketplacePlanId": "plan-premium",  "SeatQuantity": "10",  "TermUnit": "P1Y",  "InitialUserEmail": "purchasing\@contoso.com",  "AdditionalDetails": "\{}",  "Channel": "Indirect",  "BeneficiaryEmail": "user\@endcustomer.io",  "ResellerName": "Contoso"}
:::

### 4.2 取消订阅

当客户取消时发送。服务将持续保持激活状态，直到承诺期限结束。

| 字段                        | 类型   | 描述        |
| ------------------------- | ---- | --------- |
| MarketplaceSubscriptionId | GUID | 已取消订阅的 ID |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.3 SuspendSubscription

当 Microsoft 无法收取付款时发送。请考虑暂停服务或联系客户。

| 字段                        | 类型   | 描述        |
| ------------------------- | ---- | --------- |
| MarketplaceSubscriptionId | GUID | 已暂停订阅的 ID |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.4 ReinstateSubscription

当 Microsoft 在暂停后成功收取付款时发送。如果服务已被暂停，请恢复该服务。

| 字段                        | 类型   | 描述        |
| ------------------------- | ---- | --------- |
| MarketplaceSubscriptionId | GUID | 要恢复的订阅 ID |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.5 RenewSubscription

当订阅通过手动方式或自动续订方式续订时发送。

| 字段                        | 类型   | 描述        |
| ------------------------- | ---- | --------- |
| MarketplaceSubscriptionId | GUID | 已续订订阅的 ID |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

### 4.6 ChangePlan

当客户更改套餐层级时发送。请更新功能标志、权益或资源分配。

| 字段                        | 类型     | 描述           |
| ------------------------- | ------ | ------------ |
| MarketplaceSubscriptionId | GUID   | 受影响订阅的 ID    |
| MarketplacePlanId         | STRING | 新套餐（SKU）的 ID |

json

:::BlockQuote
\{  "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0",  "MarketplacePlanId": "plan-premium"}
:::

### 4.7 更改席位数量

当客户更改席位数量时发送。仅适用于 Per-User 计划。请相应更新计算/资源分配。

| 字段                        | 类型     | 说明        |
| ------------------------- | ------ | --------- |
| MarketplaceSubscriptionId | GUID   | 受影响订阅的 ID |
| SeatQuantity              | STRING | 新的席位总数    |

json

:::BlockQuote
\{  "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0",  "SeatQuantity": "150"}
:::

### 4.8 激活订阅失败

当 API 调用返回 200 OK 后，下游激活失败时发送。请立即联系 WeTransact Support。

| 字段                        | 类型   | 说明         |
| ------------------------- | ---- | ---------- |
| MarketplaceSubscriptionId | GUID | 激活失败的订阅 ID |

json

:::BlockQuote
\{ "MarketplaceSubscriptionId": "a1fabe21-7904-4c2f-932d-5253a35e97d0" }
:::

## 5. 消息路由

所有消息都包含一个 Subject 字段，用于在您的 Event Grid 订阅中过滤：

| Subject                    | 触发条件    |
| -------------------------- | ------- |
| CreateSubscription         | 已下达新订单  |
| CancelSubscription         | 客户已取消   |
| SuspendSubscription        | 支付失败    |
| ReinstateSubscription      | 支付问题已解决 |
| RenewSubscription          | 订阅已续订   |
| ChangePlan                 | 计划层级已更改 |
| ChangeSeatQuantity         | 席位数量已更改 |
| ActivateSubscriptionFailed | 下游激活失败  |

# <font color="#1300fffb">第 2 部分：自动化使用情况报告</font>

## 简介

📖 API 参考：https\://apidocs.wetransact.io/openapi/subscriptions

一些 Marketplace 发布商需要通过 API 报告使用情况。当报告频率较高时（每月超过一次），这是必需的。本节说明如何使用 WeTransact API 报告使用情况。

使用情况报告始终需要针对一个有效的订阅进行，该订阅可通过 GUID 唯一标识。获取该 GUID 后，发布商可以通过定义每个计量器的数量来报告使用情况。所有 API 文档位于：

https\://apidocs.wetransact.io/openapi

此 API 规范描述了所有其他相关 API 详细信息，包括请求和响应消息示例。第 7.1 节说明了如何获取 WeTransact API 的访问权限。

![](https://api.archbee.com/api/optimize/wlBoYP3-_D88k8I6lqBSW/5SLXHR6Fv0okpak6-Blh4_.blob)

在**步骤 1**中，发布商的报告系统首先通过 GET /subscriptions 端点获取所有订阅，从而提取正确的订阅 ID（精确字段名称：marketplaceSubscriptionId）。为了包含该订阅有效的计量器信息，应添加查询参数 includeMeters=true。如果订阅 ID 和计量器详细信息已存储，则可以跳过此步骤。

在**步骤 2**中，发布商端的系统需要针对该订阅 ID 发起计费。这是通过调用 POST /subscriptions/&#x7B;id}/charge 端点完成的。在这里，系统定义要计费的订阅 ID，以及计量器 ID 和数量。WeTransact 平台负责与 Microsoft Marketplace 进行消息交换（**步骤 3**）。

### 7.1 API 访问

当发布商希望自动化使用情况报告时，需要 API 访问权限。如果尚未创建 API 密钥，Settings 部分将显示 Generate 按钮。
