Введение — различия между версиями

Текущая версия на 06:40, 8 августа 2019

Содержание

1 Регистрация приложения
2 Доступ к интерфейсам
3 Ограничения по запросам от приложения
4 Формат запросов
5 Авторизация
6 Формат ответов
7 Перейти

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

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

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

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

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

https://api.planfix.ru/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>

Перейти

XML API v1

@@ Строка 1: / Строка 1: @@
+{{#seo:
+|title=Введение
+|titlemode=append
+|keywords=планфикс, апи, api
+|description=Введение api
+}}
 == Регистрация приложения ==
 Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе '''Управление аккаунтом / Доступ к API'''.
@@ Строка 15: / Строка 22: @@
 Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.
-Все API выполняются через POST запросы.
+Все API вызовы выполняются через POST запросы.
 == Ограничения по запросам от приложения ==
-По-умолчанию, все аккаунты имеют ограничение в 20 000 запросов в сутки и 10 запросов в секунду. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос.
+По-умолчанию, все аккаунты имеют ограничение, согласно их пакета (20/50/100 000 запросов в сутки) и 1 запрос в секунду. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос.
+Примерное количество оставшихся запросов в сутки возвращается в заголовке X-RateLimit-Remaining (значение обновляется примерно раз в 10 минут).
-== Формат запросов/ответов==
+== Формат запросов==
 Пакет запроса имеет следующую структуру
 <source lang="xml">
@@ Строка 37: / Строка 45: @@
 |account ||string|| аккаунт на котором будет  выполняться функция ||обязательное поле и присутствует во всех запросах
 |-
-|sid ||string(32) ||ключ сессии полученный в результате выполнения функции  [[ПланФикс_API:Аутентификация|auth]]  ||
+|sid ||string(32) ||ключ сессии полученный в результате выполнения функции  [[ПланФикс_API:Аутентификация|auth]]  || если используется аутентификация по логину/паролю
 |-
 |}
-Каждый запрос должен включать заголовок базовой HTTP авторизации. В качестве имени пользователя используется APIKey, в качестве пароля может передаваться всё, что угодно - этот параметр игнорируется. Пример:
-<source lang="bash">
-curl -H 'Accept: application/xml' -H 'Content-Type: application/xml' \
--u 4db09df5a62a8a32a9522fcac02d3c6f:X -k -d '<request>...</request>' https://api.planfix.ru/xml/
-</source>
-Заголовок базовой авторизации выглядит следующим образом:
-<source lang="bash">
+== Авторизация ==
-Authorization : Basic NGRiMDlkZjVhNjJhOGEzMmE5NTIyZmNhYzAyZDNjNmY6WA==
+Возможно два способа авторизации - [[ПланФикс API: Авторизация по токену|по токену авторизации]] или [[ПланФикс API: Авторизация по логину и паролю|по логину и паролю]]. Предпочтительным является авторизация по токену, авторизация по логину и паролю сохраняется для целей обратной совместимости, чтобы не нарушать работу существующих клиентских приложений.
-</source>
-где слово после Basic - base64('ApiKey:X');
+== Формат ответов==
 Пакет ответа имеет следующую структуру:
@@ Строка 76: / Строка 80: @@
 </response>
 </source>
+== Перейти ==
+*[[XML API v1]]