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

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

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

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 ограничена 10 запросами в секунду на аккаунт.

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

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

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

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>

Загрузка файлов¶

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

Поле	Тип	Описание
Content	string	Контент файла закодированный с использованием MIME base64
Name	string	Название файла

Примеры загрузки файлов¶

Загрузка в кастомное поле модуля сделки¶

Cделки

{
  "Id" : 1,
  "Model" : {
    "Category1000048CustomFieldFile" : {
      "Add" : [
        {
          "Content" : "{{BASE64_ENCODED_FILE_CONTENT}}",
          "Name" : "someName.txt",
        }
      ]
    }
  }
}

Создание комментария с файлом¶

Комментарии

{
  "SubjectType" : "deal",
  "SubjectId" : 1,
  "Model" : {
    "Text" : "some text",
    "Attaches" : [
      {
        "Content" : "{{BASE64_ENCODED_FILE_CONTENT}}",
        "Name" : "testImg.jpeg",
      }
    ]
  }
}

Фильтрация¶

Большинство списков фильтруется параметром 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 года.

Условия можно объединять с помощью блоков «and», «or», «not». Например, запрос /BumsCrmApiV01/Contractor/list.api?FilterFields[or][Email]=ivan@mail.ru&FilterFields[or][Skype]=ivan&FilterFields[not][Name]=Ivan вернет клиентов у которых основная почта «ivan@mail.ru» или skype «ivan» и имя не равно «Ivan»

Пейджинация¶

Большинство списков объектов можно пейджинировать, используя параметры:

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