Задать вопрос

Общие правила

Формат запроса

Все запросы, кроме запроса авторизации, требуют специльных заголовков аутентификации.

URL любого API-запроса составляется следующим образом:

https://demo.megaplan.ru/<URI_команды>

Например, для аккаунта с именем someaccount запрос на получение списка задач, в фоормате JSON, будет следующим:

http://someaccount.megaplan.ru/BumsTaskApiV01/Task/list.api

Параметры запроса могут быть переданы как через GET, так и через POST. Для запросов получения данных рекомендуется пользоваться методом GET. Для добавления/изменения данных рекомендуется пользоваться методом POST.

GET-параметры необходимо передавать стандартным образом, добавляя в URL-запроса. Например:

https://someaccount.megaplan.ru/BumsCommonApiV01/User/authorize.xml?Login=name&Password=md5pass

Ответ на любой запрос содержит JSON или XML со следующими аттрибутами:

  • params - значения входных параметров (если функция таковые поддерживает);
  • data - выходные данные (список или один объект); формат зависит от функции и приводится в ее описании; аттрибут может отсутствовать;
  • status - статус ответа с аттрибутами:
    • code - код ответа (ok или error);
    • message - текстовое описание статуса (например, суть ошибки).

Формат ответа определяется по расширению в конце запроса. Расширение .api возвращает данные в формате JSON. Расширение .xml возвращает данные в формате XML. Подробнее различие в форматах можно посмотреть на примере получения списка задач.

Пример ответа в JSON-формате

{
  "status":
  {
    "code":"ok",
    "message":null
  },
  "params":
  {
    // список входных параметров
  },
  "data":
  {
    // формат данных зависит от команды API и описан в документации команды
  }
}

Пример ответа в XML-формате

<?xml version="1.0" encoding="utf-8"?>
<response>
  <status>
    <code>ok</code>
    <message></message>
  </status>
  <params>
    // список входных параметров
  </params>
  <data>
    // формат данных зависит от команды API и описан в документации команды
  </data>
</response>

Для упрощения механизма клиентского кэширования, API поддерживает пару стандартных HTTP-заголовков ETag и If-None-Match. Каждый ответ на GET-запрос к API содержит заголовок ETag с хэшом, который уникально идентифицирует ответ. Значение хэша не изменяется до тех пор, пока не изменится содержание тела ответа.

Если в повторный запрос добавить заголовок If-None-Match, содержащий ранее полученный хэш, то в ответ на такой запрос вернется либо статус 200 OK с новым значением ETag (если ответ изменился), либо статус 304 Not Modified с пустым телом ответа (если ответ не изменился).

Помимо этого в ответе поддерживаются HTTP-заголовки серверных ошибок 400, 401, 403, 404, 500. В остальных случаях код ответа будет 200.

Ограничения API

Частота запросов к API ограничена 50 запросами в минуту. Если запросы делаются от сотрудника с правами директора, то ограничение возрастает пропорционально количеству лицензий аккаунт. То есть, если в аккаунте 20 лицензий, то от сотрудника с правами директора может делать 50 запросов/минута * 20 лицензий = 1000 запросов в минуту.

Подсказка: запрос авторизации и получения ключей доступа не стоит выполнять каждый раз, их можно запомнить и использовать повторно, периодически обновляя. Это позволит делать больше запросов получения/изменения данных, не превышая лимит.

Работа со списками

Список системных и пользовательских фильтров для задач проектов, клиентов и сделок

URI: /BumsCommonApiV01/Filter/list.api|xml

Входные параметры

Поле Тип Допустимые значения Описание
SubjectType string task (задача), project (проект), contractor (клиент), deal (сделка) Тип объекта
FilterType string all (все, по умолчанию), fixed (системные), user (пользовательские) Тип фильтра
ProgramId int Id схемы сделки для SubjectType = deal Id схемы

Выходные данные

Поле Тип Описание  
Id string Код фильтра  
Name string Фильтра метки  
Count int Количество задач или проектов, удовлетворяющих условию фильтра  

Пример ответа в JSON-формате

{
  "status":
  {
    "code":"ok",
    "message":null
  },
  "data":
  {
    "filters":
    [
      {
        "Id":1001128,
        "Name":"Персональный фильтр",
        "Count":7
      },
    ]
  }
}

Пример ответа в XML-формате

<?xml version="1.0" encoding="utf-8"?>
<response>
  <status>
    <code>ok</code>
    <message></message>
  </status>
  <data>
    <filters>
      <item>
        <id>1001128</id>
        <name>Персональный фильтр</name>
        <time_created>2011-05-17 19:26:23</time_created>
        <count>7</count>
    </item>
    </filters>
  </data>
</response>

Фильтрация

Большинство списков фильтруется параметром FilterFields. Доступны сравнения по less, equal, lessOrEqual, greater, greaterOrEqual. Например, запрос: http://someaccount.megaplan.ru/BumsInvoiceApiV01/Invoice/list.api?FilterFields[Date][greaterOrEqual]=2011-07-01 16:11:00, вернет счета, созданные после 16 часов, 11 минут, первого июля 2011 года.

Пейджинация

Большинство списков объектов можно пейджинировать, используя параметры:
  • int Limit - максимальное количество возвращаемых объектов
  • int Offset - количество объектов, которые нужно пропустить, прежде чем возвращать данные