get

Возвращает виртуальные визитки, отвечающие заданным критериям.

  1. Ограничения
  2. Запрос
  3. Ответ
  4. Примеры

Ограничения

Метод возвращает не более 10 000 объектов.

Запрос

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

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {   /* IdsCriteria */
      "Ids": [(long), ... ] /* required */
    },
    "FieldNames": [( "Id" | "Country" | "City" | "Street" | "House" | "Building" | "Apartment" | "CompanyName" | "ExtraMessage" | "ContactPerson" | "ContactEmail" | "MetroStationId" | "CampaignId" | "Ogrn" | "WorkTime" | "InstantMessenger" | "Phone" | "PointOnMap" ), ... ], /* required */
    "Page": {   /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria IdsCriteria

Критерий отбора визиток. Если не указан, будут получены все визитки рекламодателя.

 Нет
FieldNames array of VCardFieldEnum

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

 Да
Page LimitOffset

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

 Нет
Структура IdsCriteria
Ids array of long

Идентификаторы визиток, которые требуется получить. Не более 10 000 элементов в массиве.

 Да
Параметр Тип Описание Обяза-тельный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria IdsCriteria

Критерий отбора визиток. Если не указан, будут получены все визитки рекламодателя.

 Нет
FieldNames array of VCardFieldEnum

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

 Да
Page LimitOffset

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

 Нет
Структура IdsCriteria
Ids array of long

Идентификаторы визиток, которые требуется получить. Не более 10 000 элементов в массиве.

 Да

Ответ

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

{
  "result": {
    "VCards": [{  /* VCardGetItem */
      "Id": (long),
      "CampaignId": (long),
      "Country": (string),
      "City": (string),
      "WorkTime": (string),
      "Phone": {  /* Phone */
        "CountryCode": (string), /* required */
        "CityCode": (string), /* required */
        "PhoneNumber": (string), /* required */
        "Extension": (string)
      },
      "Street": (string), /* nillable */
      "House": (string), /* nillable */
      "Building": (string), /* nillable */
      "Apartment": (string), /* nillable */
      "InstantMessenger": {  /* InstantMessenger */
        "MessengerClient": (string), /* required */
        "MessengerLogin": (string) /* required */
      }, /* nillable */
      "CompanyName": (string), /* nillable */
      "ExtraMessage": (string), /* nillable */
      "ContactEmail": (string), /* nillable */
      "Ogrn": (string), /* nillable */
      "MetroStationId": (long), /* nillable */
      "PointOnMap": {  /*  MapPoint */
        "X": (decimal), /* required */
        "Y": (decimal), /* required */
        "X1": (decimal), /* required */
        "Y1": (decimal), /* required */
        "X2": (decimal), /* required */
        "Y2": (decimal) /* required */
      }, /* nillable */
      "ContactPerson": (string) /* nillable */
    }, ... ],
    "LimitedBy": (long)
  }
}
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
VCards array of VCardGetItem Визитки.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура VCardGetItem
Id long

Идентификатор визитки.
CampaignId long

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

Country string

Страна. Не более 50 символов.
City string

Город. Не более 55 символов.
WorkTime string

Режим работы организации или режим обслуживания клиентов. Задается как строка, в которой указан диапазон дней недели, рабочих часов и минут.

Дни недели обозначаются цифрами от 0 до 6, где 0 — понедельник, 6 — воскресенье.

Минуты задают кратно 15: 0, 15, 30 или 45.

Формат строки: "день_с;день_по;час_с;минуты_с;час_до;мин_до".

Например, строка "0;4;10;0;18;0" задает такой режим:

0;4 — с понедельника по пятницу;

10;0 — с 10 часов 0 минут;

18;0 — до 18 часов 0 минут.

Режим может состоять из нескольких строк указанного формата, например: "0;4;10;0;18;0;5;6;11;0;16;0". Здесь в дополнение к предыдущему примеру задан режим:

5;6 — с субботы по воскресенье;

11;0 — с 11 часов 0 минут;

16;0 — до 16 часов 0 минут.

Круглосуточный режим работы задается строкой "0;6;00;00;00;00".

Не более 255 символов.
Phone Phone

Структура, задающая номер телефона.
Street string, nillable

Улица. Не более 55 символов.
House string, nillable

Номер дома. Не более 30 символов.
Building string, nillable

Номер строения или корпуса. Не более 10 символов.
Apartment string, nillable

Номер квартиры или офиса. Не более 100 символов.
InstantMessenger InstantMessenger, nillable

Структура, задающая контакт для обмена мгновенными сообщениями.
CompanyName string, nillable

Название организации. Не более 255 символов.
ExtraMessage string, nillable

Дополнительная информация о рекламируемом товаре или услуге. Не более 200 символов.
ContactEmail string, nillable

Адрес электронной почты. Не более 255 символов.
Ogrn string, nillable

Код ОГРН для юридических лиц. Не более 255 символов.
MetroStationId long, nillable

Идентификатор станции метрополитена.

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

Структура, описывающая положение метки на карте. Если не задана, метка ставится по указанному адресу клиента.
ContactPerson string, nillable

Контактное лицо. Не более 155 символов.
Структура Phone
CountryCode string

Телефонный код страны. Должен содержать от 1 до 5 символов. Допустимы значения:

  • начинающиеся со знака «+» и состоящие из цифр;
  • значение «8» в сочетании с кодом города «800».

Например, «+7» для России.
CityCode string

Телефонный код города. От 1 до 5 цифр. Должен быть отличен от 0.
PhoneNumber string

Телефонный номер для связи. От 5 до 9 цифр, суммарно с кодом страны и города — от 8 до 17 цифр.
Extension string

Добавочный телефонный номер для соединения через офисную АТС. От 1 до 6 цифр.
Структура InstantMessenger
MessengerClient string

Тип системы мгновенного обмена сообщениями — icq, jabber, skype, mail_agent.
MessengerLogin string

Логин (идентификатор) в системе мгновенного обмена сообщениями. Не более 255 символов.
Структура MapPoint
X decimal

Долгота точки. От -180 до 180.
Y decimal

Широта точки. От -90 до 90.
X1 decimal

Долгота левого нижнего угла области на карте. От -180 до 180.
Y1 decimal

Широта левого нижнего угла области на карте. От -90 до 90.
X2 decimal

Долгота правого верхнего угла области на карте. От -180 до 180.
Y2 decimal

Широта правого верхнего угла области на карте. От -90 до 90.
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
VCards array of VCardGetItem Визитки.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура VCardGetItem
Id long

Идентификатор визитки.
CampaignId long

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

Country string

Страна. Не более 50 символов.
City string

Город. Не более 55 символов.
WorkTime string

Режим работы организации или режим обслуживания клиентов. Задается как строка, в которой указан диапазон дней недели, рабочих часов и минут.

Дни недели обозначаются цифрами от 0 до 6, где 0 — понедельник, 6 — воскресенье.

Минуты задают кратно 15: 0, 15, 30 или 45.

Формат строки: "день_с;день_по;час_с;минуты_с;час_до;мин_до".

Например, строка "0;4;10;0;18;0" задает такой режим:

0;4 — с понедельника по пятницу;

10;0 — с 10 часов 0 минут;

18;0 — до 18 часов 0 минут.

Режим может состоять из нескольких строк указанного формата, например: "0;4;10;0;18;0;5;6;11;0;16;0". Здесь в дополнение к предыдущему примеру задан режим:

5;6 — с субботы по воскресенье;

11;0 — с 11 часов 0 минут;

16;0 — до 16 часов 0 минут.

Круглосуточный режим работы задается строкой "0;6;00;00;00;00".

Не более 255 символов.
Phone Phone

Структура, задающая номер телефона.
Street string, nillable

Улица. Не более 55 символов.
House string, nillable

Номер дома. Не более 30 символов.
Building string, nillable

Номер строения или корпуса. Не более 10 символов.
Apartment string, nillable

Номер квартиры или офиса. Не более 100 символов.
InstantMessenger InstantMessenger, nillable

Структура, задающая контакт для обмена мгновенными сообщениями.
CompanyName string, nillable

Название организации. Не более 255 символов.
ExtraMessage string, nillable

Дополнительная информация о рекламируемом товаре или услуге. Не более 200 символов.
ContactEmail string, nillable

Адрес электронной почты. Не более 255 символов.
Ogrn string, nillable

Код ОГРН для юридических лиц. Не более 255 символов.
MetroStationId long, nillable

Идентификатор станции метрополитена.

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

Структура, описывающая положение метки на карте. Если не задана, метка ставится по указанному адресу клиента.
ContactPerson string, nillable

Контактное лицо. Не более 155 символов.
Структура Phone
CountryCode string

Телефонный код страны. Должен содержать от 1 до 5 символов. Допустимы значения:

  • начинающиеся со знака «+» и состоящие из цифр;
  • значение «8» в сочетании с кодом города «800».

Например, «+7» для России.
CityCode string

Телефонный код города. От 1 до 5 цифр. Должен быть отличен от 0.
PhoneNumber string

Телефонный номер для связи. От 5 до 9 цифр, суммарно с кодом страны и города — от 8 до 17 цифр.
Extension string

Добавочный телефонный номер для соединения через офисную АТС. От 1 до 6 цифр.
Структура InstantMessenger
MessengerClient string

Тип системы мгновенного обмена сообщениями — icq, jabber, skype, mail_agent.
MessengerLogin string

Логин (идентификатор) в системе мгновенного обмена сообщениями. Не более 255 символов.
Структура MapPoint
X decimal

Долгота точки. От -180 до 180.
Y decimal

Широта точки. От -90 до 90.
X1 decimal

Долгота левого нижнего угла области на карте. От -180 до 180.
Y1 decimal

Широта левого нижнего угла области на карте. От -90 до 90.
X2 decimal

Долгота правого верхнего угла области на карте. От -180 до 180.
Y2 decimal

Широта правого верхнего угла области на карте. От -90 до 90.

Примеры

Пример запроса
{
  "method": "get",
  "params": {
    "SelectionCriteria" : {
      "Ids" : [ 13070327]
    },
    "FieldNames" : [
      "Country",
      "City",
      "Phone"
    ]
  }
}
Пример ответа
{
  "result" : {
    "VCards" : [
      {
        "Phone" : {
          "CityCode" : "812",
          "Extension" : "89",
          "PhoneNumber" : "123-45-67",
          "CountryCode" : "+7"
        },
        "Country" : "Russia",
        "City" : "Moscow"
      }
    ]
  }
}