|
|
|||||||
|
XML-интерфейсы WebMoney. Часть 3. X1, X3, X4, X9, X14, X16.© Никита Сенченко <<XML-интерфейсы WebMoney. Часть 1. WMSigner. ![]() ![]() ![]() ![]() ![]() ![]() Эта статья - последняя в серии материалов об XML-интерфейсах WebMoney. Все базовые навыки вы уже получили, однако мне хотелось бы детально рассмотреть ещё несколько наиболее используемых интерфейсов, которые могут пригодиться вам в работе. Напомним, ранее мы научились работать с WMSigner (модулем цифровой подписи под Unix-системы) и формировать подпись произвольной строки с помощью этого модуля и ключей Keeper Classic. Затем мы разобрались, как получать такую подпись программно в PHP и как генерировать возрастающий уникальный параметр reqn, необходимый для работы большинства интерфейсов. Наконец, мы написали PHP-функции для использования 4-х XML интерфейсов. Сегодня мы добавим в коллекцию ещё 6. Напомним, что примеры приводятся на языке PHP. Парсинг (разбор) XML-ответов производится с помощью библиотеки SimpleXML (поддерживается только в PHP5, но не в PHP4), однако делать это можно, конечно, и любым другим XML-разборщиком PHP: DOM XML, libxml, XML expat parsers и проч. Все функции для работы с интерфейсами, которые мы разрабатываем, мы складываем в файл wmxml.inc.php. Вот его полная версия, в него включены уже и те функции, которые будут описаны ниже в этой статье. Интерфейс X1. Выписывание счёта.С помощью этого интерфейса вы можете выписывать WM-счета другим пользователям WebMoney. Полное описание интерфейса находится здесь. Интерфейс требует наличия персонального (или выше) аттестата, других специальных требований нет. Интерфейс целесообразно применять в тех случаях, когда вы хотите получить оплату за товар\услугу и когда есть необходимость сделать так, чтобы покупатель мог оплатить её только со своего WMID и только через Кипер. В других случаях лучше использовать стандартное средство приема WM-платежей WM Merchant. Наш XML-запрос должен выглядеть так: Что означают параметры:
Формат ответа сервера WebMoney следующий: В ответе нас, прежде всего, интересует поле <retval> (eсли оно равно 0, то счёт был выставлен успешно, в противном случае retval будет содержать код ошибки, расшифровку которой нужно смотреть в поле <retdesc>). Кроме этого, крайне важным является атрибут id поля <invoice>, в нем содержится уникальный номер выставленного счёта в единой базе данных WebMoney. По нему мы в дальнейшем сможем проверять состояние оплаты этого счёта. Кроме того, будем сохранять дату создания счёта из поля <datecrt>. Остальные поля дублируют соответствующие параметры запроса, а поле <state>, в котором указывается код текущего состояния оплаты счёта, вообще всегда содержит 0 (это означает, что счёт ещё не оплачен - и это понятно, ведь он только что выписан). Приведем теперь полностью функцию, которая реализует работу с интерфейсом X1, и добавим её в wmxml.inc.php: Разберём, что происходит в этой функции. Функция получает переменные:
Генерируем уникальный номер запроса $reqn с помощью функции _GetReqn(): Выполняем некоторые преобразования, чтобы избежать ошибок. У $desc и $address убираем лишние пробелы в начале и конце. У $amount удаляем незначащие нули, если они есть. Этого требует описание интерфейса. Получаем подпись XML-пакета с помощью функции _GetSign(). На вход функции подаём строку, полученную в результате склейки параметров, как это предусмотрено в описании интерфейса. Параметры должны склеиваться именно в таком порядке, как это указано ниже. Значения всех параметров при формировании строки подписи обязательно должны быть в кодировке Win1251! Поэтому - внимание! - если функция _WMXML1(), с которой мы сейчас работаем, получила переменные $desс или $address в кодировке, отличной от Win1251, то их нужно сперва перекодировать. Остальные параметры содержат всегда только цифры и английские буквы, поэтому для них кодировка никакой роли не играет. Теперь преобразуем специальные символы ("<", "&" и др.) в html-сущности. Если этого не сделать, то при попадании в $desc или $address таких символов WebMoney наш запрос не примет и вернет ошибку "A semi colon character was expected". Обратите внимание, что при формировании строки подписи переменные $desc и $address пребывали в своем первозданном виде, со всеми спецсимволами, а преобразование мы выполняем уже после получения подписи. Преобразовать спецсимволы в PHP можно с помощью функции Но это ещё не всё. $desc и $address могут содержать русские символы. Например, в $desc может быть такой текст: "тестовый товар & тестовая услуга". И здесь нужно понимать, как подготовить $desc и $address для передачи в составе XML-пакета. Дело в том, что содержимое полученного от вас XML-пакета сервер WebMoney попытается прочитать так, будто он пришел в кодировке Unicode. Если сервер встретит в пакете русские символы в другой кодировке, то вернет ошибку: "An invalid character was found in text content" ("Обнаружен ошибочный символ"). Для того чтобы этого не произошло, нам нужно принудительно перекодировать $desc и $address в UTF-8 и уже в таком виде включать их в XML-запрос. Сделать преобразование кодировок можно с помощью функции То же самое, но с помощью функции Можно даже преобразовать не в UTF-8, а в html-сущности, это тоже сработает: Если же iconv и mbstring вашим сервером не поддерживаются, то могу предложить ещё один вариант. Оставьте $desc и $address в кодировке Win1251, а в начале XML-запроса вставляйте заголовок
Понятно, что если переменные $desc и $address были переданы в функцию _WMXML1(), уже пребывая в кодировке UTF-8, то никаких преобразований на этом этапе делать не нужно. Наконец, формируем XML-пакет с запросом: Отправляем запрос на сервер WebMoney и получаем от него ответ с помощью функции _GetAnswer(). На вход функции подаём URL интерфейса X1 из глобального массива $XML_addr, а также пакет XML-запроса, сформированный только что: Для отладки и поиска ошибок может потребоваться прочитать XML-ответ "в чистом виде". Тогда просто раскомментируйте следующую строку: Вызовом функции Если $xmlres не создан, значит, мы по какой-то причине не получили ответ от WebMoney. Тогда прерываем работу функции: Читаем следующие свойства объекта: Обратите внимание, что содержимое поля <retdesc> мы перекодировали из UTF-8 в Win1251. Дело в том, что XML-ответ от WebMoney приходит в кодировке Windows1251, но SimpleXML при помещении XML-данных в объект принудительно превратил их в Юникод. Такая вот у него особенность. А так как <retdesc> - это строка, и теоретически она может содержать русские символы, то при выемке её из объекта мы возвращаем ей "родную" кодировку. Хотя, в общем, это не обязательно и зависит от ваших нужд и задач. На выходе функция _WMXML1() возвращает массив $result: Теперь осталось только проверить, как работает то, что мы написали. Создадим скрипт для тестов test.php: "; echo "Расшифровка - ".$r['retdesc']." "; echo "Дата и время - ".$r['date']." "; echo "Номер счёта в WebMoney - ".$r['wminvid']." "; ВНИМАНИЕ! Настоятельно рекомендуем вам сохранять в своей базе данных уникальные номера, присвоенные счетам системой WebMoney (то, что на выходе нашей функции содержится в $result['wminvid']), и в дальнейшем при проверке состояния оплаты того или иного счёта с помощью интерфейса X4 оперировать именно с этими номерами. Они всегда уникальны и никогда не повторяются. Это поможет избежать проблем. Интерфейс X3. Получение истории операций.С помощью этого интерфейса вы можете получать историю операций по кошельку. Полное описание интерфейса находится здесь. Интерфейс по умолчанию включен для всех пользователей WebMoney и не имеет никаких специальных требований по активации. На наш взгляд, это самый сложный XML-интерфейс из всех. Он нуждается в некоторых пояснениях, которые мы и приведем ниже. Наш XML-запрос должен выглядеть так: Что означают параметры:
Формат ответа сервера WebMoney следующий: В ответе нас, прежде всего, интересует поле <retval> (eсли оно равно 0, то история получена успешно, в противном случае retval будет содержать код ошибки, расшифровку которой нужно смотреть в поле <retdesc>). Также нас будет интересовать атрибут cnt поля <operations>, в котором содержится количество операций, попавших в выборку. Кроме того, мы "уложим" в структуру массивов полученную выборку транзакций. Мы детально опишем всё это ниже, когда будем рассматривать работу функции. Приведем теперь полностью функцию, которая реализует работу с интерфейсом X3, и добавим её в wmxml.inc.php: Разберём, что происходит в этой функции. Функция получает переменные:
Теперь давайте разбираться, что тут к чему. Переменные: $purse (пойдет в поле getoperations\purse XML-запроса), $datestart (пойдет в поле getoperations\datestart XML-запроса) и $datefinish (пойдет в поле getoperations\datefinish XML-запроса) - являются обязательными! Если вы не зададите какое-либо из этих полей, интерфейс выдаст ошибку. Таким образом, интерфейс X3 всегда должен знать, по какому кошельку и за какой период времени запрашивается история операций. Если вам вдруг захочется получить полную историю за всё время существования кошелька, то задайте, например, $datestart="19700101 00:00:00" и $datestart="20990101 00:00:00". Что касается 4-х остальных переменных: $wmtranid (пойдет в поле getoperations\wmtranid XML-запроса), $tranid (пойдет в поле getoperations\tranid XML-запроса), $wminvid (пойдет в поле getoperations\wminvid XML-запроса), $orderid (пойдет в поле getoperations\orderid XML-запроса) - то они являются необязательными. Если задана какая-либо из них, то она сужает выборку до одной операции. Например, если задана переменная $wmtranid, то из истории будет выбрана только одна(!) операция, имеющая указанный номер, однако лишь при условии, что она была осуществлена с указанного кошелька $purse и в указанный промежуток времени $datestart - $datefinish. То же касается и $tranid, $wminvid, $orderid ($orderid, врочем, не является уникальным параметром, поэтому может ограничивать выборку не одной, а несколькими транзакциями). Таким образом, если вы хотите получить информацию об одном конкретном переводе, и знаете какой-либо из его параметров, то вы можете применить данный приём - передать в функцию соответствующую переменную. Следите при этом, чтобы $datestart и $datefinish охватывали искомую транзакцию по времени; если не знаете, когда точно проводилась искомая транзакция - укажите временной отрезок с запасом, например $datestart="19700101 00:00:00" и $datestart="20990101 00:00:00". Где же взять эти номера транзакций и счетов? Уникальный номер операции в системе WebMoney ($wmtranid):
Уникальный номер операции в системе учёта отправителя ($tranid):
Уникальный номер (в базе данных WebMoney) WM-счёта, который был оплачен посредством искомой транзакции ($wminvid):
Номер (в системе учёта выставителя) WM-счёта, который был оплачен посредством искомой транзакции ($orderid):
Резюммируя, каждая транзакция в системе WebMoney характеризуется 4 параметрами - глобальным и внутренним номером транзакции (wmtranid и tranid соответственно), глобальным и внутренним номером WM-счёта, ставшего первопричиной транзакции (wminvid и orderid соответственно); причем, ненулевым всегда является только wmtranid, остальные параметры могут отсутствовать. Зная о переводе хотя бы один из этих его параметров, с помощью интерфейса X3 вы можете запросить информацию конретно об этом переводе. Вернёмся к рассмотрению функции. Генерируем уникальный номер запроса $reqn с помощью функции _GetReqn(): Получаем подпись XML-пакета с помощью функции _GetSign(). На вход функции подаём строку, полученную в результате склейки параметров, как это предусмотрено в описании интерфейса. Параметры должны склеиваться именно в таком порядке, как это указано ниже. Наконец, формируем XML-пакет с запросом: Отправляем запрос на сервер WebMoney и получаем от него ответ с помощью функции _GetAnswer(). На вход функции подаём URL интерфейса X3 из глобального массива $XML_addr, а также пакет XML-запроса, сформированный только что: Для отладки и поиска ошибок может потребоваться прочитать XML-ответ "в чистом виде". Тогда просто раскомментируйте следующую строку: Вызовом функции Если $xmlres не создан, значит, мы по какой-то причине не получили ответ от WebMoney. Тогда прерываем работу функции: Читаем следующие свойства объекта: Обратите внимание, что содержимое поля <retdesc> мы перекодировали из UTF-8 в Win1251. Дело в том, что XML-ответ от WebMoney приходит в кодировке Windows1251, но SimpleXML при помещении XML-данных в объект принудительно превратил их в Юникод. Такая вот у него особенность. А так как <retdesc> - это строка, и теоретически она может содержать русские символы, то при выемке её из объекта мы возвращаем ей "родную" кодировку. Хотя, в общем, это не обязательно и зависит от ваших нужд и задач. Далее, если cnt больше 0, т.е. в выборке есть хотя бы одна операция, переходим к сохранению информации о транзакциях. Эта информация содержится внутри одинаковых блоков XML-ответа <operation>...</operation>. Пробегаем блоки в цикле и, применяя парсинг XML к нужным полям и атрибутам, формируем массив, где ключами элементов делаем уникальные номера транзакций в системе WebMoney (атрибут id полей <operation>), а значениями элементов делаем вложенные ассоциативные массивы, в которых, в свою очередь, ключи элементов - это обозначения параметров транзакции, а значения элементов - соответствующие этим параметрам значения. Сформированный таким образом "массив в массиве" сохраняем внутрь элемента operations выходного массива $result: Рассмотрим детальнее некоторые фрагменты этого кода. Интерфейс X3 отдаёт нам большой набор данных по каждому переводу, однако среди этих данных нет точного указателя на то, является ли конкретная транзакция исходящей или входящей. Вероятно, нам такой указатель пригодился бы в работе, поэтому мы определяем его самостоятельно следующим образом: То есть, если наш кошелёк является получателем, то транзакция входящая. Если отправителем - транзакция исходящая. В первом случае кошелёк нашего корреспондента - это кошелёк-отправитель, а во втором - это кошелёк-получатель. Сразу же сохраняем эти сведения о типе транзакции и кошельке корреспондента в переменные $type и $corrpurse. Далее, как я уже говорил выше, мы сохраняем информацию о транзакциях в однотипные массивы, один массив на одну транзакцию: Элементы массивов обозначают следующее:
Впрочем, X3 даёт нам ещё больше информации, и вы, в зависимости от своих потребностей, можете дополнить приведенную выше "выемку" из XML-ответа, либо, наоборот, сократить её. На выходе функция _WMXML3() возвращает массив $result: Чтобы было лучше понятно, ещё раз посмотрим на содержимое массива $result (его можно привести в читабельный вид с помощью функции Теперь осталось только проверить, как работает то, что мы написали. Создадим скрипт для тестов test.php: "; echo "Расшифровка - ".$r['retdesc']." "; echo "Количество - ".$r['cnt']." "; echo "
В этом примере мы получили и вывели в таблице полную историю операций за 30-е августа 2008 года. Интерфейс X4. Проверка выписанных счетов.С помощью этого интерфейса вы можете получать историю выписанных счетов и проверять их состояние (оплачен, не оплачен, отказан в оплате), а также проверять состояние конкретного счёта по его номеру. Полное описание интерфейса находится здесь. Интерфейс по умолчанию включен для всех пользователей WebMoney и не имеет никаких специальных требований по активации. Интерфейс довольно сложный, но очень похож на рассмотренный выше X3. "Поведение" этого интерфейса тоже во многом зависит от того, какие именно входные параметры он получает в XML-запросе пользователя. Наш XML-запрос должен выглядеть так: Что означают параметры:
Формат ответа сервера WebMoney следующий: В ответе нас, прежде всего, интересует поле <retval> (eсли оно равно 0, то история счетов получена успешно, в противном случае retval будет содержать код ошибки, расшифровку которой нужно смотреть в поле <retdesc>). Также нас будет интересовать атрибут cnt поля <outinvoices>, в котором содержится количество счетов, попавших в выборку. Кроме того, мы "уложим" в структуру массивов полученную выборку счетов, а именно их уникальные номера в базе данных WebMoney (атрибуты id полей <outinvoice>) и состояния оплаты (поля <state>). Мы детально опишем всё это ниже, когда будем рассматривать работу функции. Приведем теперь полностью функцию, которая реализует работу с интерфейсом X4, и добавим её в wmxml.inc.php: Разберём, что происходит в этой функции. Функция получает переменные:
Здесь всё очень похоже на интерфейс X3. Переменные: $purse (пойдет в поле getoutinvoices\purse XML-запроса), $datestart (пойдет в поле getoutinvoices\datestart XML-запроса) и $datefinish (пойдет в поле getoutinvoices\datefinish XML-запроса) - являются обязательными! Если вы не зададите какое-либо из этих полей, интерфейс выдаст ошибку. Отсюда вывод: интерфейс X4 всегда должен знать, по какому кошельку и за какой период времени запрашивается история исходящих счетов. Если вам вдруг захочется получить полную историю за всё время существования кошелька, то задайте, например, $datestart="19700101 00:00:00" и $datestart="20990101 00:00:00". Переменные: $wminvid (пойдет в поле getoutinvoices\wminvid XML-запроса) и $orderid (пойдет в поле getoutinvoices\orderid XML-запроса) - являются необязательными. Если обе эти переменные не заданы, то выбираются все счета по кошельку за указанный промежуток времени - так, как это описано в предыдущем абзаце. Если задана переменная $wminvid, то в выборку попадёт только один счёт, имеющий именно такой уникальный номер в базе данных WebMoney, однако лишь при условии, что он был выписан с указанного кошелька $purse и в указанный промежуток времени $datestart - $datefinish. Если задана переменная $orderid, то в выборку попадут счета, имеющие именно такой внутренний номер в учетной системе вашего сайта и удовлетворяющие условиям, что они были выписаны с указанного кошелька $purse и в указанный промежуток времени $datestart - $datefinish. Поскольку внутренний номер в вашей учетной системе - это неуникальное поле (иными словами, вы могли выписать несколько счетов с одинаковым orderid), то в такой выборке может оказаться не один счёт, а несколько. Если в getoutinvoices\orderid будет передан 0, то интерфейс посчитает, что orderid вообще не передан и является пустым. Наконец, если заданы одновременно и переменная $wminvid, и переменная $orderid, то $orderid будет проигнорирован интерфейсом. Отсюда ещё один вывод: $wminvid и $orderid, если заданы, сужают выборку и, как правило, ограничивают её одним единственным счётом. Откуда можно узнать wminvid и orderid конкретного интересующего нас счёта, мы уже рассказывали, когда говорили об интерфейсе X3. Повторим. Уникальный номер (в базе данных WebMoney) WM-счёта ($wminvid):
Номер (в системе учёта выставителя) WM-счёта ($orderid):
Всё это может показаться вам слишком сложным, однако на самом деле вам важно лишь определиться, каким именно образом вы будете использовать интерфейс X4. Как правило, единственная задача, которая стоит перед разработчиком при использовании X4 - автоматически проверить состояние оплаты выписанных ранее счетов. Для этого есть два пути:
О том, какие бывают состояния оплаты счёта и как их определить, я расскажу ниже. Вернёмся к рассмотрению функции. Генерируем уникальный номер запроса $reqn с помощью функции _GetReqn(): Получаем подпись XML-пакета с помощью функции _GetSign(). На вход функции подаём строку, полученную в результате склейки параметров, как это предусмотрено в описании интерфейса. Параметры должны склеиваться именно в таком порядке, как это указано ниже. Наконец, формируем XML-пакет с запросом: Отправляем запрос на сервер WebMoney и получаем от него ответ с помощью функции _GetAnswer(). На вход функции подаём URL интерфейса X4 из глобального массива $XML_addr, а также пакет XML-запроса, сформированный только что: Для отладки и поиска ошибок может потребоваться прочитать XML-ответ "в чистом виде". Тогда просто раскомментируйте следующую строку: Вызовом функции Если $xmlres не создан, значит, мы по какой-то причине не получили ответ от WebMoney. Тогда прерываем работу функции: Читаем следующие свойства объекта: Обратите внимание, что содержимое поля <retdesc> мы перекодировали из UTF-8 в Win1251. Дело в том, что XML-ответ от WebMoney приходит в кодировке Windows1251, но SimpleXML при помещении XML-данных в объект принудительно превратил их в Юникод. Такая вот у него особенность. А так как <retdesc> - это строка, и теоретически она может содержать русские символы, то при выемке её из объекта мы возвращаем ей "родную" кодировку. Хотя, в общем, это не обязательно и зависит от ваших нужд и задач. Далее, если cnt больше 0, т.е. в выборке есть хотя бы один счёт, переходим к сохранению информации о счетах. Нас, напомню, интересует состояние их оплаты. Информация о счетах содержится внутри одинаковых блоков XML-ответа <outinvoice>...</outinvoice>. Пробегаем эти блоки в цикле и формируем массив, где ключами элементов делаем уникальные номера счетов в системе WebMoney (атрибут id полей <outinvoice>), а значениями элементов делаем соответствующие этим счетам состояния их оплаты (поля <state>). Сформированный массив сохраняем внутрь элемента invoices выходного массива $result: На выходе функция _WMXML4() возвращает массив $result: Чтобы было лучше понятно, ещё раз посмотрим на содержимое массива $result (его можно привести в читабельный вид с помощью функции Что касается состояния оплаты, то оно по каждому счёту может иметь одно из следующих значений: 0 - не оплачен, 1 - оплачен с протекцией, 2 - оплачен окончательно, 3 - отказ от оплаты. "Оплачен окончательно" (2) означает, что протекция перевода по счёту уже снята, либо счёт был выставлен и оплачен вообще без протекции. Теперь осталось только проверить, как работает то, что мы написали. Создадим скрипт для тестов test.php: "; echo "Расшифровка - ".$r['retdesc']." "; echo "Количество - ".$r['cnt']." "; while(list($key,$val)=each($r['invoices'])) { echo "* У счёта ".$key." состояние оплаты ".$val." "; } В этом примере мы получили полную историю счетов, выписанных 30-го августа 2008 года. Завершая разговор об X4, хотим заметить, что приведенный пример функции _WMXML4() во многом является лишь демонстративным. В вашем конкретном случае может понадобиться получение "на выходе" более расширенной информации, либо структурирование её в ином виде. Не сомневаемся, что вы сможете адаптировать функцию под свои нужды. Главное - понять, как устроен интерфейс. Интерфейс X9. Получение балансов по кошелькам.С помощью данного интерфейса вы можете получать информацию о текущих остатках на кошельках вашего WMID. Полное описание интерфейса находится здесь. Интерфейс требует включения путем обращения в службу поддержку WMID 941977853154. X9 особенно полезен для автоматических обменных пунктов, сайтов, выплачивающих "WM-бонусы" и других проектов, в которых посетитель должен видеть текущие денежные резервы сервиса. Наш XML-запрос должен выглядеть так: Что означают параметры:
Формат ответа сервера WebMoney следующий: Что нас интересует в ответе? Во-первых, поле <retval> (если оно равно 0, то балансы получены успешно, в противном случае retval будет содержать код ошибки, расшифровку которой нужно смотреть в поле <retdesc>). Во-вторых, поля <pursename> и <amount>, содержащие соответственно номера кошельков и их балансы. Как вы уже поняли, запросить остаток по одному конкретному кошельку, к сожалению, нельзя. Ответ возвращает балансы сразу всех кошельков. Приведем теперь полностью функцию, которая реализует работу с интерфейсом X9, и добавим её в wmxml.inc.php: Разберём, что происходит в этой функции. Функция не получает никаких входных параметров. Генерируем уникальный номер запроса $reqn с помощью функции _GetReqn(): Получаем подпись XML-пакета с помощью функции _GetSign(). На вход функции подаём строку, полученную в результате склейки параметров, как это предусмотрено в описании интерфейса. Параметры должны склеиваться именно в таком порядке, как это указано ниже. Наконец, формируем XML-пакет с запросом: Отправляем запрос на сервер WebMoney и получаем от него ответ с помощью функции _GetAnswer(). На вход функции подаём URL интерфейса X9 из глобального массива $XML_addr, а также пакет XML-запроса, сформированный только что: Для отладки и поиска ошибок может потребоваться прочитать XML-ответ "в чистом виде". Тогда просто раскомментируйте следующую строку: Вызовом функции Если $xmlres не создан, значит, мы по какой-то причине не получили ответ от WebMoney. Тогда прерываем работу функции: Читаем следующие свойства объекта: Обратите внимание, что содержимое поля <retdesc> мы перекодировали из UTF-8 в Win1251. Дело в том, что XML-ответ от WebMoney приходит в кодировке Windows1251, но SimpleXML при помещении XML-данных в объект принудительно превратил их в Юникод. Такая вот у него особенность. А так как <retdesc> - это строка, и теоретически она может содержать русские символы, то при выемке её из объекта мы возвращаем ей "родную" кодировку. Хотя, в общем, это не обязательно и зависит от ваших нужд и задач. Если retval равен 0, то можно перейти к сохранению балансов по кошелькам. Номера кошельков и их балансы содержатся внутри одинаковых блоков XML-ответа <purse>...</purse> в <pursename> и <amount> соответственно. Пробегаем эти блоки в цикле и формируем ассоциативный массив, где ключами элементов делаем номера кошельков, а значениями элементов делаем соответствующие этим кошелькам балансы. Сформированный массив сохраняем внутрь элемента purses выходного массива $result: На выходе функция _WMXML9() возвращает массив $result: Чтобы было лучше понятно, ещё раз посмотрим на содержимое массива $result (его можно привести в читабельный вид с помощью функции Теперь осталось только проверить, как работает то, что мы написали. Создадим скрипт для тестов test.php: "; echo "Расшифровка - ".$r['retdesc']." "; while(list($key,$val)=each($r['purses'])) { echo "* На кошельке ".$key." ".$val." WM "; } Интерфейс X14. Бескомиссионный возврат перевода.С помощью этого интерфейса вы можете в течение 30 дней сделать возврат полученных WM-средств отправителю, не потеряв при этом комиссию системы 0.8%. Интерфейс будет очень полезен для обменных пунктов, интернет-магазинов и других сервисов в случае необходимости произвести возврат клиенту ошибочного платежа. Полное описание интерфейса находится здесь. Если Вы являетесь владельцем аттестата продавца и используете merchant.webmoney.ru, то использовать X14 вы можете без дополнительной регистрации. В противном случае, необходимо включить интерфейс путем обращения в службу поддержку WMID 941977853154. Наш XML-запрос должен выглядеть так: Что означают параметры:
Обратите, внимание на параметр moneybackphone. Дело в том, что перед совершением возврата очень важно понять, каким именно способом переводил WM ваш контрагент. Если он платил вам с WM-карты или из сервиса WebMoney Check, то такой платеж на ваш кошелек поступил со служебного кошелька R000000000001, U000000000001, Z000000000001 и т.д. На эти кошельки делать возврат нельзя! Что же делать? Для возврата платежа, совершенного с WM-карты, нужно сначала узнать у контрагента его номер мобильного телефона, после чего указать этот номер в параметре moneybackphone - тогда WM зачислятся контрагенту на его WebMoney Чек. Если же платеж на ваш кошелек был совершен с самого WebMoney Чека, то параметр moneybackphone можно не указывать - вебмани в этом случае всегда будут возвращены на WebMoney Чек отправителя. Как узнать, что возвращаемая транзакция была совершена с WM-карты или Чека? Если транзакция производилась через WebMoney Merchant, то помимо служебного кошелька отправителя (R000000000001, U000000000001, Z000000000001 и т.д.) есть и другие признаки. Так, в "форме оповещения о платеже" вы получаете непустой параметр LMI_PAYMER_NUMBER, если оплата с WM-карты, или непустой параметр LMI_WMCHECK_NUMBER, если оплата с WebMoney Чека. В ответе на Х18 об этом сигнализирует непустой параметр paymer_number. Итак, параметр moneybackphone в запросе X14 нужен для указания телефона контрагента, если исходная транзакция на ваш кошелек производилась с WM-карты. Но вернемся к интерфейсу Х14. Формат ответа сервера WebMoney можно посмотреть в описании интерфейса. В ответе нас интересуют: поле <retval> (eсли оно равно 0, то возврат произведён успешно, в противном случае retval будет содержать код ошибки, расшифровку которой нужно смотреть в поле <retdesc> или всё в том же описании интерфейса), а также атрибут id поля <operation> (содержит номер транзакции возврата) и поле <datecrt> (дата и время создания транзакции возврата). Приведем теперь полностью функцию, которая реализует работу с интерфейсом X14, и добавим её в wmxml.inc.php: Разберём, что происходит в этой функции. Функция получает переменные:
Напомним, откуда мы можем получить значение $wmtranid:
Генерируем уникальный номер запроса $reqn с помощью функции _GetReqn(): У $amount удаляем незначащие нули, если они есть: Получаем подпись XML-пакета с помощью функции _GetSign(). На вход функции подаём строку, полученную в результате склейки параметров, как это предусмотрено в описании интерфейса. Параметры должны склеиваться именно в таком порядке, как это указано ниже. Наконец, формируем XML-пакет с запросом: Отправляем запрос на сервер WebMoney и получаем от него ответ с помощью функции _GetAnswer(). На вход функции подаём URL интерфейса X14 из глобального массива $XML_addr, а также пакет XML-запроса, сформированный только что: Для отладки и поиска ошибок может потребоваться прочитать XML-ответ "в чистом виде". Тогда просто раскомментируйте следующую строку: Вызовом функции Если $xmlres не создан, значит, мы по какой-то причине не получили ответ от WebMoney. Тогда прерываем работу функции: Читаем следующие свойства объекта: Обратите внимание, что содержимое поля <retdesc> мы перекодировали из UTF-8 в Win1251. Дело в том, что XML-ответ от WebMoney приходит в кодировке Windows1251, но SimpleXML при помещении XML-данных в объект принудительно превратил их в Юникод. Такая вот у него особенность. А так как <retdesc> - это строка, и теоретически она может содержать русские символы, то при выемке её из объекта мы возвращаем ей "родную" кодировку. Хотя, в общем, это не обязательно и зависит от ваших нужд и задач. При возврате ЧАСТИ суммы исходной транзакции (когда $amount меньше суммы исходной транзакции) - на сервере WebMoney срабатывает защита от случайного "задвоения". Она состоит в том, что в течение получаса нельзя сделать еще один возврат ТАКОЙ ЖЕ суммы $amount. Например, если сумма исходной транзакции - 1.00, и вы делаете возврат $amount = 0.2, то повторный возврат 0.2 будет возможен только через полчаса, а до тех пор интерфейс будет отдавать код ошибки retval = 104. На выходе функция _WMXML14() возвращает массив $result: Теперь осталось только проверить, как работает то, что мы написали. Создадим скрипт для тестов test.php: "; echo "Расшифровка - ".$r['retdesc']." "; echo "Номер - ".$r['wmtranid_ret']." "; echo "Дата - ".$r['date']." "; ?> Отметим, что примечание операции возврата, совершенной интерфейсом X14, всегда будет иметь следующий вид: "Moneyback transaction: номер возвращаемой транзакции. (примечание возвращаемой транзакции)", и изменить его нельзя. Интерфейс X16. Создание кошелька.Пожалуй, один из самых простых интерфейсов. С его помощью вы можете создавать кошельки в своём WMID. Полное описание интерфейса находится здесь. Интерфейс доступен всем пользователям с любым аттестатом и не требует специального включения. Наш XML-запрос должен выглядеть так: Что означают параметры:
Формат ответа сервера WebMoney можно посмотреть в описании интерфейса. В ответе нас интересуют поля <retval> (eсли оно равно 0, то кошелёк создан успешно, в противном случае retval будет содержать код ошибки, расшифровку которой нужно смотреть в поле <retdesc> или всё в том же описании интерфейса) и <pursename>. В последнем содержится номер созданного кошелька. Приведем теперь полностью функцию, которая реализует работу с интерфейсом X16, и добавим её в wmxml.inc.php: Разберём, что происходит в этой функции. Функция получает переменные:
Генерируем уникальный номер запроса $reqn с помощью функции _GetReqn(): У $desc убираем лишние пробелы в начале и конце: Получаем подпись XML-пакета с помощью функции _GetSign(). На вход функции подаём строку, полученную в результате склейки параметров, как это предусмотрено в описании интерфейса. Параметры должны склеиваться именно в таком порядке, как это указано ниже. Теперь преобразуем специальные символы ("<", "&" и др.) в html-сущности. Если этого не сделать, то при попадании в $desc таких символов WebMoney наш запрос не примет и вернет ошибку "A semi colon character was expected". Преобразовать спецсимволы в PHP можно с помощью функции Но это ещё не всё. $desc может содержать русские символы. Например, в $desc может быть такой текст: "тестовый кошелёк". И здесь нужно понимать, как подготовить $desc для передачи в составе XML-пакета. Дело в том, что содержимое полученного от вас XML-пакета сервер WebMoney попытается прочитать так, будто он пришел в кодировке Unicode. Если сервер встретит в пакете русские символы в другой кодировке, то вернет ошибку: "An invalid character was found in text content" ("Обнаружен ошибочный символ"). Для того чтобы этого не произошло, нам нужно принудительно перекодировать $desc в UTF-8 и уже в таком виде включать его в XML-запрос. Сделать преобразование кодировок можно с помощью функции То же самое, но с помощью функции Можно даже преобразовать не в UTF-8, а в html-сущности, это тоже сработает: Если же iconv и mbstring вашим сервером не поддерживаются, то могу предложить ещё один вариант. Оставьте $desc в кодировке Win1251, а в начале XML-запроса вставляйте заголовок
Наконец, формируем XML-пакет с запросом: Отправляем запрос на сервер WebMoney и получаем от него ответ с помощью функции _GetAnswer(). На вход функции подаём URL интерфейса X16 из глобального массива $XML_addr, а также пакет XML-запроса, сформированный только что: Для отладки и поиска ошибок может потребоваться прочитать XML-ответ "в чистом виде". Тогда просто раскомментируйте следующую строку: Вызовом функции Если $xmlres не создан, значит, мы по какой-то причине не получили ответ от WebMoney. Тогда прерываем работу функции: Читаем следующие свойства объекта: Обратите внимание, что содержимое поля <retdesc> мы перекодировали из UTF-8 в Win1251. Дело в том, что XML-ответ от WebMoney приходит в кодировке Windows1251, но SimpleXML при помещении XML-данных в объект принудительно превратил их в Юникод. Такая вот у него особенность. А так как <retdesc> - это строка, и теоретически она может содержать русские символы, то при выемке её из объекта мы возвращаем ей "родную" кодировку. Хотя, в общем, это не обязательно и зависит от ваших нужд и задач. На выходе функция _WMXML16() возвращает массив $result: Теперь осталось только проверить, как работает то, что мы написали. Создадим скрипт для тестов test.php: "; echo "Расшифровка - ".$r['retdesc']." "; echo "Номер кошелька - ".$r['purse']." "; В заключение ещё раз приведём ссылку на файл с функциями всех 10 XML-интерфейсов WebMoney, которые мы рассмотрели в статьях на оВебМани.Ру. Вот он. Файл готов к работе, вы можете включать его в свои программы и использовать. ![]() 4.09.2008 Внимание! Все права на данный материал принадлежат сайту owebmoney.ru. Копирование материала разрешено с обязательным указанием гиперссылки на http://owebmoney.ru. |
|
Все права на материалы, опубликованные на owebmoney.ru, охраняются в соответствии с законом об авторском праве. Разрешено копирование без согласования при условии указания гиперссылки на сайт (без атрибута nofollow и сокрытий) непосредственно до\после материала.
|
|