Skip to content

Data API

Соглашения

Приняты следующие соглашения при использовании Data API:

  • Пустые поля всегда возвращаются в ответе со значением null. В случае массива возвращается пустой массив, в случае объекта возвращается пустой объект;
  • Все поля связанные с датой и временем передаются в формате YYYY-MM-DD hh:mm:ss;
  • Запросы к API выполняются всегда с помощью метода POST;
  • Все параметры в запросах/ответах, а также в структурах данных в формате JSON и название методов именуются в стиле Snake Case - разделение слов через нижнее подчёркивание;
  • Данные возвращаются только в JSON формате согласно спецификации RFC 7159. Заголовок Accept игнорируется;
  • Кодировка данных UTF-8;
  • Заголовок Content-Type должен быть "application/json; charset=UTF-8";
  • Заголовок Content-Length должен содержать корректную длину сообщения, следуя спецификации HTTP/1.1

Добавить IP-адрес в список разрешенных

По умолчанию доступ к API запрещен всем, чтобы можно было делать запросы необходимо IP-адрес хоста с которого делается запрос добавить в белый список. Это можно сделать через личный кабинет "Администратор -> Аккаунт -> Правила и настройки безопасности" вкладка "API".

Если необходимо разрешить доступ всем IP-адресам, то нужно добавить в список разрешенных 0.0.0.0/0

Если запрос делается из под агента, то его IP адрес должен быть добавлен в белый список клиентского аккаунта

Пользователи API и аутентификация

К пользователям и ключам доступа применяются права доступа аналогичные правам доступа в личном кабинете

Доступ по ключу

Ключи генерируются на уровне пользователя в разделе личного кабинета "Аккаунт" → "Управление пользователями" Существует два типа ключей:

  • Постоянный;
  • Временный;

Постоянный ключ имеет неограниченное время действия. Временный ключ имеет конкретную дату окончания действия ключа.

Доступ по логину и паролю

Используется аутентификация с использованием сессий

Время жизни сессии 1 час.

Отчёт по запросам к API

В личном кабинете "Отчёты"->"Служебные"->"Запросы к API" можно построить отчёт по запросам к API

Базовый URL для доступа к API

Базовый URL для доступа к API соответствует следующему шаблону:

<protocol> :// <hostname> / <version>
  • <protocol> - https;
  • <hostname> - dataapi.comagic.ru, dataapi.uiscom.ru (в зависимости от проекта, где зарегистрирован портал);
  • <version> - версия API (см. раздел Версионность)
Авторизационные данные портала uiscom не действительные для url https://dataapi.comagic.ru/ и наоборот

https://dataapi.comagic.ru/<version>

https://dataapi.uiscom.ru/<version>

Версионность

Текущая версия Data API 2.0

Data API поддерживает версионность. Версия указывается в базовом URL как vX.Y, где X - номер мажорной версии, Y - номер минорной версии

Если была выпущена новая версия, то старая считается устаревшей и соответственно при обращении к старой версии API в мета-параметрах (см. раздел Мета-параметры) будет возвращаться параметр "current_version_deprecated" со значением "true"

Максимальное количество поддерживаемых версий - 2 Период поддержки устаревшей версии 2 месяца

Лимиты и ограничения

Баллы списываются только за успешные запросы, т.е в отчете по запросам к API (см. раздел Отчёт по запросам к API) он помечен как успешный.

Информация о лимитах возвращается во всех ответах в мета-парметрах (см. раздел Мета-параметры) кроме случаев когда лимиты не учитываются;

Лимиты построены по бальной системе, т.е каждый метод имеет свой вес. Вызов метода уменьшает доступные дневные/минутные баллы на размер веса вызываемого метода

Информация о лимитах в мета-параметрах:

Название параметра Описание
day_limit Текущий лимит баллов в день
day_remaining Какое количество баллов осталось до достижения дневного лимита
day_reset Время в секундах через которое дневной лимит будет сброшен
minute_limit Текущий лимит баллов за минуту
minute_remaining Какое количество баллов осталось до достижения минутного лимита
minute_reset Время в секундах через которое минутный лимит будет сброшен

Методы и их стоимость в баллах

Тип операции Стоимость в баллах
Все операции 1

Расширение лимитов

На странице "Аккаунт" -> "Тарифы и опции" в личном кабинете можно расширить лимиты.

Обработка ошибок

Параметры сообщения об ошибке

Название Тип Обязательный Описание
error object да Объект с содержимым ошибки
code number да Не уникальный код ошибки (см. раздел Группы кодов ошибок )
message string да Cообщение об ошибке
data object да Объект с деталями ошибки
mnemonic string да Уникальный текстовый код ошибки. При обработке ошибок рекомендуется использовать этот параметр.
value string нет Содержит то, что передал пользователь без изменений
В некоторых случаях может отсутствовать. К примеру, обязательный параметр вообще не был заполнен.
extended_helper string нет Ссылка на более подробное описание ошибки и возможные решения
params object нет Карта подстановок параметров для шаблона с текстом об ошибке. Т.е. содержит динамически изменяемые значения, к примеру, лимиты. Значения указанные в этом параметре могут быть использованы в сообщениях об ошибках в интерфейсе, который базируется на Data API.
field string нет Название параметра, с которым связана ошибка
Вложенные параметры отображаются через разделитель точка "."
К примеру: "employee.phone_number"

JSON структура ошибки

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": "number",
    "message": "string",
    "data": {
      "mnemonic": "string",
      "field": "string",
      "value": "string",
      "params": {
        "object": "string"
      },
      "extended_helper": "string",
      "metadata": {

      }
    }
  }
}

Группы кодов ошибок

Код ошибки Описание
-32700 Ошибки связанные с валидацией JSON
-32600 Ошибки связанные с валидацией параметров запроса - id, jsonrpc
-32601 Ошибки связанные с методом
-32602 Ошибки связанные с валидацией параметров в вызываемом методе
-32603 Внутренние ошибки JSON RPC сервера
-32001 Ошибки аутентификации и ошибки с ключами
-32003 Ошибки с правами доступа - ip адрес не в белом списке, нет прав у пользователя
-32004 Ошибки связанные с неверной последовательностью вызываемых методов
-32007 Ошибки связанные с виртуальным номером
-32008 Ошибки связанные с компонентами
-32009 Ошибки связанные с аккаунтом
-32029 Ошибки связанные с лимитами
-32099 Ошибки связанные с поддержкой различных частей спецификации JSON RPC 2.0 - Групповые операции, Уведомления

Список ошибок общих для всех методов

Текст сообщение Код Мнемоника Описание
Invalid Request The JSON sent is not a valid Request object -32600 invalid_request Ошибки связанные с валидацией параметров запроса - id, jsonrpc
Access token has been expired -32001 access_token_expired Применяется только к постоянному токену. Если время жизни постоянного токена истекло, то возвращается указанная ошибка
Access token has been blocked -32001 access_token_blocked Если постоянный токен заблокирован, то возвращается указанная ошибка
Access token is invalid -32001 access_token_invalid Указанная ошибка возвращается если постоянный/временный токен не найден
Limit per {limit_type} has been exceeded. Value of current limit per {limit_type} is {limit_max_value} -32029 limit_exceeded Лимит превышен
You need at least on of the following components to access this method: {components} -32008 method_component_disabled Если не подключен компонент, который требуется для работы метода
You need at least on of the following components to access this paremeter: {components} -32008 parameter_component_disabled Если не подключен компонент, который нужен для заполнения параметра и создания сущности
Your IP {ip} is not whitelisted -32003 ip_not_whitelisted IP адрес с которого делается запрос не находится в белом списке адресов. Если запрос делается из под агента, то ваш IP адрес должен быть в списках разрешеных адресов внутри клиентского аккаунта
Login or password is wrong -32001 auth_error Неправильный логин или пароль
Your account has been disabled, contact the support service -32009 account_inactive Аккаунт заблокирован
Internal error, contact the support service -32603 internal_error Внутренняя ошибка, необходимо обратиться в службу технической поддержки
Data supplied is of wrong type -32602 data_type_error К примеру, если ожидаем string а передали int
The method does not exist / is not available -32601 method_not_found Вызываемый метод не найден
Permission denied -32003 forbidden Нет прав на доступ к методу или API, или запрещено выполнять какое-либо действие
Invalid JSON was received by the server. -32700 parse_error Ошибка валидации JSON
Batch operations not supported -32099 batch_opreations_not_supported Групповые операции не поддерживаются
Notifications not supported -32099 notifications_not_supported Был потерян параметр id в запросе. См. раздел Общие параметры для всех методов"
The required parameter has been missed -32602 required_parameter_missed Обязательный параметр не передали
Invalid parameter value -32602 invalid_parameter_value Возвращается во всех случаях, если было передано некорректное значение параметра или переданное значение не соответствует требуемому формату ввода
Unexpected method parameter(s) -32602 unexpected_parameters Если в "params" были переданы параметры которые не предусмотрены JSON структурой метода или указан параметр для сортировки, фильтрации и выборки, который не существует
The combination of parameters is not permitted -32602 invalid_parameters_combination Если параметры указанные в методе находятся в недопустимой комбинации или имеют зависмость друг от друга. Нужно смотреть документацию по методу и его параметрам.
{error_message} -32602 error Динамические ошибки

Список ошибок для методов с глаголом get

Текст ошибки Код Мнемоника Описание
Invalid parameter value -32602 invalid_parameter_value Если в фильтрах было передано некорректное значение для regexp, jsquery или любых значений не соответствующих документации
Sort by parameter is prohibited -32602 sort_prohibited Сортировка по параметру запрещена и невозможна, так как параметр для сортировки не находится в списке разрешенных для сортировки
Filter by parameter is prohibited -32602 filter_prohibited Фильтрация по параметру запрещена и невозможна, так как параметр для фильтрации не находится в списке разрешенных для фильтрации
Max value of requested date interval is 3 months -32602 date_interval_limit_reached Если в запросе период между указанными датами в date_from и date_till превышает 3 месяца. В основном ошибка актуальна только для методов получения отчетов, но не для всех.

Список ошибок общих для методов с глаголом delete

Текст ошибки Код Мнемоника Описание
Entity not found -32602 entity_not_found Если передан уникальный идентификатор сущности, которая не найдена
You have interdependet entities -32602 dependency_error Удаляемая сущность используется в других сущностях. Чтобы удалить, необходимо убрать удаляемую сущность из всех возможных мест где она используется
Permission denied -32602 forbidden Удалить сущность невозможно так как она системная, к примеру группа "Черный список" в адресной книге

Список ошибок общих для методов с глаголом create и update, set, unset

Текст ошибки Код Мнемоника Описание
Entity not found -32602 entity_not_found Если передан уникальный идентификатор сущности, которая не найдена
Duplicate entity -32602 duplicate_entity Если сущность уже существует
Campaign is inactive -32602 campaign_is_inactive Рекламная кампания не активна
Invalid date time -32602 invalid_date_time Не валидная дата или время, смотрите описание метода
A new data limit has been exceeded -32602 data_limit_exceeded Ошибка возникает в случае, если было достигнуто максимальное количество данных.
Action is not allowed for your tariff plan. You need contact support service or change your tariff plan settings in your account -32602 tariff_restrictions Любые ограничения тарифного плана
This value is already used by another entity -32602 already_in_use Значение указанного параметра уже используется в другой сущности. К примеру, виртуальный номер уже используется в другой рекламной кампании.

Групповые операции

Функционал не поддерживается

Принцип именования методов

Имя JSON-RPC метода состоит из двух частей разделенных точкой: глагола и имени объекта.

Имя объекта выбирается как существительное во множественном числе, отражающее бизнес-сущность, например subscribers.

Имя метода должно начинаться с глагола, отражающего суть операции.

Глаголы используемые в именовании методов

Глагол Описание
create Добавляет сущность.
get Возвращает список отсортированных и отфильтрованных данных с помощью критериев фильтрации и методов сортировки. К запросу возможно применить лимит и постраничный вывод на количество получаемых данных (см. раздел Постраничный вывод). С помощью критериев фильтрации может быть так же получена одна запись, по ёё уникальному идентификатору (см. раздел Критерии фильтрации). В специальном мета-параметре возвращается общее количество записей (см. раздел Мета-параметры). С помощью специального параметра можно указать какие поля возвращать в ответном сообщении (см. раздел Представление возвращаемых данных).
update Обновляет сущность с определённым идентификатором.
Возможно частичное обновление параметров
При обновлении массивов обновляется весь массив целиком, т.е все элементы которые не были переданы удаляются.
Для зануления необязательного параметра нужно передать null
upload Загружает исторические данные, при первой загрузке создает сущность, при последующих запросах обновляет ее
delete Удаляет сущность с определённым идентификатором.
add Связь одного объекта с другим.
enable Подключение объекта
disable Отключение объекта
set Простановка свойства на другой объект, к примеру, установка тега на обращение
unset Снятие свойства с другого объека, к примеру, снятие тега с обращения

Критерии фильтрации

Фильтрация данных применяется только к глаголу "get" (см. раздел "Глаголы используемые в именовании методов" с помощью необязательного примитива "filter", который является объектом и может содержать:

  1. Простой фильтр;
  2. Дерево фильтров которое содержит простые фильтры с условиями.

Простой фильтр - это объект, который содержит в себе обязательные примитивы:

  • field - поле сущности к которой будет применяться фильтрация (список заранее определён для метода);
  • operator - оператор фильтрации. Список всех операторов можно получить в разделе "Операторы фильтрации";
  • value - значение для оператора фильтрации. Необязательное поле, если оно отсутствует, то считается пустота.

Дерево фильтров содержит специальный примитив "filters", который может содержать в себе как простые фильтры, так и дерево фильтров.

Возможные ошибки при фильтрации

Текст Код Мнемоника Описание
Filter by parameter is prohibited -32602 filter_prohibited Фильтрация по параметру запрещена и невозможна, так как параметр для фильтрации не находится в списке разрешенных для фильтрации
Unexpected method parameter(s) -32602 unexpected_parameters Передан ошибочный параметр или параметр, которого не существует

Пример JSON структуры простого фильтра

Получаем список записей у которых поле "name" имеет имя "Bob"

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"get.entity",
  "params":{
    "filter":{
      "field":"name",
      "operator":"=",
      "value":"Bob"
    }
  }
}

Пример JSON структуры дерева фильтров с одним уровнем вложенности

Получаем список записей у которых поле "name" имеет имя "Bob" и его возраст 25 лет

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"get.entity",
  "params":{
    "filter":{
      "filters":[
        {
          "field":"name",
          "operator":"=",
          "value":"Bob"
        },
        {
          "field":"age",
          "operator":"=",
          "value":25
        }
      ],
      "condition":"and"
    }
  }
}

Пример JSON структуры дерева фильтров с двойным уровнем вложенности

Получаем список записей у которых поле "name" имеет имя "Bob" и его возраст 25 лет или список записей у которых поле "name" имеет имя "Dexter" и его возраст 2 года

{
  "jsonrpc":"2.0",
  "id":1,
  "method":"get.entity",
  "params":{
    "filter":{
      "filters":[
        {
          "filters":[
            {
              "field":"name",
              "operator":"=",
              "value":"Bob"
            },
            {
              "field":"age",
              "operator":"=",
              "value":25
            }
          ],
          "condition":"and"
        },
        {
          "filters":[
            {
              "field":"name",
              "operator":"=",
              "value":"Dexter"
            },
            {
              "field":"age",
              "operator":"=",
              "value":2
            }
          ],
          "condition":"and"
        }
      ],
      "condition":"or"
    }
  }
}

Пример JSON структуры дерева фильтров с тройным уровнем вложенности

Условие запроса ((addv_comp_id = 10 or addv_comp_id = 12) and (tag_id = 1 or tag_id = 5)) or visitor_id = 14 or (date_from = 2015-12-14 and date_till = 2015-12-16)

{
  "filter":{
    "filters":[
      {
        "filters":[
          {
            "filters":[
              {
                "field":"addv_comp_id",
                "operator":"=",
                "value":10
              },
              {
                "field":"addv_comp_id",
                "operator":"=",
                "value":12
              }
            ],
            "condition":"or"
          },
          {
            "filters":[
              {
                "field":"tag_id",
                "operator":"=",
                "value":1
              },
              {
                "field":"tag_id",
                "operator":"=",
                "value":5
              }
            ],
            "condition":"or"
          }
        ],
        "condition":"and"
      },
      {
        "field":"visitor_id",
        "value":14,
        "operator":"="
      },
      {
        "filters":[
          {
            "field":"date_from",
            "value":"2015-12-14 12:00:00",
            "operator":"="
          },
          {
            "field":"date_till",
            "value":"2015-12-16 15:00:00",
            "operator":"="
          }
        ],
        "condition":"and"
      }
    ],
    "condition":"or"
  }
}

Операторы фильтрации

Фильтрация null и not null будет =null, !=null

Оператор Описание Учёт регистра строк Тип данных
= Равно да number, string, null, boolean, iso8601, enum
!= Не равно да number, string, null, boolean, iso8601, enum
< Меньше чем - number, iso8601
> Больше чем - number, iso8601
<= Меньше или равно - number, iso8601
>= Больше или равно - number, iso8601
like Начинается с, Заканчивается на, Содержит
Используйте "%"
 да string
regexp Posix да string
jsquery PostgreSQL jsquery да object, array
in Массив значений в отношении "or" да number, string, enum

Сортировка данных

Сортировка данных применяется только к глаголу "get" (см. раздел "Глаголы используемые в именовании методов") с помощью массива объектов сортировки со следующими примитивами:

  • field - поле по которому производится сортировка;
  • order - направления сортировки. Возможные значения "asc"/"desc". "asc" - по возрастанию, "desc" - по убыванию. Параметр необязателен. Значение по умолчанию "asс".

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

Возможные ошибки при сортировки

Текст ошибки Код Мнемоника Описание
Sort by parameter is prohibited -32602 sort_prohibited Сортировка по параметру запрещена и невозможна, так как параметр для сортировки не находится в списке разрешенных для сортировки
Unexpected method parameter(s) -32602 unexpected_parameters Передан ошибочный параметр или параметр, которого не существует

JSON структура:

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"string",
  "params":{
    "sort":[
      {
        "field":"string",
        "order":"string"
      }
    ]
  }
}

Постраничный вывод

Постраничный вывод может быть применён к глаголу "get" (см. раздел "Глаголы используемые в именовании методов"). Для выполнения пагинации данных используются следующие параметры:

Параметр Значение по умолчанию Допустимое значение Описание
offset 0 100 000 Сдвиг, определяет с какого номера записи возвращать "limit" записей
limit 1000 10 000 Размер возвращаемых данных (количество записей)

JSON структура:

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"string",
  "params":{
    "offset":"number",
    "limit":"number"
  }
}

Мета-параметры

Возвращаются при использовании глагола "get" (см. раздел "Глаголы используемые в именовании методов").

Присутствуют как в ошибочном, так и в успешном ответе

Параметр "api_version" возвращается только для версий которые deprecated.

JSON структура:

{
  "metadata":{
    "api_version":{
      "current_version_deprecated":"boolean",
      "current_version":"string",
      "latest_version":"string"
    },
    "limits":{
      "day_limit":"number",
      "day_remaining":"number",
      "day_reset":"number",
      "minute_limit":"number",
      "minute_remaining":"number",
      "minute_reset":"number"
    },
    "total_items":"number"
  }
}

Представление возвращаемых данных

Отдельный список возвращаемых столбцов

В глаголе получения данных "get" (см. раздел "Глаголы используемые в именовании методов") может быть указан специальный необязательный примитив "fields" с типом массив, который может содержать список полей которые необходимо показать в выводе. Если примитив "fields" не используется, то в выводе показываются все поля по умолчанию для вызываемого метода.

Список полей индивидуален для каждого метода.

JSON структура:

{
  "jsonrpc":"2.0",
  "id":"number",
  "method":"string",
  "params":{
    "fields":[
      "string"
    ]
  }
}

Возможные ошибки в представлении возвращаемых данных

Текст Код Мнемоника Описание
Unexpected method parameter(s) -32602 unexpected_parameters Передан ошибочный параметр или параметр, которого не существует

Общие поля для всех методов

Название Тип Обязательный Допустимые значения Описание
id string или number да Уникальный идентификатор запроса к API, который используется для связи запроса с ответом. Рекомендуется делать в виде уникального хэша или случайного числа.
method string да Вызываемый метод
jsonrpc string да 2.0 Номер спецификации JSON-RPC
params object да Содержит тело запроса к API. В зависимости от вызываемого метода тело запроса меняется.

Аутентификация

Список доступных методов

Метод Описание
"login.user" Вход
"logout.user" Выход и удаление ключа сессии аутентификации