Различия

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

--- gui [2019/07/09 07:48]
ilya создано
+++ gui [2019/07/10 07:27]
ilya
@@ Строка 1: / Строка 1: @@
 ====== Руководство по использованию CleverFormsTM API. ======
+Платформа CleverFormsTM предоставляет возможность внешним разработчикам программными средствами получать и записывать данные в CleverFormsTM. Одним из способов такого взаимодействия является
+использование [[api|CleverForms API]].
+====== Что такое CleverFormsTM API. ======
+[[api|CleverFormsTM API]] определяет набор функций, к которым разработчики могут совершать запросы и
+получать ответы. Взаимодействие происходит по протоколу HTTP. Преимуществом такого подхода является
+широкое распространение протокола HTTP, поэтому [[api|CleverFormsTM API]] можно использовать практически из
+любого языка программирования.
+[[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. Одинаковые для всех функций
+параметры перечислены ниже.
+^Имя^Тип^Описание^
+|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.\\

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

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

Различия

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