Различия

Здесь показаны различия между двумя версиями данной страницы.

--- gui [2019/07/09 08:35]
ilya
+++ gui [2019/07/10 08:24] (текущий)
ilya
@@ Строка 2: / Строка 2: @@
 Платформа CleverFormsTM предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в CleverFormsTM. Одним из способов такого взаимодействия является
 использование [[api|CleverForms API]].
 ====== Что такое CleverFormsTM API. ======
@@ Строка 13: / Строка 14: @@
 ====== Как использовать API. ======
-Все вызовы методов API — это GET или POST HTTP-запросы к URL <protocol>://<domain>/<appname>/handler/api. с некоторым набором параметров. Вы выбираете в документации нужный метод,
+Все вызовы методов **API** — это **GET** или **POST** HTTP-запросы к URL
-например, document.calculate, формируете запрос согласно документации метода, и осуществляете этот
+    <protocol>://<domain>/<appname>/handler/api.
+с некоторым набором параметров. Вы выбираете в документации нужный метод,
+например, ''document.calculate'', формируете запрос согласно документации метода, и осуществляете этот
 запрос. В ответ на запрос вы получаете его результат, который также описан в документации каждой функции. Кодировка результата — UTF-8.\\
 Например, на PHP для осуществления такого запроса можно использовать cURL, на Perl —
-LWP::Simple, на Python — httplib, использовать cURL из командной строки и даже просто ваш браузер.
+**LWP::Simple**, на Python — **httplib**, использовать cURL из командной строки и даже просто ваш браузер.
 Данные запроса могут передаваться в виде query-строки (после знака ?) при использовании метода
-GET, либо в теле POST-запроса. Помните, что все параметры должны быть закодированы с помощью URL
+**GET**, либо в теле **POST**-запроса. Помните, что все параметры должны быть закодированы с помощью URL
 encoding.\\
-На данный момент, API не делает различий между GET- и POST-запросами. Тем не менее, помните,
+На данный момент, API не делает различий между **GET**- и **POST**-запросами. Тем не менее, помните,
-что существует ограничение на длину URL запроса — 2048 символов. Поэтому мы рекомендуем вам выполнять запросы на получение информации с помощью метода GET (они обычно легко умещаются в ограничение), а запросы на изменение данных — с помощью метода POST. Так вы не будете ограничены длиной запроса, кроме того, такое использование больше соответствует спецификации протокола HTTP.\\
+что существует ограничение на длину URL запроса — 2048 символов. Поэтому мы рекомендуем вам выполнять запросы на получение информации с помощью метода **GET** (они обычно легко умещаются в ограничение), а запросы на изменение данных — с помощью метода **POST**. Так вы не будете ограничены длиной запроса, кроме того, такое использование больше соответствует спецификации протокола **HTTP**.
-**Table**
+====== Параметры запроса. ======
+В каждом запросе должен присутствовать набор обязательных параметров. Также для каждой
+функции в ее документации определены дополнительные параметры, нужные только для этой функции.
+Текстовые значения параметров должны быть преданы в кодировке 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
+s2ujYWoHnRETze+X5P9j4dActJB9CxHdglblBAAMUucxuQQIDAQAB)=c19756527380670027c3d49663e19c93c2fbd3b2
+    Итоговый запрос:
+    https://cleverforms.com:8443/svd/handler/api?
+    app_id=3&format=xml&method=load.countries&secure=1&sig=c19756527380670027c3d49
+e19c93c2fbd3b2&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; обязательный параметр|
+|<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**\\
-|s|s|
+====== Авторизация пользователя в системе ======
+    <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**.

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

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

Различия

Инструменты страницы