Это старая версия документа!
Платформа 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
рассчитываются в зависимости от схемы запроса (см. ниже).
Чтобы удостовериться, что запрос отправлен действительно вами, а не злоумышленниками от лица
вашего приложения, все запросы к REST API должны быть подписаны. Подпись может вычисляться по
двум схемам: клиент-сервер и сервер-сервер. Результат расчета подписи вы должны передать в параметре sig
, Платформа проверит подпись и выполнит запрос только если подпись правильная
Схема сервер-сервер является более надежной, чем схема клиент-сервер, поэтому с ее помощью
можно выполнять все запросы, даже те, которые не могут быть выполнены при подписании по схеме клиент сервер. Используйте ее для критичных к безопасности запросов.
Схема сервер-сервер использует отдельный ключ secret_key
, который мы настоятельно рекомендуем вам хранить только на ваших серверах и использовать только при запросах с них к серверам Платформы.
Когда вы хотите использовать схему сервер-сервер, вы должны передать в параметрах запроса параметр secure=1
и рассчитать значение параметра sig
следующим образом:
sig = sha(params + secret_key)
Значение params — это конкатенация пар «имя=значение» отсортированных в алфавитом порядке по «имя», где «имя» — это название параметра, передаваемого в функцию API, «значение» — значение
этого параметра. Разделитель в конкатенации не используется. Параметр sig при расчете подписи не учитывается, все остальные параметры запроса должны учитываться при расчете.
Значение secret_key
является публичным ключем, который вы сможете получить после подключения.
Например:
Пусть secret_key= MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCNpXjiYH5PCebH1TBOjwsi6Btx+xgPuBTVLs4DDu/6fOZH8/B3pRxem8eHpiZoKZDhSgJBs nzf5cAObiA2EVrGMuMBvzX0RLJesYh8DB08wCpbSh7asqvyPxTQPy8s2ujYWoHnRETze+X5P9j4dActJB9CxHdglblBAAMUucxuQQIDAQAB Запрос, который вы хотите выполнить: https://clever-forms.com/svd/handler/api?method=load.countries&app_id=3&uid=5&secure=1&format=xml Тогда: params = app_id=3format=xmlmethod=load.countriessecure=1uid=5 sig = sha(app_id=3format=xmlmethod=load.countriessecure=1uid=5MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCNpXjiYH5PCebH1 TBOjwsi6Btx+xgPuBTVLs4DDu/6fOZH8/B3pRxem8eHpiZoKZDhSgJBsnzf5cAObiA2EVrGMuMBvzX0RLJesYh8DB08wCpbSh7asqvyPxTQPy 8s2ujYWoHnRETze+X5P9j4dActJB9CxHdglblBAAMUucxuQQIDAQAB)=c19756527380670027c3d49663e19c93c2fbd3b2 Итоговый запрос: https://cleverforms.com:8443/svd/handler/api? app_id=3&format=xml&method=load.countries&secure=1&sig=c19756527380670027c3d49 663e19c93c2fbd3b2&uid=5
Все дополнительные данные запросов и ответы сервера оформляются в виде структурированных пакетов данных, подписанных цифровой подписью с помощью алгоритмов SHA1 и RSA. Для данной процедуры используются сертификаты, которые выдает наш сервис при подключении. Запрос к серверу XML формат пакета
<?xml version="1.0" encoding="UTF-8"?> <request version="1.0"> <transaction type="dictionary_list" id="1254254" /> <datetime>2014-01-13T10:29:34.000+0300</datetime> <xmlsign>c94f3d3e36bef3cd53a70266222eefa60d2a9df6</xmlsign> </request>
JSON формат пакета
{ "request":{ "@version":"1.0", "datetime":"2014-01-13T09:29:34.000+0200", "xmlsign":"a697381f4bd2669a56c3c5b0cf7c90a194e4a4bb", "transaction":{"@type":"dictionary_list","@id":"1254254"} } }
Тэг/Параметр | Тип | Описание |
---|---|---|
<request> | — | данный тэг говорит о том, что данные этого пакета относятся к запросам |
version | string | идентификатор версии формата запроса; обязательный параметр |
<datetime> | date-time | дата и время создания запроса в формате yyyy-MM-dd'T'HH:mm:ss.SSSZ; обязательный параметр |
<xmlsign> | string | подпись пакета (подробнее см. Формирование подписи пакета); обязательный параметр |
<transaction> | — | внутри данного тэга находятся передаваемые на сервер данные; обязательный параметр |
type | string | идентификатор типа транзакции; зависит от вызываемого метода; обязательный параметр |
id | long | уникальный номер транзакции в вашей системе; обязательный параметр |
XML формат пакета
<?xml version="1.0" encoding="UTF-8"?> <response> <datetime>2014-01-15T15:14:37.135+0200</datetime> <xmlsign>cb05586bf7dca4c153eaf6156ab6d5e932ad153e</xmlsign> <transaction id="10037" document="379"> <signer id="88" name="KAG admin"/> <timestamp>2014-01-15T15:14:37.129+0200</timestamp> MCwCFCIhloIDw9/vtq8p9u8buDTUAWHLAhRUGOJiHVQ6BZFT3Vdmz9fr/41Idw== </transaction> </response>
JSON формат пакета
{ "response":{ "datetime":"2014-01-15T15:14:36.600+0200", "xmlsign":"2fd23c2528f6b792c9ab9442fc50c80ef38959a1", "transaction":{ "@id":"10036", "@document":"379", "signer":{"@id":"2","@name":"Sergey Titarchuk"}, "timestamp":"2014-01-15T15:14:36.577+0200", "$":"MCwCFCOlRYkrgD54W0lLQLY8FonCf0b8AhRGfk\/drCz96j5Bj6nUGI04CjiqYw==" } } }
Тэг/Параметр | Тип | Описание |
---|---|---|
<response> | — | данный тэг говорит о том, что данные этого пакета относятся к ответам |
<datetime> | date-time | дата и время создания ответа в формате yyyy-MM-dd'T'HH:mm:ss.SSSZ; обязательный параметр |