API для партнерских магазинов - My

Программный интерфейс My-shop.ru
для партнерских магазинов
Содержание
ВЕРСИЯ .......................................................................................................................................... 2
ПРАВА И ОБЯЗАННОСТИ ПАРТНЕРА ....................................................................................... 3
ПОПУЛЯРНЫЕ ВОПРОСЫ. РЕКОМЕНДАЦИИ MY-SHOP.RU .................................................. 5
ОБЩИЕ ХАРАКТЕРИСТИКИ ПРОГРАММНОГО ИНТЕРФЕЙСА .............................................. 8
ДО ОФОРМЛЕНИЯ ЗАКАЗА....................................................................................................... 11
Корзина ........................................................................................................................................................................................... 11
Выбор способов доставки/оплаты .............................................................................................................................................. 12
Предварительная проверка параметров заказа и расчет стоимости .................................................................................. 14
Оформление нового заказа .......................................................................................................................................................... 16
ПОСЛЕ ОФОРМЛЕНИЯ ЗАКАЗА ............................................................................................... 21
Информация о состоянии заказа ................................................................................................................................................ 21
Аннулирование заказа.................................................................................................................................................................. 24
Переписка клиента с операторами My-shop.ru: новое сообщение клиента ....................................................................... 25
Переписка клиента с операторами My-shop.ru: список сообщений .................................................................................... 26
Краткий отчет об оформленных заказах .................................................................................................................................. 28
СПРАВОЧНАЯ ИНФОРМАЦИЯ ................................................................................................. 31
Проверка текущей версии API ................................................................................................................................................... 31
Различные константы .................................................................................................................................................................. 32
Информация о цене и доступности товара ............................................................................................................................... 34
Справочник регионов доставки ................................................................................................................................................. 36
Справочник способов доставки .................................................................................................................................................. 37
Справочник способов оплаты..................................................................................................................................................... 38
Справочник станций метро ......................................................................................................................................................... 39
Справочник почтовых индексов ................................................................................................................................................ 40
Справочник ограничений на пересылку .................................................................................................................................. 41
Справочник кодов ошибок .......................................................................................................................................................... 42
ПРОЧИЕ ЗАПРОСЫ .................................................................................................................... 43
Поиск товаров ................................................................................................................................................................................ 43
стр. 1 из 44
Версия
Версия описываемого в данном документе программного интерфейса (API) – 1.13.
Дата последнего изменения версии API – 3 июня 2015 года.
Версия документа – 1.13.1.
Дата последнего изменения документа – 3 июня 2015 г.
Что нового в версии 1.13:
 Параметр «discount» («Скидка, %») в ответах на все запросы считается устаревшим, его
использование не рекомендуется. Данный параметр может быть удалён в следующих версиях
API. (Связано с переходом от начисления скидки на заказ целиком к начислению скидки
отдельно для каждого товара в заказе.)
 Если партнёр предоставляет скидку за счёт своего партнёрского вознаграждения, считается,
что скидка, указанная в запросе, относится к основной системе скидок. Для товаров,
относящихся к другим системам скидок, величина скидки вычисляется в соответствии с
описанием систем скидок: http://my-shop.ru/my/helper_24
 В ответе на запрос «product» («Информация о цене и доступности товара») появился параметр
«ds» (код системы скидок).
 С помощью запроса «list_orders» («Краткий отчет об оформленных заказах») теперь можно
получить значение суммы партнёрского вознаграждения за каждый заказ.
Что нового в версии 1.12:
 Запрос «list_search» (поиск товаров).
Что нового в версии 1.11:
 Параметр «phone_sms» (номер мобильного телефона для SMS-уведомлений) стал
обязательным при оформлении заказа (запрос «order_new»).
Изменение вступило в силу 17 августа 2013 г. Соответствующие уведомления были разосланы подписчикам
рассылки «Новости партнерской программы My-shop.ru» за два с половиной месяца – 31 мая 2013 г.
Что нового в версии 1.10:
 В ответе на запрос «list_regions» («Справочник регионов доставки») появился параметр
«delivery_0_free» (см. описание ниже).
 В ответе на запрос «list_delivery» («Справочник способов доставки») появились параметры
«info» и «info_importance» (см. описание ниже). C 1 декабря 2012 года использование этих
параметров обязательно!
Что нового в версии 1.9:
 В ответе на запрос «Различные константы» («const») в параметрах «last_modified_list_regions»
и «last_modified_list_delivery» всегда возвращается текущая дата. Эти параметры больше не
используются, текущая дата в значениях этих параметров возвращается для совместимости с
предыдущими версиями.
стр. 2 из 44
Права и обязанности партнера
Участник партнерской программы, использующий данный API, имеет право:
 Создавать собственные интерфейсы для выбора товаров и оформления заказов без
перенаправления клиентов на сайт Интернет-магазина My-shop.ru.
 Вести собственную историю заказов.
 Создавать собственную систему регистрации клиентов.
 Создавать собственные интерфейсы для реализации «личных кабинетов» клиентов с
информацией об оформленных ранее заказах и пр.
 Использовать собственную систему оповещения клиентов о ходе выполнения их заказов.
Начиная с сентября 2013 г., мы не рекомендуем этого делать, т.к. предоставляем всем
клиентам, оформившим заказ в партнерском магазине, доступ к странице заказа на сайте
Интернет-магазина My-shop.ru. На этой странице клиент может проверять состояние заказа,
вносить изменения в заказ и вести переписку с операторами магазина. Кроме того, таким
клиентам отправляются SMS-уведомления о ходе выполнения заказа.
 Предоставлять клиентам скидки за счет своего партнерского вознаграждения, создавать
собственную накопительную систему скидок.
 Проводить рекламные акции с предоставлением скидок за счет своего партнерского
вознаграждения.
 Ограничивать ассортимент товаров.
 Использовать собственные ограничения списка регионов доставки.
 Использовать собственные ограничения набора способов доставки.
 Использовать собственные ограничения набора способов оплаты.
Участник партнерской программы, использующий данный API, обязан:
 Не допускать разглашения кода для аутентификации партнерского магазина. Изменять код
для аутентификации партнерского магазина не реже одного раза в год.
 Не допускать разглашения персональных данных клиентов и информации о заказах клиентов.
 Разместить на индексируемой странице сайта партнерского магазина ссылку на Интернетмагазин My-shop.ru.
 Информировать клиентов о том, что заказы выполняет «Интернет-магазин My-shop.ru», а
сайт, на котором оформляется заказ, является партнером My-shop.ru.
 Показывать клиентам текст, возвращаемый данным API в параметре «conditions» в ответ на
запрос «const» («Различные константы»). Данный текст должен располагаться над кнопкой
«Подтвердить заказ». Перед указанным текстом должна быть примерно такая фраза:
«Нажимая кнопку "Подтвердить заказ", Вы подтверждаете свое согласие со следующими
условиями». Сам текст может располагаться в поле «textarea», но при этом в видимой части
данного поля (без прокрутки) должны находиться, как минимум, первый пункт и первые две
строки второго пункта условий. Данный текст должен быть хорошо виден, его затемнение
и/или уменьшение размера шрифта не допускается.
 Предоставлять клиентам достоверную информацию о товарах и услугах Интернет-магазина
My-shop.ru.
 Перед подтверждением заказа клиентом сообщать ему итоговую стоимость заказа и
ориентировочную дату отгрузки заказа (для заказов с предоплатой – ориентировочный срок
формирования заказа), предлагать клиентам проверять прочие параметры заказа.
 Сообщать клиенту номер оформленного им заказа (номер заказа в My-shop.ru) и настоятельно
рекомендовать сохранять этот номер до момента получения заказа.
 По запросу клиента предоставлять контактную информацию Интернет-магазина My-shop.ru
(см. раздел «Различные константы»).
 При передаче параметров, имена которых в настоящем описании программного интерфейса
выделены красным, использовать только значения, указанные клиентами.
стр. 3 из 44



Кэшировать справочную информацию в соответствии с рекомендациями, приведенными в
настоящем описании программного интерфейса.
Выполнять прочие требования, указанные в настоящем описании программного интерфейса.
Не производить электронные, SMS и прочие рассылки от имени Интернет-магазина Myshop.ru или с упоминанием Интернет-магазина My-shop.ru без согласия администрации Myshop.ru, данного в письменной форме.
Интернет-магазин My-shop.ru имеет право в любой момент проверять работу партнерского магазина,
в том числе, оформляя тестовые заказы, а при выявлении нарушений, запрещать прием заказов через
партнерский магазин. При выявлении грубых нарушений возможна полная блокировка
регистрационной записи партнера без выплаты вознаграждения.
стр. 4 из 44
Популярные вопросы. Рекомендации My-shop.ru
Зачем столько пунктов в «обязанностях партнера»? Разве вам не достаточно, что я отправляю
вам заказы?
My-shop.ru – клиент-ориентированная компания. Мы прилагаем все усилия для того, чтобы клиенты
остались довольны нашей работой, и требуем того же от наших партнеров. Большая часть наших
требований к партнерским магазинам касается правильного информирования клиентов о товарах и
услугах. Мы стараемся не допускать ситуаций, когда клиентам не предоставляют необходимую им
информацию о товарах и услугах, и тем более не позволяем специально вводить клиентов в
заблуждение. Если вы считаете, что руководствоваться интересами клиентов неправильно, не
начинайте работу в режиме «партнерского магазина».
Зачем нужно говорить клиенту, что заказы выполняет My-shop.ru?
Возможно, этого требования не было бы, если бы можно было избежать контактов My-shop.ru с
клиентом. Но заказы выполняем мы, и в большинстве случаев при выполнении заказов мы так или
иначе контактируем с клиентами. Соответственно, клиенту необходима информация о том, кто будет
выполнять его заказ (см. предыдущий вопрос). Если клиенты не будут знать, кто выполняет их
заказы, увеличится доля заказов, аннулированных из-за различных недоразумений, например, клиент
может отказаться от получения заказа на почте, поскольку просто не узнает его: он сделал заказ в
одном магазине (напр., наложенным платежом), а ему приходит неизвестно что из неизвестной ему
компании, и за это почему-то просят денег. Разумеется, мы не можем себе позволить нести убытки
из-за таких недоразумений.
Кроме того, этого требует наше законодательство. Клиент не может не знать, кто является
продавцом, кто несет ответственность за выполнение заказа и к кому обращаться в случае
возникновения спорного вопроса.
Если вас это не устраивает, возможно, вам нужно делать настоящий магазин, т.е. закупать у нас (или
где-то еще) товары по оптовым ценам и продавать их самостоятельно. В этом случае у нас не будет
никаких требований к вашему магазину.
Можно ли продавать товары по ценам, отличающимся от цен My-shop.ru?
Вы можете предоставлять клиентам скидки за счет своего партнерского вознаграждения, см.
параметр «discount» в описании API. Такие скидки могут предоставляться только персонально
(например, в рамках накопительной системы скидок партнерского магазина или в рамках каких-либо
специальных акций, проводимых партнером). До авторизации на сайте партнера или до оформления
заказа запрещается показывать цены, отличающиеся от цен на сайте Интернет-магазина My-shop.ru.
Повышение цены не допускается, но мы не исключаем предоставления такой возможности в
будущем.
Почему нельзя принимать предварительные заказы и заказы от юридических лиц?
С юридическими лицами сложный документооборот, для этого, как минимум, необходимо заполнять
намного больше полей. Кроме того, если юридическое лицо оформляет заказы и на нашем сайте (с
регистрацией и личным счетом, на котором могут оставаться деньги), и через другие сайты, может
возникнуть путаница с взаиморасчетами, т.е. для юридических лиц лучше вообще не разрешать
«разовые» заказы.
В данном случае совсем неразрешимых проблем нет, но и для нас, и для партнеров проще не
использовать эту схему работы с юридическими лицами.
С предварительными заказами ситуация похожая – взаимодействие с клиентом заметно сложнее,
кроме того, сама услуга по розыску отсутствующих товаров ориентирована именно на
зарегистрированных клиентов, у которых есть свой счет в магазине.
В любом случае, доля заказов юридических лиц и предварительных заказов невелика, в партнерских
магазинах ими можно пренебречь.
стр. 5 из 44
Я сделал(а) партнерский магазин на своем сайте, однако при попытке оформить заказ ваш API
сообщает об ошибке «Недопустимый тип запроса для тестового режима работы партнерского
магазина». Как включить нормальный режим?
У нас предусмотрено два режима работы партнерского магазина: тестовый и рабочий. По умолчанию
включается тестовый режим, в котором можно делать все запросы, кроме запроса на оформление
нового заказа. Когда будете готовы к включению рабочего режима, напишите нам с этой страницы:
http://my-shop.ru/my/helper_11
В письме укажите ваш id партнера и URL страницы, где можно будет проверить работу вашего
партнерского магазина.
Как получить код для аутентификации?
Секретный код вы должны указать сами в настройках партнерской программы (в вашем
персональном разделе на странице «Партнерская программа»):
http://my-shop.ru/my/partnership
Поле, в котором нужно указать этот код, называется «Секретный код для запросов партнерского
магазина». Введите в этом поле случайную последовательность от 20 до 50 символов. Секретный код
можно изменить в любой момент.
Зачем вообще нужна аутентификация и секретный код? Если с моим id партнера будет
оформлять заказы кто-то еще, я буду только рад(а).
Если кто-то от вашего имени будет оформлять заказы несуществующих клиентов, эти заказы,
естественно, будут аннулироваться после попытки их выполнения. Мы при этом будем нести убытки
– увидим, что сотрудничество с вами для нас не выгодно, и будем вынуждены заблокировать ваш
аккаунт. Иными словами, аутентификация нужна вам, чтобы вы были уверены, что никто не
действует от вашего имени без вашего ведома.
Какой метод аутентификации выбрать? Ваш «md5» – это надежно?
Сравним, что будет, если кто-то перехватит значение параметра «auth_code» в вашем запросе:
 при аутентификации «plain», этот «кто-то» сможет делать любые запросы от вашего имени,
 при аутентификации «md5», этот кто-то сможет делать запросы от вашего имени только с тем
же значением «request» (для этого требуется одновременный перехват значений параметров
«auth_code» и «auth_salt»).
В данном случае «md5» не сильно защищает, поэтому мы не настаиваем на его использовании.
В дополнение к этому мы рекомендуем вам указать в настройках партнерской программы (в вашем
персональном разделе на странице «Партнерская программа») один или несколько IP-адресов, с
которых должны приниматься запросы вашего партнерского магазина.
В описании API упоминается около 20 типов запросов. Для создания партнерского магазина
нужно использовать все эти запросы?
В данном API действительно предусмотрено много типов запросов, и их количество еще может
увеличиться. Чтобы принимать заказы на своем сайте, достаточно использовать лишь два типа
запросов: «Предварительная проверка параметров заказа» и «Оформление нового заказа». Все
остальное – на ваше усмотрение. Решайте сами, что понадобится для вашего магазина, а что нет.
Рекомендации по обновлению справочников и программного обеспечения партнерского
магазина.
Мы рекомендуем сделать отдельную программу для ежедневной проверки ответов на запрос
«Различные константы». Что стоит делать при этой проверке:
1) Собственно обновлять константы, которые используются вашими программами.
2) Проверять, не изменилась ли версия API. См. рекомендации в разделе «Проверка текущей
версии API».
3) Проверять дату последнего изменения каждого используемого вами справочника, сравнивать
ее с датой последнего обновления справочника в вашей базе данных и при необходимости
запускать обновление справочника.
стр. 6 из 44
Даты изменения справочников в ответах на запрос «Различные константы» определяются не
автоматически, эти даты мы обновляем вручную. Риск того, что мы забудем изменить дату при
изменении справочника, очень невелик, но вы можете дополнительно обновлять справочники с
какой-то перериодичностью, при этом лучше ориентироваться на значение параметра «expires_sec»
(см. ниже). Обычно изменения справочников таковы, что даже устаревание справочника на
несколько месяцев вряд ли будет критично для работы партнерского магазина.
Если вы хотите добиться максимальной надежности ваших программ, мы рекомендуем обновлять
справочники при каждом из этих трех событий:
1) Изменилась дата последнего обновления справочника в ответе на запрос «Различные
константы».
2) После последнего обновления справочника прошло время, указанное в параметре
«expires_sec» (указанное время не является жестким требованием, его можно изменять в
любую сторону).
3) При работе партнерского магазина получена ошибка, косвенно указывающая на то, что какойто из справочников устарел.
Рекомендации по проверке «статусов» заказов и новых писем.
Если вы храните историю оформленных заказов, вы также можете дать клиентам возможность
отслеживать «статусы» (состояния) их заказов. Это можно сделать двумя способами:
1) Пассивно: информация о заказе загружается и отображается в «личном кабинете», когда туда
заходит клиент.
2) Активно*: программное обеспечение партнерского магазина с какой-то периодичностью
проверяет, не изменилось ли состояние заказов с помощью запроса «list_orders» («Краткий
отчет об оформленных заказах»), и, обнаружив изменения, отправляет клиентам
соответствующие уведомления по электронной почте. Как и с какой периодичностью это
стоит делать (см. расшифровку «статусов» заказов в описании запроса «order_old» –
«Информация о состоянии заказа»):
a. если заказ в обработке (последний статус заказа «2», «3» или «4»), проверять его
«статус» раз в три-четыре часа (в ночные часы проверять не стоит), пока статус не
изменится на «0», «5» или «6»;
b. если последний статус заказа «5», проверять его один раз в сутки, пока статус не
изменится на «0» или «6»;
при этом необходимо запоминать день, когда статус заказа последний раз изменился на
«0» или «6»;
обратите внимание, что не имеет смысла отправлять клиентам сообщение об
изменении статуса с «5» на «6».
c. если последний статус заказа «0» или «6», проверять его максимум один раз в сутки в
течение 45 дней.
Если вы хотите обеспечить клиентам возможность переписываться с нашими операторами,
проверять наличие новых писем от наших операторов можно теми же способами (в случае
«активного» способа – с учетом статуса заказа по тому же алгоритму).
* Начиная с сентября 2013 г., мы не рекомендуем использовать описанный выше «активный» способ,
т.к. предоставляем всем клиентам, оформившим заказ в партнерском магазине, доступ к странице
заказа на сайте Интернет-магазина My-shop.ru. На этой странице клиент может проверять состояние
заказа, вносить изменения в заказ и вести переписку с операторами магазина. Кроме того, таким
клиентам отправляются SMS-уведомления о ходе выполнения заказа.
Если, вы не нашли ответ на свой вопрос, напишите нам:
http://my-shop.ru/my/helper_11
стр. 7 из 44
Общие характеристики программного интерфейса
Данный документ описывает программный интерфейс (далее – API) Интернет-магазина My-shop.ru
для партнерских магазинов, работающих в рамках партнерской программы My-shop.ru.
С использованием данного API возможно создание как самой простой витрины с приёмом «разовых»
заказов без регистрации клиентов и сохранения истории заказов, так и сложнейшего Интернетмагазина со своей системой регистрации клиентов, системой скидок, историей заказов, оповещением
клиентов об изменении состояния заказа и пр. Выполнением заказов в любом случае занимается
Интернет-магазин My-shop.ru.
Для My-shop.ru все заказы, оформленные в партнерском магазине, считаются «разовыми» заказами,
сделанными без регистрации клиентов. В связи с этим к заказам, оформленным через партнерский
магазин, применяются «разовые оптовые» скидки, но не применяются накопительные скидки.
Подробнее о скидках см. здесь:
http://my-shop.ru/my/helper_24
В качестве альтернативы накопительным скидкам партнер может предоставлять клиентам
собственные скидки за счет своего партнерского вознаграждения (подробнее см. ниже).
Через партнерский магазин невозможно оформление заказов юридических лиц и оформление
предварительных заказов (заказов, предполагающих розыск отсутствующих товаров).
Все запросы партнерского магазина к Интернет-магазину My-shop.ru должны осуществляться по
указанным ниже адресам (URL отдельно указан для каждого типа запроса – см. ниже), метод
запросов – POST. Параметры, общие для всех типов запросов, описаны в следующей таблице.
Параметры, специфичные для запросов определенных типов, описаны в соответствующих разделах
ниже.
Все запросы партнерского магазина к Интернет-магазину My-shop.ru протоколируются, однако не
отображаются в журналах обычных переходов в персональном разделе партнера.
Все ответы My-shop.ru партнерскому магазину имеют формат XML. Корневой элемент всех XMLответов – «answer», имена всех вложенных элементов соответствуют именам описанных ниже
параметров.
Если ответ представляет собой справочник (описание набора однотипных элементов), например,
справочник регионов доставки, параметры, описывающие каждый элемент, группируются внутри
элемента «item» (это относится ко всем запросам, у которых параметр «request» начинается с
префикса «list_» – см. ниже).
Обратите внимание, несмотря на то, что ответ имеет формат XML, в запросе должны быть пары «имя
параметра – значение параметра», переданные методом POST, а не XML-документ с этими
параметрами.
Кодировка – «windows-1251».
Разделитель целой и дробной части – точка.
стр. 8 из 44
Пример ответа на запрос «Информация о цене и доступности товара» (многоточие – пропущенные
параметры):
<?xml version="1.0" encoding="windows-1251"?>
<answer>
<version>1.0</version>
<datetime>2010-01-19 14:00:15</datetime>
<error>0</error>
<cost>54.00</cost>
<availability_code>2</availability_code>
…
<time_text_b>2 рабочих дня</time_text_b>
</answer>
Пример ответа на запрос «Справочник способов оплаты» (многоточие – пропущенные способы
оплаты):
<?xml version="1.0" encoding="windows-1251"?>
<answer>
<version>1.0</version>
<datetime>2010-01-19 14:00:15</datetime>
<error>0</error>
<item>
<id>0</id>
<name>наличный расчет</name>
</item>
<item>
<id>1</id>
<name>предоплата банковским переводом (Сбербанк и др.)</name>
</item>
…
</answer>
Параметры всех запросов:
Имя
Обязательный
параметра
version
ДА
partner
ДА
Формат,
Описание
допустимые
значения
число
Версия API, для работы с которой предназначено
программное обеспечение партнерского магазина.
Текущая версия API указана в разделе «Версия» (см.
выше).
О существенных обновлениях API сообщается в
рассылке «Новости партнерской программы Myshop.ru». Проверить, подписаны ли Вы на эту
рассылку, можно на этой странице:
http://my-shop.ru/my/subscriptions
См. также раздел «Проверка текущей версии API».
Поддержка старых версий API не гарантируется.
число
Идентификатор партнера.
стр. 9 из 44
Имя
параметра
Обязательный
Формат,
Описание
допустимые
значения
auth_method
ДА
«plain» или Метод аутентификации партнера:
«md5»
«plain» – в параметре «auth_code» передается
секретный код, указанный в персональном разделе
партнера;
«md5» – в параметре «auth_code» передается
MD5-хэш строки
«auth_salt;request;partner;secret_code»,
где «auth_salt», «request», «partner» – значения
одноименных параметров, передаваемых в том же
запросе, а «secret_code» – секретный код, указанный в
персональном разделе партнера.
Внимание! Значение «partner» здесь должно
указываться без ведущих нулей.
auth_salt
Только при
строка
Случайная последовательность до 8 символов (должна
аутентификации
генерироваться при каждом запросе). См. параметр
«md5»
«auth_method».
auth_code
ДА
строка
Код для аутентификации партнера. См. параметр
«auth_method».
request
ДА
строка
См. ниже.
Параметры всех ответов:
Имя
Обязательный Формат, допустимые
параметра
значения
version
ДА
число
datetime
ДА
error
ДА
дата и время в формате
YYYY-MM-DD HH:MM:SS
число
error_text
нет
строка
expires_sec
нет
число
Описание
Версия API.
Дата и время ответа на запрос. Время
московское.
Результат проверки и выполнения
запроса:
0 – нет ошибок в запросе, успешное
выполнение запроса,
другое число – код ошибки (см.
раздел «Справочник кодов ошибок»).
Текстовое описание ошибки.
Количество секунд, на которое можно
кэшировать данный ответ.
стр. 10 из 44
До оформления заказа
Корзина
Может использоваться для проверки состава заказа и отображения «Корзины» с товарами. Товары,
которых нет в наличии, в ответ не включаются (они не должны отображаться в «корзине»).
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра
допустимые
значения
request
ДА
«list_cart»
cart
ДА
Описание
строка в формате
«X1-Y1,X2Y2,…Xn-Yn»
Параметры ответа:
Имя
Обязательный Формат,
параметра
допустимые
значения
id
ДА
число
name
ДА
строка
cost
ДА
число
quantity
ДА
число
Состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие количества.
Внимание! Если в состав заказа включен хотя бы
один товар из комплекта товаров, которые не
продаются по частям, все остальные части этого
комплекта будут добавлены автоматически.
Описание
Код (идентификатор) товара в My-shop.ru.
Наименование товара. Помимо собственно названия
может включать информацию о типе товара, формате
данных, авторе произведения и т.п.
Стоимость одного экземпляра товара в рублях.
Стоимость указывается с учетом «распродажной»
скидки, если товар в распродаже и скидка
распространяется на заказываемое количество
экземпляров. Во всех остальных случаях используется
стоимость без учета «распродажной» скидки.
Количество экземпляров товара в корзине. Может быть
меньше количества, указанного в параметре «cart»,
если указанного там количества точно нет в наличии.
стр. 11 из 44
Выбор способов доставки/оплаты
Данный запрос предназначен для формирования интерфейса выбора основных параметров
доставки/оплаты заказа, аналогичного соответствующему интерфейсу в My-shop.ru (регион –>
доставка –> оплата). В запросе передается состав заказа и код региона доставки, а в ответ на запрос
возвращается список всех доступных в данном случае способов доставки и оплаты, а также
стоимость доставки данного заказа для каждого сочетания «доставка-оплата».
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра
допустимые
значения
request
ДА
«list_rdp»
cart
ДА
строка в
формате «X1Y1,X2Y2,…Xn-Yn»
region
ДА
число, 1–999
zip_code
нет
код из 6 цифр
discount
нет
целое число
Описание
«rdp» – сокращение от «region, delivery, payment».
Состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие количества.
Внимание! Если в состав заказа включен хотя бы
один товар из комплекта товаров, которые не
продаются по частям, все остальные части этого
комплекта будут добавлены автоматически.
Все остальные ошибки в составе заказа при данном
запросе также исправляются автоматически,
информации об этом не будет в ответе на запрос.
Код региона доставки.
Почтовый индекс. Используется только в случае
доставки «Почтой России». Если не указан, стоимость
почтовой доставки рассчитывается без учета
возможных сезонных транспортных ограничений
(иными словами, после указания почтового индекса
может оказаться, что стоимость почтовой доставки
выше).
См. описание одноименного параметра в запросе
«Оформление нового заказа».
Параметры ответа:
Имя
Обязательный Формат, допустимые
параметра
значения
delivery
ДА
число, 0–999999
payment
ДА
строка
sum_delivery
ДА
число
Описание
Код способа доставки.
Коды способов оплаты через
запятую.
Стоимость доставки заказа, руб.
стр. 12 из 44
Пример ответа:
<?xml version="1.0" encoding="windows-1251"?>
<answer>
<version>1.3</version>
<datetime>2010-04-26 10:31:15</datetime>
<error>0</error>
<item>
<delivery>0</delivery>
<payment>0,1,2,3,5,6</payment>
<sum_delivery>130</sum_delivery>
</item>
<item>
<delivery>1</delivery>
<payment>1,2,3,5,6</payment>
<sum_delivery>92</sum_delivery>
</item>
<item>
<delivery>1</delivery>
<payment>4</payment>
<sum_delivery>114</sum_delivery>
</item>
<item>
<delivery>2</delivery>
<payment>0,1,2,3,5,6</payment>
<sum_delivery>0</sum_delivery>
</item>
</answer>
Из этого ответа следует, что стоимость доставки данного заказа в выбранном регионе:
- курьером – 130 руб.,
- почтой – 92 руб., но при использовании наложенного платежа 114 руб.,
- самовывоз – бесплатно.
стр. 13 из 44
Предварительная проверка параметров заказа и расчет стоимости
Без указания параметров доставки и оплаты может использоваться для проверки состава заказа и
расчета стоимости «корзины», с параметрами доставки и оплаты – для расчета стоимости доставки,
формирования страницы подтверждения заказа и пр.
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра*
допустимые
значения
request
ДА
«order_pre»
Описание
cart
ДА
строка в формате
«X1-Y1,X2Y2,…Xn-Yn»
region
нет
число, 1–999
delivery
нет
число, 0–999999
Состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие количества.
Внимание! Если в состав заказа включен хотя бы
один товар из комплекта товаров, которые не
продаются по частям, все остальные части этого
комплекта будут добавлены автоматически.
Код региона доставки. В случае доставки «Почтой
России» данный параметр игнорируется.
Код способа доставки.
payment
нет
число, 0–255
Код способа оплаты.
нет
код из 6 цифр
Почтовый индекс. Используется только в случае
доставки «Почтой России», а также при выборе
любого из способов предоплаты.
discount
нет
целое число
См. описание одноименного параметра в запросе
«Оформление нового заказа».
* Имена параметров, выделенные красным – см. раздел «Права и обязанности партнера».
zip_code
Параметры ответа:
Имя
Обязательный Формат,
параметра
допустимые
значения
order_ok
ДА
«0» или «1»
Описание
Результат проверки состава заказа, параметров
доставки и оплаты. Значение «1» означает
отсутствие ошибок и наличие всех данных,
необходимых для расчета стоимости доставки –
можно переходить к завершающему этапу
оформления заказа.
стр. 14 из 44
Имя
параметра
Обязательный Формат,
допустимые
значения
нет
строка в
формате «X1Y1,X2-Y2,…XnYn»
Описание
sum_cart
ДА*
число
Исправленный состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие количества.
Данный параметр передается только при
обнаружении одной из ошибок в составе заказа:
несуществующий товар, товар снят с продажи,
товара нет в наличии, нет нужного количества.
Если при проверке состава заказа были удалены
все товары, значением параметра будет пустая
строка.
Стоимость товаров в заказе, руб.
sum_discount
ДА*
число
Скидка, руб.
sum_delivery
ДА*
число
Стоимость доставки заказа, руб.
sum_total
ДА*
число
Итоговая стоимость заказа, руб.
ДА*
число
cart_ok
Скидка, %.
Устаревший параметр: в настоящее время
соответствует скидке на заказ в условиях, когда
все товары в нём относятся к основной системе
скидок.
Не рекомендуется использовать.
Может быть удалён.
time_days
ДА*
число
Ориентировочное количество рабочих дней до
отгрузки заказа.
time_date
ДА*
дата в формате
Ориентировочная дата отгрузки заказа в формате
YYYY-MM-DD YYYY-MM-DD.
time_text_a
ДА*
строка
Строка с ориентировочной датой отгрузки заказа
следующего вида: «12.01.2010 (Вт.)».
time_text_b
ДА*
строка
Строка, описывающая ориентировочный срок
формирования заказа, следующего вида:
«2 рабочих дня» (рекомендуется использовать для
заказов с предоплатой).
* Если нет ошибок и достаточно данных для расчета значения параметра.
discount
стр. 15 из 44
Оформление нового заказа
Разрешается только после подтверждения клиентом всех параметров заказа.
URL: https://my-shop.ru/cgi-bin/p/order.pl
Параметры запроса:
Имя параметра*
Обязательный
request
ДА
Формат,
допустимые
значения
«order_new»
test
нет
«0» или «1»
cart
ДА
строка в формате
«X1-Y1,X2Y2,…Xn-Yn»
Описание
число, 1–999
delivery
ДА
(кроме доставки
«Почтой России»)
ДА
«1» или любое другое значение, отличное
от нуля или пустой строки, означает
оформление тестового заказа. Тестовый
заказ принимается в обычном режиме, но
не выполняется магазином.
Состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие
количества.
Внимание! Если в состав заказа включен
хотя бы один товар из комплекта товаров,
которые не продаются по частям, все
остальные части этого комплекта будут
добавлены автоматически.
Код региона доставки.
число, 0–999999
Код способа доставки.
payment
ДА
число, 0–255
Код способа оплаты.
zip_code
Только для
доставки «Почтой
России» и при
выборе любого из
способов
предоплаты
код из 6 цифр
Почтовый индекс.
region
стр. 16 из 44
Имя параметра*
discount
Обязательный
нет
Формат,
допустимые
значения
целое число
Описание
Величина скидки в процентах1, которую
партнер предоставляет клиенту за счет
своего партнерского вознаграждения.
Вычитается из вознаграждения партнера.
Обычно не может превышать размера
вознаграждения партнера, максимальная
величина такой скидки указана в
константе «partner_discount_max».
Для заказа клиента итоговая скидка
вычисляется как максимальная из этой
скидки и разовой оптовой скидки:
http://my-shop.ru/my/helper_24
Внимание! Если используется этот
параметр, и клиент получает оптовую
скидку, вознаграждение партнера все
равно уменьшается на указанную в
данном параметре величину.
Считается, что скидка, указанная в
запросе, относится к основной системе
скидок. Для товаров, относящихся к
другим системам скидок, величина
скидки вычисляется в соответствии с
описанием систем скидок:
http://my-shop.ru/my/helper_24
Итоговая стоимость заказа, руб. Должна
использоваться сумма, полученная на
этапе предварительной проверки
параметров заказа (сумма, которую
подтвердил клиент).
Ориентировочная дата отгрузки заказа в
формате YYYY-MM-DD. Должна
использоваться дата, полученная на этапе
предварительной проверки параметров
заказа (дата, которую подтвердил
клиент).
ФИО получателя (полностью; русскими
буквами).
Рекомендуется требовать заполнение трех
отдельных полей («Фамилия», «Имя» и
«Отчество»), хранить их также отдельно,
а в подобных запросах «склеивать» их
значения.
Адрес получателя. Без региона доставки.
Для доставки «Почтой России»: без
региона доставки, района и названия
населенного пункта (только улица/микрн, дом, корп., кв./офис).
1
sum_total
ДА
число
time_date
ДА
дата в формате
YYYY-MM-DD
name
ДА
строка, до 100
символов
Кроме сочетания
«самовывоз /
наличный расчет»
строка, до 255
символов
address
стр. 17 из 44
Имя параметра*
Обязательный
metro
Только для
доставки
«курьером Myshop.ru»
нет
address_comment
phone
ДА
Описание
текст (одна или
несколько строк)
Комментарий к адресу доставки (номера
автобусов, название остановки, номер
подъезда, код на дверях, этаж и т.п.).
Игнорируется, если выбрана не
курьерская доставка.
Контактные телефоны.
строка, до 255
символов
строка в формате
«H1-H2»
Код ближайшей станции метро.
Время, когда оператор может позвонить
по указанным телефонам, часы
(максимальный интервал: 9-21).
Примеры: «9-15», «10-21».
phone_sms
ДА
10 цифр, первая
Номер мобильного телефона для SMS– «9»
уведомлений (только телефоны РФ). В
федеральном формате, без кода страны
«7», пример: 9161112233. Прямые номера
необходимо указывать с федеральным
кодом: московские абоненты Билайн
имеют федеральный аналог своего номера
с кодом 903, московские абоненты МТС с кодом 985, московские абоненты
МегаФон - с кодом 925.
SMS-уведомления служат исключительно
для оповещения покупателей о ходе
выполнения их заказов (заказ принят,
заказ передан "Почте России", заказ
поступил в пункт выдачи и т.п.) и
отправляются за счет Интернет-магазина
My-shop.ru.
pin
нет
«0» или целое
Значение этого параметра никак не
положительное
используется магазином, но сохраняется
число, до 19
и возвращается в каждом ответе на запрос
цифр
«Информация о состоянии заказа».
Может использоваться партнером для
передачи собственного номера заказа,
собственного кода клиента или кода
«субпартнера».
* Имена параметров, выделенные красным – см. раздел «Права и обязанности партнера».
phone_time
Параметры ответа:
Имя параметра
ДА
Формат,
допустимые
значения
число, 1–255
Обязательный
Формат,
допустимые
значения
Описание
стр. 18 из 44
Имя параметра
cart_ok
нет
Формат,
допустимые
значения
строка в
формате «X1Y1,X2-Y2,…XnYn»
sum_cart
ДА*
число
Исправленный состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие
количества.
Данный параметр передается только при
обнаружении одной из ошибок в составе
заказа: несуществующий товар, товар снят
с продажи, товара нет в наличии, нет
нужного количества.
Если при проверке состава заказа были
удалены все товары, значением параметра
будет пустая строка.
Стоимость товаров в заказе, руб.
sum_discount
ДА*
число
Скидка, руб.
sum_delivery
ДА*
число
Стоимость доставки заказа, руб.
sum_total
ДА*
число
Итоговая стоимость заказа, руб.
discount
ДА*
число
time_days
ДА*
число
time_date
ДА*
time_text_a
ДА*
дата в формате
YYYY-MM-DD
строка
time_text_b
ДА*
строка
id
ДА*
число
Скидка, %.
Устаревший параметр: в настоящее время
соответствует скидке на заказ в условиях,
когда все товары в нём относятся к
основной системе скидок.
Не рекомендуется использовать.
Может быть удалён.
Ориентировочное количество рабочих дней
до отгрузки заказа.
Ориентировочная дата отгрузки заказа в
формате YYYY-MM-DD.
Строка с ориентировочной датой отгрузки
заказа следующего вида: «12.01.2010
(Вт.)».
Строка, описывающая ориентировочный
срок формирования заказа, следующего
вида:
«2 рабочих дня» (рекомендуется
использовать для заказов с предоплатой).
Номер заказа.
Только для
заказов с
предоплатой
нет
строка
url_payment_form
info_1
Обязательный
текст (одна или
несколько
строк)
Описание
URL страницы с платежной формой или
заполненной счет-квитанцией для оплаты
заказа в банке или на почте.
Дополнительная информация, которая
обязательно должна быть передана
клиенту.
Перед выводом на HTML-страницу
необходимо заменять символы новой
строки на «<br>», а также превращать
URL-ы в гиперссылки.
стр. 19 из 44
Имя параметра
info_2
Обязательный
нет
Формат,
допустимые
значения
текст (одна или
несколько
строк)
Описание
Дополнительная информация, которую
рекомендуется передать клиенту.
Перед выводом на HTML-страницу
необходимо заменять символы новой
строки на «<br>», а также превращать
URL-ы в гиперссылки.
* Если нет ошибок.
стр. 20 из 44
После оформления заказа
Информация о состоянии заказа
Позволяет получить информацию только о заказах, оформленных через данный API и только
партнером с идентификатором, указанным в параметре «partner».
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра
допустимые
значения
request
ДА
«order_old»
Описание
id
ДА
число
Номер заказа.
light
нет
«0» или «1»
Значение «0» – режим по умолчанию, значение «1» –
«лайт-режим», позволяющий уменьшить нагрузку и
ускорить отправку ответа. При использовании лайтрежима в ответе не будет параметров «cart» и «rpo», а
также может быть сокращено значение параметров
«info_1» и «info_2».
Внимание! Если ваше программное обеспечение не
использует значения «cart» и «rpo», мы настоятельно
рекомендуем использовать лайт-режим.
Параметры ответа:
Имя параметра
order_datetime
Обязательный
ДА
Описание
Дата и время оформления заказа. Время
московское.
sum_cart
ДА
число
Состав заказа:
X1, X2…Xn – идентификаторы товаров,
Y1, Y2…Yn – соответствующие
заказанные количества,
Z1, Z2… Zn – соответствующие
зарезервированные количества
(актуально только для заказов «в
обработке»),
C1, C2… Cn – стоимость
соответствующих товаров в данном
заказе (фиксируется в момент
оформления заказа).
Если сумма Y1, Y2…Yn равна сумме
Z1, Z2… Zn, заказ сформирован.
Стоимость товаров в заказе, руб.
sum_discount
ДА
число
Скидка, руб.
cart
ДА
(кроме лайтрежима – см.
выше)
Формат,
допустимые
значения
дата и время в
формате YYYYMM-DD
HH:MM:SS
строка в формате
«X1-Y1-Z1C1,X2-Y2-Z2C2,…Xn-Yn-ZnCn»
стр. 21 из 44
Имя параметра
sum_delivery
ДА
Формат,
допустимые
значения
число
sum_total
ДА
число
Итоговая стоимость заказа, руб.
discount
ДА
число
delivery
ДА
число, 0–999999
Скидка, %.
Устаревший параметр: в настоящее
время соответствует скидке на заказ в
условиях, когда все товары в нём
относятся к основной системе скидок.
Не рекомендуется использовать.
Может быть удалён.
Код способа доставки.
payment
ДА
число, 0–255
Код способа оплаты.
status
ДА
число, 0–9
status_text
ДА
строка
Код текущего состояния заказа:
0 – заказ аннулирован,
2 – ожидание предоплаты,
3 – комплектуется, ожидает отправки
или находится в пункте выдачи,
4 – заблокирован в ожидании ответа
клиента,
5 – отправлен, но не оплачен (только
для наложенного платежа),
6 – отправлен и оплачен.
Строка с описанием состояния заказа.
Помимо состояния заказа может
содержать дополнительную
информацию о формировании заказа,
согласовании доставки, причине
аннулирования и пр.
Код причины аннулирования заказа:
1 – тестовый заказ (тестирование или
чья-то неудачная шутка),
2 – аннулирован по просьбе клиента,
3 – закончился товар (клиент отказался
от оставшихся товаров),
4 – почтовый возврат (отказ клиента
или ошибка Почты России),
5 – объединен с другим заказом
клиента,
6 – истек срок ожидания товара для
предварительного заказа,
7 – истек срок ожидания предоплаты,
8 – истек срок ожидания ответа
клиента,
9 – невозможно выполнить пожелание
клиента,
10 – истек срок ожидания наложенного
платежа (вероятно, ошибка Почты
России).
status_0_cause
Обязательный
Только для
аннулированных
заказов
число, 1–99
Описание
Стоимость доставки заказа, руб.
стр. 22 из 44
Имя параметра
url_payment_form
assembled
shipment_date
Обязательный
Только для заказов
в состоянии
ожидания
предоплаты
Только для заказов
«в обработке»
Только для
отправленных
заказов
ДА
(кроме лайтрежима – см.
выше)
Формат,
допустимые
значения
строка
Описание
«0» или «1»
Признак сборки заказа (не путать с
формированием заказа – заказ может
быть сформирован (укомплектован), но
еще не собран):
0 – заказ не собран,
1 – заказ собран.
Дата отгрузки заказа или его передачи в
транспортную компанию.
дата в формате
YYYY-MM-DD
URL страницы с платежной формой или
заполненной счет-квитанцией для
оплаты заказа в банке или на почте.
Список идентификаторов РПО
(регистрируемых почтовых
отправлений – посылок и бандеролей)
через запятую. Идентификаторы РПО
присваиваются в течение нескольких
часов после изменения кода состояния
заказа на «5» или «6». Параметр
используется только для заказов с
почтовой доставкой.
info_1
нет
текст (одна или
Дополнительная информация, которая
несколько строк) обязательно должна быть передана
клиенту, если это возможно.
Перед выводом на HTML-страницу
необходимо заменять символы новой
строки на «<br>», а также превращать
URL-ы в гиперссылки.
info_2
нет
текст (одна или
Дополнительная информация, которую
несколько строк) рекомендуется передать клиенту, если
это возможно.
Перед выводом на HTML-страницу
необходимо заменять символы новой
строки на «<br>», а также превращать
URL-ы в гиперссылки.
pin
нет
число
Значение одноименного параметра,
указанное при оформлении заказа.
Подробнее см. в описании запроса
«Оформление нового заказа».
Для заказов с предоплатой, находящихся «в обработке»: понять, поступил ли платеж, можно по коду
состояния заказа: 2 – платеж не поступил или еще не обработан, 3 – платеж поступил.
rpo
строка в формате
«N1,N2,…Nn»
стр. 23 из 44
Аннулирование заказа
Позволяет аннулировать только заказы, оформленные через данный API, и только партнером с
идентификатором, указанным в параметре «partner». Также невозможно аннулировать следующие
заказы:
 Отправленные.
 Оплаченные (заказы с предоплатой).
 Заказы с курьерской доставкой, доставка которых уже согласована.
 Заказы, заблокированные в ожидании уточнения каких-то параметров (в этом случае с
клиентом свяжется сотрудник магазина).
URL: https://my-shop.ru/cgi-bin/p/order.pl
Параметры запроса:
Имя
Обязательный Формат, допустимые
параметра
значения
request
ДА
«order_cancel»
Описание
id
ДА
число
Номер заказа.
cause
ДА
«1» или «2»
Код причины аннулирования
заказа:
1 – тестовый заказ,
2 – аннулирован по просьбе
клиента.
Параметры ответа:
См. общие параметры ответа. Если значение параметра «error» равно нулю, заказ успешно
аннулирован.
стр. 24 из 44
Переписка клиента с операторами My-shop.ru: новое сообщение клиента
В сочетании со следующим запросом («Переписка клиента с операторами My-shop.ru: список
сообщений») позволяет реализовать переписку клиента с операторами My-shop.ru на странице заказа
в партнерском магазине. Имеет смысл, когда в партнерском магазине используется регистрация
клиента и хранится история заказов. Подробнее см. в описании следующего запроса.
URL: https://my-shop.ru/cgi-bin/p/order.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«message_new»
id
ДА
число
Номер заказа.
text
ДА
текст
Текст сообщения клиента.
Параметры ответа:
Имя
Обязательный Формат, допустимые
параметра
значения
message_id
ДА
число
Описание
Идентификатор сохраненного
сообщения.
стр. 25 из 44
Переписка клиента с операторами My-shop.ru: список сообщений
В сочетании с предыдущим запросом («Переписка клиента с операторами My-shop.ru: новое
сообщение клиента») позволяет реализовать переписку клиента с операторами My-shop.ru на
странице заказа в партнерском магазине. Имеет смысл, когда в партнерском магазине используется
регистрация клиента и хранится история заказов.
Данный запрос позволяет получить полный архив переписки по конкретному заказу (список
сообщений клиента и операторов My-shop.ru), либо только последние ответы операторов My-shop.ru
(подробнее см. ниже). Рекомендуется отображать список сообщений так же, как это делается на
страницах заказов в My-shop.ru – самые последние сообщения сверху (сортировка по
идентификаторам сообщений по убыванию).
Новые сообщения операторов могут появляться не только в ответ на сообщения клиента. Если
оператору не удается связаться с клиентом, он может сохранить какое-то сообщение просто в
надежде, что клиент увидит его в партнерском магазине.
В партнерском магазине могут использоваться различные варианты оповещения клиентов о новых
сообщениях:
1) Пассивное – список сообщений загружается и отображается на страницах партнерского
магазина, когда туда заходит клиент.
2) Активное – программное обеспечение партнерского магазина с какой-то периодичностью (см.
наши рекомендации в разделе «Популярные вопросы. Рекомендации My-shop.ru») проверяет,
не появилось ли новых сообщений, а при появлении новых сообщений пересылает их по
электронной почте клиентам.
Начиная с сентября 2013 г., мы не рекомендуем использовать подобный способ оповещения,
т.к. предоставляем всем клиентам, оформившим заказ в партнерском магазине, доступ к
странице заказа на сайте Интернет-магазина My-shop.ru. На этой странице клиент может
проверять состояние заказа, вносить изменения в заказ и вести переписку с операторами
магазина. Кроме того, таким клиентам отправляются SMS-уведомления о ходе выполнения
заказа.
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра
допустимые
значения
request
ДА
«list_messages»
Описание
id
ДА
число
Номер заказа.
light
нет
«0» или «1»
Значение «0» – режим по умолчанию, при котором
в ответ включаются все сообщения клиента и
операторов My-shop.ru, относящиеся к этому
заказу.
Значение «1» – «лайт-режим», при использовании
которого в ответ включаются только сообщения
операторов My-shop.ru, добавленные после
последнего сообщения клиента (последние ответы).
стр. 26 из 44
Параметры ответа:
Имя параметра
Обязательный Формат, допустимые
значения
message_id
ДА
число
message_datetime
ДА
operator_id
ДА
дата и время в
формате YYYY-MMDD HH:MM:SS
число
text
ДА
текст
Описание
Идентификатор сообщения.
Дата и время сообщения. Время
московское.
Идентификатор оператора, добавившего
сообщение. Значение «0» означает, что
сообщение добавлено клиентом.
Текст сообщения.
стр. 27 из 44
Краткий отчет об оформленных заказах
Позволяет получить информацию обо всех заказах, оформленных с участием партнера,
идентификатор которого указан в параметре «partner» (не только о заказах, оформленных через
данный API).
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра
допустимые
значения
request
ДА
«list_orders»
filter
ДА
fee
нет
см. описание Допустимые форматы:
 NNN – номер заказа (пример: "123456");
 KKK,MMM,NNN… – список номеров заказов через
запятую без пробелов (пример: "123456,123459");
 KKK-NNN – диапазон номеров заказов (пример:
"123456-123470"), в качестве разделителя
допускается только символ «-» (минус), без
пробелов;
 KKK- – все заказы, номера которых больше или
равны KKK (пример: "123456-");
 -MMM – все заказы, номера которых меньше или
равны MMM (пример: "-123456");
 YYYY-MM – месяц оформления заказов (пример:
"2010-03");
 YYYY-MM-DD – дата оформления заказов (пример:
"2010-03-23");
 YYYY-MM-DD-YYYY-MM-DD – диапазон дат
оформления заказов (пример: "2010-03-18-2010-0323");
 YYYY-MM-DD HH:MM-SS-YYYY-MM-DD
HH:MM-SS – диапазон дат оформления заказов с
указанием времени (пример: "2010-03-18 01:00:002010-03-23 13:30:00").
«0», «1» или «0» (по умолчанию) – без вычисления размера
«2»
партнёрского вознаграждения (работает быстрее);
«1» – включать в ответ одноименные параметры с
суммой вознаграждения за каждый заказ, находящийся
в состоянии «отправлен и оплачен» (начисленное
вознаграждение); для остальных заказов будет указано
нулевое вознаграждение;
«2» – то же, но для всех заказов, независимо от их
состояния.
Параметры ответа:
Имя
Обязательный
параметра
id
Описание
ДА
Формат,
допустимые
значения
число
Описание
Номер заказа.
стр. 28 из 44
Имя
параметра
Обязательный
order_datetime
ДА
sum_cart
ДА
Формат,
допустимые
значения
дата и время в
формате YYYYMM-DD
HH:MM:SS
число
sum_discount
ДА
число
Скидка, руб.
discount
ДА
число
status
ДА
число, 0–9
Скидка, %.
Устаревший параметр: в настоящее время
соответствует скидке на заказ в условиях,
когда все товары в нём относятся к
основной системе скидок.
Не рекомендуется использовать.
Может быть удалён.
Код текущего состояния заказа:
0 – заказ аннулирован,
2 – ожидание предоплаты,
3 – комплектуется, ожидает отправки или
находится в пункте выдачи,
4 – заблокирован в ожидании ответа
клиента,
5 – отправлен, но не оплачен (только для
наложенного платежа),
6 – отправлен и оплачен.
Код причины аннулирования заказа:
1 – тестовый заказ (тестирование или чья-то
неудачная шутка),
2 – аннулирован по просьбе клиента,
3 – закончился товар (клиент отказался от
оставшихся товаров),
4 – почтовый возврат (отказ клиента или
ошибка Почты России),
5 – объединен с другим заказом клиента,
6 – истек срок ожидания товара для
предварительного заказа,
7 – истек срок ожидания предоплаты,
8 – истек срок ожидания ответа клиента,
9 – невозможно выполнить пожелание
клиента,
10 – истек срок ожидания наложенного
платежа (вероятно, ошибка Почты России).
Код товара, на который был осуществлен
переход по прямой ссылке (этого товара
может не быть в составе заказа).
status_0_cause
Только для
число, 1–99
аннулированных
заказов
product_id
Только в случае
оформления
заказа после
перехода по
прямой ссылке
нет
pin
число
число
Описание
Дата и время оформления заказа. Время
московское.
Стоимость товаров в заказе, руб.
Значение одноименного параметра,
указанное при оформлении заказа.
Подробнее см. в описании запроса
«Оформление нового заказа».
стр. 29 из 44
Имя
параметра
fee
Обязательный
Формат,
допустимые
значения
В соответствии с число
запросом (см.
выше)
Описание
Сумма партнёрского вознаграждения за
заказ, руб.
стр. 30 из 44
Справочная информация
Проверка текущей версии API
Такую проверку имеет смысл делать раз в сутки в автоматическом режиме. При увеличении номера
версии API ваша программа может, например, оповестить ваших программистов по электронной
почте или с помощью SMS-рассылки.
Изменение целой части числа в номере версии означает существенное изменение API, при котором
рекомендуется как можно быстрее ознакомиться с полным списком изменений (в актуальной версии
данного документа) и внести необходимые изменения в программное обеспечение партнерского
магазина.
Изменение дробной части числа в номере версии означает несущественное изменение API или
добавление новых функций, которые не должны сказаться на работе приложений, адаптированных
для работы с предыдущей версией API.
О существенных обновлениях API сообщается в рассылке «Новости партнерской программы Myshop.ru». Проверить, подписаны ли Вы на эту рассылку, можно на этой странице:
http://my-shop.ru/my/subscriptions
Разработчики API прилагают усилия для поддержания устаревших версий API в течение времени,
необходимого для обновления программного обеспечения партнерских магазинов, однако такая
поддержка не гарантируется.
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«version»
Параметры ответа:
Имя параметра Обязательный Формат,
допустимые
значения
version
ДА
число
Описание
Версия API.
дата в формате
Дата последнего изменения целой части
YYYY-MM-DD
числа в номере версии API.
last_modified_2
ДА
дата в формате
Дата последнего изменения API (изменения
YYYY-MM-DD
дробной части числа в номере версии API).
Эти параметры также передаются в ответе на запрос «Различные константы» (см. ниже).
last_modified_1
ДА
стр. 31 из 44
Различные константы
Если ваши программы используют перечисленные ниже параметры, имеет смысл проверять их раз в
сутки в автоматическом режиме.
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«const»
Параметры ответа:
Имя параметра
phone
Обязательный Формат,
допустимые
значения
ДА
строка
email
ДА
строка
payment_forward_limit
ДА
число
payment_forward_extra
ДА
число
partner_discount_max
ДА
число
url_company
ДА
строка
url_address
ДА
строка
url_schedule
ДА
строка
conditions
ДА
текст
Описание
Телефонные номера, по которым
покупатель может связаться с
клиентской службой My-shop.ru.
E-mail клиентской службы.
Внимание! Публикация адреса
электронной почты на страницах,
которые могут быть доступны не
только конкретному покупателю
(могут быть «просканированы» извне),
категорически запрещена!
Максимальная стоимость товаров в
заказе (с учетом скидки, если она есть),
который может быть отправлен
наложенным платежом, руб.
«0» – ограничений нет.
Наценка на стоимость заказа при
использовании наложенного платежа,
%. Данная наценка рассчитывается как
процент от итоговой стоимости заказа
(с учетом скидки и стоимости
доставки) и прибавляется к стоимости
доставки заказа.
Максимальная величина скидки (в
процентах), которую партнер может
предоставить клиенту.
URL страницы с информацией о
продавце.
URL страницы с адресом пункта
выдачи заказов и схемой проезда.
URL страницы с графиком работы
магазина.
Условия, согласие с которыми должен
подтвердить покупатель,
оформляющий заказ на сайте партнера.
стр. 32 из 44
Имя параметра
last_modified_list_regions*
last_modified_list_delivery*
last_modified_list_payment
last_modified_list_metro
last_modified_list_zip_code
Обязательный Формат,
допустимые
значения
ДА
дата в
формате
YYYY-MMDD
Описание
Дата последнего изменения
соответствующего справочника.
last_modified_list_zip_code_limitation
last_modified_list_errors
version
last_modified_1
См. раздел «Проверка текущей версии API».
last_modified_2
В ответе могут быть и другие параметры, они являются служебными.
* В параметрах «last_modified_list_regions» и «last_modified_list_delivery» всегда возвращается
текущая дата. Эти параметры больше не используются (начиная с версии 1.9), текущая дата в
значениях этих параметров возвращается для совместимости с предыдущими версиями.
стр. 33 из 44
Информация о цене и доступности товара
Если вашим программам приходится делать очень большое количество таких запросов,
воспользуйтесь прайсом в формате CSV, подробнее см. здесь:
http://my-shop.ru/my/helper_89
Для отображения «корзины» с товарами вместо таких запросов рекомендуется использовать запрос
«Корзина».
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя
Обязательный Формат, допустимые
параметра
значения
request
ДА
«product»
id
ДА
число
Параметры ответа:
Имя параметра
Обязательный
cost
ДА
Формат,
допустимые
значения
число
availability_code
ДА
число, 0–3
ds
ДА
число
limit
нет
число
Только для
товаров в
распродаже
Только для
товаров в
распродаже
число
sale_percent
sale_cost
число
Описание
Код (идентификатор) товара в Myshop.ru.
Описание
Стоимость товара в рублях. Параметр
«sale_cost», если он определен, имеет
приоритет над данным параметром.
Код доступности товара:
0 – нет в наличии, заказы не принимаются,
1 – нет в наличии, но принимаются
«предварительные» заказы,
2 – есть в наличии (на складе My-shop.ru или на
складах поставщиков My-shop.ru),
3 – есть в наличии (на складе My-shop.ru или на
складах поставщиков My-shop.ru) и может быть
отгружен очень быстро (в течение нескольких
рабочих часов).
Код системы скидок. Подробнее:
http://my-shop.ru/my/helper_24
Максимальное количество свободных
экземпляров товара (которые можно заказать).
Внимание! В большинстве случаев значение
данного параметра не определенно, однако это
не означает, что в наличии есть большое
количество. Неопределенное значение
необходимо интерпретировать как отсутствие
информации о количестве свободных
экземпляров товара.
Распродажная скидка, %.
Стоимость товара с учетом распродажной
скидки, руб.
стр. 34 из 44
Имя параметра
Обязательный
sale_limit
Только для
товаров в
распродаже
time_days
Только для
товаров,
имеющихся в
наличии
Только для
товаров,
имеющихся в
наличии
time_text_a
Формат,
допустимые
значения
число
число
строка
Описание
Количество экземпляров товара в распродаже
(максимальное количество экземпляров товара,
которое можно приобрести с распродажной
скидкой). При заказе большего количества
стоимость всех заказанных экземпляров
рассчитывается без учета распродажной
скидки.
Ориентировочное количество рабочих дней до
отгрузки товара (при условии оформления
заказа в этот момент).
Строка с ориентировочной датой отгрузки
товара (при условии оформления заказа в этот
момент) следующего вида: «12.01.2010 (Вт.)».
стр. 35 из 44
Справочник регионов доставки
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_regions»
Параметры ответа:
Имя
Обязательный Формат,
параметра
допустимые
значения
id
ДА
число, 1–999
name
ДА
строка, до 75
символов
число, 1–999
country_id
ДА
delivery_0
delivery_1
…
delivery_n
ДА
число,
1–65535
delivery_0_free
нет
число,
1–65535
Описание
Код региона.
Название региона.
Код страны. В других запросах код страны не
используется, в данный справочник включается
только для того, чтобы можно было отличить
российский регион (код страны – «1») от региона с
названием другой страны. Использовать в
пользовательских интерфейсах список, в котором
перемешаны российские регионы и другие страны,
не рекомендуется!
Допустимый способ доставки. Число в имени
параметра после «delivery_» – код способа
доставки. Значение параметра – стоимость доставки
в рублях (для курьерской доставки My-shop.ru) или
номер тарифной зоны (для остальных способов
доставки). Указываются только допустимые для
данного региона способы доставки, т.е. наличие
параметра «delivery_k» означает возможность
использования способа доставки с кодом k в
данном регионе.
Минимальная сумма (стоимость товаров в заказе за
вычетом скидки, если она есть) для бесплатной
курьерской доставки (только для способа доставки
с кодом «0» – доставка собственной курьерской
службой в Москве и Подмосковье), руб.
стр. 36 из 44
Справочник способов доставки
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_delivery»
Параметры ответа:
Имя параметра
Обязательный
Формат,
допустимые
значения
число, 0–9999
Описание
Название способа доставки.
id
ДА
name
ДА
payment
ДА
строка, до 50
символов
строка, до 255
символов, пример:
«4,1,2,3,5,6,7»
info
нет
текст
info_importance
Только при
наличии
параметра «info»
число, 1-3
Код способа доставки.
Список кодов способов оплаты (через
запятую), допустимых при данном способе
доставки. Первым указывается самый
популярный для данного способа доставки
способ оплаты (способ оплаты по
умолчанию).
Текст, содержащий дополнительную
информацию о способе доставки (может
содержать простой HTML-код:
гиперссылки на страницы сайтов
транспортных компаний, « », «<br>»
и т.п.).
Важность информации в параметре «info»:
1 – просто дополнительная информация,
отображение рекомендуется, но
необязательно;
2 – отображение обязательно;
3 – отображение обязательно, очень важно.
стр. 37 из 44
Справочник способов оплаты
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_payment»
Параметры ответа:
Имя параметра Обязательный Формат, допустимые значения Описание
id
ДА
число, 0–255
Код способа оплаты.
name
ДА
строка, до 255 символов
Название способа оплаты.
стр. 38 из 44
Справочник станций метро
Только для курьерской доставки по Москве.
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_metro»
Параметры ответа:
Имя
Обязательный Формат, допустимые значения
параметра
id
ДА
число, 1–255
station
ДА
строка, до 50 символов
line
ДА
строка, до 50 символов
rgb
ДА
строка, 6 HEX-символов, пример:
«9CB5FF»
Описание
Код станции метро.
Название станции
метро.
Название линии метро.
RGB-цвет линии метро.
стр. 39 из 44
Справочник почтовых индексов
Используется только для доставки «Почтой России», а также при выборе любого из способов
предоплаты.
Источник данных – сайт «Почты Росси»: http://info.russianpost.ru/database/ops.html
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_zip_code»
Параметры ответа:
Имя
Обязательный Формат, допустимые
параметра
значения
zip_code
ДА
код из 6 цифр
region
ДА
autonom
нет
area
нет
city
ДА
строка, до 255
символов
строка, до 255
символов
строка, до 255
символов
строка, до 255
символов
Описание
Индекс (код) отделения почтовой связи
(ОПС).
Наименование области, края, республики, в
которой находится ОПС.
Наименование автономной области, в
которой находится ОПС.
Наименование района, в котором находится
ОПС.
Наименование населенного пункта, в
котором находится ОПС.
стр. 40 из 44
Справочник ограничений на пересылку
Используется только для доставки «Почтой России».
Источник данных – сайт «Почты Росси»: http://info.russianpost.ru/database/dlimits.html
В My-shop.ru указанные ограничения начинают применяться за 7 дней до дат, указанных в
справочнике.
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_zip_code_limitation»
Параметры ответа:
Имя
Обязательный Формат,
параметра
допустимые
значения
zip_code
ДА
код из 6 цифр
date_1
ДА
2000-MM-DD
date_2
ДА
2000-MM-DD
type
ДА
«0» или «1»
Описание
Индекс (код) отделения почтовой связи (ОПС).
Дата начала действия ограничения по приему
посылок и бандеролей (приведена к високосному
2000-му году).
Дата окончания действия ограничения по приему
посылок и бандеролей (приведена к високосному
2000-му году).
Тип ограничения: 0 – доставка запрещена, 1 –
обязательна доставка авиапочтой (увеличивает
стоимость доставки).
стр. 41 из 44
Справочник кодов ошибок
URL: https://my-shop.ru/cgi-bin/p/info.pl
Параметры запроса:
Имя параметра Обязательный Формат, допустимые значения Описание
request
ДА
«list_errors»
Параметры ответа:
Имя
Обязательный Формат, допустимые
параметра
значения
error_code
ДА
число
error_text
ДА
строка
Описание
Код ошибки, возвращаемый данным API в
параметре «error».
Текстовое описание ошибки.
Ошибки, коды которых начинаются с «1», касаются общих параметров запроса. Клиентам такие
ошибки не стоит показывать ни при каких обстоятельствах!
Ошибки, коды которых начинаются с «2», касаются состава заказа.
Ошибки, коды которых начинаются с «3», касаются основных параметров доставки и оплаты заказа.
Ошибки, коды которых начинаются с «4» – прочие ошибки, специфичные для конкретных типов
запросов.
стр. 42 из 44
Прочие запросы
Поиск товаров
Возвращает список id найденных товаров, отсортированных по соответствию запросу.
URL: https://my-shop.ru/cgi-bin/p/search.pl
Параметры запроса:
Имя
Обязательный Формат,
параметра
допустимые
значения
request
ДА
«list_search»
search
ДА
строка
availability
нет
«0», «1» или
«2»
sale
нет
«1»
catalogue_id
нет
число
__page
нет
число
__onpage
нет
число
Описание
Строка поискового запроса.
Поиск осуществляется по названиям товаров, по
фамилиям авторов, составителей и редакторов книг,
а также по кодам ISBN, EAN и артикулам товаров
(некоторые артикулы могут не учитываться в
поиске).
Значение фильтра по наличию товаров:
«0» – все товары;
«1» – только товары, которые есть в наличии +
товары «под заказ» (по умолчанию);
«2» – только товары, которые есть в наличии.
Признак того, что поиск нужно осуществлять только
среди товаров в распродаже.
Идентификатор раздела каталога, в котором нужно
осуществлять поиск.
Номер отображаемой страницы результатов (по
умолчанию – «1»).
Количество отображаемых результатов (по
умолчанию – «25»).
Параметры ответа (для каждого элемента «item»):
Имя
Обязательный Формат,
параметра
допустимые
значения
id
ДА
число
i
ДА
число
Описание
Код (идентификатор) товара в My-shop.ru.
Порядковый номер товара в результатах поиска,
отсортированных по соответствию запросу.
Дополнительные параметры ответа (не относящиеся к элементам «item»):
Имя
Обязательный Формат,
Описание
параметра
допустимые
значения
results
ДА
число
Количество найденных товаров (3000 –
искусственное ограничение количества результатов).
стр. 43 из 44
Имя
параметра
corrected
Обязательный Формат,
допустимые
значения
нет
строка
Описание
Исправленная строка запроса (только для случаев,
когда поиск по исходной строке запроса не дал
результатов, а поиск по исправленной строке
оказался результативным).
стр. 44 из 44