Введение
ПланФикс API - это набор интерфейсов, предназначенный для доступа к данным ПланФикс-аккаунта используя протоколы HTTP и XML.
API позволяет Вам быстро и просто создавать веб- и настольные приложения, которые можно интегрировать с любым ПланФикс-аккаунтом.
Вот несколько вариантов, для чего можно использовать интерфейсы ПланФикс API:
- Создание собственных приложений или сервисов на базе ПланФикс;
- Разработка дополнений к основному функционалу ПланФикс. Расширение возможностей использования сервиса;
- Импорт данных из других систем в ПланФикс;
- Экспорт данных из ПланФикса в другие системы;
- Организация уведомлений о задачах и действиях в ПланФиксе удобным для клиента способом;
- Портирование сервиса ПланФикс на другие платформы, в том числе и мобильные;
- Создание сервисов для получения и дальнейшего использования аналитической информации, находящейся в ПланФикс.
Регистрация приложения
Для того, чтобы приложение смогло начать работу, необходимо его зарегистровать на странице http://dev.planfix.ru.
В результате регистрации будет получены два ключа: аутентификационный ключ и ключ подписи.
Доступ к интерфейсам
Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу: https://api.planfix.ru/xml/.
Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.
Все API выполняются через POST запросы.
Ограничения по запросам от приложения
По-умолчанию, все аккаунты имеют ограничение в 5000 запросов в сутки. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос.
Формат запросов/ответов
Пакет запроса имеет следующую структуру
<?xml version="1.0" encoding="UTF-8"?>
<request method="{Имя_вызываемой функции}">
<account></account>
<sid></sid>
<!-- ... -->
</request>| Название | Тип | Значение | Примечание |
|---|---|---|---|
| account | string | аккаунт на котором будет выполняться функция | обязательное поле и присутствует во всех запросах |
| sid | string(32) | ключ сессии полученный в результате выполнения функции auth |
Пакет ответа имеет следующую структуру:
<?xml version="1.0" encoding="UTF-8"?>
<response status="{ok|error}">
<code>xxxx</code> <!-- присутствует если статус ошибки error -->
<!-- тело ответа -->
</response>Все ответы на запросы списков содержат в корневом элементе два атрибута. totalCount - количество всех элементов удовлетворяющих условию, count - количество возвращенных элементов в результате. Например:
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
<actions count="5" totalCount="23">
</actions>
</response>Структура ответа с ошибкой:
<?xml version="1.0" encoding="UTF-8"?>
<response status="error">
<code></code>
</response>