Введение

Материал из Planfix
Перейти к: навигация, поиск

Регистрация приложения

Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе Управление аккаунтом / Доступ к API.

Важно: работа с API доступна только в платных или премиум-аккаунтах.


Доступ к интерфейсам

Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу:

https://api.planfix.com/xml/ - для аккаунтов расположенных в Европе

https://apiru.planfix.ru/xml/ - для аккаунтов расположенных в России


Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.

Все API вызовы выполняются через POST запросы.


Ограничения по запросам от приложения

По-умолчанию, все аккаунты имеют ограничение, согласно их пакета (20/50/100 000 запросов в сутки) и 1 запрос в секунду. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос. Примерное количество оставшихся запросов в сутки возвращается в заголовке X-RateLimit-Remaining (значение обновляется примерно раз в 10 минут).


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

Пакет запроса имеет следующую структуру

<?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>

Перейти