Programática

Este guia é uma visão geral de como usar os recursos do Programático direto por meio da API. Ele descreve como criar uma proposta e como realizar negociação.

Primer

Uma proposta programática é semelhante a um pedido no Google Ad Manager. As propostas programáticas contêm informações abrangentes sobre uma transação proposta entre você e um comprador. Uma proposta e os respectivos itens de linha representam uma oferta de inventário para um comprador.

Para mais informações, consulte a Central de Ajuda.

Como criar uma proposta usando a API

Para criar um objeto Proposal, são necessários apenas o nome e o comprador programático. O ID do comprador programático pode ser encontrado na interface ou na tabela PQL 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 no 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 no GitHub

PHP

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

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

Ver no 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 no GitHub

Ruby

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

Ver no GitHub

Antes de enviar ao comprador para negociação, é necessário definir outros campos. A proposta precisa ter um anunciante, vendedor, coordenador de publicidade e contato do vendedor.

Java

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

Ver no GitHub

Python

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

Ver no 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 no 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 no GitHub

Ruby

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

Ver no GitHub

Como as propostas geralmente são compostas por objetos ProposalLineItem, a próxima etapa será adicionar itens de linha abaixo da sua proposta recém-criada.

Estados de uma proposta programática

A figura a seguir mostra uma proposta programática em vários pontos durante o processo de negociação do ponto de vista da API. Cada estado é representado por várias combinações dos seguintes campos:

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

Para mais informações, consulte a Central de Ajuda do Ad Manager.

Figura 1: estados de uma proposta programática

Tutorial de negociação

Aqui, vamos mostrar como usar a API para concluir a negociação de uma proposta programática com um comprador. Faremos referência aos estados no diagrama acima.

Preparação para a análise ou aceitação do comprador

Primeiro, é preciso criar uma proposta programática com os itens de linha da proposta que você quer enviar a um comprador. Isso é state C na figura acima.

Como solicitar a análise ou aceitação do comprador

Quando estiver tudo pronto para que o comprador revise a proposta programática, você poderá RequestBuyerReview ou RequestBuyerAcceptance usando o método ProposalService.performProposalAction. Isso levará você à fase de negociação.

Negociação

Nesta fase, várias coisas podem acontecer.

• O comprador pode aceitar sua proposta programática sem mudanças.
• O comprador pode propor mudanças. Nesse caso, a proposta será enviada de volta para o estado de rascunho (state B na Figura 1). Em seguida, abra a proposta para edição, faça as mudanças propostas e a envie novamente para análise do comprador.
• Também é possível fazer alterações antes mesmo de o comprador responder. Para fazer isso, abra a proposta de edição de state D na Figura 1.

Observação: quando uma proposta programática está aberta para edição (state A na Figura 1), ela não recebe atualizações do Marketplace automaticamente. Isso significa que, se o comprador fizer uma alteração antes de você solicitar a aceitação do comprador, você receberá a mensagem de erro NEW_VERSION_FROM_BUYER ao tentar solicitar a aceitação. Para corrigir isso, execute a ação DiscardProposalDrafts, que substituirá as edições locais pelas mudanças mais recentes do comprador no Marketplace. Em seguida, você vai precisar aplicar novamente as edições locais.

Essa negociação continua até você chegar a um acordo com o comprador. Os comentários entre você e o comprador podem ser recuperados usando getMarketplaceCommentsByStatement. É possível enviar um comentário para o comprador enquanto você estiver em state A. Para fazer isso, é necessário atualizar o campo marketplaceComment na proposta usando updateProposals. O comentário será enviado quando você solicitar a aceitação do comprador.

Finalizada

Quando você e o comprador aceitam a proposta programática, ela passa para o estado finalizado (state F na Figura 1). Em seguida, o Ad Manager cria itens de linha automaticamente a partir dessa proposta programática.

Na maioria dos casos, você já concluiu a proposta programática. No entanto, há duas ações que podem ser realizadas nesse estado:

• É possível reabrir a proposta programática para renegociação editando os campos relacionados à veiculação na proposta. Para isso, abra a proposta para edição (state E to A na Figura 1), faça mudanças e solicite a aceitação do comprador.
• É possível fazer edições relacionadas que não são exibidas, como atualizar o nome da proposta e refletir essas mudanças no pedido do Ad Manager e nos itens de linha criados com essa transação. Para fazer isso, edite o state E na Figura 1 e execute a ação UpdateOrderWithSellerData.