--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.com/dev/direct/doc/dg-v4/en/concepts/requirements.md - https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/requirements.md - href: ru/concepts/requirements.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/dg-v4/ru/llms.txt # Требования к приложению Данный раздел содержит требования и рекомендации для приложений, взаимодействующих с API Директа. ## Общие требования. Обработка ошибок {#general} 1. Приложение должно протоколировать все запросы к API Директа и хранить логи запросов и ответов API не менее чем за последние 3 суток. 1. Приложение должно контролировать и обрабатывать ошибки взаимодействия с API. Приложение не должно повторно отправлять некорректно сформированный запрос. 1. Приложение должно контролировать количество одновременных запросов к API от имени одного пользователя (п. [1](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#simult) раздела [Технические ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Technical)). 1. Приложение должно контролировать суммарное количество вызовов каждого метода от имени одного пользователя в течение суток (п. [2](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#calls-per-day) раздела [Технические ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Technical)). 1. При возникновении ошибки, связанной с ограничениями на количество запросов, приложение должно прекращать выполнение запросов. 1. Перед вызовом методов, для которых предусмотрены балльные ограничения (см. раздел [Балльные ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Units)), приложение должно контролировать наличие доступных баллов с помощью метода [GetClientsUnits](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetClientsUnits.md). ## Назначение ставок {#bids} 1. Для назначения ставок следует использовать преимущественно метод [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/SetAutoPrice.md). Для назначения единых ставок для массива фраз или баннеров, а также для назначения ставок, равных цене показа на определенной позиции с некоторой надбавкой, всегда следует использовать метод [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/SetAutoPrice.md). 1. Количество вызовов метода [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/SetAutoPrice.md) следует минимизировать. Оптимальное количество вызовов — не более 1 раза в час и не более 10 раз в сутки для каждой кампании. 1. Если в приложении реализована собственная логика изменения ставок, которую невозможно реализовать с помощью метода [SetAutoPrice](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/SetAutoPrice.md), допускается назначение ставок методом [UpdatePrices](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/UpdatePrices.md). 1. Количество вызовов метода [UpdatePrices](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/UpdatePrices.md) следует минимизировать. Для этого следует включать в каждый вызов метода максимальное количество фраз, в том числе относящихся к разным объявлениям или группам объявлений одной кампании (с учетом ограничения, указанного в п. [3](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#max-input) раздела [Технические ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Technical)). 1. При вызове метода [UpdatePrices](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/UpdatePrices.md) следует использовать идентификаторы фраз (`PhraseID`), заранее сохраненные в [кэше](#cache), вместо получения идентификаторов фраз перед каждым назначением ставок. 1. Рекомендуется варьировать частоту назначения ставок в зависимости от приоритета кампаний или объявлений (групп объявлений). См. подраздел [Механизм приоритизации](#priority). 1. Не следует продолжать изменение ставок для остановленных кампаний и кампаний, на которых закончились средства. ## Обновление кэша {#cache} 1. Полученные с сервера параметры кампаний, объявлений (групп объявлений), ключевых фраз следует сохранять в кэше (в локальной базе данных, в памяти, в файлах на диске и т. д.). 1. Перед обновлением данных в кэше следует использовать метод [GetChanges](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetChanges.md) для проверки наличия изменений. Заново получать с сервера API Директа следует только те кампании и объявления (группы объявлений), в которых произошли изменения с момента предыдущего обновления кэша. 1. Для получения списка кампаний следует использовать метод [GetCampaignsList](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetCampaignsList.md), для получения параметров кампаний — метод [GetCampaignsParams](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetCampaignsParams.md). Оптимальное количество вызовов — не чаще 1 раза в час. 1. Для получения параметров объявлений следует использовать метод [GetBanners](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetBanners.md) с параметром `GetPhrases = "Yes"` (получение сокращенного состава параметров, без результатов аукциона). В случае большого количества фраз следует вызывать метод [GetBanners](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetBanners.md) с параметром `GetPhrases = "No"`, а затем получать фразы методом [GetBannerPhrasesFilter](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetBannerPhrasesFilter.md) (см. п. [5](#get-phrases)). В случае большого количества объявлений в кампании (~1000 и более) при получении объявлений следует использовать параметры `Limit`/`Offset`. 1. Для получения ключевых фраз следует использовать метод [GetBannerPhrasesFilter](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetBannerPhrasesFilter.md), указывая в параметре `FieldsNames` состав параметров, которые необходимо получить (например, `FieldsNames = ["PhraseID","BannerID","Phrase","Price","ContextPrice","AutoBudgetPriority"]`, а в параметре `BannerIDS` — идентификаторы объявлений (оптимальное количество — от 100 до 300)). 1. Для высокоприоритетных кампаний или объявлений (групп объявлений) допускается более частое обновление кэша (см. подраздел [Механизм приоритизации](#priority)). ## Механизм приоритизации {#priority} 1. Кампании, группы, объявления и/или фразы рекомендуется разделить на высоко- и низкоприоритетные. Например, можно присвоить высокий приоритет наиболее активным и важным кампаниям: с большим количеством кликов или высокой ценой клика. Приоритеты могут задаваться вручную пользователем или присваиваться автоматически по определенному алгоритму, например, исходя из статистики кликов и показов. 1. Для высокоприоритетных объектов допускается более частое назначение ставок и обновление кэша (при условии выполнения п. [3](#low-priority)). 1. Для низкоприоритетных объектов следует уменьшить периодичность назначения ставок и обновления кэша: до 1–2 раза в сутки. ## Контроль статистики расходов {#expenses} 1. Для получения сводной статистики кампании по дням или за период необходимо использовать метод [GetSummaryStat](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetSummaryStat.md). Оптимальная периодичность вызова — не чаще 5 раз в час для каждой кампании. 1. Для получения статистики по объявлениям и фразам необходимо использовать метод [GetBannersStat (Live)](https://yandex.com/dev/direct/doc/dg-v4/ru/live/GetBannersStat.md). Оптимальная периодичность вызова — не чаще 1 раза в час для каждой кампании. 1. Метод [CreateNewReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md) следует применять только для получения статистики в разрезе регионов показа, площадок, позиций показа, достижения целей Яндекс Метрики. При этом отчетный период следует ограничивать минимальным возможным значением (например, 1–2 дня). Оптимальная периодичность вызова — не чаще 5 раз в сутки для каждой кампании. 1. При необходимости получить несколько отчетов методом [CreateNewReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewReport.md) следует запустить формирование сразу максимального количества отчетов (с учетом ограничения, указанного в п. [6](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#reports) раздела [Технические ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Technical)). Это ускоряет обработку очереди запросов. По мере готовности отчетов следует скачивать их, удалять с сервера (метод [DeleteReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/DeleteReport.md)) и запускать формирование следующего отчета. 1. Проверку готовности отчетов (метод [GetReportList](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetReportList.md)) следует выполнять в одном потоке, не чаще 1 раза в 10–30 секунд. Рекомендуется увеличивать интервал перед каждой следующей проверкой, например: 10, 20, 40, ... секунд. 1. Если требуется повышенная точность статистики с учетом корректировок, необходимо использовать метод [GetChanges](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetChanges.md) для проверки наличия корректировок статистики. Заново получать статистику следует только по тем кампаниям и периодам, по которым статистика была скорректирована. ## Прогноз бюджета и подбор фраз {#forecast} 1. Отчеты, формируемые методами [CreateNewForecast](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewForecast.md) и [CreateNewWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewWordstatReport.md), предназначены для расширения и уточнения рекламных кампаний клиентов в Директе. Не следует формировать данные отчеты для других целей. 1. При необходимости получить несколько отчетов следует запустить формирование сразу максимального количества отчетов (с учетом ограничения, указанного в п. [6](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#reports) раздела [Технические ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Technical)). Это ускоряет обработку очереди запросов. По мере готовности отчетов следует получать их (методы [GetForecast](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetForecast.md), [GetWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetWordstatReport.md)), удалять с сервера (методы [DeleteForecastReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/DeleteForecastReport.md), [DeleteWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/DeleteWordstatReport.md)) и запускать формирование следующих отчетов. 1. Проверку готовности отчетов (методы [GetForecastList](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetForecastList.md), [GetWordstatReportList](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetWordstatReportList.md)) следует выполнять в одном потоке, не чаще 1 раза в 10–30 секунд. 1. Перед вызовом методов [CreateNewWordstatReport](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/CreateNewWordstatReport.md) и [GetKeywordsSuggestion](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetKeywordsSuggestion.md) приложение должно контролировать наличие доступных баллов с помощью метода [GetClientsUnits](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetClientsUnits.md) (см. раздел [Балльные ограничения](https://yandex.com/dev/direct/doc/dg-v4/ru/concepts/restrictions.md#Units)). ## Словарные данные {#dictionary} 1. Список регионов (метод [GetRegions](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetRegions.md)) и временных зон (метод [GetTimeZones](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetTimeZones.md)) следует получить с сервера однократно и сохранить в кэше. 1. Перед обновлением данных в кэше следует использовать метод [GetChanges](https://yandex.com/dev/direct/doc/dg-v4/ru/reference/GetChanges.md) для проверки наличия изменений. Периодичность проверки — не чаще 1 раза в сутки.