Модуль интеграции с сервисом «Покупка на Яндекс.Маркет» для HostCMS v.6

20 января 2015 года

Данный модуль реализует интеграцию интернет-магазина (далее Магазин) под управлением HostCMS v.6 с сервисом «Покупка на Яндекс.Маркет» (далее Маркет).

Модуль позволяет пользователям Яндекс.Маркета оформлять заказы в вашем интернет-магазине прямо со страниц Маркета, без перехода на ваш сайт, на те товары, которые вы размещаете на Маркете средствами стандартного экспорта товаров в него.

Модуль находится в стадии бета-тестирования, о начале продаже будет дополнительный анонс на официальном форуме HostCMS.

Модуль предоставляет базовый функционал взаимодействия между Магазином и Маркетом, описанный здесь https://tech.yandex.ru/market/partner/doc/dg/reference/purchase-methods-docpage/, с учетом способов авторизации запросов, описанных в документах https://tech.yandex.ru/market/partner/doc/dg/concepts/identification-docpage/ (запросы от Яндекс.Маркета) и https://tech.yandex.ru/market/partner/doc/dg/concepts/authorization-docpage/ (запросы от Магазина).

Заказы, оформленные через Модуль интеграции с сервисом «Покупка на Яндекс.Маркет», попадают в общий список заказов вашего магазина, и имеют такой же набор полей и свойств, как и обычные заказы, оформленные через корзину на вашем сайте. Вместе с тем, для заказов, оформленных через Яндекс.Маркет введен ряд ограничений на действия, совершаемые в списке заказов и в карточке заказа, из-за технических ограничений протокола взаимодействия между Магазином и Маркетом. (Подробнее об этих ограничениях вы можете прочитать ниже.)

Текущая версия модуля основана на API Яндекс.Маркет версии 2.4 от 11 февраля 2014 года, и реализует только минимальный набор функционала, необходимый для принятия заказов и их обработки. Изменение способа доставки заказа, после его оформления, по инициативе Магазина пока не возможно, и будет реализовано позднее.

Настоящая документация является неотъемлемой частью дистрибутива Модуля, и должна распространяться в составе дистрибутива в обязательном порядке и в полном объеме.

Условия и требования, предъявляемые к магазину

Для подключения к сервису «Покупка на Яндекс.Маркет» магазин должен отвечать следующим требованиям, предъявляемые со стороны Яндекс.Маркета

  • Тип магазина — интернет-магазин (У магазина должен быть собственный сайт с описанием товаров и формой заказа);
  • Магазин должен быть подключен к Яндекс.Маркету и передавать прайс-лист в формате YML;
  • Рейтинг магазина — 3 звезды и более;
  • Продолжительность размещения магазина на Яндекс.Маркете до подключения к программе — не менее 90 суток;
  • Заключение договора между Магазином и Яндексом об участии в программе.

Более полное и актуальное описание условий и требований, предъявляемых к магазину со стороны Маркета для участия в данной программе вы можете получить в официальном разделе помощи Яндекса — http://help.yandex.ru/partnermarket/purchase/about.xml

Кроме того, для магазинов, работающих под управлением HostCMS важно выполнение следующих специфичных условий:

  • В настройках интернет-магазина должно быть включено резервирование товаров;
  • Количество товара на складах, указанное в карточке товара, должно соответствовать реальному количеству товара, доступному для заказа. В противном случае, покупатель не сможет оформить заказ;
  • В условиях доставки, для тех способов доставки, которые вы предлагаете на Маркете, должна быть описана стоимость доставки во все регионы, доставку в которые вы предлагаете. В противном случае, покупатель не сможет оформить заказ. Стоимость доставки может быть как задана набором правил, так и вычисляться динамически с помощью запросов к api-сервисам различных служб доставки.

Порядок подключения к сервису «Покупка на Яндекс.Маркет»

Общий порядок подключения к программе описан в документе http://help.yandex.ru/partnermarket/purchase/how-to-start.xml

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

  1. Убедитесь, что ваш магазин соответствует приведенным выше условиям;
  2. Приобретите данный модуль, и установите его на ваш экземпляр системы HostCMS, как описано ниже;
  3. Настройте для вашего магазина интеграцию с сервисом «Покупка на Яндекс.Маркет», согласно инструкции, приведенной ниже;
  4. Проверьте взаимодействие вашего магазина с Яндекс.Маркетом с помощью инструмента «Отладка API покупки» в личном кабинете Маркета;
  5. Заключите договор с Яндекс.Маркетом и переключите сервис «Покупка на Яндекс.Маркет» в боевой режим (чтобы избежать бюрократических задержек, вы можете начать оформление договора одновременно с покупкой модуля)
  6. Принимайте заказы через Яндекс.Маркет и получайте прибыль! :)

Системные требования

  • Система управления сайтом HostCMS v6.1.7 и выше;
  • На сервере должен быть установлен интерпретатор php версии 5.2.2 и выше, собранный с поддержкой OpenSSL (в результатах phpinfo() в строке «Registered Stream Socket Transports» должно присутствовать хотя бы одно из значений ssl / sslv2 / sslv3);
  • Вы должны иметь доступ к настройками вашего веб-сервера, с возможностью настроить доступ к страницам вашего сайта по протоколу https.

Важно! Если ваша версия системы HostCMS ниже чем 6.1.8, то перед установкой модуля, вам необходимо скачать дистрибутив бесплатной редакции с официального сайта системы http://hostcms.ru/hostcms/editions/free/ и из скачанного дистрибутива взять и заменить в вашей системе следующие файлы:

  • modules/core/http.php
  • modules/core/http/curl.php
  • modules/core/http/socket.php
  • modules/core/request.php

Лицензионная политика

Модуль интеграции с сервисом «Покупка на Яндекс.Маркет» предназначен для коммерческой реализации заказчикам сайтов, веб-студиям, интеграторам и прочим третьим лицам (далее — Покупатели).

Реализацию модуля могут осуществлять разработчик модуля, а также дилеры, с которыми у разработчика заключено соответствующее соглашение (далее — Дистрибьюторы)

Код модуля привязывается к конкретному экземпляру HostCMS, установленному на сервере. Привязка осуществляется по номеру лицензии системы. При этом, в лицензионной политике не содержится ограничений на количество сайтов и интернет-магазинов, работающих под управлением одного и того же экземпляра системы.

То есть, одна лицензия на модуль интеграции с сервисом «Покупка на Яндекс.Маркет» выдается на один номер договора на установку системы HostCMS на сервер, и покрывает неограниченное количество сайтов и магазинов на этом экземпляре системы.

Дистрибутив модуля и лицензионный ключ доступны Покупателю после оплаты лицензии, и передаче Дистрибьютору модуля следующих данных:

  • Логин, к которому привязана лицензия HostCMS;
  • Номер договора;
  • Пин-код.

В ответ на эти данные, Дистрибьютор предоставляет Покупателю архив с исходным кодом модуля и инструкцию по его установке. Лицензионные ключи будут сгенерированы и встроены в систему автоматически, в момент установки модуля.

Важно При совершении в системе некоторых операций, связанных с Модулем, он время от времени автоматически проверяет корректность лицензионного ключа.

Важно Работы по настройки модуля на сайте (сайтах) Покупателя в состав лицензии не входят, но при необходимости могут быть заказаны у Дистрибьюторов с отдельной оплатой.

Важно Пользователям HostCMS редакции Халява, перед покупкой и установкой Модуля, необходимо получить бесплатную лицензию в Личном кабинете на сайте http://hostcms.ru (в разделе Личный кабинет — Лицензии), а затем внести полученные данные в Центре администрирования системы, в раздел «Сайты» — «Настройки» — «Регистрационные данные».

Установка модуля

Установка модуля очень проста, и состоит из двух шагов:

  1. вам необходимо скопировать в корневую папку системы, на вашем сервере, файлы и папки, находящиеся в дистрибутиве:
  2. в центре администрирования системы перейти в раздел «Модули», вы выпадающем меню выбрать «Модуль» — «Добавить», заполнить форму следующими данными:
    • Название модуля — Покупка на Яндекс.Маркет;
    • Галочка «Активен» — включена;
    • Галочка «Индексировать» — выключена;
    • Путь к модулю — shopmarket;
  3. нажать на кнопку «Применить».

Модуль автоматически внесет необходимые изменения в базу данных и подключит нужные хуки. Кроме того, ко всем магазинам в системе будет добавлена новая платежная система «Покупка на Яндекс.Маркет» (создается в статусе «Неактивна», так что пользователям она доступна не будет), также в систему добавятся новые статусы заказов, и новая ТДС «Покупка на Яндекс.Маркет» в группе «Интернет-магазин».

Настройка модуля

Настройка модуля состоит из нескольких этапов:

  1. Настройка веб-сервера для поддержки доступа к вашему сайту по протоколу https;
  2. Создание и настройка раздела структуры;
  3. Настройка параметров подключения к сервису в личном кабинете Маркета;
  4. Настройка OAuth-авторизации;
  5. Настройка интеграции для магазина.

1. Настройка веб-сервера

Яндекс.Маркет взаимодействует с магазинами только по защищенному соединению SSL, поэтому вам необходимо настроить ваш сервер таким образом, чтобы страницы вашего сайта могли открываться как по протоколу http, так и по протоколу https.

При этом Маркет не накладывает требований на сам сертификат, он может быть как официальным, приобретенным в центре сертификации, так и самоподписным. Подлинность сертификата Маркет проверяет по его отпечатку SHA1, который вы указываете в настройках в личном кабинете Маркета. Для пользователей же можно оставить обычный доступ к сайту по http.

Здесь я не буду приводить инструкций по настройкам SSL-соединений для конкретных веб-серверов (Nginx, Apache и т.п.), т.к. они в значительной мере зависят от конфигурации вашего сервера и установленной на нем панели управления.

Признаком успешного выполнения данного пункта является то, что страницы вашего сайта (например, главная) открываются в браузере по протоколу https. (Если вы использовали самоподписной сертификат, то браузер перед этим будет выдавать предупреждающее сообщение о том, что сертификат не является доверенным — это нормально, и не будет мешать работе модуля)

2. Создание и настройка раздела структуры

Обработка запросов от Маркета будет производиться специальной страницей вашего сайта, с произвольным url, (например https://mysite.ru/shopmarket/), которая должна быть настроена на устанавливающуюся вместе с модулем ТДС «Покупка на Яндекс.Маркет».

  1. На сайте вашего магазина, зайдите в центр администрирования HostCMS, и перейдите в раздел «Структура сайта».
  2. В выпадающем меню выберите пункт «Раздел» — «Добавить»
  3. В открывшейся форме введите следующие параметры:
    • Название раздела в меню — Покупка на Яндекс.Маркет
    • Родительский раздел — оставьте значение пустым (…) или выберите желаемый родительский раздел
    • Меню — любое значение
    • Галочка «Отображать в меню сайта» — не включена
    • Макет — любое значение
    • Название раздела — например, shopmarket
    • Группа доступа — Все
    • Галочка «Активность страницы» — включена
    • Галочка «Индексировать» — не включена
    • Галочка «Доступ через HTTPS» — Включена (Обязательно!)
    • Тип раздела — Типовая динамическая страница
    • Раздел — Интернет-магазин
    • Страница — Покупка на Яндекс.Маркет
    • Идентификатор магазина — идентификатор нужного вам магазина, например, Демонстрационный магазин [1]
  4. Нажмите кнопку «Применить»

Созданный раздел структуры, при обращении по протоколу http будет автоматически переключаться на протокол https, это является корректным поведением.

Важно При открытии в браузере страницы взаимодействия с Маркетом, в зависимости от настроек ТДС, вы должны видеть пустую страницу, или сообщение об ошибке вида {«error»:{«message»:»No or incorrect Authorization header»,»code»:403}}. Такое поведение является корректным.

3. Настройка параметров подключения к сервису в личном кабинете Маркета

  1. Авторизуйтесь в личном кабинете Яндекс.Маркета, тем логином, под которым вы размещаете на Маркете товарные предложения вашего Магазина.
  2. Из списка ваших магазинов, вам необходимо выбрать тот, который вы хотите подключить к программе «Покупка на Яндекс.Маркет».
  3. Сохраните в Блокнот номер кампании для выбранного магазина, он понадобится позже (сохранять нужно только часть номера, идущую после дефиса, например, если вы видите запись «Кампания №11-21029222», то сохранить нужно номер 21029222)
  4. Затем раскройте выпадающее меню «Покупка на Маркете» и выбрать в нем пункт «Настройки API покупки». В открывшейся форме вы должны ввести следующие настройки:
    • URL API — адрес страницы, созданной на этапе 2, например, https://mysite.ru/shopmarket/
    • SHA1 fingerprint — цифровой отпечаток SSL-сертификата, с которым открывается данная страница (чтобы его узнать, откройте эту страницу в браузере, и посмотрите подробную информацию о сертификате);
    • Авторизационный токен — нажмите на псеводссылку «создать» и сохраните это значение в Блокнот, оно нам понадобится позднее, на этапе 5;
    • Тип авторизации — выберите значение HEADER;
    • Формат данных — выберите значение JSON.

4. Настройка OAuth-авторизации

  1. Зайдите в раздел настройки доступа приложения к вашим данным на Яндексе — https://oauth.yandex.ru/ Важно! Вы должны быть авторизованы под тем же логином, под которым вы вносили настройки в личном кабинете Маркета на этапе 3.
  2. Перейдите по ссылке «Регистрация клиентских приложений». В открывшейся форме введите следующие настройки:
    • В поле «Название» — Покупка на Яндекс.Маркет для HostCMS
    • В списке «Права» нужно выбрать пункт «Яндекс.Маркет» и включить галочку «API Яндекс.Маркета для партнеров»
    • В поле «Callback URL» — укажите страницу /admin/shopmarket/application.php на вашем сайте, например https://mysite.ru/admin/shopmarket/application.php
  3. Нажмите кнопку «Сохранить».
  4. На следующей странице вы увидите информацию о созданном приложении, вам необходимо сохранить в Блокнот значения строк ID и Пароль.
  5. Перейдите в центр администрирования HostCMS на вашем сайте. Зайдите в раздел «Интернет-магазин», и выберите нужный магазин.
  6. В меню «Заказы» выберите пункт «Настройки сервиса „Покупка на Маркете“«
  7. В открывшемся диалоге, в секции „Параметры авторизации“ перейдите по ссылке «Изменить список», которая находится справа от списка «OAuth-приложение для Яндекса»
  8. В форме заполните поля:
    • Зарегистрированные приложения — «Добавить новое»;
    • Название приложения — Покупка на Яндекс.Маркет;
    • Логин на Яндексе — тот логин, под которым вы авторизовывались в Яндексе на этапах 3 и 4;
    • ID Приложения — значение строки ID, которое вы сохранили в п.4 данного этапа, например, 9d9a1ef9dda34ea4ae554ddd5d7d7111;
    • Пароль приложения — значение строки Пароль, которое вы сохранили в п.4 данного этапа, например, 6dd4ee7a6b5742b7a89a1c77473a2222.
  9. Нажмите кнопку «Сохранить приложение»
  10. Вы увидите сохраненные данные вашего приложение, и пустое поле «Токен». Перейдите по ссылке «Получить/продлить», которая находится правее этого поля
  11. Вы будете перенаправлены на сайт https://oauth.yandex.ru для подтверждения доступа. Вам нужно нажать кнопку «Разрешить».
  12. После этого, вы будете перенаправлены обратно в центр администрирования вашего магазина, к тому же самому диалогу редактирования параметров приложения. В поле «Токен» появится некое значение, например, 0963e52d17c646e9bd31c9c39dcd3333. Если этого не произошло, попробуйте получить токен еще раз.

5. Настройка интеграции для магазина

  1. Перейдите в центр администрирования HostCMS на вашем сайте. Зайдите в раздел «Интернет-магазин», и выберите нужный магазин.
  2. В меню «Заказы» выберите пункт «Настройки сервиса „Покупка на Маркете“»
  3. В секции „Параметры авторизации“
    • выберите в списке «OAuth-приложение для Яндекса» приложение, созданное вами на этапе 4;
    • в поле «Идентификатор кампании на Маркете» введите номер кампании, сохраненный вами в пункте 3 этапа 3
    • в поле «Авторизационный токен» введите токен, сохраненный вами в пункте 4 этапа 3
  4. В секции «Разрешенные способы оплаты» включите галочки у тех способов оплаты, которые вы готовы принимать при покупках через Яндекс.Маркет
  5. В секции «Процессинг заказов» для тех способов доставки, которые вы готовы предоставлять при покупках через Яндекс.Маркет, выберите описание условий доставки, а также минимальный и максимальный сроки доставки в днях. Для способов доставки, которые будут недоступны при покупках через Яндекс.Маркет, оставьте значения в списках пустыми. (Значение 0 в поле «Мин. срок в днях», означает, что заказ может быть доставлен сегодня (или завтра, если текущее время больше, чем указанное в списке «Время, после которого заказы принимаются только с доставкой на завтра»)
  6. В списке «Обработчик заказов» выберите платежную систему «Покупка на Яндекс.Маркет»
  7. В списке «Время, после которого заказы принимаются только с доставкой на завтра», укажите время, после которого заказы принимаются только с доставкой на завтра. Если в вашем магазине в принципе не возможна доставка в день оформления заказа, то выберите в этом списке значение «Всегда».
  8. Нажмите кнопку «Сохранить настройки».

На этом настройка модуля завершена.

Отладка модуля

Отладка модуля осуществляется с помощью инструментов отладки в личном кабинете Яндекс.Маркета.

Авторизуйтесь в личном кабинете Яндекс.Маркета тем логином, под которым вы размещаете на Маркете товарные предложения вашего Магазина, и выберите из списка ваших магазинов тот, подключить которого к программе «Покупка на Яндекс.Маркет» вы настроили на предыдущих этапах. Затем раскройте выпадающее меню «Покупка на Маркете» и выберите в нем пункт «Отладка API покупки».

Возможности и ход процесса отладки подробно описаны в документации Яндекса — https://tech.yandex.ru/market/partner/doc/dg/concepts/sandbox-docpage/.

Ограничения на действия, совершаемые в Центре администрирования HostCMS с заказами, оформленными через Яндекс.Маркет

Как было сказано выше, в соответствии с требованиями протокола взаимодействия между Магазином и Маркетом, для заказов, оформленных через Яндекс.Маркет введен ряд ограничений на действия, совершаемые в списке заказов и в карточке заказа.

  1. При оформлении заказа, в карточке заказа отсутствует информация о Фамилии, Имени, Отчестве заказчика, его телефоне, электронной почте и прочие контактные данные, до тех пор, пока Маркет не пришлет Модулю уведомление о переходе заказа в статус «[М2] Поступил в обработку»;
  2. При оформлении, заказу присваивается номер (инвойс) выданный Яндекс.Маркетом, поиск нужного заказа в ЦА необходимо производить по этому номеру;
  3. В карточке заказа, оформленного через Яндекс.Маркет, присутствует текстовая метка» * Заказ оформлен через сервис «Покупка на Яндекс.Маркет»»;
  4. В карточке заказа заблокирована галочка «Оплачен» и поле «Дата оплаты» — для заказов, при оформлении которых был выбран способ «Предоплата при оформлении», эти данные будут выставлены автоматически при смене статуса заказа с «[М1] Ждет оплаты» на «[М2] Поступил в обработку»;
  5. В карточке заказа заблокирована галочка «Отменен» — она будет выставлена автоматически при переходе статуса заказа в любой из статусов отмены;
  6. В карточке заказа заблокировано поле «Дата изменения статуса заказа» — при смене статуса (как по инициативе Магазина, так и по инициативе Маркета) поле будет заполнено автоматически;
  7. В карточке заказа заблокирован список «Платежная система» — для заказов, оформленных через Яндекс.Маркет изменять обработчик платежной системы нельзя;
  8. В карточке заказа заблокированы списки «Типы доставок» и «Условия доставки», а также скрыта ссылка «Пересчитать стоимость доставки» — в текущей версии Модуля (1.0.х), для заказов, оформленных через Яндекс.Маркет, возможность изменять условия доставки по инициативе Магазина не поддерживается. Реализация поддержки этой возможности планируется в будущих версиях Модуля;
  9. В карточке заказа заблокирован список «Валюта» — для заказов, оформленных через Яндекс.Маркет изменять валюту суммы заказа нельзя;
  10. Комментарии, добавленные покупателем при оформлении заказа, можно увидеть в карточке заказа на вкладке «Описание заказа» в одноименном поле;
  11. Дополнительную информация о доставке заказа (код домофона, ФИО получателя, согласованные даты доставки и т.п.), а также информацию о выбранном покупателем способе оплаты можно увидеть в карточке заказа, на вкладке «Описание заказа» в поле «Информация о заказе»;
  12. В заказах, оформленных через Яндекс.Маркет, запрещено редактировать набор товаров, их количество и стоимость, а также стоимость доставки. Если вам нужно изменить содержимое заказа, вам следует попросить покупателя оформить новый заказ, а уже оформленный перевести в статус «[М] Отменен, покупатель изменяет состав заказа». В текущей версии Модуля, данное ограничение технически еще не реализовано, и будет сделано в следующих версиях, однако при работе с модулем вам следует о нем помнить;
  13. Для заказов, оформленных через Яндекс.Маркет, важна последовательность переходов из одного статуса в другой, кроме того, есть статусы, выставлять которые может только Маркет, по своей инициативе. Правильный порядок смены статусов описан в справочной документации Яндекса, здесь и здесь. Пожалуйста, ознакомьтесь с ней перед началом использования Модуля. При попытке произвести некорректную смену статуса, Маркет ответит ошибкой, после чего заказу будет возвращен исходный статус.

Разработчики модуля

Разработчиком и майнтейнером модуля интеграции с сервисом «Покупка на Яндекс.Маркет» для HostCMS v.6 является Стриго Евгений Васильевич (известный также как Евгений Котов).

Все права на код Модуля и сопровождающую его документацию исключительно принадлежат только Разработчику.

Официальным и единственно верным способом связи с Разработчиком по любым вопросам является электронная почта james.kotoff@gmail.com

Порядок оказания технической поддержки и разрешения спорных вопросов

Разработчик оказывает техническую поддержку только Дистрибьюторам модуля, а также Покупателям, приобретавшим модуль лично у него. Покупателям, приобретавшим модуль у других Дистрибьюторов за технической поддержкой необходимо обращаться к тому Дистрибьютору, у которого они приобрели модуль.

Разработчик участвует в разрешении спорных вопросов только с Покупателями, приобретавшим модуль лично у него. Покупателям, приобретавшим модуль у других Дистрибьюторов за разрешением спорных вопросов необходимо обращаться к тому Дистрибьютору, у которого они приобрели модуль.

Модуль предоставляется «Как есть», разработчик не несет ответственности за любой ущерб, полученный покупателем в результате приобретения и/или использования данного модуля.

В состав технической поддержки входит устранение выявленных и стабильно воспроизводимых ошибок в работе Модуля и во взаимодействии Модуля и Яндекс.Маркета. Устранение таких ошибок производится бесплатно, за исключением следующих случаев:

  • ошибки, появившиеся в результате изменения параметров API со стороны Яндекс.Маркета;
  • ошибки, возникшие в результате неверных действий администратора Магазина, работающего с заказами и с Модулем;
  • ошибки, возникшие в результате нарушения Покупателем вышеизложенной лицензионной политики Модуля.

Разработчик принимает от Покупателей и Дистрибьюторов запросы на расширение функциональности модуля, однако оставляет за собой решение о возможности и сроках реализации конкретных запросов. Работы по расширению функциональности модуля осуществляются только за дополнительную плату.

Разработчик, за отдельную плату, может оказывать Покупателю услуги по настройке Модуля для конкретного Магазина, однако оставляет за собой решение о возможности и сроках оказания такой услуги.

Разработчик благодарит вас за приобретение и использование данного Модуля!

Версия документа 1.2 от 21 января 2015 г.

P.S. Разработчик выражает свою признательность команде KAD Systems и лично Артему за участие в разработке этого модуля.