Access код ошибки 32004

• Соглашения
• Пользователи API и аутентификация
• Добавить IP-адрес в список разрешенных
  • Доступ по ключу
  • Доступ по логину и паролю
• Отчёт по запросам к API
• Базовый 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 и аутентификация

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

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

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

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

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

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

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

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

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

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

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

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

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

• <protocol> — https;
• <hostname> — api.comagic.ru, api.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) он помечен как успешный.

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

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

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

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

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

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

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

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

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": {

      }
    }
  }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Пример 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

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

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

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

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

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

JSON структура:

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

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

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

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"
    ]
  }
}

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

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

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

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