Параметры подключения Контрагента Сертификат Контрагента
Контрагенту следует получить сертификат X.509, посредством которого он будет формировать запросы к сервису «Яндекс.Деньги». См. документ «Процедура обмена сертификатами».
Информационные запросы Запрос списка заказов (listOrders)
Запрос позволяет получить перечень заказов и их свойств. Список параметров приведен в Таблице 4. Типы данных описаны в разделе «Типы данных».
Адрес операции: https://server:port/webservice/mws/api/listOrders
Формат запроса
ИС формирует POST-запрос по протоколу HTTP/1.1 (http://www.ietf.org/rfc/rfc2616.txt, http://www.ietf.org/rfc/rfc2618.txt ). Параметры запроса упаковываются как набор параметров POST запроса в виде пар «имя=значение». MIME-тип: application/x-www-form-urlencoded. Кодировка символов: UTF-8.
Некоторые параметры могут отсутствовать в запросе, в этом случае для них используется значение параметра по умолчанию. Если параметр присутствует в запросе, но имеет пустое значение, то значение по умолчанию для параметра не используется. Если отсутствует обязательный параметр, возвращается ошибка «Неверное значение параметра NNNN».
Таблица . Параметры запроса списка заказов
Название параметра
|
Тип
|
Примечания
|
requestDT
|
xs:dateTime
|
Дата и время запроса по часам ИС. Обязательный параметр.
|
outputFormat
|
xs:normalizedString
|
Формат представления результата запроса. Допустимые значения — «XML» или «CSV». Необязательный параметр: значение по умолчанию «XML».
|
csvDelimiter
|
xs:string, 1 символ
|
Разделитель значений для формата CSV. Не может быть равен символу «”» (кавычка). Необязательный параметр: значение по умолчанию «;».
|
shopID
|
xs:long
|
Идентификатор Контрагента, список заказов которого запрашивается.
Если параметр не задан, то возвращаются заказы по shopID, для которых у данного пользователя MWS имеется право получать список заказов.
|
orderCreatedDatetimeGreaterOrEqual
|
xs:dateTime
|
Нижняя граница времени создания заказа.
Выбираются заказы, время создания которых больше или равно значению этого параметра.
|
orderCreatedDatetimeLessOrEqual
|
xs:dateTime
|
Верхняя граница времени создания заказа.
Выбираются заказы, время создания которых меньше или равно значению этого параметра.
|
paid
|
xs:boolean
|
Если параметр имеет значение «true», то возвращаются только оплаченные заказы.
Если параметр имеет значение «false», то возвращаются только неоплаченные заказы.
Если параметр не задан, будут возвращены как оплаченные, так и неоплаченные заказы.
|
paymentDatetimeGreaterOrEqual
|
xs:dateTime
|
Нижняя граница времени оплаты заказа.
Выбираются заказы, время оплаты которых больше или равно значению этого параметра.
|
paymentDatetimeLessOrEqual
|
xs:dateTime
|
Верхняя граница времени оплаты заказа.
Выбираются заказы, время оплаты которых меньше или равно значению этого параметра.
|
invoiceId
|
xs:long
|
Уникальный номер транзакции Оператора.
|
orderNumber
|
xs:string, до 64 символов
|
Уникальный номер заказа в ИС.
Использование параметра возможно, если Оператор получает от Контрагента и хранит номера заказов.
|
outputFields
|
xs:string, до 4000 символов
|
Список свойств заказа, которые должны быть выведены в результате выполнения запроса.
Разделитель имен в списке — символ «;» (без кавычек).
Значение по умолчанию:
«shopID;shopName;articleId;articleName;invoiceId;orderNumber;paymentSystemOrderNumber;
customerNumber; createdDatetime;paid;orderSumAmount;
orderSumCurrencyPaycash;orderSumBankPaycash;paidSumAmount;
paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAmount;
receivedSumCurrencyPaycash;receivedSumBankPaycash;
shopSumAmount;shopSumCurrencyPaycash;shopSumBankPaycash;
paymentDatetime;paymentAuthorizationTime;payerCode;
payerAddress;payeeCode;paymentSystemDatetime;
avisoReceivedDatetime;avisoStatus» (без кавычек).
Полный список свойств заказа, которые могут присутствовать в ответе на запрос списка заказов, см. в Таблица . Свойства заказа, которые могут присутствовать в ответе на запрос списка заказов.
|
В параметрах запроса списка заказов обязательно должно быть задано как минимум одно из условий:
номер транзакции (invoiceId) и идентификатор Контрагента (shopID);
номер заказа (orderNumber) и идентификатор Контрагента (shopID);
диапазон времени создания заказа (orderCreatedDatetimeGreaterOrEqual и/или orderCreatedDatetimeLessOrEqual);
диапазон времени оплаты заказа (paymentDatetimeGreaterOrEqual и/или paymentDatetimeLessOrEqual).
При запросах по номеру транзакции (invoiceId) или номеру заказа (orderNumber) в запросе обязательно должен быть указан идентификатор Контрагента (shopID).
Для запросов, выборка в которых ограничена диапазоном времени создания или диапазоном времени оплаты заказа, действуют следующие правила:
если задана только одна граница диапазона для времени создания или оплаты заказа, то значение второй берется по умолчанию. Значение по умолчанию для верхней границы — текущее время Оператора, значение по умолчанию для нижней границы — время верхней границы, указанное в запросе, минус одни сутки;
если задан диапазон времени оплаты заказа, то в запросе обязательно должен присутствовать параметр paid со значением «true» (без кавычек);
длина диапазона времени, ограничивающего выборку, не должна превышать 31 день.
Формат ответа
Формат ответа определяется входными параметрами запроса outputFormat и csvDelimiter. В случае ошибки ее код и описание возвращаются в заказанном формате представления результата.
Пример . Сообщение об ошибке в формате XML
status="3" error="111"
processedDT="2011-07-02T20:38:01.000+04:00"
techMessage="Неверное значение параметра requestDT"
/>
Пример . Сообщение об ошибке в формате CSV
status=3;error=111;processedDT=2011-07-21T13:20:14.869+04:00;"techMessage=Неверное значение параметра requestDT"
|
Если результат выборки списка заказов содержит более 10 000 записей, возвращается ошибка с кодом 216. Получив такую ошибку, следует изменить параметры запроса, чтобы уменьшить длину временного диапазона, ограничивающего выборку.
Таблица . Дополнительные поля заголовка ответа запроса списка заказов
Название
|
Содержание
|
Тип
|
Примечания
|
orderCount
|
Количество заказов в результате.
|
xs:int
|
Присутствует в случае успешной выборки списка заказов.
|
Ниже приведен полный перечень свойств заказа, которые могут быть получены в результате запроса списка заказов.
Таблица . Свойства заказа, которые могут присутствовать в ответе на запрос списка заказов
Название
|
Содержание
|
Тип
|
Примечания
|
shopID
|
Идентификатор Контрагента, присвоенный Оператором.
|
xs:long
|
|
articleId
|
Идентификатор товара, присвоенный Оператором.
|
xs:long
|
|
shopName
|
Название Контрагента.
|
xs:string, до 64 символов
|
|
articleName
|
Название товара.
|
xs:string, до 128 символов
|
|
invoiceId
|
Уникальный номер транзакции Оператора.
|
xs:long
|
|
orderNumber
|
Номер заказа в ИС Контрагента.
|
xs:string, до 64 символов
|
Если Оператор получает от ИС и хранит номера заказов, то свойство содержит номер заказа в ИС. В противном случае свойство содержит номер транзакции, назначенный Оператором.
|
paymentSystemOrderNumber
|
Идентификатор перевода на стороне Оператора.
|
xs:string, до 40 символов
|
Присутствует только для оплаченных заказов.
|
customerNumber
|
Идентификатор покупателя в ИС Контрагента (присланный в платежной форме).
Номер мобильного телефона, договора и т. п., специфично для Контрагента.
|
xs:string, до 64 символов
|
|
createdDatetime
|
Момент (дата и время) регистрации заказа на стороне Оператора.
|
xs:dateTime
|
|
paid
|
Имеет значение «true», если заказ оплачен. Иначе — «false».
|
xs:boolean
|
|
paymentDatetime
|
Момент (дата и время) оплаты заказа по часам Оператора.
|
xs:dateTime
|
Значение присутствует в ответе только для оплаченных заказов.
|
paymentAuthorizationTime
|
Номер заказа в процессинговом центре Оператора.
|
xs:long
|
Значение присутствует в ответе только для оплаченных заказов.
|
payerCode
|
Номер счета плательщика.
|
xs:string, до 33 символов
|
Значение присутствует в ответе только для оплаченных заказов.
|
payerAddress
|
IP-адрес плательщика, если он известен.
|
xs:string, до 33 символов
|
Значение присутствует в ответе только для оплаченных заказов.
|
payeeCode
|
Номер счета получателя перевода при оплате заказа.
|
xs:string, до 33 символов
|
Значение присутствует в ответе только для оплаченных заказов.
|
paymentSystemDatetime
|
Момент (дата и время) регистрации оплаты заказа в процессинговом центре Оператора.
|
xs:dateTime
|
Значение присутствует в ответе только для оплаченных заказов.
|
avisoReceivedDatetime
|
Момент времени регистрации оплаты заказа в ИС Контрагента.
|
xs:dateTime
|
Присутствует, если Контрагент на момент запроса получил уведомление о данном переводе.
|
avisoStatus
|
Код состояния уведомления о переводе.
|
xs:int
|
Состояния уведомлений описаны в разделе «Коды состояний уведомления о переводе».
|
avisoRegistryId
|
Номер реестра, в котором содержится данный заказ.
|
xs:long
|
|
orderSumAmount
|
Сумма заказа.
|
CurrencyAmount
|
|
orderSumCurrencyPaycash
|
Код валюты для orderSumAmount.
|
CurrencyCode
|
|
orderSumBankPaycash
|
Код процессингового центра для orderSumAmount.
|
CurrencyBank
|
|
contractAmount
|
Сумма к оплате в валюте счета плательщика.
|
CurrencyAmount
|
|
contractCurrency
|
Код валюты счета плательщика.
|
CurrencyCode
|
|
paidSumAmount
|
Сумма, уплаченная плательщиком.
|
CurrencyAmount
|
Значение присутствует в ответе только для оплаченных заказов.
|
paidSumCurrencyPaycash
|
Код валюты для paidSumAmount.
|
CurrencyCode
|
Значение присутствует в ответе только для оплаченных заказов.
|
paidSumBankPaycash
|
Код процессингового центра для paidSumAmount.
|
CurrencyBank
|
Значение присутствует в ответе только для оплаченных заказов.
|
shopSumAmount
|
Сумма, получаемая Контрагентом на р/с: сумма заказа за вычетом комиссии Оператора.
|
CurrencyAmount
|
|
shopSumCurrencyPaycash
|
Код валюты для суммы, получаемой Контрагентом на р/с.
|
CurrencyCode
|
|
shopSumBankPaycash
|
Код процессингового центра для суммы, получаемой Контрагентом на р/с.
|
CurrencyBank
|
|
receivedSumAmount
|
Сумма, полученная Оператором от плательщика.
|
CurrencyAmount
|
Значение присутствует в ответе только для оплаченных заказов.
|
receivedSumCurrencyPaycash
|
Код валюты для receivedSumAmount.
|
CurrencyCode
|
Значение присутствует в ответе только для оплаченных заказов.
|
receivedSumBankPaycash
|
Код банка для receivedSumAmount.
|
CurrencyBank
|
Значение присутствует в ответе только для оплаченных заказов.
|
paymentFormParams
|
Параметры платежной формы.
|
xs:string
|
Значение присутствует в ответе только для Контрагентов, у которых установлена настройка «сохранять параметры платежной формы».
|
paymentType
|
Способ проведения платежа пользователем.
|
PaymentType
|
|
Если в запросе указан формат представления результата CSV, то заголовок и тело ответа представляют собой набор строк, разделенных переводами строк (\r\n). В первой строке ответа содержатся значения полей заголовка результата выполнения запроса. Во второй строке содержится перечень названий свойств заказа в том порядке, в котором в последующих строках будут содержаться значения соответствующих свойств заказа. Каждая строка ответа, начиная с третьей, содержит свойства одного заказа.
В качестве разделителя свойств заказа используется значение параметра запроса csvDelimiter. Если свойство заказа содержит символ разделителя значений (параметр запроса csvDelimiter) или символ «”» (без обрамляющих кавычек), то в ответе MWS значение свойства помещается в кавычки «”» (без обрамляющих кавычек), при этом кавычки, содержащиеся внутри свойства, удваиваются.
Если значение какого-либо свойства не может быть определено (например, время перевода для неоплаченного заказа), то в ответе формата CSV значение этого свойства будет пустым.
Пример . Ответ на запрос списка заказов, формат CSV, набор свойств заказа по умолчанию
Длинные строки перенесены, их границы показаны строками таблицы.
status=0;error=0;processedDT=2011-08-02T18:28:08.541+04:00;orderCount=2
|
shopID;articleId;invoiceId;orderNumber;paymentSystemOrderNumber;customerNumber;createdDatetime;paid;orderSumAmount;orderSumCurrencyPaycash;orderSumBankPaycash;paidSumAmount;paidSumCurrencyPaycash;paidSumBankPaycash;receivedSumAmount;receivedSumCurrencyPaycash;receivedSumBankPaycash;shopSumAmount;shopSumCurrencyPaycash;shopSumBankPaycash;paymentDatetime;paymentAuthorizationTime;payerCode;payerAddress;payeeCode;paymentSystemDatetime;avisoReceivedDatetime;avisoStatus;avisoRegistryId
|
1;2;2000000294394;12345670;;;2011-08-02T18:28:08.269+04:00;false;2.08;10643;1003;;;;;;;
2.00;10643;1003;;;;;;;;;;
|
2;3;2000000294386;12345671;334074060091013004;;2011-08-02T18:20:58.562+04:00;true;350.00;10643;1002;350.00;10643;1003;350.00;10643;1003;300.00;10643;1002;
2011-08-02T18:21:00.091+04:00;334074060091013004;41003321020;192.168.1.127;410031234567;
2011-08-02T18:21:00.091+04:00;2011-08-02T18:27:59.448+04:00;81;
|
Если значение какого-либо свойства не может быть определено (например, время перевода для неоплаченного заказа), то в ответе формата XML соответствующий атрибут будет отсутствовать.
Пример . Ответ на запрос списка заказов, формат XML
processedDT="2011-08-02T20:38:01.000+04:00"
orderCount="2">
shopName="ЗАО "Мобильник""
articleName="Оплата мобильного телефона"
orderNumber="12345678"
paymentSystemOrderNumber="334074426144011004"
createdDatetime="2011-08-02T18:27:05.568+04:00"
paid="true"
paymentDatetime="2011-08-02T18:27:06.144+04:00"
paymentAuthorizationTime="334074426144011004"
payerCode="41003122233"
payerAddress="192.168.1.127"
payeeCode="41003987654"
paymentSystemDatetime="2011-08-02T18:27:06.144+04:00"
avisoReceivedDatetime="2011-08-02T18:27:06.144+04:00"
avisoStatus="1000"
orderSumAmount="2.08"
orderSumCurrencyPaycash="643"
orderSumBankPaycash="1001"
paidSumAmount="2.08"
paidSumCurrencyPaycash="643"
paidSumBankPaycash="1001"
shopSumAmount="2.07"
shopSumCurrencyPaycash="643"
shopSumBankPaycash="1001"
receivedSumAmount="2.07"
receivedSumCurrencyPaycash="643"
receivedSumBankPaycash="1001"
/>
shopName="ЗАО "Виртуальная реальность""
articleName="Футбол навсегда"
orderNumber="12345679"
createdDatetime="2011-08-02T18:28:08.269+04:00"
paid="false"
orderSumAmount="2.08"
orderSumCurrencyPaycash="643"
orderSumBankPaycash="1001"
shopSumAmount="2.07"
shopSumCurrencyPaycash="643"
shopSumBankPaycash="1001"
/>
|
Формат отображения параметров платежной формы в ответе зависит от того, какой формат ответа задан в параметре запроса outputFormat:
в формате CSV параметры платежной формы возвращаются в свойстве заказа paymentFormParams в виде перечисления пар «имя=значение» (без кавычек), в качестве разделителя пар используется символ «;» (без кавычек). Если пара содержит кавычки (“), то она помещается в двойные кавычки;
в формате XML параметры платежной формы возвращаются как вложенные элементы элемента paymentFormParams. Для каждого параметра платежной формы создается элемент, атрибут «key» которого содержит имя параметра, а «val» — значение параметра.
Пример . Параметры платежной формы в ответе в формате CSV
“PROPERTY1=123;PROPERTY2=1234567;Sum=10.00;NetSum=0;ShopArticleId=2;ShowCaseId=99901;
BankId=1003;CurrencyId=10643;TargetBankId=1003;TargetCurrencyId=10643;
BuyButton=Оплатить;””ArticleName=””””Оплата мобильного телефона”””””””
|
Пример . Параметры платежной формы в ответе в формате XML
|
