API 工作流程

本指南說明如何使用 Deal Sync API 建立、取消、擷取、更新及協商交易，並介紹常見的 API 工作流程。

建立交易

1. 呼叫 LIST 產品並使用 externalDealId 篩選器，檢查是否已建立產品。請注意，篩選器字串支援 camelCase externalDealId 和 snake_case external_deal_id。所有產品的 external_deal_id 均不得重複。

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

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

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

或者，您也可以使用 external_deal_id 呼叫 LIST。資源名稱包含訂單 ID 和產品 ID，因此您可以識別父項訂單。

取消交易

1. 將訂單狀態更新為「已取消」。 只有在訂單尚未獲准的情況下，才能取消訂單。「已取消」是終止狀態，訂單取消後即無法重新啟用。如果訂單包含任何產品，則無法重複使用 external_deal_id。

取得交易詳細資料

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

取得優惠清單

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

更新交易

1. 更新 發布商聯絡資訊的順序。
   1. name 無法更新 (無法在 updateMask 中設定)。狀態只能使用 API 設為 CANCELED。
   2. partner_id 無法更新。
2. 更新 特定交易條件更新的產品。
   1. name、externalDealId、transactionType、pricingType 和 updateTime 無法更新。
   2. 更新 displayName 時，使用者不必重新接受。
   3. 更新 rateDetails 或 creativeConfig 會將父項訂單狀態變更為 PENDING_ACCEPTANCE。無論先前是否已接受訂單，系統都會要求 DV360 廣告主在「協商」頁面接受新條款。

確認使用者是否已接受特惠

1. Get Order 如果您知道對應的訂單名稱，檢查 status 欄位。
2. 如果系統未追蹤訂單名稱：列出含有 external_deal_id 篩選條件的產品、從產品名稱找出訂單名稱，然後呼叫 Get Order。 檢查 status 欄位。

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

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：交易已接受。當 DV360 收到相符的出價要求、有效的委刊項指定交易，且出價要求符合委刊項指定條件時，交易就會開始支出費用。詳情請參閱「委刊項」。(注意：沒有 Seller API 可查詢交易是否以放送項目為目標)。
      2. BUYER_STATUS_PENDING：不適用於非預訂交易。
      3. BUYER_STATUS_PAUSED：廣告主已明確暫停交易。處於這個狀態時不會產生任何支出。

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

1. 更新 廣告空間來源 賣家 狀態。
   1. 暫停或取消暫停不會停止放送交易。賣家暫停交易後，DV360 使用者介面會向廣告主顯示資訊訊息，協助排解無法放送的交易。

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

重新協商是指買方接受交易後，對交易進行的更新。廣告交易平台和買方可藉此調整現有交易的條款。 舉例來說，如果交易平台發現已接受交易的檔期結束時間有誤，可以在交易開始放送前，使用「產品修補程式」將更新推送給 DV360 買方。

允許和不允許的變更

如要完整瞭解交易協商和重新協商規則，請參閱 Display & Video 360 說明中心文章：

• 重新協商程式輔助保證交易
• 在 Display & Video 360 中協商交易