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

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

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

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

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

Рекомендуем ознакомиться с примерами использования API на PHP.
Ограничение на количество запросов — 500 запросов в час на активного сотрудника (за исключением сотрудников с доступом «только просмотр»), но не менее 1 000 запросов в час.

К примеру, если у вас только один сотрудник, лимит составит 1 000 запрос в час. Если в аккаунте 15 активных сотрудников, лимит будет 7 500 запросов в час.

При превышении лимита выдаётся сообщение с ошибкой.

Количество оставшихся API-запросов при любом запросе можно отследить в заголовках ответа через параметр: api_calls_left.

Максимальный лимит — 50 000 запросов в час.
Аутентификация
Работа с 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-адрес сотрудника с полным доступом.