API 工作流程

创建交易

1. 通过使用 external_deal_id 过滤条件列出商品，查看是否已创建商品。External_deal_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. partner_id 不允许更新。
2. 更新特定交易条款更新的商品。
   1. 无法更新 name、externalDealId、transactionType、pricingType、updateTime。
   2. 更新显示名称不需要用户接受。
   3. 更新 rateDetails 后，creativeConfig 会将父订单状态更改为“待接受”。无论之前的订单是否已被接受，DV3 广告客户都需在协商页面中接受新条款。

查看用户是否已接受交易

1. 如果您知道相应的订单 ID，请使用 Get Order。检查状态字段。
2. 如果未跟踪订单 ID：列出带有 external_deal_id 过滤条件的商品，根据商品名称确定订单名称，然后获取订单。检查状态字段。

查看用户是否已配置特惠（仅限 PG）

1. 获取广告资源来源。名称为“exchanges/{exchangeId}/inventorysources/{external_deal_id}”。请查看买方状态。
   1. 预订优惠
      1. BUYER_STATUS_ACTIVE 表示交易已被接受并已配置。当 DV3 收到与交易条款匹配的出价请求时，交易预计会处于此状态。在“交易配置”步骤中，系统会自动生成订单项。如需了解详情，请参阅交易配置。
      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. 暂停/取消暂停不会影响交易投放。如果卖家暂停交易，系统只会向广告客户显示一条字符串消息，供其参考。这有助于广告客户排查未产生支出的交易。

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

重新协商是指在买方接受交易后对交易进行的更新。这对于交易所和买方将新更改推送到已接受的交易都非常有用。例如，交易平台可能会发现已接受的交易的结束时间不正确，如果交易尚未开始，交易平台可以使用 DV3 Update Product 将更新推送给 DV3 买方。

允许和不允许进行哪些更改。

我们允许更改所有字段，但一些投放关键字段（例如 startTime、endTime、rateDetails、creativeConfig 等）除外。我们会对这些投放关键字段进行验证。一般来说，如果交易的开始时间至少在 1 天后，则允许更新这些字段（creativeConfig 除外）。对于开始时间在过去但结束时间在未来的有效交易，只允许进行增量更新。对于已完成的交易（结束时间为过去的时间），不允许进行任何更改。例如，不允许更新一年前完成的交易的 rateDetails。在这种情况下，DV3 更新产品会抛出验证错误。