API 工作流程

本指南介绍了使用 Deal Sync API 创建、取消、检索、更新和协商交易的常见 API 工作流程。

创建交易

1. 使用 externalDealId 过滤条件调用 LIST products，以检查是否已创建产品。请注意，过滤条件字符串中同时支持 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. 在 订单下创建产品。 产品名称由 DV360 生成，我们建议您将此 ID 存储在系统中，以便日后检索。

或者，您也可以使用 external_deal_id 调用 LIST。资源名称同时包含订单 ID 和产品 ID，因此您可以识别父级订单。

取消交易

1. 将订单状态更新为 CANCELED。 只有在订单尚未被接受的情况下，才支持取消。CANCELED 是一种终止状态；订单一经取消便无法重新激活。如果订单包含任何产品，则其 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. 如果您知道相应的订单名称，请 获取 订单。检查 status 字段。
2. 如果订单名称未被跟踪：使用 external_deal_id 过滤条件列出产品， 从产品 名称中识别订单名称， 然后调用“获取 订单”。 检查 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 界面中会向广告客户显示一条信息性消息，以帮助排查未支出的交易。

重新协商（在接受交易后更新交易）

重新协商是指在买方接受交易后对交易进行的更新。这样，交易平台和买方就可以调整现有交易的条款。 例如，交易平台可能会发现已接受交易的投放结束时间不正确；交易平台可以使用 Product Patch 在交易开始投放之前将更新推送给 DV360 买方。

允许和不允许的更改

如需详细了解交易协商和重新协商规则，请参阅 Display &Video 360 帮助中心文章：

• 重新协商有保证的程序化交易
• 在 Display &Video 360 中协商交易