Поддержка валют в API версии Live 4

Обратная совместимость

Клиент может перейти на работу в валюте прежде, чем в приложении будет реализована поддержка валют.

С целью поддержки совместимости в следующие методы добавлен входной параметр Currency:

Если приложение не передает в запросе этот параметр, это означает, что приложение не поддерживает работу в валюте. В этом случае для поддержки обратной совместимости запрос обрабатывается следующим образом:

  • API предполагает, что передаваемые приложением денежные параметры (ставки, денежные параметры стратегий, суммы оплат и т. п.) выражены в у. е.

    Если кампания ведется в реальной валюте, то API конвертирует эти суммы в валюту кампании.

  • API возвращает в ответе приложению данные (ставки, денежные параметры стратегий, статистику кампаний, цены позиций показа и ставки конкурентов и др.), выраженные в у. е.

    Если кампания ведется в реальной валюте, API конвертирует эти суммы из валюты кампании в у. е.

В метод GetCampaignsListFilter (Live) добавлен входной параметр CurrencySupported. Если приложение не передает в запросе этот параметр, то метод возвращает данные в у. е.

Следующие методы возвращают только данные в у. е. Если кампания ведется в валюте (клиент работает в валюте), возвращаемые значения конвертируются из валюты в у. е.

Следующие методы возвращают данные (значение лимита овердрафта) как в у. е., так и в валюте клиента.

Ограничения

Если кампания ведется в у. е., то в методах, работающих с этой кампанией или ее объявлениями, для параметра Currency допустимо только значение NULL. Если указано другое значение, выдается ошибка.

Если кампания ведется в реальной валюте, то в методах, работающих с этой кампанией или ее объявлениями, для параметра Currency допустимо только значение, соответствующее валюте кампании, и значение NULL. Если указано другое значение, выдается ошибка.

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

Выполнение финансовых операций (методы CreateInvoice (Live), PayCampaigns (Live), TransferMoney (Live)) возможно только при условии, что все кампании, с которых списываются и на которые зачисляются средства, ведутся в одной валюте (или все в у. е.).

Ставки и параметры стратегий: правила конвертации

Ставки и денежные параметры стратегий (в частности, бюджеты), выраженные в валюте, не включают НДС. Пересчет из у. е. в валюту и обратно осуществляется следующим образом:

    Сумма в валюте = Сумма в у. е. × Курс валюты / (1 + Ставка НДС)

    Сумма в у. е. = Сумма в валюте × (1 + Ставка НДС) / Курс валюты

Курсы валют и ставки НДС для каждой валюты представлены в таблице Курсы валют.

Правила округления:

  • Ставки (Price, ContextPrice) при назначении ставок округляются вверх с точностью до шага торгов, при получении параметров фраз — округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге).
  • Цены позиций показа, ставки конкурентов и т. п. (Min, Max, PremiumMin, PremiumMax, Prices, MinPrice, ContextCoverage) после конвертации округляются вверх с точностью до шага торгов.
  • Параметр стратегии MaxPrice после конвертации округляется вниз с точностью до шага торгов.
  • Остальные параметры стратегий (AveragePrice, WeeklySumLimit) округляются по математическим правилам с точностью до второго знака после запятой (для всех валют, в том числе тенге).

Пример 1

Если кампания ведется в рублях, а приложение передает ставку 1 у. е., то будет сохранено значение ставки 30 / (1 + 0,18) = 25,5 руб. (с учетом округления вверх до 0,1 руб.).

Если приложение запрашивает параметры объявления и не передает параметр Currency, в параметре Price будет возвращено значение 25,5 × (1 + 0,18) / 30 = 1 у. е. (с учетом округления).

Зачисления и текущий баланс: правила конвертации

Параметры кампаний Sum, Rest и SumAvailableForTransfer, выраженные в валюте, не включают НДС. Пересчет из валюты кампании в у. е. осуществляется следующим образом:

    Сумма в у. е. = Сумма в валюте × (1 + Ставка НДС) / Курс валюты

Курсы валют и ставки НДС для каждой валюты представлены в таблице Курсы валют.

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

Перенос средств: правила конвертации

В методе TransferMoney (Live) и в операции TransferMoney метода AccountManagement (Live) параметр Sum в реальной валюте следует указывать без НДС.

Пересчет из у. е. в валюту кампании осуществляется следующим образом:

    Сумма в валюте = Сумма в у. е. × Курс валюты / (1 + Ставка НДС)

Курсы валют и ставки НДС для каждой валюты представлены в таблице Курсы валют.

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

Выставление счета, оплата из кредитного лимита или овердрафта: правила конвертации

Для пополнения кампании или общего счета в реальной валюте можно выставить счет в этой валюте: обычный счет — с помощью метода CreateInvoice (Live) или операции Invoice метода AccountManagement (Live), счет с отложенной оплатой или размещение в кредит — с помощью метода PayCampaigns (Live) или операции Deposit метода AccountManagement (Live):

  • в параметре Currency следует указать реальную валюту кампании;
  • в параметре Sum следует указать сумму счета в реальной валюте с учетом НДС клиента, осуществляющего оплату (то есть прямого рекламодателя либо агентства). Именно на эту сумму будет выставлен счет.

Ставку НДС клиента можно получить в результирующем параметре VATRate метода GetClientInfo (Live).

Если параметр Currency не указан, перед выставлением счета сумма пересчитывается из у. е. в валюту следующим образом:

   Сумма в валюте = Сумма в у. е. × Курс валюты / (1 + Ставка НДС) × (1 + Ставка НДС для клиента)

Курсы валют и ставки НДС для каждой валюты представлены в таблице Курсы валют. Ставка НДС для клиента возвращается в результирующем параметре VATRate метода GetClientInfo (Live).

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

Пример 3

Если клиент (прямой рекламодатель) работает в рублях и является плательщиком НДС, а приложение вызывает метод CreateInvoice (Live) и передает сумму 100 у. е., то счет будет выставлен на сумму

100 × (30 / (1 + 0,18)) × (1 + 0,18) = 3000 руб. с учетом НДС.

После оплаты счета на кампанию будет зачислено 3000 / (1 + 0,18) ≈ 2542,37 руб.

Если клиент работает в рублях и не является плательщиком НДС, то счет будет выставлен на сумму

100 × (30 / (1 + 0,18)) = 2542,37 руб. (с учетом округления).

После оплаты счета на кампанию будет зачислена именно эта сумма.

Пример 4

Если клиент (прямой рекламодатель) работает в рублях и является плательщиком НДС, а приложение вызывает метод PayCampaigns (Live) с методом оплаты Overdraft и передает сумму 100 у. е., то счет с отложенной оплатой будет выставлен на сумму

100 × (30 / (1 + 0,18)) × (1 + 0,18) = 3000 руб. с учетом НДС.

На кампанию будет сразу же зачислено 3000 / (1 + 0,18) ≈ 2542,37 руб.

Если клиент работает в рублях и не является плательщиком НДС, то счет будет выставлен на сумму

100 × (30 / (1 + 0,18)) = 2542,37 руб. (с учетом округления).

На кампанию будет сразу же зачислена эта сумма.

Счет необходимо оплатить в течение 15 календарных дней.

Получение валюты кампании и клиента

В методы GetCampaignsList (Live), GetCampaignsListFilter (Live), GetCampaignParams (Live), GetCampaignsParams (Live) добавлен результирующий параметр — CampaignCurrency.

В метод GetClientInfo (Live) добавлен результирующий параметр — ClientCurrencies.

Соответствие кампаний в у. е. и валюте

В методы GetCampaignsList (Live), GetCampaignsListFilter (Live), GetCampaignParams (Live), GetCampaignsParams (Live) добавлен результирующий параметр — SourceCampaignID.

НДС

В метод GetClientInfo (Live) добавлен результирующий параметр — VATRate.

Параметры кампаний Sum, Rest, SumAvailableForTransfer, выраженные в валюте, не включают НДС. Получив НДС клиента, приложение может отображать эти данные для пользователя с учетом НДС.

Cкидочный бонус

В методы GetCampaignParams (Live), GetCampaignsParams (Live), GetCampaignsListFilter (Live) добавлен результирующий параметр — BonusDiscount.

Регистрация клиентов

C помощью метода CreateNewSubclient (Live) агентства могут регистрировать субклиентов, работающих в валюте. Допустимые валюты субклиентов перечислены в параметре ClientCurrencies, возвращаемом методом GetClientInfo (Live).