atol-online/docs/kkt.md

Работа с ККТ

Объект ККТ инициализируется следующим образом:

$kkt = new AtolOnline\Api\Kkt();

Настройка ККТ

Для работы с облачной ККТ необходимы следующие параметры:

• логин кассы;
• пароль кассы;
• код группы кассы;

Чтоб получить их, нужно:

1. авторизоваться на online.atol.ru;
2. на странице Мои компании нажать кнопку Настройки интегратора.
   Скачается XML-файл с нужными настройками.

Установить эти параметры можно двумя путями:

// 1 способ - через конструктор
$kkt = new AtolOnline\Api\Kkt($group, $login, $password);

// 2 способ - через сеттеры
$kkt = (new AtolOnline\Api\Kkt())
    ->setLogin($login)
    ->setGroup($group)
    ->setPassword($password);

Получить заданные параметры можно через соответствующие геттеры:

$kkt->getLogin();
$kkt->getPassword();
$kkt->getGroup();

Также для работы потребуются:

• ИНН продавца;
• URL места расчёта (ссылка на ваш интернет-сервис).

Эти параметры нужно задать объекту компании, который будет передаваться в документах через эту ККТ.

Тестовый режим

На самом деле, в АТОЛ Онлайн нет понятия тестовая операция или чего-то в этом духе. АТОЛ предоставляет нам отдельную тестовую ККТ. Её настройки уже указаны в коде библиотеки. Под тестовым режимом работы подразумевается использование этой тестовой ККТ.

В библиотеке есть переключатель настроек ККТ. С его помощью можете поменять вашу боевую ККТ на тестовую и наоборот. Это можно сделать одним из следующих способов:

// включить в любом месте кода:
$kkt->setTestMode(); 
$kkt->setTestMode(true);
$kkt->setTestMode(false); // выключить

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

Если по каким-то причинам у вас не получится использовать тестовый режим, вы можете проводить свои тесты в боевом режиме (на собственной ККТ). В этом случае важно понимать следующее:

1. сразу после оформления документа прихода необходимо оформлять точно такой же документ возврата прихода;
2. вы обязательно забудете о пункте 1;
3. пп. 1 и 2 в любом случае скажутся на ваших финансовых отчётах;
4. вся ответственность за пп. 1-3 и последствия ложится только на вас.

Регистрация документа

Для регистрации документа прихода необходимо вызвать метод sell():

$result = $kkt->sell($document);

Для регистрации документа возврата прихода необходимо вызвать метод sellRefund():

$result = $kkt->sellRefund($document);

Для регистрации документа расхода необходимо вызвать метод buy():

$result = $kkt->buy($document);

Для регистрации документа возврата расхода необходимо вызвать метод buyRefund():

$result = $kkt->buyRefund($document);

Для операций, перечисленных выше, документы не должны содержать данных коррекции. Тогда как для операций коррекции, которые описаны ниже, эти данные должны присутствовать.

Для регистрации документа коррекции прихода необходимо вызвать метод sellRefund():

$result = $kkt->sellCorrection($document);

Для регистрации документа коррекции расхода необходимо вызвать метод buyRefund():

$result = $kkt->buyCorrection($document);

Передача callback_url

Перед регистрацией документа можно указать callback_url. АТОЛ отправит на указанный URL результат регистрации. Вам необходимо расположить по этому адресу скрипт, обрабатывающий этот результат.

$kkt->setCallbackUrl('http://example.com/process-kkt-result');
$kkt->getCallbackUrl();

Обработка результата регистрации

Методы sell(), sellRefund(), sellCorrection(), buy(), buyRefund() и buyCorrection() возвращают объект AtolOnline\Api\KktResponse.

Этот же объект можно получить через геттер getLastResponse().

Этот объект содержит в себе HTTP-код ответа, массив заголовков и JSON-декодированные данные тела ответа.

$result = $kkt->getLastResponse();
$headers = $result->getHeaders(); // вернёт заголовки
$code = $result->getCode(); // вернёт код ответа
$body = $result->getContent(); // вернёт JSON-декодированное тело ответа

Обращаться к полям JSON-декодированного объекта можно опуская вызов метода getContent() таким образом:

// вернёт значение поля uuid
$uuid = $result->getContent()->uuid;
$uuid = $result->uuid; 
// вернёт текст ошибки
$err_text = $result->getContent()->error->text;
$err_text = $result->error->text;

Проверка корректности ответа (отсутствия ошибок) работает через метод isValid():

$kkt->isValid(); // вернёт true, если ошибок нет

Проверка статуса документа

Если перед отправкой документа на регистрацию был задан callback_url через метод setCallbackUrl(), то ответ придёт на указанный адрес автоматически, как только документ обработается на стороне ККТ. Ответ может быть как об успешной регистрации, так и ошибочной.

В любом случае, вам доступны два метода, с помощью которых вы можете проверять статус документа самостоятельно:

$kkt->getDocumentStatus();
$kkt->pollDocumentStatus();

Эти методы принимают на вход uuid кода регистрации. Этот UUID можно получить из ответа, полученного при отправке документа на регистрацию:

$sell_result = $kkt->sell($document);
$kkt->pollDocumentStatus($sell_result->uuid);
$kkt->getDocumentStatus($sell_result->uuid);

Метод pollDocumentStatus() многократно опрашивает ККТ на предмет состояния документа. Метод может принимать до трёх параметров:

• uuid;
• количество попыток (по умолчанию — 5);
• время между попытками в секундах (по умолчанию — 1).

// Проверять статус 10 раз на протяжении 20 секунд — каждые две секунды 
$kkt->pollDocumentStatus($sell_result->uuid, 10, 20);

Учитывайте, что метод вернёт результат как только сменится статус регистрации на успешный или ошибочный.

Использовать его лучше сразу после отправки документа на регистрацию (как в примере выше).

Как правило, полная регистрация одного документа занимает 4-5 секунд.

Метод getDocumentStatus() принимает на вход только uuid и запрашивает состояние документа лишь единожды. Использовать его целесообразнее в те моменты, когда нет необходимости знать успех регистрации сразу после отправки документа.

Обратите внимание, что АТОЛ позволяет получать статус документа в течение 32 суток с момента его регистрации.

Методы pollDocumentStatus() и getDocumentStatus() возвращают объект AtolOnline\Api\KktResponse. Оба выбрасывают исключение AtolUuidValidateException (если переданная строка UUID невалидна).

Объект класса приводится к JSON-строке автоматически или принудительным приведением к string:

echo $item;
$json_string = (string)$item;

Чтобы получить те же данные в виде массива, нужно вызвать метод jsonSerialize():

$json_array = $item->jsonSerialize();