OMNIDESK API
Общие моменты
Введение
API — это интерфейс для управления каким-либо программным обеспечением извне. Подобное управление осуществляется с помощью набора готовых классов, процедур и функций. Зачастую API используют для интеграции одного сервиса с другим.

API Омнидеска позволяет удаленно: считывать, изменять, добавлять и удалять данные из вашего аккаунта. Вот лишь небольшой перечень его возможных применений:

  • подключение собственной формы для создания обращений;
  • получение списка всех обращений;
  • изменение параметров обращений;
  • получение списка пользователей;
  • блокировка пользователей;
  • создание и редактирование групп;
  • отключение и удаление сотрудников.

По умолчанию во многих методах используется поиск. Допустим, нужно найти пользователя с email-адресом [email protected]. В выборку попадёт не только этот ящик, но и другие ящики ([email protected], [email protected]), которые могут быть нам не нужны. Чтобы искать именно строку, а не включение, используйте символ ^. Примеры: ^string^ ищет строку; ^string найдет строки, которые начинаются на string; string^ найдет строки, которые заканчиваются на string.

Мы постоянно добавляем новые API-методы, чтобы покрывать ваши потребности в плане интеграции с Омнидеском. Если у API ещё нет нужных вам возможностей, напишите нам. Наиболее востребованные методы будут реализованы в первую очередь.

Рекомендуем ознакомиться с примерами использования API на PHP.
Лимит на количество запросов зависит от вашего тарифа:
  • Базовый — до 50 запросов в минуту, но не меньше 20;
  • Стандартный — до 750 запросов в минуту;
  • Профи — до 1 500 запросов в минуту.

Для тарифов «Базовый» и «Стандартный» лимит составляет 5 запросов в минуту, а для тарифа «Профи» — 10 запросов в минуту на каждого включенного сотрудника. Примеры вычисления лимита:
  • 10 сотрудников, тариф «Базовый» → 10 * 5 = 50 запросов в минуту;
  • 100 сотрудников, тариф «Стандартный» → 100 * 5 = 500 запросов в минуту;
  • 200 сотрудников, тариф «Стандартный» → 200 * 5 > 750, поэтому лимит = 750 запросов в минуту;
  • 100 сотрудников, тариф «Профи» → 100 * 10 = 1 000 запросов в минуту.

Лимит общий на весь Омнидеск-аккаунт, поэтому все запросы по лимиту можно выполнять как от одного сотрудника, так и от разных.

При превышении лимита выдаётся сообщение с ошибкой «429 Too Many Requests».

Запросы на запись (методы POST, PUT, DELETE) засчитываются как два запроса в рамках лимита.

Чтобы не превышать лимит на количество запросов, ваш скрипт должен проверять заголовки в ответе:
  • rate_limit_per_minute — максимальное количество запросов в минуту;
  • api_calls_left — количество запросов, оставшихся в текущем интервале лимита;
  • retry_after — количество секунд, после которых лимит сбросится.
Аутентификация
Работа с API требует аутентификации. Она производится по API-ключу, но дополнительно нужно указать email-адрес сотрудника (не администратора), так как некоторые методы требуют определения сотрудника. Используйте email-адрес сотрудника, который едва ли будет когда-то отключен или удален.
Пример запроса
curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X GET https://[domain].omnidesk.ru/api/cases.json
Как получить API-ключ?
  1. Войдите в аккаунт администратора
  2. Перейдите в раздел «Настройки», подраздел «API»
  3. Нажмите на ссылку «добавить API-ключ»
Общие правила запросов
Чтобы просмотреть, передать или изменить данные, в запросе нужно использовать идентификаторы или «URI». URL любого API-запроса составляется следующим образом:
https://[domain].omnidesk.ru/api/[URI]
    К примеру, для получения списка обращений аккаунта robotsrules запрос должен быть следующим:
    https://robotsrules.omnidesk.ru/api/cases.json
    Методы, используемые при передаче параметров запроса
    Уровень доступа к данным
    При аутентификации, помимо API-ключа, вы указываете email-адрес сотрудника. Соответственно, уровень доступа к данным и возможность их изменения зависит от прав сотрудника.

    Если у выбранного сотрудника ограниченный доступ, вы не сможете получить список всех обращений. Поэтому зачастую целесообразно указывать email-адрес сотрудника с полным доступом.