Служба BudgetOrderService

Эта служба доступна только в управляющих аккаунтах AdWords с кредитной линией. Дополнительную информацию можно получить у представителя Google.

The BudgetOrderService (BOS) enables approved manager accounts to programmatically create account–level budgets for the client accounts they manage on consolidated billing. Благодаря этому менеджер может оплачивать расходы по клиентским аккаунтам через свой управляющий аккаунт.

С помощью API менеджеры могут создавать объекты BudgetOrder и управлять ими. Эти объекты определяют бюджеты на уровне аккаунта для клиентских аккаунтов. Каждый объект BudgetOrder, в свою очередь, связывается с объектом BillingAccount. Он представляет платежный аккаунт, на который выставляются счета по клиентским аккаунтам. Менеджер может добавить объекты BudgetOrder из нескольких клиентских аккаунтов в один объект BillingAccount, чтобы объединить расходы по этим аккаунтам.

Терминология

Вот основные термины, которые вам следует знать при настройке оплаты с помощью BOS.

Клиентский аккаунт
Стандартный аккаунт AdWords с кампаниями, группами объявлений, объявлениями и т. д. То же самое, что "клиент" или "аккаунт клиента".
Платежный аккаунт
Набор данных, необходимых для создания счетов. К ним в том числе относятся: валюта, получатель счетов (организация, которой нужно отправлять счета) и отображаемое название, которое будет значиться в счетах.
  • Информацию в платежных аккаунтах можно редактировать через веб-интерфейс AdWords. Ее нельзя указывать или изменять с помощью AdWords API.
  • Обратите внимание, что "аккаунт" в названии "платежный аккаунт" не означает какой-то особый клиентский аккаунт – это просто объект, содержащий информацию, которая используется при выставлении счетов.
  • Платежные аккаунты в BOS представлены объектами BillingAccount.
  • Для ссылки на платежные аккаунты можно использовать поле id в объекте BillingAccount и поле billingAccountId в объекте BudgetOrder.
Заказ бюджета
Разрешение для определенного клиентского аккаунта потратить заданную максимальную сумму за указанный период. Расходы начисляются в определенный платежный аккаунт.
  • Например, в заказе бюджета может быть указано "В аккаунте AdWords 123-456-7890 можно потратить за август до 100 долларов США. Эти расходы должны начисляться в платежный аккаунт 1212-1234-3434-3434".
  • Один платежный аккаунт можно использовать для разных заказов бюджета в нескольких клиентских аккаунтах. Иначе говоря, в один счет (он называется единым) могут добавляться расходы по нескольким клиентским аккаунтам. Для этого в заказах бюджета необходимо указать один и тот же платежный аккаунт.
  • Платежный аккаунт в BOS представлен объектом BudgetOrder.
Плательщик
Юридическое лицо, которое может получать и оплачивать счета. То же самое, что "юридическое лицо" в старой платежной системе.
  • Чтобы указать плательщика, обратитесь к представителю службы поддержки. Когда хотя бы один плательщик будет создан и связан с вашим управляющим аккаунтом, вы сможете работать с заказами бюджета программным путем.
  • Для ссылки на плательщика используйте поле primaryBillingId в объекте BillingAccount или BudgetOrder.

Взаимосвязь между менеджером и клиентом

Поскольку служба заказов бюджета предназначена специально для управляющих аккаунтов, важно понимать различие между менеджером, отправляющим запрос, и клиентским аккаунтом, от имени которого этот менеджер действует.

  • Менеджер: управляющий аккаунт, принадлежащий пользователю API, прошедшему аутентификацию.
  • Клиент: клиентский аккаунт, идентификатор (clientCustomerId) которого указан в поле заголовка запроса.

Плательщики связываются с управляющими аккаунтами представителем службы поддержки Google. Для клиентского аккаунта может быть создан BudgetOrder, если менеджер, выполняющий запрос к API:

  • имеет доступ к управляющему аккаунту, к которому относится этот плательщик;
  • имеет доступ к соответствующему клиентскому аккаунту;
  • внесен в белый список для службы BudgetOrderService.

Например, выполнив аутентификацию в качестве менеджера аккаунта A, вы сможете добавить клиента 123-456-7890 в платежные аккаунты (BillingAccounts), связанные с любым управляющим аккаунтом в дереве, так как управляющий аккаунт верхнего уровня может получать доступ к обоим управляющим аккаунтам (B и C), а также к клиентскому аккаунту.

Выполняйте аутентификацию для аккаунта высшего уровня, чтобы у вас был доступ к управляющим и клиентским аккаунтам, с которыми вы хотите работать.

Получение списка доступных платежных аккаунтов

Чтобы получить список объектов BillingAccounts, доступных менеджеру, прошедшему аутентификацию, используйте операцию getBillingAccounts() службы BudgetOrderService. Каждый объект BillingAccount представляет платежный аккаунт, связанный с управляющим аккаунтом, который принадлежит менеджеру целевого клиентского аккаунта. Эти объекты BillingAccount могут использоваться в BudgetOrders целевого клиентского аккаунта.

Например, чтобы получить список объектов BillingAccounts, доступных клиенту 123-456-7890, вызовите getBillingAccounts(), выполнив аутентификацию для одного из управляющих аккаунтов верхнего уровня. Пример (Java + клиентские библиотеки):

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

От того, в качестве какого менеджера вы пройдете аутентификацию зависит, какие объекты BillingAccounts будут возвращены в ответ на вызов getBillingAccounts(). Эта операция возвращает платежные аккаунты (BillingAccounts), связанные со всеми менеджерами определенного клиента, но только если они не находятся в иерархии выше, чем менеджер, прошедший аутентификацию.

Например, если активные платежные аккаунты (BillingAccounts) есть в двух управляющих аккаунтах, A и C, то в результате вызова getBillingAccounts() от менеджера A для clientCustomerId 123-456-7890 вы получите оба набора данных. Однако если вызов будет выполнен менеджером C, будут возвращены только платежные аккаунты (BillingAccounts) для C.

У каждого объекта BillingAccount есть два идентификатора: ID и primaryBillingId. ID идентифицирует платежный аккаунт (BillingAccount) и называется billingAccountId в других объектах, а primaryBillingId идентифицирует плательщика.

Идентификатор primaryBillingId также можно найти в интерфейсе AdWords под заголовком "Кто платит" в разделе Оплата > Платежные настройки.

Создание объекта BudgetOrder

Чтобы добавить клиента в один из доступных платежных аккаунтов (BillingAccounts), создайте объект BudgetOrder, определяющий бюджет на уровне аккаунта, в том числе начало и окончание действия, а также предел расходов для клиента.

Вернемся к примеру выше. Получив доступные объекты BillingAccounts, мы можем создать бюджет на уровне аккаунта на август с пределом затрат в 100 долларов США. Для этого бюджета будет использоваться первый платежный аккаунт (BillingAccount), полученный на предыдущем шаге:

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});

Контейнер BudgetOrderReturnValue, полученный от операции mutate, будет содержать идентификатор нового BudgetOrder. Этот объект BudgetOrder будет включать поле lastRequest с информацией о статусе запроса. Новые объекты BudgetOrder имеют статус UNDER_REVIEW до тех пор, пока заказы бюджета не будут одобрены и активированы.

Может пройти некоторое время (обычно меньше часа), прежде чем новые BudgetOrders вступят в силу, поэтому лучше создать их заранее, с хорошим запасом по времени до даты начала (startDateTime). Одновременно для каждого клиента может быть активен только один BudgetOrder, однако создавать и ставить в очередь будущие бюджеты можно когда угодно. Например, вы можете создать заказы бюджета (объекты BudgetOrder) на сентябрь и октябрь для clientCustomerId 123-456-7890 сразу же после августовского BudgetOrder.

В каждый момент времени может действовать только один BudgetOrder, поэтому убедитесь, что значения в полях startDateTime и endDateTime нового объекта BudgetOrder не входят в период действия существующего BudgetOrder (активного или запланированного). Имейте в виду, что startDateTime и endDateTime определяют закрытый интервал: период действия BudgetOrder включает startDateTime и endDateTime. В нашем примере время окончания (endDateTime) – 20140831 235959 America/New_York, так что оно не пересекается с периодом действия запланированного BudgetOrder на сентябрь (startDateTime – 20140901 000000 America/New_York). При попытке создать BudgetOrder, который пересекается по времени действия с другим BudgetOrder для того же аккаунта, вы получите ошибку INVALID_BUDGET_DATE_RANGE.

Как видно из примера выше, startDateTime и endDateTime указываются с точностью до секунды. В большинстве случаев в качестве часового пояса будет использоваться dateTimeZone клиента.

Изменение объекта BudgetOrder

Чтобы обновить существующий заказ бюджета (BudgetOrder), укажите его идентификатор в операции mutate. Всегда лучше изменить имеющийся BudgetOrder, а не создавать новый, поскольку существует лимит на количество объектов BudgetOrder для одного платежного аккаунта (BillingAccount).

В нашем примере мы можем увеличить предел расходов и время действия бюджета на уровне аккаунта, задав для существующего объекта BudgetOrder новые значения spendingLimit и 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});

Можно также понизить предел расходов для BudgetOrder, однако новая сумма не может быть меньше, чем уже потрачено.

Предел расходов и корректировки

Изменяя предел расходов для BudgetOrder, важно помнить о корректировках. Корректировки – это кредиты, применяемые к заказу бюджета. Они позволяют вам тратить больше, чем позволяет ваш обычный предел расходов.

В запросах mutate() предел расходов не учитывает корректировки. Любое отправленное вами значение – это сумма, которую вы хотите потратить до применения корректировок. Однако в запросах get() значение spendingLimit включает корректировки для BudgetOrder. Если вы задаете предел расходов относительно ранее установленного лимита, не забудьте учесть корректировки.

Удаление объекта BudgetOrder

Объект BudgetOrder становится неактивным, когда заканчивается его время действия. Вы также можете отменить заказ бюджета сами. Чтобы снова включить расходы по клиентскому аккаунту, нужно создать новый BudgetOrder.

Чтобы отменить активный BudgetOrder, отправьте запрос REMOVE через API. В результате для endDateTime будет выставлено текущее время, бюджет закончит свое действие и расходы перестанут начисляться.

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

Изменение плательщика

Чтобы изменить плательщика для клиентского аккаунта, создайте объект BudgetOrder, указывающий на новый объект BillingAccounts. Однако для каждого клиентского аккаунта можно запланировать только одну такую операцию.

Например, чтобы изменить плательщика для клиента 123-456-7890 после того, как закончится действие BudgetOrder на август, можно добавить новый BudgetOrder на сентябрь, который использует платежный аккаунт (BillingAccount), связанный с другим плательщиком. Однако этот плательщик будет использоваться для всех последующих BudgetOrders, так как операцию по смене плательщика можно запланировать для клиентского аккаунта только один раз.

Ограничения

Описание Значение Ошибка Примечания
Кол-во объектов BudgetOrder на один BillingAccount 75 000 BudgetOrderError.GENERIC_BILLING_ERROR, trigger: TOO_MANY_ORDER_LINES_NEW_BILLING_ACCOUNT_REQUIRED

Максимум 75 000 BudgetOrders на платежный аккаунт (BillingAccount).

Если вы достигли этого предела, создайте новый платежный аккаунт в интерфейсе AdWords. После этого добавляйте будущие BudgetOrders к новому BillingAccount.

Кол-во операций для запроса mutate 1 BudgetOrderError.MORE_THAN_ONE_OPERATIONS Каждую операцию необходимо отправлять в отдельном запросе.
Кол-во запросов в секунду 1 RateExceededError.RATE_EXCEEDED

Частота запросов в секунду для этой службы – 1.

Ограничьте частоту запросов до одного в секунду и не отправляйте конкурентные запросы.

Распространенные ошибки

Ошибка Примечания и пути решения проблемы
BudgetOrderError.INVALID_BUDGET_DATE_RANGE, trigger: Overlapping budget found

Невозможно создать пересекающиеся объекты BudgetOrder.

Измените startDateTime или endDateTime, чтобы время действия BudgetOrder не пересекалось со временем действия других активных или запланированных заказов бюджета.

Если вы пытались создать заказ бюджета в интерфейсе AdWords, возможно, этот процесс не был завершен. В результате у вас появился ожидающий заказ бюджета. Завершите создание заказа в интерфейсе AdWords или свяжитесь со службой поддержки клиентов AdWords API, чтобы решить эту проблему.

BudgetOrderError.INVALID_BUDGET_ALREADY_SPENT

Невозможно установить более низкий предел расходов, чем уже было потрачено за данный период.

Задайте для BudgetOrder значение spendingLimit, превышающее сумму, израсходованную с startDateTime до endDateTime для этого BudgetOrder.

BudgetOrderError.CUSTOMER_NOT_WHITELISTED_FOR_NEW_BILLING

В управляющем аккаунте не включены единые счета.

Чтобы это сделать, свяжитесь с представителем Google.

NotWhitelistedError.CUSTOMER_NOT_WHITELISTED_FOR_API

Такого управляющего аккаунта нет в белом списке BudgetOrderService.

Чтобы получить доступ к службе, обратитесь к представителю Google.

Оставить отзыв о...

Текущей странице
Нужна помощь? Обратитесь в службу поддержки.