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

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

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

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

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

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

Поле

Тип

Описание

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 - количество объектов, которые нужно пропустить, прежде чем возвращать данные