Документация по использованию сервиса

В настоящее время, сервис поддерживает выполнение следующих операций:

pay_order (операция оплаты заказа). test_action (тестовая операция, для проверки работоспособности взаимодействия). get_option_price (получение стоимости опции). check_login (проверка существования логина). get_account (получение информации по аккаунту). reg (регистрация нового пользователя). check_auth (проверка возможности авторизации). change_password (изменение пароля).

Для того чтобы пользоваться сервисом: http://www. *****/ext_service/query. php Вы должны:

Сгенерировать на своей стороне пару ключей. Открытый и закрытый, например:

openssl genrsa - out /path/to/dir/output_key. pem - des3 - rand /path/to/dir/rand. file 4096

openssl rsa - in /path/to/dir/output_key. pem - out /path/to/dir/output_publickey. pem - pubout

Предоставить нам только открытый ключ (output_publickey. pem), сгенерированный вами в связке с полученным закрытым ключем, который вы будете использовать для дешифрации ответов с сервиса. Указать IP адрес с которого Вы будете использовать сервис. Скачать открытый ключ http://www. *****/ext_service/pubkey. pem. Его вы будете использовать для шифрования данных отправляемых сервису. Реализовать клиента сервиса собственными силами (пример см. ниже).

Все данные передаваемые вами по адресу http://www. *****/ext_service/query. php должны быть зашифрованы открытым ключем, который вы получили. Все данные, полученные от нас шифруются вашим открытым ключем, который Вы нам предоставляете. Вы должны будете использовать свой закрытый ключ, чтобы их расшифровать.

НЕ нашли? Не то? Что вы ищете?

Все данные передаются методом POST в XML вида:

<?xml version="1.0" encoding="UTF-8"?>

<params>

<param1>значение_param1</param1>

<param2>значение_param2</param2>

....

<paramN>значение_paramN</paramN>

</params>

, где param1 – paramN – названия параметров, а значение_param1 - значение_paramN – значения соответствующих параметров.

Обязательные параметры, значения, которых должны быть в XML - ac (код вашей компании на сайте Софткея, action - необходимое для выполнения внешним сервисом действие).

Принцип работы сервиса

Вендор формирует XML с входными параметрами. Шифрует его открытым ключем софткея. Передает сервису. Сервис формирует XML ответа, шифрует его открытым ключем вендора и отвечает, полученным XML. В XML если всё впорядке присутсвует поле confirmation_code – уникальный код подтверждения запрошенной операции. Если произошла ошибка, то XML содержит поле error с ненулевым значением (код ошибки) и поле message с текстом ошибки. XML может быть зашиврованным или нет, взависимости от того удалось ли найти открытый ключ вендора на софткее. Этот факт Вы должны предусмотреть в реализации взаимодействия сервиса. Получив код подтверждения Вы отправляете сервису XML вида: <?xml version="1.0" encoding="UTF-8"?> <result> <error>0</error> <message>Can process</message> <data></data> <confirmation_code></confirmation_code> </result> В XML подтверждении параметры ac и action уже необязательные. Сервис отвечает Вам XML с результатом выполнения операции.

Если запрос на подтверждение не пришел от Вас в течение 30 секунд с момента первого запроса, то вы не сможете выполнить операцию и получите ошибку 'Affirmation time has expired'. В этом случае нужно будет отправить запрос на получение confirmation_code повторно.

Схематически порядок действий можно представить следующим образом:

1)  Вендор начинает транзакцию, формирует запрос к Магазину;

2)  Магазин в ответ на запрос отдает confirmation code;

3)  Вендор используя полученый confirmation code завершает транзакцию.

Параметры операций

Параметры ac и action – обязательные, поэтому в таблице они не перечислены.

Название действия

Входные параметры

Выходные параметры

pay_order

order_id (код заказа на софткее)

currency (валюта в которой сделан заказ)

amount (сумма по заказу)

ВНИМАНИЕ! Вы должны сохранять на своей стороне идентификаторы всех обработанных заказов для последующей сверки совместно с компанией Софткей.

Пример XML:

<action>оплата заказа</action>

<order_id>1111111</order_id>

<currency>РУР</currency>

<amount>1234</amount>

<basket>

<id>123456</id>

<name>sdfdsf</name>

<basket_amount>490.00</basket_amount>

<key></key>

</basket>

...

<basket>

<id>123456</id>

<name>sdfdsf</name>

<key></key>

</basket>

action – всегда pay_order

order_id – код заказа

currency - валюта

amount – сумма заказа

далее идут позиции заказа в тегах <baket> </basket>

id – код позиции заказа

name – название позиции

basket_amount – сумма позиции в валюте заказа

key – регистрационный ключ к программе

get_option_price

Примечание: кодирование информации не нужно

option_id (код опции)

quantity (количество, необязательный параметр. Если не указан, то в качестве количества используется минимальное значение при котором можно купить опцию)

action- всегда get_option_price

option_id – код опции

quantity - количество

price - цена

currency – валюта (всегда RUR)

check_login

проверка занятости логина

Примечание: кодирование информации не нужно

LOGIN – логин пользователя

action - всегда check_login

exists – 1/0 (логин занят/нет)

get_account (получение информации о аккаунте пользователя)

ID – идентификатор пользователя

action - всегда get_account

second_name - отчество

date_last_loginn - дата последней авторизации

date_reg – дата регистрации

email - email

lastname - фамилия

name - имя

active – признак активности Y/N

timestamp_x – дата изменения записи

login - логин

company_id – код компании

lid – код сайта

id – код пользователя

mobile_phone – мобильный телефон

phone - телефон

reg (регистрация нового пользователя)

LOGIN – логин пользователя

PASSWORD – пароль пользователя

CONFIRM_PASSWORD – подтверждение пароля пользователя

EMAIL – электронный адрес пользователя

NAME - имя регистрируемого пользователя (необязательное. если не указано, то имя = логин, макс. 50 символов)

LAST_NAME - фамилия регистрируемого пользователя (необязательное. макс. 50 символов)

COMPANY_NAME - имя компании, которая создается для регистрации пользователя (необязательное. если не указано = Auto generated, макс. 50 символов)

REC_NAME - название компании в реквизитах, создаваемых для компании (необязательное. если не указано = Auto generated, макс. 500 символов)

action – всегда reg

id – код пользователя

check_auth (проверка возможности авторизации)

LOGIN – логин пользователя

PASSWORD – пароль пользователя

action - всегда check_auth

can_login – 1/0 (авторизация возможна/нет).

id – код пользователя

change_password (изменение пароля)

LOGIN – логин пользователя

PASSWORD – текущий пароль пользователя

NEW_PASSWORD – новый пароль пользователя

action - всегда pay_order

new_password – новый пароль

id – код пользователя

test_action

val (любое значение типа integer)

Пример (оплата заказа)

В ответ на запрос методом POST вида:

<?xml version="1.0" encoding="UTF-8"?>

<params>

<order_id>1472721</order_id>

<currency>RUR</currency>

<amount>2292.00</amount>

<ac>1228399</ac>

<action>pay_order</action>

</params>

Сервисом будет сформирован ответ XML вида:

<?xml version="1.0" encoding="UTF-8"?>

<result>

<error>0</error>

<message>Can process</message>

<data></data>

<confirmation_code></confirmation_code>

</result>

Если не произошло ошибок, то в XML значение тега error - 0 и присутствует поле confirmation_code. Если же произошла ошибка то XML будет следующего вида:

<result>

<error>705</error>

<message>Affirmation time has expired</message>

<data></data>

</result>

далее, вы должны подтвердить ваш запрос кодом, полученным в поле confirmation_code. Отправив уже запрос вида

<?xml version="1.0" encoding="UTF-8"?>

<params>

<iconfirmationcode></iconfirmationcode>

</params>

Доп. данных в данном случае для оплаты заказа передавать уже не нужно. Если ошибок не произошло, то будет сформирован ответ с XML вида:

<?xml version="1.0" encoding="UTF-8"?>

<result>

<error>0</error>

<message>Operation succesfull</message>

<data>

<action>pay_order</action>

<order_id>1472721</order_id>

<currency>RUR</currency>

<amount>2292.00</amount>

</data>

<confirmation_code></confirmation_code>

</result>

XML в поле data может принимать различный вид в зависимости от поля action. Для запроса с action - «pay_order» XML в этом поле принимает вид приведенный выше в примере.

Пример клиента (с кодированием)

Пример реализации на PHP приведен ниже. Просьба не использовать его как конечный функционал:

<?

// пример реализации взаимодействия на стороне клиента

// id компании -

// id заказа - 1472721

// currency - RUR

// amount - 2292.00

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

function CreateQueryString($arFields, $strPathToPublicKey)

{

$strRes = '<?xml version="1.0" encoding="UTF-8"?><params>';

foreach($arFields as $key => $val)

$strRes .= '<'.$key.'>'.$val.'</'.$key.'>';

$strRes .= '</params>';

// шифруем

if($pkeyid = openssl_get_publickey($strPathToPublicKey))

openssl_public_encrypt($strRes, $strRes, $pkeyid);

return $strRes;

}

function Send($strEncryptedDataToSend)

{

global $DOCUMENT_ROOT;

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'http://www. *****/ext_service/query. php');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_TIMEOUT, 5);

mb_internal_encoding('WINDOWS-1251'); // считаем строку как в однобайтовой кодировке для правильной работы strlen

curl_setopt($ch, CURLOPT_HTTPHEADER, Array("Content-length: ".strlen($strEncryptedDataToSend)));

mb_internal_encoding('UTF-8'); // назад к UTF-8

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, $strEncryptedDataToSend);

curl_setopt($ch, CURLOPT_HEADER, 0);

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

// ответ. закодирован Вашим открытым ключом, который вы должны сгенерить вместе с закрытым, для того чтобы расшифровать ответ

$data = curl_exec($ch);

if(curl_errno($ch))

{

echo curl_error($ch);

die();

}

curl_close($ch);

// расшифруем ответ. Расшифровка проходит вашим закрытым ключем

if($keyid = openssl_get_privatekey("путь_к_вашему_закрытому_ключу", "пароль_к_вашему_закрытому_ключу"))

{

if(openssl_private_decrypt($data, $strDataDecrypted, $keyid))

return $strDataDecrypted;

else

return $data;

}

else

return $data;

}

// необходимые поля для запроса оплаты заказа

$arFields = Array(

'order_id' => 1

'currency' => 'RUR',

'amount' => '2292.00',

'action' => 'pay_order',

'ac' => ,

);

// строка для оплаты заказа

$strEncryptedDataToSend = CreateQueryString($arFields, "путь_к_софткеевскому_публичному_ключу");

// посылаем данные для оплаты заказа

$strDataDecrypted = Send($strEncryptedDataToSend);

//echo $strDataDecrypted;die();

// тут можно посмотреть отвеченный XML. распарсить его нужным образом. если в поле error нет ошибки и присутствует поле confirmation_code с заполненным значением, то отсылаем подтверждение с указанием этого кода для проведения нужного вам действия.

//<result><error>0</error><message>Can process</message><data><action>pay_order</action><order_id>1472721</order_id><currency>RUR</currency><amount>2292.00</amount></data><confirmation_code>77938</confirmation_code></result>

// ищем confirmation_code

$iConfirmationCode = 0;

$iBeginPos = strpos($strDataDecrypted, "<confirmation_code>");

if($iBeginPos !== false)

{

$iEndPos = strpos($strDataDecrypted, "</confirmation_code>");

if($iEndPos !== false)

$iConfirmationCode = intval(substr($strDataDecrypted, $iBeginPos + strlen("<confirmation_code>"), $iEndPos - $iBeginPos - strlen("<confirmation_code>")));

}

if($iConfirmationCode > 0) // посылаем запрос на выполнение, если есть код подтверждения

{

// шифруем

$arFields = Array(

"iConfirmationCode" => $iConfirmationCode,

);

$strEncryptedDataToSend = CreateQueryString($arFields, "путь_к_софткеевскому_публичному_ключу");

$strDataDecrypted = Send($strEncryptedDataToSend);

// посылаем

echo $strDataDecrypted; // что пришло?

die(); // конец :)

}

?>

Пример клиента (без кодирования)

Для выполнения некоторых оперций шифровать и дешифровывать ответы и сами запросы не нужно, например, запрос get_option_price. Также не нужно указывать в этом запросе и код вашей компании. Вы можете даже не иметь компании на софткее. Пример реализации для таких действий:

<?

class CSoftkeyExtService

{

var $strPathToPublicKey;

var $strPathToPrivateKey;

var $strPrivatePwd;

var $bUseEncoding;

var $bLocalRun;

var $strAnswer;

var $strErrCode;

var $pkeyid;

var $keyid;

function __construct($bUseEncoding = false, $strPathToPublicKey, $strPathToPrivateKey, $strPrivatePwd, $bLocalRun = false)

{

return $this->CSoftkeyExtService($bUseEncoding, $strPathToPublicKey, $strPathToPrivateKey, $strPrivatePwd, $bLocalRun);

}

function CSoftkeyExtService($bUseEncoding = false, $strPathToPublicKey, $strPathToPrivateKey, $strPrivatePwd, $bLocalRun = false)

{

$this->bUseEncoding = $bUseEncoding;

$this->strPathToPublicKey = $strPathToPublicKey;

$this->strPathToPrivateKey = $strPathToPrivateKey;

$this->strPrivatePwd = $strPrivatePwd;

$this->bLocalRun = $bLocalRun;

if($this->bUseEncoding)

{

if(!$this->pkeyid = openssl_get_publickey($this->strPathToPublicKey))

$this->strErrCode = 101;

if(!$this->keyid = openssl_get_privatekey($this->strPathToPrivateKey, $this->strPrivatePwd))

$this->strErrCode = 102;

}

}

function _CreateQueryString($arFields)

{

$strRes = '<?xml version="1.0" encoding="UTF-8"?><params>';

foreach($arFields as $key => $val)

$strRes .= '<'.$key.'>'.$val.'</'.$key.'>';

$strRes .= '</params>';

if($this->bUseEncoding) // шифруем

openssl_public_encrypt($strRes, $strRes, $this->pkeyid);

return $strRes;

}

function _Send($strData) // отсылает данные

{

$ch = curl_init();

if($this->bLocalRun)

curl_setopt($ch, CURLOPT_URL, 'http://10.50.1.188/ext_service/query. php');

else

curl_setopt($ch, CURLOPT_URL, 'http://www. *****/ext_service/query. php');

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_TIMEOUT, 10);

mb_internal_encoding('WINDOWS-1251'); // считаем строку как в однобайтовой кодировке для правильной работы strlen

curl_setopt($ch, CURLOPT_HTTPHEADER, Array("Content-length: ".strlen($strData)));

mb_internal_encoding('UTF-8'); // назад к UTF-8

curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, $strData);

curl_setopt($ch, CURLOPT_HEADER, 0);

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

$strAnswer = curl_exec($ch);

if(curl_errno($ch))

{

echo curl_error($ch);

die();

}

curl_close($ch);

if($this->bUseEncoding) // расшифруем ответ. Расшифровка проходит вашим закрытым ключем

openssl_private_decrypt($strAnswer, $strAnswer, $this->keyid);

return $strAnswer;

}

function Send($arFields) // отсылает данные с подтверждением

{

$this->strAnswer = $this->_Send($this->_CreateQueryString($arFields));

$iBeginPos = strpos($this->strAnswer, "<confirmation_code>");

if($iBeginPos !== false)

{

$iEndPos = strpos($this->strAnswer, "</confirmation_code>");

if($iEndPos !== false)

$iConfirmationCode = intval(substr($this->strAnswer, $iBeginPos + strlen("<confirmation_code>"), $iEndPos - $iBeginPos - strlen("<confirmation_code>")));

}

if($iConfirmationCode > 0) // посылаем запрос на выполнение, если есть код подтверждения

$this->strAnswer = $this->_Send($this->_CreateQueryString(Array("iConfirmationCode" => $iConfirmationCode)));

return $this->strAnswer;

}

}

$arFields = Array(

'option_id' =>

'action' => 'get_option_price',

);

$obSoftkeyExtService = new CSoftkeyExtService();

if(intval($obSoftkeyExtService->strErrCode) <= 0)

echo $obSoftkeyExtService->Send($arFields);

else

echo $obSoftkeyExtService->strErrCode;

?>