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

Материал из ПланФикс
Перейти к: навигация, поиск
(→‎Ограничения по запросам от приложения)
 
(не показаны 32 промежуточные версии 5 участников)
Строка 1: Строка 1:
−
ПланФикс API - это набор интерфейсов, предназначенный для доступа к данным ПланФикс-аккаунта используя протоколы HTTP и XML.
+
{{#seo:
 +
|title=Введение
 +
|titlemode=append
 +
|keywords=планфикс, апи, api
 +
|description=Введение api
 +
}}
  
−
API позволяет Вам быстро и просто создавать веб- и настольные приложения, которые можно интегрировать с любым ПланФикс-аккаунтом.
+
== Регистрация приложения ==
 +
Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе '''Управление аккаунтом / Доступ к API'''.
  
  
−
Вот несколько вариантов, для чего можно использовать интерфейсы ПланФикс API:
+
'''Важно:''' работа с API доступна только в платных или премиум-аккаунтах.
  
−
# Создание собственных приложений или сервисов на базе ПланФикс;
+
== Доступ к интерфейсам ==
−
# Разработка дополнений к основному функционалу ПланФикс. Расширение возможностей использования сервиса;
+
Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу:  
−
# Импорт данных из других систем в ПланФикс;
 
−
# Экспорт данных из ПланФикса в другие системы;
 
−
# Организация уведомлений о задачах и действиях в ПланФиксе удобным для клиента способом;
 
−
# Портирование сервиса ПланФикс на другие платформы, в том числе и мобильные;
 
−
# Создание сервисов для получения и дальнейшего использования аналитической информации, находящейся в ПланФикс.
 
−
 
 
−
 
 
−
== Регистрация приложения ==
 
−
Для того, чтобы приложение смогло начать работу, необходимо его зарегистровать на странице '''http://dev.planfix.ru'''.
 
  
−
В результате регистрации будет получены два ключа: аутентификационный ключ и ключ подписи.
+
'''https://api.planfix.ru/xml/''' - для аккаунтов расположенных в Европе
  
 +
'''https://apiru.planfix.ru/xml/''' - для аккаунтов расположенных в России
  
−
== Доступ к интерфейсам ==
 
−
Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу: '''https://api.planfix.ru/xml/'''.
 
  
 
Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.
 
Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.
  
−
Все API выполняются через POST запросы.
+
Все API вызовы выполняются через POST запросы.
  
  
 
== Ограничения по запросам от приложения ==
 
== Ограничения по запросам от приложения ==
−
По-умолчанию, все аккаунты имеют ограничение в 5000 запросов в сутки. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос.
+
По-умолчанию, все аккаунты имеют ограничение, согласно их пакета (20/50/100 000 запросов в сутки) и 1 запрос в секунду. Также, для методов, которые возвращают списки значений, установлено ограничение в размере 100 результатов за один запрос.
 +
Примерное количество оставшихся запросов в сутки возвращается в заголовке X-RateLimit-Remaining (значение обновляется примерно раз в 10 минут).
 +
 
  
−
== Формат запросов/ответов==
+
== Формат запросов==
 
Пакет запроса имеет следующую структуру
 
Пакет запроса имеет следующую структуру
 
<source lang="xml">
 
<source lang="xml">
Строка 47: Строка 45:
 
|account ||string|| аккаунт на котором будет  выполняться функция ||обязательное поле и присутствует во всех запросах  
 
|account ||string|| аккаунт на котором будет  выполняться функция ||обязательное поле и присутствует во всех запросах  
 
|-
 
|-
−
|sid ||string(32) ||ключ сессии полученный в результате выполнения функции  [[ПланФикс_API:Аутентификация|auth]]  ||
+
|sid ||string(32) ||ключ сессии полученный в результате выполнения функции  [[ПланФикс_API:Аутентификация|auth]]  || если используется аутентификация по логину/паролю
 
|-
 
|-
 
|}
 
|}
 +
 +
 +
== Авторизация ==
 +
Возможно два способа авторизации - [[ПланФикс API: Авторизация по токену|по токену авторизации]] или [[ПланФикс API: Авторизация по логину и паролю|по логину и паролю]]. Предпочтительным является авторизация по токену, авторизация по логину и паролю сохраняется для целей обратной совместимости, чтобы не нарушать работу существующих клиентских приложений.
 +
 +
 +
== Формат ответов==
  
 
Пакет ответа имеет следующую структуру:
 
Пакет ответа имеет следующую структуру:
Строка 75: Строка 80:
 
</response>
 
</response>
 
</source>
 
</source>
 +
 +
== Перейти ==
 +
*[[XML API v1]]

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

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

Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе Управление аккаунтом / Доступ к 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>

Перейти

Источник — «http://planfix.ru/wiki/index.php?title=Введение&oldid=19100»