Programática

Esta guía es una descripción general de alto nivel sobre el uso de funciones de Programática directa a través de la API. Describe cómo crear una propuesta y cómo realizar una negociación.

Primer

Una propuesta programática es similar a un pedido en Google Ad Manager. Las propuestas programáticas contienen información amplia sobre una transacción propuesta entre tú y un comprador. Una propuesta, junto con sus líneas de pedido, representa una oferta de inventario para un comprador.

Para obtener más información, consulte el Centro de ayuda.

Cómo crear una propuesta a través de la API

Para crear un objeto Proposal, solo se requieren el nombre y el comprador programático. El ID del comprador programático se puede obtener a través de la IU o la tabla de PQL de Programmatic_Buyer.

Java

Proposal proposal = new Proposal();

// Setting required Marketplace information.
ProposalMarketplaceInfo proposalMarketplaceInfo = new ProposalMarketplaceInfo();
proposalMarketplaceInfo.setBuyerAccountId(programmaticBuyerId);

// Set common required fields for a proposal.
proposal.setName("Proposal #" + new Random().nextInt(Integer.MAX_VALUE));
proposal.setPrimaryTraffickerId(primaryTraffickerId);
proposal.setMarketplaceInfo(proposalMarketplaceInfo);
    

Ver en GitHub

Python

proposal = {
    # Setting required Marketplace information.
    'isProgrammatic': 'true',
    'marketplaceInfo': {
        'buyerAccountId': programmatic_buyer_id,
    },
    # Set common required fields for proposals.
    'name': 'Proposal #%s' % uuid.uuid4(),
    # ...
}
    

Ver en GitHub

PHP

$proposal = new Proposal();
$proposal->setName('Proposal #' . uniqid());

// Set the required Marketplace information.
$proposalMarketplaceInfo = new ProposalMarketplaceInfo();
$proposalMarketplaceInfo->setBuyerAccountId($buyerId);
$proposal->setMarketplaceInfo($proposalMarketplaceInfo);
    

Ver en GitHub

C#

// Create a proposal with the minimum required fields.
Proposal proposal = new Proposal()
{
    name = "Programmatic proposal #" + new Random().Next(int.MaxValue),
    // Set required Marketplace information
    marketplaceInfo = new ProposalMarketplaceInfo()
    {
        buyerAccountId = programmaticBuyerId
    }
};
    

Ver en GitHub

Ruby

# Create proposal configuration object.
proposal = {
  :marketplace_info => {
    :buyer_account_id => buyer_id
  },
  :name => 'Proposal %s' % SecureRandom.uuid(),
  # ...
}
    

Ver en GitHub

Antes de enviar al comprador para la negociación, se deben establecer campos adicionales. La propuesta debe tener contactos de anunciante, vendedor, coordinador de anuncios y vendedor.

Java

SalespersonSplit primarySalesperson = new SalespersonSplit();
primarySalesperson.setUserId(primarySalespersonId);
proposal.setPrimarySalesperson(primarySalesperson);
    

Ver en GitHub

Python

'primarySalesperson': {
    'userId': primary_salesperson_id,
},
'primaryTraffickerId': primary_trafficker_id,
'probabilityOfClose': '100000',
    

Ver en GitHub

PHP

// Create salesperson splits for the primary salesperson.
$primarySalesperson = new SalespersonSplit();
$primarySalesperson->setUserId($primarySalespersonId);
$proposal->setPrimarySalesperson($primarySalesperson);

// Set the primary trafficker on the proposal for when it becomes an
// order.
$proposal->setPrimaryTraffickerId($primaryTraffickerId);

$advertiser = new ProposalCompanyAssociation();
$advertiser->setType(
    ProposalCompanyAssociationType::ADVERTISER
);
$advertiser->setCompanyId($advertiserId);
$proposal->setAdvertiser($advertiser);
    

Ver en GitHub

C#

// Set fields that are required before sending the proposal to the buyer.
proposal.primaryTraffickerId = primaryTraffickerId;
proposal.sellerContactIds = new long[] { primarySalespersonId };
proposal.primarySalesperson = new SalespersonSplit()
{
    userId = primarySalespersonId,
};
proposal.advertiser = new ProposalCompanyAssociation()
{
    type = ProposalCompanyAssociationType.ADVERTISER,
    companyId = advertiserId
};
    

Ver en GitHub

Ruby

:primary_salesperson => {
  :user_id => primary_salesperson_id
},
:primary_trafficker_id => primary_trafficker_id
    

Ver en GitHub

Dado que las propuestas generalmente están compuestas por objetos ProposalLineItem, el siguiente paso sería agregar líneas de pedido propuestas debajo de la propuesta recién creada.

Estados de una propuesta programática

En la siguiente figura, se muestra una propuesta programática en varios momentos del proceso de negociación desde el punto de vista de la API. Cada estado se representa con varias combinaciones de los siguientes campos:

• ProposalMarketplaceInfo.hasLocalVersionEdits
• ProposalMarketplaceInfo.negotiationStatus
• Proposal.status

Para obtener más información, consulta el Centro de ayuda de Ad Manager.

Figura 1: Estados de una propuesta programática

Explicación de la negociación

A continuación, te indicamos cómo usar la API para completar una negociación para una propuesta programática con un comprador. Haremos referencia a los estados en el diagrama anterior.

Cómo prepararse para la revisión o aceptación del comprador

Primero, debes crear un borrador de una propuesta programática con líneas de pedido propuestas que quieras enviar a un comprador. Es state C en la figura anterior.

Solicitar la revisión o aceptación del comprador

Una vez que estés listo para que el comprador revise la propuesta programática, puedes RequestBuyerReview o RequestBuyerAcceptance con el método ProposalService.performProposalAction. Esto te llevará a la fase de negociación.

Negociación

En esta fase, pueden ocurrir varias cosas.

• Es posible que el comprador acepte su propuesta programática sin realizar cambios.
• El comprador puede proponer cambios. En este caso, la propuesta se enviará de vuelta al estado de borrador (state B en la Figura 1). Luego, deberás abrir la propuesta para editarla, realizar los cambios propuestos y enviarla de vuelta para que la revise el comprador.
• También puedes decidir realizar cambios incluso antes de que el comprador responda. Puedes hacerlo abriendo la propuesta para editar desde state D en la Figura 1.

Nota: Cuando una propuesta programática esté abierta para su edición (state A en la Figura 1), no recibirá actualizaciones de Marketplace automáticamente. Esto significa que, si el comprador realiza un cambio antes de que solicites la aceptación del comprador, recibirás el mensaje de error NEW_VERSION_FROM_BUYER cuando intentes solicitar la aceptación del comprador. Para solucionar este problema, realiza la acción DiscardProposalDrafts, que reemplazará tus ediciones locales con los últimos cambios de comprador de Marketplace. Luego, deberás volver a aplicar los cambios locales.

Esta negociación continúa hasta que llega a un acuerdo con el comprador. Los comentarios entre tú y el comprador se pueden recuperar con getMarketplaceCommentsByStatement. Puedes enviarle un comentario al comprador desde state A. Para hacer esto, deberás actualizar el campo marketplaceComment en la propuesta mediante updateProposals. El comentario se enviará cuando solicites la aceptación del comprador.

Finalizada

Cuando tanto tú como el comprador hayan aceptado la propuesta programática, esta entra en el estado finalizado (state F en la Figura 1). Luego, Ad Manager crea automáticamente líneas de pedido a partir de esta propuesta programática.

En la mayoría de los casos, ya terminaste con la propuesta programática. Sin embargo, hay dos acciones que puedes realizar desde este estado:

• Puedes reabrir la propuesta programática para su renegociación; para ello, edita los campos relacionados con la entrega en la propuesta. Puedes hacerlo abriendo la propuesta para editarla (state E to A en la Figura 1), realizando cambios y, luego, solicitando la aceptación del comprador.
• Puedes realizar ediciones no relacionadas con la publicación, como actualizar el nombre de la propuesta y reflejar estos cambios en el pedido de Ad Manager y las líneas de pedido creadas a partir de este acuerdo. Para ello, edita desde state E en la Figura 1 y, luego, realiza la acción UpdateOrderWithSellerData.