Programática

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

Primer

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

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

Como criar uma proposta pela API

Para criar um objeto Proposal, apenas o nome e o comprador programático são obrigatórios. O ID do comprador programático pode ser obtido na interface ou na tabela Programmatic_Buyer da PQL.

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, um vendedor, um coordenador de publicidade e contatos 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 é adicionar itens de linha da proposta à 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 uma negociação de uma proposta programática com um comprador. Vamos consultar os estados no diagrama acima.

Preparação para revisão ou aceitação do comprador

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

Solicitar revisão ou aceitação do comprador

Quando estiver tudo pronto para o comprador analisar a proposta programática, você poderá RequestBuyerReview ou RequestBuyerAcceptance usando o método ProposalService.performProposalAction. Isso vai levar você para a 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, você precisará abrir a proposta para edição, fazer as mudanças propostas e enviá-la de volta para revisão do comprador.
• Você também pode fazer mudanças antes mesmo de o comprador responder. Para isso, abra a proposta para edição em 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 automáticas do Marketplace. Isso significa que, se o comprador fizer uma mudança antes de você solicitar a aceitação, você vai receber a mensagem de erro NEW_VERSION_FROM_BUYER ao tentar solicitar a aceitação. Para corrigir isso, execute a ação DiscardProposalDrafts, que vai substituir suas edições locais pelas mudanças mais recentes do comprador no Marketplace. Depois, você precisará aplicar novamente as edições locais.

Essa negociação continua até que vocês cheguem a um acordo com o comprador. Os comentários entre você e o comprador podem ser recuperados usando getMarketplaceCommentsByStatement. Você pode enviar um comentário ao comprador enquanto estiver em state A. Para fazer isso, atualize 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 entra em um estado finalizado (state F na Figura 1). Em seguida, o Ad Manager cria automaticamente itens de linha com base nessa 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 as mudanças e solicite a aceitação do comprador.
• É possível fazer edições não veiculadas, como atualizar o nome da proposta, e refletir essas mudanças no pedido e nos itens de linha do Ad Manager criados com base nessa transação. Para isso, edite o state E na Figura 1 e execute a ação UpdateOrderWithSellerData.