get

Возвращает список рекламодателей — клиентов агентства, их параметры и настройки главных представителей рекламодателя.

Примечание

В запросе к сервису AgencyClients:

  • В HTTP-заголовке Authorization укажите токен, полученный для представителя агентства.
  • HTTP-заголовок Client-Login не указывайте.

Узнайте больше

Запрос

Структура запроса в формате JSON:

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* AgencyClientsSelectionCriteria */
      "Logins": [(string), ... ],
      "Archived": ( "YES" | "NO" )
    }, /* required */
    "FieldNames": [( "AccountQuality" | "Archived" | "ClientId" | "ClientInfo" | "CountryId" | "CreatedAt" | "Currency" | "Grants" | "Bonuses" | "Login" | "Notification" | "OverdraftSumAvailable" | "Phone" | "Representatives" | "Restrictions" | "Settings" | "Type" | "VatRate" | "ForbiddenPlatform" | "AvailableCampaignTypes" ), ... ], /* required */
    "TinInfoFieldNames" : [( "TinType" | "Tin"), ... ],
    "OrganizationFieldNames": [( "Name" | "EpayNumber" | "RegNumber" | "OksmNumber" | "OkvedCode" ), ... ],
    "ContractFieldNames": [( "Number" | "Date" | "Price" | "Type" | "ActionType" | "SubjectType" ), ... ],
    "ContragentFieldNames": [( "Name" | "Phone" | "EpayNumber" | "RegNumber" | "OksmNumber" ), ... ],
    "ContragentTinInfoFieldNames": [( "TinType" | "Tin" ), ... ],
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}

Параметр

Тип

Описание

Обязательный

Структура params (для JSON) / GetRequest (для SOAP)

SelectionCriteria

AgencyClientsSelectionCriteria

Критерии отбора клиентов.

Чтобы получить параметры всех клиентов агентства, необходимо указать пустую структуру SelectionCriteria.

Да

FieldNames

array of AgencyClientFieldEnum

Имена параметров, которые требуется получить.

Да

TinInfoFieldNames

array of TinInfoFieldEnum

Имена параметров с налоговыми данными о конечном рекламодателе, которые требуется получить.

Нет

OrganizationFieldNames

array of OrganizationFieldEnum

Имена параметров с информацией об организации конечного рекламодателя, которые требуется получить.

Нет

ContractFieldNames

array of ContractFieldEnum

Имена параметров с информацией о договоре клиента-контрагента с конечным рекламодателем, которые требуется получить.

Нет

ContragentFieldNames

array of ContragentFieldEnum

Имена параметров с информацией о контрагенте, которые требуется получить.

Нет

ContragentTinInfoFieldNames

array of TinInfoFieldEnum

Имена параметров с налоговыми данными о контрагенте, которые требуется получить.

Нет

Page

LimitOffset

Структура, задающая страницу при постраничной выборке данных.

Нет

Структура AgencyClientsSelectionCriteria

Logins

array of string

Отбирать клиентов с указанными логинами представителей. Не более 10 000 элементов в массиве.

Нет

Archived

YesNoEnum

Отбирать клиентов по признаку нахождения в архиве: YES — архивные клиенты, NO — активные клиенты.

Нет

Ответ

Примечание

  • Параметры Login, ClientInfo, CreatedAt, Notification, Phone относятся к главному представителю рекламодателя (см. раздел Роли и доступы пользователей Директа). Остальные параметры относятся к рекламодателю.

  • Если в запросе в параметре Logins указан логин представителя рекламодателя, который не является главным представителем, то ответ будет содержать логин главного представителя, отличающийся от логина в запросе.

  • Если в запросе в параметре Logins указано несколько логинов представителей одного рекламодателя, рекламодатель (и его главный представитель) будет присутствовать в ответе только один раз.

  • Список всех представителей рекламодателя представлен в параметре ответа Representatives.

Структура ответа в формате JSON:

{
  "result": { /* result */
    "Clients": [{  /* ClientGetItem */
      "AccountQuality": (decimal), /* nillable */
      "Archived": ( "YES" | "NO" ),
      "ClientId": (long),
      "ClientInfo": (string),
      "CountryId": (int),
      "CreatedAt": (string),
      "Currency": ( "RUB" | "BYN" | "CHF" | "EUR" | "KZT" | "TRY" | "UAH" | "USD" ),
      "Grants": [{  /* GrantGetItem */
        "Privilege": ( "EDIT_CAMPAIGNS" | "IMPORT_XLS" | "TRANSFER_MONEY" ), /* required */
        "Value": ( "YES" | "NO" ), /* required */
        "Agency": (string)
      }, ... ],
      "Bonuses" : {  /* BonusesGet */
        "AwaitingBonus" : (long) /* required */,
        "AwaitingBonusWithoutNds" : (long) /* required */
      },
      "Login": (string),
      "Notification": {  /* NotificationGet */
        "Lang": ( "RU" | "UK" | "EN" | "TR" ), /* required */
        "SmsPhoneNumber": (string), /* required */
        "Email": (string), /* required */
        "EmailSubscriptions": [{  /* EmailSubscriptionItem */
          "Option": ( "RECEIVE_RECOMMENDATIONS" | "TRACK_MANAGED_CAMPAIGNS" | "TRACK_POSITION_CHANGES" ), /* required */
          "Value": ( "YES" | "NO" ) /* required */
        }, ... ] /* required */
      },
      "OverdraftSumAvailable": (long),
      "Phone": (string),
      "Representatives": [{  /* Representative */
        "Login": (string), /* required */
        "Email": (string), /* required */
        "Role": ( "CHIEF" | "DELEGATE" | "READONLY" | "UNKNOWN" ) /* required */
      }, ... ],
      "Restrictions": [{  /* ClientRestrictionItem */
        "Element": ( "CAMPAIGNS_TOTAL_PER_CLIENT" | "CAMPAIGNS_UNARCHIVED_PER_CLIENT" | "ADGROUPS_TOTAL_PER_CAMPAIGN" | "ADS_TOTAL_PER_ADGROUP" | "KEYWORDS_TOTAL_PER_ADGROUP" | "AD_EXTENSIONS_TOTAL" | "STAT_REPORTS_TOTAL_IN_QUEUE" | "FORECAST_REPORTS_TOTAL_IN_QUEUE" | "WORDSTAT_REPORTS_TOTAL_IN_QUEUE" | "API_POINTS" | "GENERAL_DOMAIN_BLACKLIST_SIZE" | "VIDEO_DOMAIN_BLACKLIST_SIZE" ), /* required */
        "Value": (int) /* required */
      }, ... ],
      "Settings": [{  /* ClientSettingGetItem */
        "Option": ( "CORRECT_TYPOS_AUTOMATICALLY" | "DISPLAY_STORE_RATING" | "SHARED_ACCOUNT_ENABLED"  ), /* required */
        "Value": ( "YES" | "NO" ) /* required */
      }, ... ],
      "Type": (string),
      "VatRate": (decimal), /* nillable */
      "ForbiddenPlatform": ("SEARCH" | "NETWORK" | "NONE"),
      "AvailableCampaignTypes": ("TEXT_CAMPAIGN" | "MOBILE_APP_CAMPAIGN" | "DYNAMIC_TEXT_CAMPAIGN" | "CPM_BANNER_CAMPAIGN" | "SMART_CAMPAIGN" | "CONTENT_PROMOTION" | "BILLING_AGGREGATE" | "UNIFIED_CAMPAIGN" ),
      "TinInfo": { /* TinInfoGet */
        "TinType": ( "PHYSICAL" | "FOREIGN_PHYSICAL" | "LEGAL" | "FOREIGN_LEGAL" | "INDIVIDUAL" ),
        "Tin": (string) /* nillable */
      },
      "ErirAttributes": { /* ErirAttributesGet */
        "Organization": { /* OrganizationGet */
          "Name": (string), /* nillable */
          "EpayNumber": (string), /* nillable */
          "RegNumber": (string), /* nillable */
          "OksmNumber": (string), /* nillable */
          "OkvedCode": (string) /* nillable */
        },
        "Contract": { /* ContractGet */
          "Number": (string), /* nillable */
          "Date": (string), /* nillable */
          "Type": ( "CONTRACT" | "INTERMEDIARY_CONTRACT" | "ADDITIONAL_AGREEMENT" ), /* nillable */
          "ActionType": ( "COMMERCIAL" | "DISTRIBUTION" | "CONCLUDE" | "OTHER" ), /* nillable */
          "SubjectType": ( "REPRESENTATION" | "MEDIATION" | "DISTRIBUTION" | "ORG_DISTRIBUTION" | "OTHER" ), /* nillable */
          "Price": { /* PriceGet */
            "Amount": (decimal), /* required */
            "IncludingVat": ( "YES" | "NO" ) /* required */
          }
        },
        "Contragent": { /* ContragentGet */
          "Name": (string), /* nillable */
          "Phone": (string), /* nillable */
          "EpayNumber": (string), /* nillable */
          "RegNumber": (string), /* nillable */
          "OksmNumber": (string), /* nillable */
          "TinInfo": { /* TinInfoGet */
            "TinType": ( "PHYSICAL" | "FOREIGN_PHYSICAL" | "LEGAL" | "FOREIGN_LEGAL" | "INDIVIDUAL" ),
            "Tin": (string) /* nillable */
          }
        }
      }
    }, ... ],
    "LimitedBy": (long)
  }
}

Параметр

Тип

Описание

Структура result (для JSON) / GetResponse (для SOAP)

Clients

array of ClientGetItem

Рекламодатели — клиенты агентства и их главные представители.

LimitedBy

long

Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.

Структура ClientGetItem

AccountQuality

decimal, nillable

Показатель качества аккаунта.

Archived

YesNoEnum

Признак того, что рекламодатель помещен в архив (не активен).

ClientId

long

Идентификатор рекламодателя.

ClientInfo

string

Название клиента (до 255 символов).

CountryId

int

Идентификатор страны рекламодателя из справочника регионов.

Справочник регионов можно получить с помощью метода Dictionaries.get.

CreatedAt

string

Дата регистрации пользователя в Директе, в формате YYYY-MM-DD.

Currency

CurrencyEnum

Валюта рекламодателя.

Справочник валют можно получить с помощью метода Dictionaries.get.

Grants

array of GrantGetItem

Полномочия рекламодателя по управлению кампаниями.

Bonuses

BonusesGet

Бонус, ожидающий начисления. Параметр актуален только для валюты RUB.

Login

string

Логин пользователя Директа.

Notification

NotificationGet

Настройки SMS- и email-уведомлений пользователя Директа.

OverdraftSumAvailable

long

Лимит овердрафта, которым рекламодатель может воспользоваться в текущий момент времени (см. раздел Отсрочка платежа помощи Директа).

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

Phone

string

Номер телефона пользователя Директа (до 50 символов, содержит только цифры и должен начинаться с кода страны).

Representatives

array of Representative

Представители рекламодателя.

См. Роли и доступы пользователей Директа.

Restrictions

array of ClientRestrictionItem

Количественные ограничения на объекты рекламодателя.

Settings

array of ClientSettingGetItem

Настройки рекламодателя, допускающие только значения YES или NO.

Type

string

Тип клиента: SUBCLIENT.

VatRate

decimal, nillable

Ставка НДС агентства.

ForbiddenPlatform

ForbiddenPlatformEnum

Запрещенные площадки:

  • SEARCH.
  • NETWORK.
  • NONE.

AvailableCampaignTypes

AvailableCampaignTypesEnum

Типы кампаний, которые доступны логину:

  • TEXT_CAMPAIGN.
  • MOBILE_APP_CAMAIGN.
  • DYNAMIC_TEXT_CAMPAIGN.
  • CPM_BANNER_CAMPAIGN.
  • SMART_CAMPAIGN.
  • CONTENT_PROMOTION.
  • BILLING_AGGREGATE.
  • UNIFIED_CAMPAIGN.

TinInfo

TinInfoGet

Налоговые данные конечного рекламодателя.

ErirAttributes

ErirAttributesGet

Дополнительные данные рекламодателя для маркировки рекламы.

Структура GrantGetItem

Privilege

PrivilegeEnum

Имя полномочия:

Value

YesNoEnum

Есть ли у клиента данное полномочие.

Agency

string

Название рекламного агентства, если полномочие предоставлено агентством.

Структура BonusesGet

AwaitingBonus

long

Размер бонуса с НДС, который ожидает начисления. Возвращается в виде целого числа, умноженного на 1 000 000.

AwaitingBonusWithoutNds

long

Размер бонуса без НДС, который ожидает начисления. Возвращается в виде целого числа, умноженного на 1 000 000.

Структура NotificationGet

Lang

LangEnum

Язык уведомлений.

SmsPhoneNumber

string

Телефонный номер для отправки SMS-уведомлений из профиля пользователя на Яндексе (см. раздел Мои телефоны помощи Яндекс Паспорта).

Email

string

Адрес электронной почты для отправки уведомлений, связанных с аккаунтом (до 255 символов).

EmailSubscriptions

array of EmailSubscriptionItem

Типы уведомлений, отправляемых по электронной почте.

Структура EmailSubscriptionItem

Option

EmailSubscriptionEnum

Тип уведомления:

  • RECEIVE_RECOMMENDATIONS — новости Директа и рекомендации.

  • TRACK_MANAGED_CAMPAIGNS — уведомления по кампаниям, обслуживаемым персональным менеджером.

  • TRACK_POSITION_CHANGES — предупреждения о снижении прогноза трафика относительно того, который обеспечивали ставки на момент установки.

Value

YesNoEnum

Отправлять ли уведомления данного типа.

Структура Representative

Login

string

Логин пользователя.

Email

string

Адрес электронной почты для отправки уведомлений.

Role

RepresentativeRoleEnum

Роль пользователя:

  • CHIEF — главный представитель рекламодателя.
  • DELEGATE — представитель рекламодателя с полным доступом.
  • READONLY — представитель с доступом “Только чтение”.
  • UNKNOWN — роль не поддерживается в данной версии API.

См. Роли и доступы пользователей Директа.

Структура ClientRestrictionItem

Element

ClientRestrictionEnum

Имя ограничения:

  • CAMPAIGNS_TOTAL_PER_CLIENT — максимальное количество кампаний у рекламодателя.

  • CAMPAIGNS_UNARCHIVED_PER_CLIENT — максимальное количество кампаний, не находящихся в архиве.

  • ADGROUPS_TOTAL_PER_CAMPAIGN — максимальное количество групп в кампании.

  • ADS_TOTAL_PER_ADGROUP — максимальное количество объявлений в группе.

  • KEYWORDS_TOTAL_PER_ADGROUP — максимальное количество ключевых фраз в группе.

  • AD_EXTENSIONS_TOTAL — максимальное количество расширений к объявлениям у рекламодателя.

  • STAT_REPORTS_TOTAL_IN_QUEUE — максимальное количество одновременно формируемых статистических отчетов.

  • FORECAST_REPORTS_TOTAL_IN_QUEUE — максимальное количество хранимых на сервере отчетов о прогнозируемом бюджете, количестве показов и кликов.

  • WORDSTAT_REPORTS_TOTAL_IN_QUEUE — максимальное количество хранимых на сервере отчетов о статистике поисковых запросов.

  • API_POINTS — суточный лимит баллов.

  • GENERAL_DOMAIN_BLACKLIST_SIZE — максимальное количество площадок, на которых запрещены показы объявлений.

  • VIDEO_DOMAIN_BLACKLIST_SIZE — максимальное количество площадок, на которых запрещены показы видеообъявлений.

Value

int

Значение ограничения.

Структура ClientSettingGetItem

Option

ClientSettingGetEnum

Имя настройки:

  • CORRECT_TYPOS_AUTOMATICALLY — автоматически исправлять ошибки и опечатки.

  • DISPLAY_STORE_RATING — дополнять объявления данными из внешних источников (см. раздел Данные из внешних источников помощи Директа).

  • SHARED_ACCOUNT_ENABLED — подключен общий счет.

Value

YesNoEnum

Значение настройки.

Структура TinInfoGet

TinType

TinTypeEnum

Тип организации:

  • LEGAL — юридическое лицо;
  • PHYSICAL — физическое лицо;
  • INDIVIDUAL — индивидуальный предприниматель;
  • FOREIGN_LEGAL — иностранное юридическое лицо;
  • FOREIGN_PHYSICAL — иностранное физическое лицо.

Tin

string

Номер налогоплательщика либо его аналог в стране регистрации.

Структура ErirAttributesGet

Organization

OrganizationGet

Информация об организации конечного рекламодателя.

Contract

ContractGet

Информация о договоре клиента-контрагента с конечным рекламодателем.

Contragent

ContragentGet

Информация о контрагенте конечного рекламодателя.

Структура OrganizationGet

Name

string

Наименование организации (до 255 символов).

EpayNumber

string

Номер электронного средства платежа (до 255 символов).

RegNumber

string

Регистрационный номер либо его аналог (до 255 символов).

OksmNumber

string

Код страны регистрации юрлица в соответствии с ОКСМ (до 3 символов, содержит только цифры).

OkvedCode

string

Код вида деятельности по ОКВЭД.

Структура ContractGet

Number

string

Номер договора (до 255 символов).

Date

string

Дата договора в формате YYYY-MM-DD (не раньше 01.01.1991).

Type

ContractTypeEnum

Тип договора:

  • CONTRACT — договор оказания услуг;
  • INTERMEDIARY_CONTRACT — посреднический договор;
  • ADDITIONAL_AGREEMENT — дополнительное соглашение.

ActionType

ContractActionTypeEnum

Тип осуществляемых посредником-представителем действий:

  • COMMERCIAL — коммерческое представительство;
  • DISTRIBUTION — действия в целях распространения рекламы;
  • CONCLUDE — заключение договоров;
  • OTHER — иное.

SubjectType

ContractSubjectTypeEnum

Предмет договора:

  • REPRESENTATION — представительство;
  • MEDIATION — посредничество;
  • DISTRIBUTION — договор на распространение рекламы;
  • ORG_DISTRIBUTION — договор на организацию распространения рекламы;
  • OTHER — иное.

Price

ContractPrice

Цена договора (не более двух знаков после разделителя).

Структура ContractPrice

Amount

decimal

Стоимость договора.

IncludingVat

YesNoEnum

Включен ли в стоимость НДС.

Структура ContragentGet

Name

string

Наименование (до 255 символов).

Phone

string

Номер телефона (до 50 символов, содержит только цифры и должен начинаться с кода страны).

EpayNumber

string

Номер электронного средства платежа (до 255 символов).

RegNumber

string

Регистрационный номер либо его аналог (до 255 символов).

OksmNumber

string

Код страны регистрации юрлица в соответствии с ОКСМ (до 3 символов, содержит только цифры).

TinInfo

TinInfoGet

Налоговые данные контрагента.
Предыдущая
addPassportOrganizationMember
Следующая
update