API 工作流程

建立交易

1. 使用 external_deal_id 篩選器，查看是否已透過 LIST 產品建立產品。所有產品的外部交易 ID 不得重複。

   GET https://dv360seller.googleapis.com/v1beta1/{parent=exchanges/*/orders/*}/products?filter=externalDealId="{external_deal_id}"
   

2. 建立訂單。名稱是由 DV3 產生，建議您將這個 ID 儲存在系統中的某個位置，以供日後擷取。

3. 在訂單下建立產品。產品名稱是由 DV3 產生，建議您將這個 ID 儲存在系統中，以供日後擷取。

   或者，您隨時可以透過 external_deal_id 執行 LIST。名稱欄位包含訂單 ID 和產品 ID，方便您以這種方式識別父項。

取消交易

1. 將訂單狀態更新為「已取消」 只有在訂單尚未接受時，才能取消訂單。 「已取消」是最終狀態。訂單取消後就無法重新啟用。

取得交易詳細資料

1. 取得訂單詳細資料。使用者接受、封存或取消訂單後，狀態就會更新。
2. 取得產品詳細資料。

取得特惠清單

1. 列出訂單並套用狀態篩選器，即可取得所有已接受/待接受的訂單。
2. 使用 external_deal_id 篩選條件列出產品。
3. 列出訂單中的所有產品。

更新交易

1. 更新發布商聯絡資訊的順序。
   1. 名稱「不」允許更新(無法在 field_mask 中設定)。狀態只能透過 API 設為「已取消」。
   2. 合作夥伴 ID「不」允許更新。
2. 更新特定交易條件的產品。
   1. 名稱、externalDealId、transactionType、pricingType、updateTime 無法更新。
   2. 更新顯示名稱不需要使用者接受。
   3. 更新費率詳細資料、creativeConfig 會將上層訂單狀態變更為「等待接受」。無論先前是否接受訂單，DV3 廣告主都必須在協商頁面接受新條款。

查看使用者是否已接受交易

1. 如果您知道對應的訂單 ID，請取得訂單。查看狀態欄位。
2. 如果系統未追蹤訂單 ID：列出含有 external_deal_id 篩選器的產品、從產品名稱找出訂單名稱，然後取得訂單。查看狀態欄位。

查看使用者是否已設定交易(僅限程式輔助保證交易)

1. 取得廣告空間來源。名稱為「exchanges/{exchangeId}/inventorysources/{external_deal_id}」。請查看「買方狀態」。
   1. 預訂特惠
      1. BUYER_STATUS_ACTIVE 代表交易已獲接受並完成設定。當 DV360 收到符合交易條款的出價要求時，交易預計會處於這個狀態。系統會在「交易設定」步驟中自動產生委刊項。詳情請參閱「交易設定」。
      2. BUYER_STATUS_PENDING表示訂單已接受，但交易尚未設定。處於這種狀態時，系統不會產生任何支出。
      3. BUYER_STATUS_PAUSED表示廣告主已明確暫停交易。處於這種狀態時，系統不會產生任何支出。
   2. 免預訂優惠
      1. BUYER_STATUS_ACTIVE 表示交易已獲接受。當 DV3 收到符合交易條款的出價要求，且有指定這筆交易的有效委刊項，且出價要求符合委刊項指定條件時，交易預計會處於這個狀態。詳情請參閱委刊項。** 賣家 API 無法查詢委刊項是否指定交易。**
      2. BUYER_STATUS_PENDING不適用。
      3. BUYER_STATUS_PAUSED表示廣告主已明確暫停交易。處於這種狀態時，系統不會產生任何支出。

接受交易後暫停/取消暫停交易

1. 更新廣告空間來源賣家狀態。
   1. 暫停/取消暫停不會影響交易放送。賣家暫停交易時，廣告主只會看到 FYI 字串訊息。這有助於廣告主排解無法放送的交易。

重新協商 (接受交易後更新)

重新協議是指買方接受交易後，對交易進行的更新。這對交易平台和買方來說都非常實用，可將新變更推送至已接受的交易。舉例來說，如果交易平台發現已接受交易的交易結束時間不正確，且交易尚未開始，交易平台可以使用 DV3 更新產品，將更新推送給 DV3 買方。

允許和不允許的變更。

除了部分放送重要欄位 (例如：startTime、endTime、rateDetails、creativeConfig 等) 之外，我們允許變更所有欄位。我們針對這些放送重要欄位設有驗證機制。一般來說，如果交易的開始時間至少在 1 天後，除了 creativeConfig 以外，這些欄位都可以更新。對於進行中的交易 (開始時間在過去，但結束時間在未來)，只允許進行增量更新。如果交易已完成 (結束時間為過去)，則無法進行任何變更。舉例來說，您無法更新一年前完成交易的 rateDetails。在這種情況下，DV3 Update Product 會擲回驗證錯誤。