Serviço de pedido com limite de orçamento

Esse serviço está disponível apenas para as contas de administrador do Google AdWords presentes na lista de permissões que também foram configuradas para o faturamento mensal. Entre em contato com o seu representante do Google para receber mais informações sobre o uso desse serviço com a sua conta de administrador.

The BudgetOrderService (BOS) enables approved manager accounts to programmatically create account–level budgets for the client accounts they manage on consolidated billing. Isso permite que as contas de cliente apliquem a cobrança dos gastos à conta de faturamento de um administrador.

Com o uso da API, os administradores podem criar e gerenciar objetos BudgetOrder que definem os orçamentos em nível de conta para as contas de cliente. Cada BudgetOrder, por sua vez, é associado a um BillingAccount, que representa a configuração da fatura na qual as cobranças do cliente são feitas. Um administrador pode adicionar objetos BudgetOrder de várias contas do cliente ao mesmo BillingAccount para agrupar as cobranças em uma única configuração de fatura.

Terminologia

Veja os termos-chave a serem considerados durante a configuração do faturamento usando BOS.

Conta de cliente
Uma conta normal do Google AdWords que tem campanhas e grupos de anúncios, veicula anúncios etc. Também é possível referir-se a ela como "cliente", mas este guia usa o termo "conta de cliente" para evitar confusão com o termo "cliente de faturamento".
Conta de faturamento
As informações comuns necessárias para a criação das faturas relacionadas (o que também é conhecido como "configuração" da fatura). Isso inclui, por exemplo, a moeda das faturas e a entidade para a qual as faturas devem ser enviadas e pela qual devem ser pagas, além do nome de exibição impresso nas faturas para facilitar a consulta.
  • As contas de faturamento podem ser editadas na interface do Google AdWords na Web, mas não é possível criar ou editá-las com a AdWords API.
  • É importante ressaltar que a palavra "conta" na expressão "conta de faturamento" não representa um tipo especial de conta de cliente usado para faturamento. É simplesmente uma referência a um objeto que contém informações comuns usadas para gerar as faturas relacionadas.
  • Elas são representadas como um BillingAccount no BOS.
  • Elas podem ser referenciadas usando o campo id de um BillingAccount e o campo billingAccountId de um BudgetOrder.
Pedido com limite de orçamento
Uma autorização para uma conta de cliente específica gastar determinado valor ao longo de um determinado período, acumulando essa quantia em uma conta de faturamento específica.
  • Por exemplo, um pedido com limite de orçamento poderia trazer a seguinte mensagem: "A conta do Google AdWords 123-456-7890 tem autorização para gastar até R$ 100,00 em agosto. Essa quantia deve ser faturada usando as informações da conta de faturamento 1212-1234-3434-3434".
  • A mesma conta de faturamento pode ser usada por pedidos com limite de orçamento diferentes em várias contas de cliente. Em outras palavras, é possível ter diferentes contas de cliente cujos gastos sejam acumulados na mesma fatura, ou seja, em uma fatura consolidada: basta configurar os pedidos com limite de orçamento de modo que eles sejam faturados na mesma conta de faturamento.
  • Representado como um BudgetOrder no BOS.
Cliente de faturamento
A pessoa jurídica que tem autorização para receber e pagar uma fatura. Isso é análogo ao cliente pessoa física ou jurídica no nosso antigo sistema de faturamento.
  • Para criar um cliente de faturamento, entre em contato com o seu representante de atendimento ao cliente. Depois de criar pelo menos um cliente de faturamento e associá-lo à sua conta de administrador, você poderá começar a gerenciar "BudgetOrders" programaticamente.
  • Pode ser referenciado usando o campo primaryBillingId em um BillingAccount ou um BudgetOrder.

Relações administrador-cliente

Como o BOS foi criado para ser usado especificamente por contas de administrador, é importante entender a distinção entre o administrador que envia uma solicitação e a conta de cliente que ele está usando.

  • administrador: a conta de administrador pertencente ao usuário da API autenticado.
  • cliente: a conta de cliente cujo clientCustomerId é definido no campo de cabeçalho de uma solicitação.

Para associar clientes de faturamento a contas de administrador específicas, entre em contato com seu representante de atendimento ao cliente. Dessa forma, é possível criar um BudgetOrder para uma conta de cliente contanto que o administrador que faz a solicitação da API:

  • tenha acesso à conta de administrador que contém um cliente de faturamento específico;
  • tenha acesso à conta de cliente que deve usar o cliente de faturamento;
  • esteja na lista de permissões para o serviço BudgetOrderService.

Por exemplo, ao autenticar com a conta de administrador A acima, você consegue adicionar o cliente 123-456-7890 aos BillingAccounts associados a qualquer conta de administrador da hierarquia. Isso ocorre porque a conta de administrador de nível superior pode acessar a conta de administrador B, a conta de administrador C e a conta de cliente.

Faça a autenticação com a conta de administrador de nível mais alto disponível para garantir acesso às contas de administrador e clientes que deseja gerenciar.

Como listar os BillingAccounts disponíveis

É possível recuperar uma lista de BillingAccounts que podem ser acessados pelo administrador autenticado usando a operação getBillingAccounts() do BudgetOrderService. Cada objeto BillingAccount representa uma configuração de fatura vinculada a uma conta de administrador dos responsáveis pela conta de cliente desejada. Esses são os BillingAccounts que podem ser usados por BudgetOrders da conta de cliente desejada.

Por exemplo, se você quiser ver uma lista dos BillingAccounts que podem ser usados pelo cliente 123-456-7890, faça a autenticação usando uma das contas de administrador pais para chamar getBillingAccounts(). Usando Java com as nossas bibliotecas de cliente, você executaria o código a seguir:

session.setClientCustomerId("123-456-7890");
BudgetOrderServiceInterface bos = services.get(session, BudgetOrderServiceInterface.class);
BillingAccount[] accts = bos.getBillingAccounts();

O administrador usado para a autenticação pode influenciar quais BillingAccounts são retornados por uma chamada para getBillingAccounts(). A operação retornará os BillingAccounts associados a todos os administradores de um determinado cliente. No entanto, essa operação terá o mesmo nível de permissão do administrador autenticado.

Por exemplo, se as duas contas de administrador A e C citadas acima tiverem BillingAccounts ativos, a chamada de getBillingAccounts() com a conta A para clientCustomerId 123-456-7890 retornará os dois conjuntos. No entanto, se a chamada for feita com a conta C, somente os BillingAccounts de C serão visíveis.

Cada objeto BillingAccount tem um ID e um primaryBillingId. O ID é o identificador único do BillingAccount e também é conhecido como billingAccountId em outros objetos. O primaryBillingId identifica o cliente de faturamento responsável pelo pagamento das cobranças da fatura.

O primaryBillingId também é encontrado na IU (interface do usuário) do Google AdWords identificado como "Quem paga", em Faturamento > Configurações de pagamento.

Como criar um novo BudgetOrder

Para adicionar um cliente a um dos BillingAccounts acessíveis, crie um BudgetOrder para definir o orçamento em nível de conta. Isso inclui detalhes como os horários de início e de término e os limites de gastos do cliente.

Depois de recuperar os BillingAccounts acima, você pode criar um novo orçamento em nível de conta para o mês de agosto, com um limite de gastos de R$ 100,00, que usa o primeiro BillingAccount retornado no exemplo anterior:

BillingAccount acct = accts[0];
BudgetOrder order = new BudgetOrder();
order.setBillingAccountId(acct.getId());
order.setStartDateTime("20140801 000000 America/New_York");
order.setEndDateTime("20140831 235959 America/New_York");
Money amt = new Money();
amt.setMicroAmount(100000000L);  // $100 in micros
order.setSpendingLimit(amt);

BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.ADD);
op.setOperand(order);
BudgetOrderReturnValue response = bos.mutate(new BudgetOrderOperation[] {op});

O BudgetOrderReturnValue retornado pela operação de modificação contém o código do novo BudgetOrder. O BudgetOrder contém um campo lastRequest que inclui informações sobre o status da solicitação. Os BudgetOrder enviados recentemente recebem um status de UNDER_REVIEW até serem aprovados e se tornarem ativos.

Pode levar algum tempo (normalmente menos de uma hora) para que os BudgetOrders se tornem ativos. Dessa forma, é melhor criá-los com antecedência em relação ao startDateTime desejado. Somente um BudgetOrder pode estar ativo para um cliente em determinado momento, mas é possível criar orçamentos futuros e colocá-los na fila a qualquer momento. Por exemplo, você pode criar os BudgetOrders de setembro e outubro do clientCustomerId 123-456-7890 imediatamente após o BudgetOrder de agosto criado acima.

Como não pode haver mais de um BudgetOrder em vigor ao mesmo tempo, configure os campos startDateTime e endDateTime de um novo BudgetOrder de forma que eles não coincidam com a duração de outro BudgetOrder existente (ativo ou pendente no futuro). É importante destacar que os valores startDateTime e endDateTime definem um intervalo fechado, ou seja, a duração do BudgetOrder inclui o startDateTime e o endDateTime. No exemplo acima, o endDateTime é 20140831 235959 America/New_York para não haver sobreposição com um BudgetOrder em potencial para setembro com um startDateTime de 20140901 000000 America/New_York. Se você tentar criar um BudgetOrder cuja duração esteja em sobreposição com outro BudgetOrder da mesma conta, ocorrerá um erro INVALID_BUDGET_DATE_RANGE.

Conforme ilustrado no exemplo acima, o startDateTime e o endDateTime são especificados até a casa dos segundos. Para a maioria dos casos de uso, o fuso horário deve ser o dateTimeZone do cliente.

Como editar um BudgetOrder

Para atualizar um BudgetOrder existente, referencie o ID dele em uma operação de modificação. É sempre recomendável atualizar um BudgetOrder existente em vez de criar um novo, pois existe um limite do número de BudgetOrders que podem usar determinado BillingAccount.

É possível aumentar o limite de gastos e a duração do orçamento em nível de conta criados na seção anterior. Para fazer isso, atualize o objeto BudgetOrder existente com novos valores spendingLimit e endDateTime:

Long existingId = response.getValue()[0].getId();
BudgetOrder existingOrder = new BudgetOrder();
existingOrder.setId(existingId);
Money newAmt = new Money();
newAmt.setMicroAmount(200000000L);
existingOrder.setSpendingLimit(newAmt);
existingOrder.setEndDateTime("20140930 235959 America/New_York");

BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.SET);
op.setOperand(order);
bos.mutate(new BudgetOrderOperation[] {op});

Você também pode reduzir o limite de gastos de um BudgetOrder. No entanto, não é possível defini-lo como uma quantia menor do que o que já foi gasto pelo pedido.

Limites e ajustes de gastos

Quando você modifica o limite de gastos de um BudgetOrder, também é importante lembrar-se de alguns ajustes. Os ajustes são créditos aplicados ao pedido com limite de orçamento que permitem um gasto maior do que seu limite normal, mas sem custos adicionais.

Nas solicitações mutate(), o limite de gastos não leva os ajustes em consideração. O valor enviado será considerado como o valor que você deseja gastar antes de qualquer ajuste. No entanto, nas solicitações get(), o spendingLimit inclui os ajustes feitos no seu BudgetOrder. Se você quiser definir seu limite de gastos em comparação com um limite enviado anteriormente, inclua os ajustes.

Como remover um BudgetOrder

O serviço BudgetOrder é encerrado quando alcança o fim do período de validade ou quando é ativamente cancelado. Depois que um BudgetOrder for encerrado, será necessário criar um novo para reativar os gastos de uma conta de cliente.

Para cancelar um BudgetOrder ativo, envie uma solicitação de operação REMOVE para o serviço pela API. Esse processo definirá o endDateTime como o horário atual, o que encerra o período do orçamento e evita novos gastos.

BudgetOrder o = new BudgetOrder();
o.setId(budgetOrderId);
BudgetOrderOperation op = new BudgetOrderOperation();
op.setOperator(Operator.REMOVE);
op.setOperand(o);
bos.mutate(new BudgetOrderOperation[] {op});

Como alterar o cliente de faturamento

Para alterar o cliente de faturamento responsável pelos pagamentos de uma conta de cliente, crie um BudgetOrder que aponte para um dos novos BillingAccounts do cliente de faturamento. No entanto, uma conta de cliente pode ter somente uma dessas operações de Alteração do faturado (CBT, na sigla em inglês) pendente.

Por exemplo, para alterar o responsável pelos pagamentos do cliente 123-456-7890 após a expiração do BudgetOrder de agosto, você pode adicionar um novo BudgetOrder para setembro que use uma BillingAccount vinculada a um novo cliente de faturamento. No entanto, como somente uma operação de CBT pode ser programada para a conta de cliente, todos os BudgetOrders subsequentes precisam usar esse novo cliente de faturamento.

Limitações

Descrição Valor Erro Observações
Objetos BudgetOrder por BillingAccount 75.000 BudgetOrderError.GENERIC_BILLING_ERROR, trigger: TOO_MANY_ORDER_LINES_NEW_BILLING_ACCOUNT_REQUIRED

Há um número máximo de 75.000 BudgetOrders por BillingAccount.

Se você atingiu esse limite, crie uma nova configuração de fatura na IU do Google AdWords e adicione os BudgetOrders futuros à nova BillingAccount.

Operações por solicitação de modificação 1 BudgetOrderError.MORE_THAN_ONE_OPERATIONS É preciso enviar várias operações em solicitações separadas.
Solicitações por segundo 1 RateExceededError.RATE_EXCEEDED

O limite de taxa para esse serviço é de 1 qps.

As solicitações devem ser enviadas a uma frequência de uma por segundo. Evite o envio de solicitações simultaneamente.

Erros comuns

Erro Observações e soluções alternativas
BudgetOrderError.INVALID_BUDGET_DATE_RANGE, trigger: Overlapping budget found

Não é possível criar objetos BudgetOrder em sobreposição.

Altere o startDateTime ou o endDateTime do BudgetOrder de modo que ele não se sobreponha a outro orçamento ativo ou pendente.

Se você tentou criar um novo pedido com limite de orçamento usando a interface de usuário do Google AdWords, é possível que esse processo não tenha sido concluído e tenha um pedido com limite de orçamento pendente. Finalize a criação do pedido na IU ou entre em contato com a equipe de suporte da AdWords API para receber ajuda.

BudgetOrderError.INVALID_BUDGET_ALREADY_SPENT

Não é possível definir um limite de gastos abaixo da quantia gasta em um determinado período.

Defina o spendingLimit do BudgetOrder como um valor maior do que a quantia gasta entre o startDateTime e o endDateTime do BudgetOrder.

BudgetOrderError.CUSTOMER_NOT_WHITELISTED_FOR_NEW_BILLING

O faturamento consolidado não foi ativado para a sua conta de administrador.

Entre em contato com o seu representante do Google para ativar o faturamento consolidado para a sua conta.

NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_API

A conta de administrador não foi colocada na lista de permissões para usar a BudgetOrderService da API.

Entre em contato com o seu representante do Google para receber acesso ao serviço da API.

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.