Веб-сервисы для эффективного управления бизнесом!

Инструменты пользователя

Инструменты сайта


gui

Руководство по использованию CleverFormsTM API.

Платформа CleverFormsTM предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в CleverFormsTM. Одним из способов такого взаимодействия является использование CleverForms API.

Что такое CleverFormsTM API.

CleverFormsTM API определяет набор функций, к которым разработчики могут совершать запросы и получать ответы. Взаимодействие происходит по протоколу HTTP. Преимуществом такого подхода является широкое распространение протокола HTTP, поэтому CleverFormsTM API можно использовать практически из любого языка программирования. CleverFormsTM API предназначено, в основном, для запросов с внешних серверов к серверам CleverFormsTM.

Как использовать API.

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

ИмяТипОписание
methodstringназвание вызываемого метода, например, documents.calculate; обязательный параметр
app_idlongидентификатор приложения; обязательный параметр
sigstringподпись запроса; обязательный параметр
sidstringномер текущей сессии; обязательный параметр
uidlongидентификатор пользователя, для которого вызывается метод; обязательный параметр для запросов «клиент-сервер»
secureboolфлаг, обозначающий, что запрос идет по защищенной схеме «сервер-сервер»; возможные значения: 1 или 0; по-умолчанию 0 («клиент-сервер»)
formatstringформат приема/выдачи ответа API; возможные значения: form, xml или json; по умолчанию json; в случае form - данные считываются с формы приложения и выдаются в формате json
datastringпакет дополнительных данных (только при использовании метода 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>данный тэг говорит о том, что данные этого пакета относятся к запросам
versionstringидентификатор версии формата запроса; обязательный параметр
<datetime>date-timeдата и время создания запроса в формате yyyy-MM-dd'T'HH:mm:ss.SSSZ; обязательный параметр
<xmlsign>stringподпись пакета (подробнее см. Формирование подписи пакета); обязательный параметр
<transaction>внутри данного тэга находятся передаваемые на сервер данные; обязательный параметр
typestringидентификатор типа транзакции; зависит от вызываемого метода; обязательный параметр
idlongуникальный номер транзакции в вашей системе; обязательный параметр

Ответ сервера

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; обязательный параметр
<xmlsign>stringподпись пакета (подробнее см. Формирование подписи пакета); обязательный параметр
<transaction>внутри данного тэга находятся передаваемые с сервера данные; обязательный параметр

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

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."
		}
	}
}
Тэг/ПараметрТипОписание
<response>данный тэг говорит о том, что данные этого пакета относятся к ответам
<datetime>date-timeдата и время создания ответа в формате yyyy-MM-dd'T'HH:mm:ss.SSSZ; обязательный параметр
<xmlsign>stringподпись пакета (подробнее см. Формирование подписи пакета); обязательный параметр
<error>внутри данного тэга находятся передаваемые с сервера данные (информация об ошибке); обязательный параметр
<code>longкод ошибки в системе; обязательный параметр
<text>stringтекст ошибки

Формирование подписи пакета

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

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

Общие запросы для всех систем CleverFormsTM API

Чтение сертификата приложения

  <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.

Чтение Java key-store с ключами приложения

  <protocol>://<domain>/<app-name>/handler/api/keystore/<file-name>.keystore?app_id=<app_id>& password=<password>>&serial_number=<serial_number>&sig=<signature> – Возвращает файл Java key-store с ключами зарегистрированного приложения.\\ 


Параметры запроса:

  • <app_id> - идентификатор приложения в системе. Выдается при подключении.
  • <password> - пароль, которым будет зашифровано хранилище.
  • <serial_number> - идентификатор сертификата в системе. Выдается при подключении.
  • <signature> - подпись запроса. *

Данные транзакции для запроса: транзакция отсутствует.
Данные транзакции для ответа: транзакция отсутствует.
Получение информации только с помощью метода GET

Авторизация пользователя в системе

  <protocol>://<domain>/<app-name>/handler/api/authenticate?app_id=<app_id>&username=<username>&password=<password>&format=<format>&sig=<signature> – Авторизует пользователя в системе.

Параметры запроса:

  • <app_id> - идентификатор приложения в системе. Выдается при подключении.
  • <username> - имя пользователя в системе.
  • <password> - пароль пользователя.
  • <format> - формат приема/выдачи ответа API (json/xml).
  • <signature> - подпись запроса.

Данные транзакции для запроса: транзакция отсутствует. Данные транзакции для ответа:

  • <uid> – идентификатор пользователя в системе;
  • <sid> – номер текущей сессии;

XML формат ответа:

<?xml version="1.0" encoding="UTF-8"?>
<response>
	<datetime>2015-06-02T10:46:28.670+0300</datetime>
	<xmlsign>BDPiPGrdY2DfjCu6z3VTdwA12ag%2F%2FGjg1eyDb5aR%2BslrNozFvVZtBfHUn2RIUgO%2FE42RNmWPD
	G7qiK2MpKQUa%2Fn%2BJW3TUhDwo%2FOBn%2BaK5c85HM1rZiNE4xQW050Mtukvxj%2Ff8vX6Rh%2F6pJiU1XbWlls
	U9R6YSW8%2B3SMJl%2Fi4Xa0%3D</xmlsign>
	<transaction>
		<uid>1</uid>
		<sid>4dc9257edab6104da518bfc86c32e37d5d15</sid>
	</transaction>
</response>

JSON формат ответа:

{
	"response":{
		"datetime":"2015-06-02T10:46:28.670+0300",
		"xmlsign":"BDPiPGrdY2DfjCu6z3VTdwA12ag%2F%2FGjg1eyDb5aR%2BslrNozFvVZtBfHUn2RIUgO%2F
		E42RNmWPDG7qiK2MpKQUa%2Fn%2BJW3TUhDwo%2FOBn%2BaK5c85HM1rZiNE4xQW050Mtukvxj%2Ff8vX6R
		h%2F6pJiU1XbWllsU9R6YSW8%2B3SMJl%2Fi4Xa0%3D",
		"transaction":{
			"uid":1,
			"sid":"4dc9257edab6104da518bfc86c32e37d5d15"
		}
	}
}

Получение информации только с помощью метода POST

Загрузка файлов

method=resource.download – Находит и выгружает файл в браузер как бинарный. Дополнительные параметры запроса:

  • type – тип файлов (обычно совпадает с относительным путем к папке в которой находится файл).
  • path – название файла или относительный путь к файлу.

Данные транзакции для запроса: отсутствуют Получение информации только с помощью метода GET

Выгрузка файлов

method=resource.upload – Служит для потоковой загрузки файлов из браузера. Дополнительные параметры запроса:

  • type – тип файлов (обычно совпадает с относительным путем к папке в которой находится файл).
  • path – название файла или относительный путь к файлу

Данные транзакции для запроса: файлы с формы ввода или FormData Отправка информации только с помощью метода POST.

gui.txt · Последние изменения: 2019/07/10 08:24 — ilya