Это старая версия документа!
Платформа CleverFormsTM предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в CleverFormsTM. Одним из способов такого взаимодействия является использование CleverForms API.
CleverFormsTM API определяет набор функций, к которым разработчики могут совершать запросы и получать ответы. Взаимодействие происходит по протоколу HTTP. Преимуществом такого подхода является широкое распространение протокола HTTP, поэтому CleverFormsTM API можно использовать практически из любого языка программирования. CleverFormsTM API предназначено, в основном, для запросов с внешних серверов к серверам CleverFormsTM.
Все вызовы методов API — это GET или POST HTTP-запросы к URL
<protocol>://<domain>/<appname>/handler/api.
с некоторым набором параметров. Вы выбираете в документации нужный метод,
например, document.calculate
, формируете запрос согласно документации метода, и осуществляете этот
запрос. В ответ на запрос вы получаете его результат, который также описан в документации каждой функции. Кодировка результата — UTF-8.
Например, на PHP для осуществления такого запроса можно использовать cURL, на Perl —
LWP::Simple, на Python — httplib, использовать cURL из командной строки и даже просто ваш браузер.
Данные запроса могут передаваться в виде query-строки (после знака ?) при использовании метода
GET, либо в теле POST-запроса. Помните, что все параметры должны быть закодированы с помощью URL
encoding.
На данный момент, API не делает различий между GET- и POST-запросами. Тем не менее, помните,
что существует ограничение на длину URL запроса — 2048 символов. Поэтому мы рекомендуем вам выполнять запросы на получение информации с помощью метода GET (они обычно легко умещаются в ограничение), а запросы на изменение данных — с помощью метода POST. Так вы не будете ограничены длиной запроса, кроме того, такое использование больше соответствует спецификации протокола HTTP.
В каждом запросе должен присутствовать набор обязательных параметров. Также для каждой функции в ее документации определены дополнительные параметры, нужные только для этой функции. Текстовые значения параметров должны быть преданы в кодировке UTF-8. Одинаковые для всех функций параметры перечислены ниже.
Имя | Тип | Описание |
---|---|---|
method | string | название вызываемого метода, например, documents.calculate ; обязательный параметр |
app_id | long | идентификатор приложения; обязательный параметр |
sig | string | подпись запроса; обязательный параметр |
sid | string | номер текущей сессии; обязательный параметр |
uid | long | идентификатор пользователя, для которого вызывается метод; обязательный параметр для запросов «клиент-сервер» |
secure | bool | флаг, обозначающий, что запрос идет по защищенной схеме «сервер-сервер»; возможные значения: 1 или 0; по-умолчанию 0 («клиент-сервер») |
format | string | формат приема/выдачи ответа API; возможные значения: form, xml или json ; по умолчанию json ; в случае form - данные считываются с формы приложения и выдаются в формате json |
data | string | пакет дополнительных данных (только при использовании метода GET); данные должны быть представлены в виде подписанного пакета в соответствующем формате подробнее см. Пакеты данных |
Порядок следования параметров в запросе значения не имеет значения, порядок параметров важен
только при расчете подписи.
Идентификатор приложения app_id
уникален для каждого приложения или сайта.
Флаг secure
и подпись sig
рассчитываются в зависимости от схемы запроса (см. ниже).