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

Материал из Planfix
Перейти к: навигация, поиск
Нет описания правки
 
(не показана 51 промежуточная версия 6 участников)
Строка 1: Строка 1:
ПланФикс API - это набор интерфейсов, предназначенный для доступа к данным ПланФикс-аккаунта используя протоколы HTTP и XML.
{{#seo:
|title=Введение
|titlemode=append
|keywords=планфикс, апи, api
|description=Введение api
}}


API позволяет Вам быстро и просто создавать веб- и настольные приложения, которые можно интегрировать с любым ПланФикс-аккаунтом.
== Регистрация приложения ==
Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе '''Управление аккаунтом / Доступ к API'''.
 
'''Важно:''' работа с API доступна только в платных или премиум-аккаунтах.
 
 
== Доступ к интерфейсам ==
Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу:
 
<geoip eq="RU,BY">'''https://apiru.planfix.ru/xml/''' - для аккаунтов расположенных в России</geoip><geoip not="RU,BY">
'''https://api.planfix.com/xml/''' - для аккаунтов расположенных в Европе
 
'''https://api-sg.planfix.com/xml/''' - для аккаунтов расположенных в Азии
 
'''https://api-us.planfix.com/xml/''' - для аккаунтов расположенных в Америке
</geoip>
 
 
Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение, будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.


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


Вот несколько вариантов, для чего можно использовать интерфейсы ПланФикс API:


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




== Регистрация приложения ==
== Формат запросов==
Для того, чтобы приложение смогло начать работу, необходимо его зарегистровать на странице '''https://dev.planfix.ru'''.
Пакет запроса имеет следующую структуру
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<request method="{Имя_вызываемой функции}">
  <account></account>
  <sid></sid>
  <!-- ... -->
</request>
</source>
{| class="wikitable" style="margin-top: 1em; width:100% "
!width="150"|Название !!width="200"| Тип !!width="50%"| Значение !! Примечание
|-
|account ||string|| аккаунт на котором будет  выполняться функция ||обязательное поле и присутствует во всех запросах
|-
|sid ||string(32) ||ключ сессии полученный в результате выполнения функции  [[ПланФикс_API:Аутентификация|auth]]  || если используется аутентификация по логину/паролю
|-
|}
 
 
== Авторизация ==
Возможно два способа авторизации - [[ПланФикс API: Авторизация по токену|по токену авторизации]] или [[ПланФикс API: Авторизация по логину и паролю|по логину и паролю]]. Предпочтительным является авторизация по токену, авторизация по логину и паролю сохраняется для целей обратной совместимости, чтобы не нарушать работу существующих клиентских приложений.


В результате регистрации будет получены два ключа: аутентификационный ключ и ключ подписи.


== Формат ответов==


== Доступ к интерфейсам ==
Пакет ответа имеет следующую структуру:
Доступ к интерфейсу осуществляется через единственную точку входа, находящуюся по адресу: '''https://api.planfix.ru/xml/'''.
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<response status="{ok|error}">
  <code>xxxx</code> <!-- присутствует если статус ошибки error -->
  <!-- тело ответа -->
</response>
</source>
Все ответы на запросы списков содержат в корневом элементе два атрибута. '''totalCount''' - количество всех элементов удовлетворяющих условию, '''count''' - количество возвращенных элементов в результате. Например:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<response status="ok">
  <actions count="5" totalCount="23">
  </actions>
</response>
</source>


Обратите внимание, что доступ к интерфейсу осуществляется по протоколу HTTPS. Все запросы, использующие незащищенное соединение будут автоматически игнорироваться, поэтому мы рекомендуем устанавливать тестовое безопасное соединение с точкой доступа к интерфейсам ПланФикс перед отправкой данных.
Структура ответа с ошибкой:
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<response status="error">
  <code></code>
</response>
</source>


Все API выполняются через POST запросы.
== Перейти ==
*[[XML API v1]]

Текущая версия от 11:20, 19 ноября 2024

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

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

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


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

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


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

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

https://api-us.planfix.com/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.com/ru/help/index.php?title=Введение&oldid=47058