Методы реализации кассы

Внимание! Перед началом реализации кассы для печати чеков через платёжную систему рекомендуем ознакомиться с написанием собственного обработчика онлайн-кассы.

Класс \Bitrix\Sale\Cashbox\CashboxPaySystem

Ваша касса должна наследовать класс CashboxPaySystem. Это абстрактный класс, содержащий абстрактные методы, которые требуется реализовать в классе-наследнике.

abstract class CashboxPaySystem extends Cashbox implements IPrintImmediately, ICheckable
{
	abstract protected function getPrintUrl(): string;
	abstract protected function getCheckUrl(): string;
	abstract protected function send(string $url, Sale\Payment $payment, array $fields): Sale\Result;
	abstract protected function processPrintResult(Sale\Result $result): Sale\Result;
	abstract protected function getDataForCheck(Sale\Payment $payment): array;
	abstract protected function processCheckResult(Sale\Result $result): Sale\Result;
	abstract protected function onAfterProcessCheck(Sale\Result $result, Sale\Payment $payment): Sale\Result;
	abstract public static function getPaySystemCodeForKkm(): string;
}

Класс CashboxPaySystem реализует интерфейсы IPrintImmediately и ICheckable. Это позволяет печатать чеки сразу же при получении оплаты и проверять их статус.

Помимо методов класса CashboxPaySystem, есть ещё следующий метод:

abstract public function buildCheckQuery(Check $check);

Данный метод находится в классе Cashbox и его также необходимо реализовать.

Рассмотрим подробнее методы:

• getPrintUrl

  abstract protected function getPrintUrl(): string;

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

  Этот метод используется в методе \Bitrix\Sale\Cashbox\CashboxPaySystem::printImmediately.



• getCheckUrl

  abstract protected function getCheckUrl(): string;

  Метод должен вернуть строку с URL-адресом, при обращении на который можно получить данные о статусе чека.

  Этот метод используется в методе \Bitrix\Sale\Cashbox\CashboxPaySystem::check.



• send

  abstract protected function send(string $url, Sale\Payment $payment, array $fields): Sale\Result;

  Метод получает URL-адрес, на который нужно отправить запрос, объект оплаты и массив данных.

  Этот метод используется в методах \Bitrix\Sale\Cashbox\CashboxPaySystem::printImmediately и \Bitrix\Sale\Cashbox\CashboxPaySystem::check.

  Метод должен только отправить данные на указанный URL и вернуть результат или ошибку, если что-то пошло не так.

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



• processPrintResult

  abstract protected function processPrintResult(Sale\Result $result): Sale\Result;

  Данный метод обрабатывает результат печати чека, полученный ранее в метод send. Как правило, в процессе обработки нужно вернуть UUID - внешний идентификатор чека, либо ошибку, если что-то пошло не так.



• getDataForCheck

  abstract protected function getDataForCheck(Sale\Payment $payment): array;

  Метод должен вернуть данные, которые нужны для проверки чека. Например, идентификатор чека, который был получен ранее при отправке чека на печать.

  Данные будут отправлены на URL, полученный методом getCheckUrl.

  Этот метод используется в методе \Bitrix\Sale\Cashbox\CashboxPaySystem::check.



• processCheckResult

  abstract protected function processCheckResult(Sale\Result $result): Sale\Result;

  Этот метод обрабатывает результат проверки статуса чека. Как правило, в процессе обработки проверяется статус чека, например, в печати (напечатан или ошибка). В качестве аргумента метод получает результат, возвращенный ранее методом send.

  Метод должен вернуть результат, который в дальнейшем будет использоваться в методе onAfterProcessCheck или ошибку, если что-то пошло не так.



• onAfterProcessCheck

  abstract protected function onAfterProcessCheck(Sale\Result $result, Sale\Payment $payment): Sale\Result;

  В качестве первого аргумента метод получает результат, возвращенный ранее методом processCheckResult.

  В случае успешной проверки статуса в методе нужно вызвать \Bitrix\Sale\Cashbox\Cashbox::applyCheckResult, чтобы сохранить результат проверки. Либо нужно вернуть ошибку, если, например, чек ещё не напечатан и запрос нужно выполнить позже.

  Внимание! При вызове метода \Bitrix\Sale\Cashbox\Cashbox::applyCheckResult нужно убедиться, что в вашей кассе реализован метод \Bitrix\Sale\Cashbox\Cashbox::extractCheckData, иначе будет выброшено исключение \Bitrix\Main\NotImplementedException.



• getPaySystemCodeForKkm

  abstract public static function getPaySystemCodeForKkm(): string;

  Метод должен вернуть код бизнес-смысла платёжной системы, для которого будет создаваться касса. Обычно это код поля логин.

  При включении печати чеков через платёжную систему автоматически добавляется касса. Касса "привязывается" не к конкретной платёжной системе, а аккаунту, с которым работает платёжная система.

  Например, если есть 2 платёжных системы, использующих 1 обработчик и настроенные с одним и тем же логином, то будет создана 1 касса и она будет использоваться для печати чеков для обеих платёжных систем. Если же 2 платёжных системы используют 1 обработчик, но настроены с разными логинами, то будут добавлены 2 кассы (если для обеих платёжных систем включена печать чеков).