Платформа 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. Одинаковые для всех функций параметры перечислены ниже.

Порядок следования параметров в запросе значения не имеет значения, порядок параметров важен только при расчете подписи. Идентификатор приложения 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"}
    }
 }   

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=="
		}
	}
}

Ошибка
В случае возникновения ошибки система должна вернуть пакет ошибки следующего вида

XML формат пакета

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<xmlsign>MCwCFBDENIKYn964yX5Dkg+F7m1pMCJdAhQTRB3UaMZ8aYk1ID6tt5Kzd1J1Ag==</xmlsign>
	<datetime>2014-01-20T11:00:43.929+0200</datetime>
	<error>
		<code>5</code>
		<text>Wrong request data packet or a signature.</text>
	</error>
	</response>

JSON формат пакета

{
	"response":{
	"datetime":"2014-01-20T11:00:43.845+0200",
	"xmlsign":"MCwCFHN0CMsiMZg3xUnWMLMP5pZcl7DQAhRka2zvFsomqj8bRzJNRAOnF5+gFA==",
	"error":{
		"code":5,
"text":"Wrong request data packet or a signature."
		}
	}
}

Каждый пакет должен быть подписан цифровой подписью с помощью алгоритма RSA с использованием алгоритма хеш-функций SHA256. Для этого формируется полный пакет с данными, которые будут передаваться. Внутрь тэга <xmlsign> помещаем пробел. Переводим строку в массив байтов используя кодировку UTF-8 и рассчитываем подпись с применением скрытого ключа. Результат подписи кодируется в base64, переводится в application/x-www-form-urlencoded формат и заменяет содержимое тэга <xmlsign>.

Проверка подписи происходит в таком же порядке: берем пакет данных, Внутрь тэга <xmlsign> помещаем пробел, переводим строку в массив байтов используя кодировку UTF-8 и проверяем подпись с применением открытого ключа.
Выдача сертификатов для данной процедуры происходит в момент подключения внешнего приложения к системе.

Чтение сертификата приложения <protocol>:<domain>/<app-name>/handler/api/certificate/<filename>.cer?app_id=<app_id>&serial_number=<serial_number>&sig=<signature> – Возвращает файл сертификата для зарегистрированного приложения. Получение информации только с помощью метода GET**.

Параметры запроса:
* <app_id> - идентификатор приложения в системе. Выдается при подключении.
* <serial_number> - идентификатор сертификата в системе. Выдается при подключении.
* <signature> - подпись запроса. * Элемент ненумерованного списка
Данные транзакции для запроса: транзакция отсутствует.
Данные транзакции для ответа: транзакция отсутствует.
Получение информации только с помощью метода GET.