使用合作夥伴中心 API 為客戶建立訂單

適用於：合作夥伴中心 |由 21Vianet 營運的合作夥伴中心 |美國政府Microsoft雲端合作夥伴中心

建立 Azure 保留 VM 執行個體產品的訂單僅適用於：

合作夥伴中心

如需目前可供銷售之專案的相關資訊，請參閱雲端解決方案提供者計劃中的合作夥伴供應專案。

先決條件

合作夥伴中心身份驗證中所述的憑證。此案例支援使用獨立應用程式和 App+使用者認證進行驗證。
客戶 ID （customer-tenant-id）。如果您不知道客戶的識別碼，您可以選取 [客戶] 工作區，然後選取客戶清單中的客戶，然後選取 [帳戶]，在合作夥伴中心進行查詢。在客戶的 [帳戶] 頁面上，在 [客戶帳戶資訊] 區段中尋找Microsoft標識碼。 Microsoft ID 與客戶 ID （customer-tenant-id）相同。
優惠 ID。

C#

若要為客戶建立訂單：

具現化 Order 物件，並將 ReferenceCustomerID 屬性設定為客戶識別碼，以記錄客戶。
建立 OrderLineItem 物件的清單，並將清單指派給訂單的 LineItems 屬性。每個訂單明細項目都包含一個優惠的購買資訊。您必須至少有一個訂單明細項目。
取得訂購操作的介面。首先，使用客戶識別碼呼叫 IAggregatePartner.Customers.ById 方法來識別客戶。接下來，從 Orders 屬性擷取介面。
呼叫 Create 或 CreateAsync 方法，並傳入 Order 物件。
若要完成證明並包含其他轉銷商，請參閱下列範例要求和回應範例：

範例請求

{
    "PartnerOnRecordAttestationAccepted":true, 
    "lineItems": [
        {
            "offerId": "CFQ7TTC0LH0Z:0001:CFQ7TTC0K18P",
            "quantity": 1,
            "lineItemNumber": 0,
            "PartnerIdOnRecord": "873452",
            "AdditionalPartnerIdsOnRecord":["4847383","873452"]
        }
    ],
    "billingCycle": "monthly"
}

回應範例

{
    "id": "5cf72f146967",
    "alternateId": "5cf72f146967",
    "referenceCustomerId": "f81d98dd-c2f4-499e-a194-5619e260344e",
    "billingCycle": "monthly",
    "currencyCode": "USD",
    "currencySymbol": "$",
    "lineItems": [
        {
            "lineItemNumber": 0,
            "offerId": "CFQ7TTC0LH0Z:0001:CFQ7TTC0K18P",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "termDuration": "P1M",
            "transactionType": "New",
            "friendlyName": "AI Builder Capacity add-on",
            "quantity": 1,
            "partnerIdOnRecord": "873452",
            "additionalPartnerIdsOnRecord": [
                "4847383",
                "873452"
            ],
            "links": {
                "product": {
                    "uri": "/products/CFQ7TTC0LH0Z?country=US",
                    "method": "GET",
                    "headers": []
                },
                "sku": {
                    "uri": "/products/CFQ7TTC0LH0Z/skus/0001?country=US",
                    "method": "GET",
                    "headers": []
                },
                "availability": {
                    "uri": "/products/CFQ7TTC0LH0Z/skus/0001/availabilities/CFQ7TTC0K18P?country=US",
                    "method": "GET",
                    "headers": []
                }
            }
        }
    ],
    "creationDate": "2021-08-17T18:13:11.3122226Z",
    "status": "pending",
    "transactionType": "UserPurchase",
    "links": {
        "self": {
            "uri": "/customers/f81d98dd-c2f4-499e-a194-5619e260344e/orders/5cf72f146967",
            "method": "GET",
            "headers": []
        },
        "provisioningStatus": {
            "uri": "/customers/f81d98dd-c2f4-499e-a194-5619e260344e/orders/5cf72f146967/provisioningstatus",
            "method": "GET",
            "headers": []
        },
        "patchOperation": {
            "uri": "/customers/f81d98dd-c2f4-499e-a194-5619e260344e/orders/5cf72f146967",
            "method": "PATCH",
            "headers": []
        }
    },
    "client": {},
    "attributes": {
        "objectType": "Order"
    }
}

IAggregatePartner partnerOperations;
string customerId;
string offerId;

var order = new Order()
{
    ReferenceCustomerId = customerId,
    LineItems = new List<OrderLineItem>()
    {
        new OrderLineItem()
        {
            OfferId = offerId,
            FriendlyName = "new offer purchase",
            Quantity = 1,
            ProvisioningContext = new Dictionary<string, string>
            {
                { "subscriptionId", "bbbb1b1b-cc2c-dd3d-ee4e-ffffff5f5f5f" },
                { "scope", "shared" },
                { "duration", "3Years" }
            }
        }
    }
};

var createdOrder = partnerOperations.Customers.ById(customerId).Orders.Create(order);

範例：主控台測試應用程式。專案：合作夥伴中心 SDK 範例類別：CreateOrder.cs

REST 要求

請求語法

方法	請求網址識別碼 (URI)
貼文	{baseURL}/v1/customers/{customer-id}/orders HTTP/1.1

URI 參數

使用下列路徑參數來識別客戶。

名稱	類型	為必填項目	Description
客戶識別碼	字串	Yes	識別客戶的 GUID 格式客戶識別碼。

請求標頭

如需詳細資訊，請參閱合作夥伴中心 REST 標頭。

請求主體

訂單

下表說明要求本文中的 Order 屬性。

房產	類型	為必填項目	Description
識別碼	字串	否	成功建立訂單時提供的訂單識別碼。
參考客戶識別碼	字串	否	客戶識別碼。
計費週期	字串	否	指出合作夥伴為此訂單計費的頻率。支援的值是在 BillingCycleType 中找到的成員名稱。訂單建立時的預設值為「每月」或「一次性」。此欄位會在成功建立訂單時套用。
明細項目	OrderLineItem 資源陣列	Yes	客戶正在購買的優惠項目的逐項清單，包括數量。
貨幣代碼	字串	否	唯讀。下單時使用的貨幣。在成功建立訂單時套用。
創建日期	日期時間	否	唯讀。訂單的建立日期，以日期時間格式。在成功建立訂單時套用。
狀態	字串	否	唯讀。訂單的狀態。支援的值是在 OrderStatus 中找到的成員名稱。
links	訂單連結	否	資源連結對應於訂單。
attributes	資源屬性	否	對應至「訂單」的中繼資料屬性。
PartnerOnRecordAttestation已接受	布林值	Yes	確認證明完成

訂單行項目

下表描述要求本文中的 OrderLineItem 屬性。

備註

透過 API 結帳購物車時，行項目會 依照放入購物車的順序處理。若購物車中有兩款相同類型的商品，一款有促銷編號，另一款沒有（例如條款不同），該訂單可能會影響具有新商品供應限制的促銷資格。如果你要結帳多件商品，務必將任何符合促銷資格的商品 優先放入購物車 。

名稱	類型	為必填項目	Description
lineItemNumber	整數 (int)	Yes	集合中的每個行項目都會有一個唯一的行號，從 0 到 count-1 計算。
offerId	字串	Yes	供應專案識別碼。確保優惠是針對正確族群的。
subscriptionId	字串	否	訂用帳戶標識碼。
parentSubscriptionId	字串	否	選擇性。附加元件供應專案中父訂用帳戶的識別碼。僅適用於 PATCH。
friendlyName	字串	否	選擇性。合作夥伴所定義的訂用帳戶易記名稱，以協助消除歧義。
數量	整數 (int)	Yes	授權型訂閱的授權數目。
customTermEndDate	DateTime	否	新訂用帳戶第一個計費期限的結束日期。
partnerIdOnRecord	字串	否	當間接提供者代表間接轉銷商下訂單時，請只填入此欄位間接轉銷商的 PartnerID （絕不會是間接提供者的識別碼）。這確保了激勵措施的正確核算。
布建內容	字典<字串，字串>	否	佈建目錄中某些項目所需的資訊。 SKU 中的 provisioningVariables 屬性會指出目錄中特定專案需要哪些屬性。
links	OrderLineItemLinks	否	唯讀。資源連結對應於訂單明細項目。
attributes	資源屬性	否	對應至 OrderLineItem 的中繼資料屬性。
renewTo	物件陣列	否	RenewTo 資源陣列。
認證已接受	布爾 (bool)	否	表示同意要約或 SKU 條件。只有 SkuAttestationProperties 或 OfferAttestationProperties enforceAttestation 為 True 的供應項目或 SKU 才需要。
AdditionalPartnerIdsOnRecord	繩子	否	當間接提供者代表間接轉銷商下訂單時，請僅使用其他間接轉銷商的 PartnerID 填入此欄位（絕不會是間接提供者的識別碼）。這些其他經銷商不適用優惠。最多只能輸入五位間接經銷商。此數值僅適用於在歐洲國家/地區內交易的合作夥伴。
scheduledNextTerm指示	物件	否	定義試用訂閱的下一個期限指示。合作夥伴可指定該付費訂閱續約時的期限、計費頻率及數量。

備註

只有在間接提供者代表間接轉銷商下訂單時，才應該提供 partnerIdOnRecord。它只會用來儲存間接轉銷商的 PartnerID （絕不會儲存間接提供者的識別碼）。

RenewTo

下表說明 Microsoft Marketplace 供應專案要求本文中的 RenewTo 屬性。

房產	類型	為必填項目	Description
termDuration	字串	否	續約期限持續時間的 ISO 8601 表示。目前支援的值為 P1M （1 個月）和 P1Y （1 年）。

ScheduledNextTerm說明

本表描述了新商務體驗（NCE）授權試用優惠請求文中排程的NextTermInstructions屬性。若未指定數值，試用將續訂為付費訂閱，享有年度期限、月費計費及25個授權。

房產	類型	為必填項目	Description
產品	陣列	否	一個陣列，指定試用訂閱轉換為付費訂閱時的優惠，以及付費訂閱的期限和計費頻率。
數量	整數 (int)	否	試用服務續約後，對應的付費訂閱的授權數量。

Product

下表描述 NCE 授權型試用供應專案要求本文中的 productTerm 屬性。若此陣列中未指定數值，試用期將續訂為付費訂閱，並以年度期限、月費計費。

房產	類型	為必填項目	Description
產品ID	字串	否	試用期轉換為的付費訂閱產品所代表的 GUID 格式。
skuId	字串	否	一個格式化為代表試用續訂的付費訂閱 SKU 的 GUID。
可用性標識碼	字串	否	格式化的 GUID 用來表示試用期過後續約為付費訂閱時的可用性。
計費週期	字串	否	付費訂閱在試用期間續約後的計費頻率。
termDuration	字串	否	對應的付費訂閱在試用優惠續約後的期限長度。

範例請求

POST https://api.partnercenter.microsoft.com/v1/customers/b0d70a69-4c42-4b27-b17b-91a835d8686a/orders HTTP/1.1
Authorization: Bearer <token>
Host: api.partnercenter.microsoft.com
Content-Length: 691
Content-Type: application/json

{
  "BillingCycle": "one_time",
  "CurrencyCode": "USD",
  "LineItems": [
    {
      "LineItemNumber": 0,
      "ProvisioningContext": {
        "subscriptionId": "cccc2c2c-dd3d-ee4e-ff5f-aaaaaa6a6a6a",
        "scope": "shared",
        "duration": "1Year"
      },
      "OfferId": "DZH318Z0BQ4B:0047:DZH318Z0DSM8",
      "FriendlyName": "A_sample_Azure_RI",
      "Quantity": 1
    }
  ]
}

// request example where some renewal values for an NCE license-based trial are specified
http
POST https://api.partnercenter.microsoft.com/v1/customers/b0d70a69-4c42-4b27-b17b-91a835d8686a/orders HTTP/1.1
Authorization: Bearer <token>
Host: api.partnercenter.microsoft.com
Content-Length: 486
Content-Type: application/json
{
  "lineItems": [
    {
      "id": 0,
      "catalogItemId": "CFQ7TTC0LCHC:0003:CFQ7TTC0XCQC",
      "quantity": 25,
      "currencyCode": "USD",
      "billingCycle": "none",
      "termDuration": "P1M",
      "promotionId": null,
      "provisioningContext": {},
      "customTermEndDate": null,
      "scheduledNextTermInstructions": {
        "product": {
          "billingCycle": "monthly",
          "termDuration": "P1M" 
        }
      }
    }
  ],
  "partnerOnRecordAttestationAccepted": true
}

REST 響應

如果成功，方法會在回應內文中傳回 Order 資源。

若訂單包含一個或多個訂閱，則相應的訂閱 ID 值僅在 API 呼叫時已配置對應訂閱時，才會出現在 REST 回應中。佈建訂用帳戶會以非同步方式進行，因此，訂用帳戶識別碼值可能不一定會顯示在 Create Order 呼叫的 REST 回應中。然而，一旦各自的訂閱設定完成，即可透過 Get Orders 和 Get Order by ID 的 API 呼叫存取其訂閱 ID 值。

回應成功和錯誤碼

每個回應都有一個 HTTP 狀態代碼，指出成功或失敗，以及更多偵錯資訊。使用網路追蹤工具來讀取此程式代碼、錯誤類型和其他參數。如需完整清單，請參閱合作夥伴中心錯誤碼。

回應範例

{
  "id": "Cs_jyTxubLpvdJXdo8xcQZN6I2RsLrgZ1",
  "referenceCustomerId": "b0d70a69-4c42-4b27-b17b-91a835d8686a",
  "billingCycle": "one_time",
  "currencyCode": "USD",
  "lineItems": [
    {
        "lineItemNumber": 0,
        "offerId": "84A03D81-6B37-4D66-8D4A-FAEA24541538",
        "friendlyName": "A_sample_Azure_RI",
        "quantity": 1,
        "links": {
            "sku": {
                "uri": "/products/DZH318Z0BQ4B/skus/0047?country=US",
                "method": "GET",
                "headers": []
            }
        }
    } ],
    "creationDate": "2018-03-15T22:30:02.085152Z",
    "status": "pending",
    "links": {
        "provisioningStatus": {
            "uri": "/customers/b0d70a69-4c42-4b27-b17b-91a835d8686a/orders/Cs_jyTxubLpvdJXdo8xcQZN6I2RsLrgZ1/provisioningstatus",
            "method": "GET",
            "headers": []
        },
        "self": {
            "uri": "/customers/b0d70a69-4c42-4b27-b17b-91a835d8686a/orders/Cs_jyTxubLpvdJXdo8xcQZN6I2RsLrgZ1",
            "method": "GET",
            "headers": []
        }
    },
    "attributes": {
        "objectType": "Order"
    }
}

// response content for an order containing an NCE license-based trial
{
  "id": "99d3777b-61da-4c95-aefa-203c248c4180",
  "creationTimestamp": "2025-02-04T22:22:36.7924103Z",
  "lastModifiedTimestamp": "2025-02-04T22:22:36.7924109Z",
  "expirationTimestamp": "2025-02-11T22:23:34.5190698Z",
  "lastModifiedUser": "b5109661-56c5-45ed-9447-f67463458a97",
  "status": "Active",
  "lineItems": [
    {
      "id": 0,
      "catalogItemId": "CFQ7TTC0LCHC:0003:CFQ7TTC0XCQC",
      "quantity": 25,
      "currencyCode": "USD",
      "billingCycle": "none",
      "termDuration": "P1M",
      "provisioningContext": {},
      "orderGroup": "0",
      "pricing": {
        "listPrice": 0.0,
        "discountedPrice": 0.0,
        "proratedPrice": 0.0,
        "price": 0.0,
        "extendedPrice": 0.0
      },
      "scheduledNextTermInstructions": {
        "product": {
          "productId": "CFQ7TTC0LCHC",
          "skuId": "0002",
          "availabilityId": "CFQ7TTC0XL82",
          "billingCycle": "monthly",
          "termDuration": "P1M"
        },
        "quantity": 25
      }
    }
  ],
  "links": {
    "self": {
      "uri": "/customers/81e78b53-9aa8-44e7-a041-3b15272d8f84/carts/99d3777b-61da-4c95-aefa-203c248c4180",
      "method": "GET",
      "headers": []
    }
  },
  "attributes": {
    "objectType": "Cart"
  }
}

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2025-12-16

使用合作夥伴中心 API 為客戶建立訂單

先決條件

C#

範例請求

回應範例

REST 要求

請求語法

URI 參數

請求標頭

請求主體

訂單

訂單行項目

RenewTo

ScheduledNextTerm說明

Product

範例請求

REST 響應

回應成功和錯誤碼

回應範例

意見反應

其他資源