Data API

• Соглашения
• Пользователи API и аутентификация
• Добавить IP-адрес в список разрешенных
  • Доступ по ключу
  • Доступ по логину и паролю
• Базовый URL для доступа к API
• Версионность
• Лимиты и ограничения
  • Методы и их стоимость в баллах
  • Расширение лимитов
• Обработка ошибок
  • Параметры сообщения об ошибке
  • JSON структура ошибки
  • Группы кодов ошибок
    • Список ошибок общих для всех методов
    • Список ошибок для методов с глаголом get
    • Список ошибок общих для методов с глаголом delete
    • Список ошибок общих для методов с глаголом create и update, set, unset
  • Глаголы используемые в именовании методов
  • Критерии фильтрации
    • Возможные ошибки при фильтрации
    • Пример JSON структуры простого фильтра
    • Пример JSON структуры дерева фильтров с одним уровнем вложенности
    • Пример JSON структуры дерева фильтров с двойным уровнем вложенности
    • Пример JSON структуры дерева фильтров с тройным уровнем вложенности
    • Операторы фильтрации
  • Сортировка данных
    • Возможные ошибки при сортировки
  • Постраничный вывод
  • Мета-параметры
  • Представление возвращаемых данных
    • Отдельный список возвращаемых столбцов
    • Возможные ошибки в представлении возвращаемых данных
  • Общие поля для всех методов
  • Аутентификация

Соглашения

Приняты следующие соглашения при использовании 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 и аутентификация

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

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

В настройках пользователя Администратор есть возможность включить доступ по ключу. Для этого в разделе Телефония - Пользователи АТС открыть настройки пользователя "Администратор". В настройках пользовтаеля в вкладке API поставьте галку "Использовать ключ API".

Существует два типа ключей:

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

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

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

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

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

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

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

<protocol> :// <hostname> / <version>

• <protocol> - https;
• <hostname> - dataapi-jsonrpc.novofon.ru;
• <version> - версия API (см. раздел Версионность)

https://dataapi-jsonrpc.novofon.ru/<version>

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

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

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

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

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

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

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

Название	Тип	Обязательный	Описание
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"	Выход и удаление ключа сессии аутентификации