Требования к разработке расширений «Инвойсбокс» для систем управления сайтами

Используемый протокол обмена данными (API)

Расширение (далее, модуль «Инвойсбокс») системы управления сайтом (далее, CMS) Интернет-магазина (далее, магазина) для передачи информации о заказе и составе корзины должен опираться на описание протокола, расположенное по адресу: Инвойсбокс API v3.

В случае доработки существующего модуля, работающего с Инвойсбокс API v2, в модуле должна быть предусмотрена настройка, позволяющая переключаться между версиями API.

Перед отправкой данных заказа в API, модуль должен проверять корректность данных, в частности, формат данных должен соответствовать описанному в API.

Наиболее важную роль проверка данных играет в реализации API v2, при формировании данных платёжной формы для дальнейшей переадресации пользователя на платёжную страницу. В случае наличия ошибок в расчёте, отсутствия необходимых сведений и других ошибок, модуль должен отобразить соответствующее сообщение пользователю, форма не должна отправляться в платёжный шлюз.

В модуле должны быть предусмотрены следующие функции:

Оформление заказа/переход на платёжную страницу системы «Инвойсбокс»;
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:

github.com/InvoiceBox.

Информация о модуле и инструкции должны быть размещены на ресурсах:

phpSDK

Для упрощенной разработки и поддержания модулей в актуальном состоянии, требуется реализация phpSDK для API v3 как отдельного проекта. В phpSDK должны быть реализованы базовые методы, описанные в документации.

Общие требования к обновлению старых версий модулей

Требуется обновить текущие модули в соответствии с актуальными версиями CMS;
Требуется обновить реализацию API v2 таким образом, чтобы:
- Корректно передавался состав корзины, включая такие поля как артикул товара, тип товара (товар или услуга), ставка НДС, единица измерения, код единицы измерения;
- Корректно передавался тип плательщика - физическое лицо или организация. Если передается организация - должны передаваться дополнительные поля, такие как ИНН, КПП и адрес регистрации
- Передавался параметр с наименованием и версией CMS и наименованием и версии модуля Invoicebox, пример, itransfer_cms_name = Bitrix/20.1.2 (Invoicebox 2.0.1). Наименование должно передаваться как при формировании счёта, так и в заголовке User-Agent при ответе на запрос с оплатой
- Обрабатывался тестовый номер заказа (00000-00000-00000-00000 или ffffffff-ffff-ffff-ffff-ffffffffffff для API v3)
Требуется обновить логотип и наименование платёжной системы в модуле - Инвойсбокс, Invoicebox (б, b - маленькие);
Требуется обновить инструкции по установке и настройке модулей с учётом нового личного кабинета в системе Инвойсбокс (вместо login.invoicebox.ru - business.invoicebox.ru), включая скриншоты;
Требуется реализовать поддержку протокола v3 и настройки модуля, которая позволяет выбирать версию используемого протокола;
В случае, если в модуле используется IP фильтр для адресов 77.244.212.7, 77.244.212.8, 77.244.212.9 - такой фильтр следует удалить из кода;
Требуется реализовать функции возврата платежа, если такие функции поддерживает CMS;
Выделить функции работы с API v3 в phpSDK для переиспользования в разных модулях;

Проект на github