diff --git a/docs/kkt.md b/docs/kkt.md index 4daf53a..c6acee8 100644 --- a/docs/kkt.md +++ b/docs/kkt.md @@ -52,9 +52,14 @@ $kkt->getGroup(); ## Тестовый режим На самом деле, в АТОЛ Онлайн нет понятия *тестовая операция* или чего-то в этом духе. -АТОЛ предоставляет нам отдельную тестовую ККТ. +АТОЛ предоставляет нам отдельную тестовую среду (ККТ). [Её настройки](https://online.atol.ru/files/ffd/test_sreda.txt) уже указаны в коде библиотеки. -*Под тестовым режимом работы подразумевается использование этой тестовой ККТ.* +*Под тестовым режимом работы подразумевается использование другой (тестовой) ККТ.* + +При включенном тестовом режиме: +* меняется логин, пароль и группа (для обращения на тестовую ККТ) +* между авторизацией и операцией над документом, в `Company` документа переопределяется ИНН, СНО и адрес места +расчётов на те, что указаны в [параметрах тестовой среды](https://online.atol.ru/files/ffd/test_sreda.txt). В библиотеке есть переключатель настроек ККТ. С его помощью можете поменять вашу боевую ККТ на тестовую и наоборот. @@ -70,13 +75,43 @@ $kkt->setTestMode(false); // выключить > Если вы включили тестовый режим (как показано выше), то используются именно эта ККТ, а не ваша. > После выключения тестового режима настройки доступа к ККТ меняются на ваши (используется уже ваша ККТ). -Если по каким-то причинам у вас не получится использовать тестовый режим, вы можете проводить свои тесты в боевом режиме (на собственной ККТ). +Для включения тестового режима необязательно задавать параметры боевой ККТ. + +Если по каким-то причинам у вас не получится использовать тестовый режим, вы можете проводить свои тесты в боевом +режиме (на собственной ККТ). В этом случае важно понимать следующее: 1. сразу после оформления документа **прихода** необходимо оформлять точно такой же документ **возврата прихода**; 2. [вы обязательно забудете о пункте 1](http://murphy-law.net.ru/basics.html); 3. пп. 1 и 2 в любом случае скажутся на ваших финансовых отчётах; 4. вся ответственность за пп. 1-3 и последствия ложится только на вас. +## Авторизация ККТ + +Перед первым запросом на ККТ происходит авторизация на сервере по логину и паролю. +В ответ приходит авторизационный токен, срок жизни коего равен 24 часам. +После первой успешной операции возможно получить этот токен следующим образом: + +```php +$kkt->getAuthToken(); // вернёт строку длиной 128 символа +``` + +Этот токен можно сохранить и переиспользовать в течение всего срока его жизни. +Спустя это время следует получить новый токен. + +Однажды полученный токен, то для дальнейшего использования следует указывать его следующим образом: + +```php +$kkt->setAuthToken($token_string); +``` + +Если токен был установлен перед выполнением операции, то при выполнении операции будет использоваться именно он, а новый +запрашиваться не будет. Если операция завершится ошибочно из-за истёкшего токена, следует повторить операцию без +использования метода `setAuthToken()`, либо обнулив его следующим образом: + +```php +$kkt->setAuthToken(null); +``` + ## Регистрация документа Для регистрации документа **прихода** необходимо вызвать метод `sell()`: @@ -106,23 +141,44 @@ $result = $kkt->buyRefund($document); Для операций, перечисленных выше, документы не должны содержать [данных коррекции](/docs/documents.md#correction). Тогда как для операций коррекции, которые описаны ниже, эти данные должны присутствовать. -Для регистрации документа **коррекции прихода** необходимо вызвать метод `sellRefund()`: +Для регистрации документа **коррекции прихода** необходимо вызвать метод `sellCorrection()`: ```php $result = $kkt->sellCorrection($document); ``` -Для регистрации документа **коррекции расхода** необходимо вызвать метод `buyRefund()`: +Для регистрации документа **коррекции расхода** необходимо вызвать метод `buyCorrection()`: ```php $result = $kkt->buyCorrection($document); ``` +### Собственный идентификатор документа + +Каждый документ, переданный на ККТ для регистрации, всегда имеет свой идентификатор, абсолютно уникальный среди всех +документов когда-либо регистрировавшихся на ККТ, даже если при регистрации были ошибки. +По умолчанию это UUID версии 4. + +Чтобы использовать собственный идентификатор, следует передать нужное строковое значение вторым параметром в любой из +шести описанных выше методов, например: + +```php +$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 результат регистрации. -Вам необходимо расположить по этому адресу скрипт, обрабатывающий этот результат. +По этому адресу должен располагаться код, который будет обрабатывать этот результат. ```php $kkt->setCallbackUrl('http://example.com/process-kkt-result'); @@ -158,7 +214,7 @@ $err_text = $result->error->text; Проверка корректности ответа (отсутствия ошибок) работает через метод `isValid()`: ```php -$kkt->isValid(); // вернёт true, если ошибок нет +$kkt->getLastResponse()->isValid(); // вернёт true, если ошибок нет ``` ## Проверка статуса документа