Требования к разработке расширений «Инвойсбокс» для систем управления сайтами
Используемый протокол обмена данными (API)
Расширение (далее, модуль «Инвойсбокс») системы управления сайтом (далее, CMS) Интернет-магазина (далее, магазина) для передачи информации о заказе и составе корзины должен опираться на описание протокола, расположенное по адресу: Инвойсбокс API v3.
Перед отправкой данных заказа в API, модуль должен проверять корректность данных, в частности, формат данных должен соответствовать описанному в API. В случае наличия ошибок в расчёте, отсутствия необходимых сведений и других ошибок, модуль должен отобразить соответствующее сообщение пользователю, данные не должны отправляться в платёжный шлюз.
В модуле должны быть предусмотрены следующие функции:
- Оформление заказа/переход на платёжную страницу системы «Инвойсбокс»;
- Callback-скрипт для получения информации об оплате заказа;
- Функции оформления возврата по заказу.
Множество способов оплаты
В тех CMS, где это технически возможно, модуль должен поддерживать оформление двух способов оплаты, а именно - оплата для физических лица (банковские карты, интернет банки и т.д.), а также оплата для юридических лиц (оплата по счёту для организаций и ИП). В настройках модуля должна быть предусмотрена возможность выбора используемых способов оплаты.
При выборе способа оплаты для организаций и ИП, по API должны передаваться данные организации - ИНН, КПП, наименование, юридический адрес (при наличие данных в заказе).
Т.е. в результате установки модуля, в CMS должно появится два способа оплаты. Там где это невозможно, выбор способа оплаты будет осуществляться на странице платёжного шлюза системы «Инвойсбокс».
Идентификация модуля
Важно обратить внимание на формирование идентификатора приложения и модуля при работе с API.
В API v3 идентификатор приложения передаётся в HTTP-заголовке User-Agent.
В API v2, в параметрах платёжной формы, в обязательном порядке должно присутствовать поле с идентификатором приложения - itransfer_cms_name.
Параметры заказа (счёта)
Модуль обязательно должен передавать тип позиции в заказе - товар или услуга, для API V3 - более детальное значение см. справочник;
Callback для получения информации об оплате
Смена статуса заказа в CMS магазина должна осуществляться по факту получения информации об оплате в формате, описанном по адресу:
Для API v3: Уведомление по умолчанию; Для API v2: HTTP-уведомления о переводах.
При получении информации об оплате, модуль должен сверить подпись запроса, идентификатор магазина, валюту заказа, сумму оплаты с суммой заказа. В случае расхождения, смена статуса заказа производится не должна, модуль должен вернуть детальное описание ошибки в соответствии с форматом ответа API.
В модуле должен быть реализован функционал получения тестового запроса с информацией об оплате, при котором модуль должен выдать успешный ответ в случае корректной передачи подписи запроса и идентификатора магазина.
Тестовый запрос используется для проверки корректность установки модуля и не должен приводить к смене статуса какого-либо из заказов.
Для API v3, описание тестового запроса расположено на странице уведомление по умолчанию (раздел Система мониторинга и автоматическое тестирование интеграции); Для API v2, в тестовом запросе передаётся номер счёта (ucode) равный: 00000-00000-00000-00000.
Настройки модуля
Обязательным набором настроек модуля, которые пользователь может менять, являются:
- Идентификатор магазина (для API v2, v3);
- Региональный код магазина (для API v2);
- API ключ магазина (для API v2, v3);
- Включить/выключить тестовый режим (для API v2);
- Описание способа оплаты (текст, который отображается в описании способа оплаты в процессе выбора способа оплаты при оформлении заказа в магазине, для API v2, v3).
Опционально, в настройках модуля может быть предусмотрен статус, на который следует изменить статус заказа, при получении информации об оплате, а также адрес эл. почты администратора магазина, на который следует отправлять отчёты, в случае возникновения ошибок в работе модуля.
При наличие технической возможности CMS, модуль должен поддерживать несколько настроек таким образом, чтобы для каждой группы товара или отдельного товара можно было бы задать параметр - какие настройки использовать для оплаты. Это требования необходимо там, где разные товары и услуги могут быть оплачены от разных организаций.
Модуль должен поддерживать 2 языка – русский и английский.
Прочие сведения
Логотип системы для использования в модуле: Логотипы системы «Инвойсбокс»
Комплект модуля
В состав модуля должны входить следующие элементы:
- Файлы модуля (архив ZIP), включая файл version.txt, в котором должна быть отражена версия модуля;
- Информация о модуле – версия(ии) CMS для которой модуль предназначен, версия(ии) CMS, на которой модуль был протестирован;
- Логотип CMS (SVG);
- Пошаговая инструкция по установке модуля включая шаги, необходимые для установки модуля, изображения, сопровождающие описательную часть;
- Пошаговая инструкция по настройке модуля, необходимые для настройки модуля, изображения, сопровождающие описательную часть;
- URL, которую следует указать в личном кабинете системы «Инвойсбокс» для передачи информации об оплате.
Исходные коды модуля должны быть загружены на github:
Информация о модуле и инструкции должны быть размещены на ресурсах:
phpSDK
Для упрощенной разработки и поддержания модулей в актуальном состоянии, рекомендуется использование phpSDK.
Общие требования к обновлению старых версий модулей
- Обновление модулей в соответствии с актуальными версиями CMS;
- Обновление логотип и наименование платёжной системы - Инвойсбокс, Invoicebox (б, b - маленькие);
- Обновление инструкций по установке и настройке модулей;
- Реализация функций возврата платежа, если такие функции поддерживает CMS;