Workflows des API

Ce guide décrit les workflows d'API courants pour créer, annuler, récupérer, modifier et négocier des accords à l'aide de l'API Deal Sync.

Créer un accord

  1. Vérifiez si un produit a déjà été créé en appelant LIST products avec le externalDealId filtre. Notez que camelCase externalDealId et snake_case external_deal_id sont acceptés dans la chaîne de filtre. external_deal_id doit être unique pour tous les produits.

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

  2. Créer une commande. Le nom de la commande est généré par DV360. Nous vous recommandons de stocker cet ID dans votre système pour pouvoir le récupérer ultérieurement.

  3. Créez un produit dans la commande. Le nom du produit est généré par DV360. Nous vous recommandons de stocker cet ID dans votre système pour pouvoir le récupérer ultérieurement.

Vous pouvez également appeler LIST avec external_deal_id. Le nom de la ressource contient l'ID de la commande et l'ID du produit. Vous pouvez donc identifier la commande parente.

Annuler un accord

  1. Définissez l'état de la commande sur CANCELED. L'annulation n'est possible que si la commande n'a pas encore été acceptée. L'état "Annulé" est un état final. Une commande ne peut pas être réactivée une fois annulée. Si la commande contenait des produits, leur external_deal_id ne peut pas être réutilisé.

Obtenir les détails d'un accord

  1. Obtenez les détails d'une commande. L'état est mis à jour une fois que l'utilisateur a accepté, archivé ou annulé la commande.
  2. Obtenez les détails d'un produit.

Obtenir la liste des accords

  1. LIST commandes avec un filtre d'état pour obtenir toutes les commandes acceptées ou en attente d'acceptation commandes.
  2. LIST les produits avec le external_deal_id filtre.
  3. LISTez tous les produits d'une commande.

Modifier un accord

  1. Modifiez la commande pour les coordonnées de l'éditeur.
    1. name ne peut pas être modifié (il ne peut pas être défini dans updateMask). L'état ne peut être défini sur CANCELED qu'à l'aide de l'API.
    2. partner_id ne peut pas être modifié.
  2. Mettre à jour le produit pour une mise à jour spécifique des conditions de l'accord.
    1. name, externalDealId, transactionType, pricingType, et updateTime ne peuvent pas être modifiés.
    2. La modification de displayName ne nécessite pas que l'utilisateur accepte à nouveau.
    3. La modification de rateDetails ou de creativeConfig fait passer l'état de la commande parente à PENDING_ACCEPTANCE. Les annonceurs DV360 seront invités à accepter les nouvelles conditions sur la page "Négociations", que la commande précédente ait déjà été acceptée ou non.

Vérifier si l'utilisateur a accepté l'accord

  1. Obtenez la commande si vous connaissez le nom de commande correspondant. Vérifiez le champ status.
  2. Si le nom de la commande n'a pas été suivi : listez les produits avec le filtre external_deal_id, identifiez le nom de la commande à partir du nom du produit, puis appelez Get Order. Vérifiez le champ status.

Vérifier si l'utilisateur a configuré l'accord (programmatique garanti uniquement)

  1. Obtenez la source d'inventaire. Le nom de la ressource est exchanges/{exchangeId}/inventorysources/{external_deal_id}. Vérifiez l'état de l'acheteur.
    1. Accords de réservation
      1. BUYER_STATUS_ACTIVE : l'accord a été accepté et configuré. Les dépenses commenceront lorsque DV360 recevra des demandes d'enchères correspondant aux conditions de l'accord. Un élément de campagne est généré automatiquement lors de la configuration de l'accord. Pour en savoir plus, consultez Configuration de l'accord.
      2. BUYER_STATUS_PENDING: la commande a été acceptée, mais l'accord n'a pas encore été configuré. Aucune dépense n'est effectuée dans cet état.
      3. BUYER_STATUS_PAUSED : l'accord a été mis en veille par l'annonceur. Aucune dépense n'est effectuée dans cet état.
    2. Accords sans réservation
      1. BUYER_STATUS_ACTIVE : l'accord a été accepté. Les dépenses commenceront lorsque DV360 recevra des demandes d'enchères correspondantes, qu'un élément de campagne actif ciblera l'accord et que les demandes d'enchères correspondront aux critères de ciblage de l'élément de campagne. Pour en savoir plus, consultez Line Items for details. (Remarque : Il n'existe pas d'API Vendeur permettant de vérifier si un accord est ciblé par des éléments de campagne).
      2. BUYER_STATUS_PENDING : ne s'applique pas aux accords sans réservation.
      3. BUYER_STATUS_PAUSED: l'accord a été explicitement mis en veille par l'annonceur. Aucune dépense n'est effectuée dans cet état.

Mettre en veille et réactiver un accord après son acceptation

  1. Mettre à jour l'état du vendeur de la source d'inventaire.
    1. La mise en veille ou la réactivation n'interrompt pas la diffusion de l'accord. Lorsqu'un vendeur met en veille un accord, un message d'information s'affiche pour les annonceurs dans l'interface utilisateur DV360 afin de les aider à résoudre les problèmes liés aux accords qui n'entraînent pas de dépenses.

Renégociation (modification d'un accord après son acceptation)

La renégociation fait référence aux modifications apportées à un accord après qu'il a été accepté par l'acheteur. Cela permet aux Ad Exchanges et aux acheteurs d'ajuster les conditions des accords existants. Par exemple, un Ad Exchange peut constater que l'heure de fin de diffusion d'un accord accepté est incorrecte. Il peut alors utiliser Product Patch pour envoyer des mises à jour aux acheteurs DV360 avant le début de la diffusion de l'accord.

Modifications autorisées et interdites

Consultez les articles du Centre d'aide Display &Video 360 pour obtenir une description complète des règles de négociation et de renégociation des accords :

Précédent
Structure de l'entité
Suivant
Processus bêta