Введение
Регистрация приложения
Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе Управление аккаунтом / Доступ к API.
Важно: работа с API доступна только в платных или премиум-аккаунтах.
Доступ к интерфейсам
Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу:
https://api.planfix.ru/xml/ - для аккаунтов расположенных в Европе
https://apiru.planfix.ru/xml/ - для аккаунтов расположенных в России
Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.
Все API вызовы выполняются через POST запросы.
Ограничения по запросам от приложения
По-умолчанию, все аккаунты имеют ограничение в 20 000 запросов в сутки и 1 запрос в секунду. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос.
Формат запросов
Пакет запроса имеет следующую структуру
<?xml version="1.0" encoding="UTF-8"?>
<request method="{Имя_вызываемой функции}">
<account></account>
<sid></sid>
<!-- ... -->
</request>| Название | Тип | Значение | Примечание |
|---|---|---|---|
| account | string | аккаунт на котором будет выполняться функция | обязательное поле и присутствует во всех запросах |
| sid | string(32) | ключ сессии полученный в результате выполнения функции auth | если используется аутентификация по логину/паролю |
Авторизация
Возможно два способа авторизации - по токену авторизации или по логину и паролю. Предпочтительным является авторизация по токену, авторизация по логину и паролю сохраняется для целей обратной совместимости, чтобы не нарушать работу существующих клиентских приложений.
В случае использования авторизации по логину и паролю каждый запрос должен содержать заголовок базовой HTTP авторизации и дополнительно в самом теле запроса поле sid - ключ сессии полученный в результате выполнения функции auth
Во случае авторизации по токену каждый запрос должен содержать только заголовок базовой HTTP авторизации. Токены авторизации создаются в разделе Управление аккаунтом / Доступ к API, и могут быть ограничены только заданными функциями.
В заголовке базовой авторизации в качестве имени пользователя используется APIKey, в качестве пароля - токен авторизации (при авторизации по логину / паролю - а качестве пароля в заголовке пустая строка). Пример для авторизации по токену:
curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
-u 4db09df5a62a8a32a9522fcac02d3c6f:06540b851b466ccf84558573aff11b65 -k -d '<request>...</request>' https://api.planfix.ru/xml/Пример для авторизации по логину / паролю:
curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
-u 4db09df5a62a8a32a9522fcac02d3c6f: -k -d '<request>...</request>' https://api.planfix.ru/xml/Информация для случая, если заголовок формируется самостоятельно. Заголовок базовой авторизации выглядит следующим образом:
Authorization : Basic NGRiMDlkZjVhNjJhOGEzMmE5NTIyZmNhYzAyZDNjNmY6WA==где слово после Basic - base64('ApiKey:Token');
Формат ответов
Пакет ответа имеет следующую структуру:
<?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>