anthony/atol-online
1
0
Fork 0
mirror of https://github.com/anthonyaxenov/atol-online.git synced 2024-11-16 09:40:47 +00:00
Code Issues Projects Releases Wiki Activity
fdc5ab112a
atol-online/docs/kkt.md
AnthonyAxenov bce21f9658 Правки по документации 
Актуализирована часть про `Vat`, пересобрал README, мелочи
2021-11-28 12:01:28 +08:00

16 KiB
Raw Blame History

Работа с ККТ

Вернуться к содержанию

Доступ к ККТ

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

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

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

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

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

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

Использование

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

$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 места расчёта (ссылка на ваш интернет-сервис).

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

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

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

При включенном тестовом режиме:

  • меняется логин, пароль и группа (для обращения на тестовую ККТ)
  • между авторизацией и операцией над документом, в Company документа переопределяется ИНН, СНО и адрес места расчётов на те, что указаны в параметрах тестовой среды.

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

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

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

Для включения тестового режима необязательно задавать параметры боевой ККТ.

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

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

Авторизация на ККТ

Перед первым запросом на ККТ происходит аутентификация на сервере по логину и паролю.
В ответ приходит авторизационный токен, срок жизни коего равен 24 часам.
После первой успешной операции возможно получить этот токен следующим образом:

$kkt->getAuthToken(); // вернёт строку длиной 128 символа

Этот токен можно сохранить и переиспользовать в течение всего срока его жизни.
Спустя это время следует получить новый токен.

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

$kkt->setAuthToken($token_string);

Если токен был установлен перед выполнением операции, то при выполнении операции будет использоваться именно он, а новый запрашиваться не будет. Если операция завершится ошибочно из-за истёкшего токена, следует повторить операцию без использования метода setAuthToken(), либо обнулив его следующим образом:

$kkt->setAuthToken(null);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Любой из перечисленных выше шести методов может выбросить исключение AtolAuthFailedException при ошибке аутентификации или авторизации.

Собственный идентификатор документа

Каждый документ, переданный на ККТ для регистрации, всегда имеет свой идентификатор, абсолютно уникальный среди всех документов когда-либо регистрировавшихся на ККТ, даже если при регистрации были ошибки. По умолчанию это UUID версии 4.

Чтобы использовать собственный идентификатор, следует передать нужное строковое значение вторым параметром в любой из шести описанных выше методов, например:

$kkt->sell($document, $my_unique_id);
$kkt->sellRefund($document, $my_unique_id);
$kkt->buy($document, $my_unique_id);
$kkt->buyRefund($document, $my_unique_id);
$kkt->sellCorrection($document, $my_unique_id);
$kkt->buyCorrection($document, $my_unique_id);

Если $my_unique_id равен null или пустой строке, то будет сгенерирован новый UUID. Узнать его можно будет только в ответе от ККТ.

Передача callback_url

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

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

Метод setCallbackUrl() проверяет входную строку на длину (до 256 символов) и валидность формата url по регулярному выражению:

^http(s?)\:\/\/[0-9a-zA-Zа-яА-Я]([-.\w]*[0-9a-zA-Zа-яА-Я])*(:(0-9)*)*(\/?)([a-zAZ0-9а-яА-Я\-\.\?\,\'\/\\\+&=%$#_]*)?$

Выбрасывает исключения:

  • AtolCallbackUrlTooLongException (если слишком длинный url);
  • AtolInvalidCallbackUrlException (если url невалиден).

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

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

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

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

$result = $kkt->getLastResponse(); // вернёт последний ответ от API
$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->getLastResponse()->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();

Вернуться к содержанию