Введение — различия между версиями
SliZzzZ (обсуждение | вклад) |
Seva (обсуждение | вклад) |
||
(не показано 57 промежуточных версий 5 участников) | |||
Строка 1: | Строка 1: | ||
− | + | {{#seo: | |
+ | |title=Введение | ||
+ | |titlemode=append | ||
+ | |keywords=планфикс, апи, api | ||
+ | |description=Введение api | ||
+ | }} | ||
− | + | == Регистрация приложения == | |
+ | Для того, чтобы приложение смогло начать работу, необходимо сгенерировать аутентификационный ключ и ключ подписи. Сделать это может владелец аккаунта в разделе '''Управление аккаунтом / Доступ к 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 минут). | ||
+ | |||
+ | |||
+ | == Формат запросов== | ||
+ | Пакет запроса имеет следующую структуру | ||
+ | <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: Авторизация по логину и паролю|по логину и паролю]]. Предпочтительным является авторизация по токену, авторизация по логину и паролю сохраняется для целей обратной совместимости, чтобы не нарушать работу существующих клиентских приложений. | ||
+ | |||
+ | |||
+ | == Формат ответов== | ||
+ | |||
+ | Пакет ответа имеет следующую структуру: | ||
+ | <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> | ||
+ | |||
+ | Структура ответа с ошибкой: | ||
+ | <source lang="xml"> | ||
+ | <?xml version="1.0" encoding="UTF-8"?> | ||
+ | <response status="error"> | ||
+ | <code></code> | ||
+ | </response> | ||
+ | </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>