Здесь показаны различия между двумя версиями данной страницы.
Предыдущая версия справа и слева Предыдущая версия Следующая версия | Предыдущая версия | ||
gui [2019/07/09 09:00] ilya |
gui [2019/07/10 08:24] (текущий) ilya |
||
---|---|---|---|
Строка 35: | Строка 35: | ||
параметры перечислены ниже. | параметры перечислены ниже. | ||
^Имя^Тип^Описание^ | ^Имя^Тип^Описание^ | ||
- | |method|string|название вызываемого метода, например, documents.calculate; обязательный параметр| | + | |method|string|название вызываемого метода, например, ''documents.calculate''; обязательный параметр| |
|app_id|long|идентификатор приложения; обязательный параметр| | |app_id|long|идентификатор приложения; обязательный параметр| | ||
|sig|string|подпись запроса; обязательный параметр| | |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; обязательный параметр| | ||
+ | |<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**. |