atol-online/docs/fiscalizing.md

Фискализация документов

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

---

Доступ к ККТ

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

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

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

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

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

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

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

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

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

Установить параметры подключения можно двумя путями:

use AtolOnline\Api\Fiscalizer;

// 1 способ - через конструктор
$kkt = new Fiscalizer(group: 'mygroup', login: 'mylogin', password: 'mypassword');

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

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

По умолчанию фискализатор создаётся для работы в тестовом режиме. Это означает, что работа с АТОЛ Онлайн API будет происходить в тестовой среде.

Под тестовым режимом работы подразумевается использование тестовых ККТ, которые принадлежат компании АТОЛ.

Управление тестовым режимом происходит следующим образом:

$kkt = new Fiscalizer(); // включен по умолчанию
$kkt = new Fiscalizer(false); // выключен явно
$kkt->setTestMode(); // включен явно
$kkt->setTestMode(true); // включен явно
$kkt->setTestMode(false); // выключен явно

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

• логин;
• пароль;
• группа ККТ;
• ИНН клиента (покупателя);
• ИНН и адрес места расчётов компании (продавца).

Таким образом:

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

При выключенном тестовом режиме используются ваши ККТ.

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

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

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

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

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

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

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

$kkt->setToken($token_string);

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

$kkt->setToken(null);

Тогда будет получен новый токен.

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

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

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

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

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

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

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

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

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

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

$result = $kkt->sellCorrect($document);
$result2 = $correction->sellCorrect($kkt);

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

$result = $kkt->buyCorrect($document);
$result2 = $correction->buyCorrect($kkt);

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

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

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

$result = $kkt->sellRefund($document, 'order_' . $order->id);

Если external_id не указан явно или имеет пустое значение, то будет сгенерирован новый UUID. Узнать его можно будет только в ответе от ККТ после регистрации документа в очереди на фискализацию.

Передача callback_url

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

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

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

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

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

$kkt->getDocumentStatus();  // делает единичный запрос
$kkt->pollDocumentStatus(); // делает запросы до получения конечного статуса (не-wait)

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

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

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

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

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

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

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

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

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

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

---

Читай также: Обработка ответа API

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