mirror of
https://github.com/anthonyaxenov/atol-online.git
synced 2024-11-16 16:33:40 +00:00
318 lines
16 KiB
Markdown
318 lines
16 KiB
Markdown
# Работа с ККТ
|
||
|
||
[Вернуться к содержанию](readme.md)
|
||
|
||
---
|
||
|
||
## Доступ к ККТ
|
||
|
||
Для работы с облачной ККТ необходимы следующие параметры:
|
||
|
||
* логин;
|
||
* пароль;
|
||
* код группы.
|
||
|
||
Чтоы получить их, нужно:
|
||
|
||
1. авторизоваться в личном кабинете [online.atol.ru](https://online.atol.ru/lk/Account/Login);
|
||
2. на странице [Мои компании](https://online.atol.ru/lk/Company/List) нажать кнопку **Настройки интегратора**.
|
||
Скачается XML-файл с нужными настройками.
|
||
|
||
Также для работы потребуются:
|
||
|
||
* ИНН продавца;
|
||
* URL места расчёта (ссылка на ваш интернет-сервис).
|
||
|
||
## Использование
|
||
|
||
Объект ККТ инициализируется следующим образом:
|
||
|
||
```php
|
||
$kkt = new AtolOnline\Api\Kkt();
|
||
```
|
||
|
||
## Настройка ККТ
|
||
|
||
Для работы с облачной ККТ необходимы следующие параметры:
|
||
* логин кассы;
|
||
* пароль кассы;
|
||
* код группы кассы;
|
||
|
||
Чтоб получить их, нужно:
|
||
1. авторизоваться на [online.atol.ru](https://online.atol.ru/lk/Account/Login);
|
||
2. на странице [Мои компании](https://online.atol.ru/lk/Company/List) нажать кнопку **Настройки интегратора**.
|
||
Скачается XML-файл с нужными настройками.
|
||
|
||
Установить эти параметры можно двумя путями:
|
||
|
||
```php
|
||
// 1 способ - через конструктор
|
||
$kkt = new AtolOnline\Api\Kkt($group, $login, $password);
|
||
|
||
// 2 способ - через сеттеры
|
||
$kkt = (new AtolOnline\Api\Kkt())
|
||
->setLogin($login)
|
||
->setGroup($group)
|
||
->setPassword($password);
|
||
```
|
||
|
||
Получить заданные параметры можно через соответствующие геттеры:
|
||
|
||
```php
|
||
$kkt->getLogin();
|
||
$kkt->getPassword();
|
||
$kkt->getGroup();
|
||
```
|
||
|
||
Также для работы потребуются:
|
||
* ИНН продавца;
|
||
* URL места расчёта (ссылка на ваш интернет-сервис).
|
||
|
||
Эти параметры нужно задать [объекту компании](/docs/company.md), который будет передаваться в документах через эту ККТ.
|
||
|
||
<a name='testmode'></a>
|
||
## Тестовый режим
|
||
|
||
На самом деле, в АТОЛ Онлайн нет понятия *тестовая операция* или чего-то в этом духе.
|
||
АТОЛ предоставляет нам отдельную тестовую среду (ККТ).
|
||
[Её настройки](https://online.atol.ru/files/ffd/test_sreda.txt) уже указаны в коде библиотеки.
|
||
*Под тестовым режимом работы подразумевается использование другой (тестовой) ККТ.*
|
||
|
||
При включенном тестовом режиме:
|
||
* меняется логин, пароль и группа (для обращения на тестовую ККТ)
|
||
* между авторизацией и операцией над документом, в `Company` документа переопределяется ИНН, СНО и адрес места
|
||
расчётов на те, что указаны в [параметрах тестовой среды](https://online.atol.ru/files/ffd/test_sreda.txt).
|
||
|
||
В библиотеке есть переключатель настроек ККТ.
|
||
С его помощью можете поменять вашу боевую ККТ на тестовую и наоборот.
|
||
Это можно сделать одним из следующих способов:
|
||
|
||
```php
|
||
// включить в любом месте кода:
|
||
$kkt->setTestMode();
|
||
$kkt->setTestMode(true);
|
||
$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()`:
|
||
|
||
```php
|
||
$result = $kkt->sell($document);
|
||
```
|
||
|
||
Для регистрации документа **возврата прихода** необходимо вызвать метод `sellRefund()`:
|
||
|
||
```php
|
||
$result = $kkt->sellRefund($document);
|
||
```
|
||
|
||
Для регистрации документа **расхода** необходимо вызвать метод `buy()`:
|
||
|
||
```php
|
||
$result = $kkt->buy($document);
|
||
```
|
||
|
||
Для регистрации документа **возврата расхода** необходимо вызвать метод `buyRefund()`:
|
||
|
||
```php
|
||
$result = $kkt->buyRefund($document);
|
||
```
|
||
|
||
Для операций, перечисленных выше, документы не должны содержать [данных коррекции](/docs/documents.md#correction).
|
||
Тогда как для операций коррекции, которые описаны ниже, эти данные должны присутствовать.
|
||
|
||
Для регистрации документа **коррекции прихода** необходимо вызвать метод `sellCorrection()`:
|
||
|
||
```php
|
||
$result = $kkt->sellCorrection($document);
|
||
```
|
||
|
||
Для регистрации документа **коррекции расхода** необходимо вызвать метод `buyCorrection()`:
|
||
|
||
```php
|
||
$result = $kkt->buyCorrection($document);
|
||
```
|
||
|
||
Любой из перечисленных выше шести методов может выбросить исключение `AtolAuthFailedException` при ошибке
|
||
аутентификации или авторизации.
|
||
|
||
### Собственный идентификатор документа
|
||
|
||
Каждый документ, переданный на ККТ для регистрации, всегда имеет свой идентификатор, абсолютно уникальный среди всех
|
||
документов когда-либо регистрировавшихся на ККТ, даже если при регистрации были ошибки.
|
||
По умолчанию это 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');
|
||
$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-декодированные данные тела ответа.
|
||
|
||
```php
|
||
$result = $kkt->getLastResponse(); // вернёт последний ответ от API
|
||
$headers = $result->getHeaders(); // вернёт заголовки
|
||
$code = $result->getCode(); // вернёт код ответа
|
||
$body = $result->getContent(); // вернёт JSON-декодированное тело ответа
|
||
```
|
||
|
||
Обращаться к полям JSON-декодированного объекта можно опуская вызов метода `getContent()` таким образом:
|
||
|
||
```php
|
||
// вернёт значение поля uuid
|
||
$uuid = $result->getContent()->uuid;
|
||
$uuid = $result->uuid;
|
||
// вернёт текст ошибки
|
||
$err_text = $result->getContent()->error->text;
|
||
$err_text = $result->error->text;
|
||
```
|
||
|
||
Проверка корректности ответа (отсутствия ошибок) работает через метод `isValid()`:
|
||
|
||
```php
|
||
$kkt->getLastResponse()->isValid(); // вернёт true, если ошибок нет
|
||
```
|
||
|
||
## Проверка статуса документа
|
||
|
||
Если перед отправкой документа на регистрацию был задан callback_url через метод `setCallbackUrl()`, то ответ придёт на указанный адрес автоматически, как только документ обработается на стороне ККТ.
|
||
Ответ может быть как об успешной регистрации, так и ошибочной.
|
||
|
||
В любом случае, вам доступны два метода, с помощью которых вы можете проверять статус документа самостоятельно:
|
||
|
||
```php
|
||
$kkt->getDocumentStatus();
|
||
$kkt->pollDocumentStatus();
|
||
```
|
||
|
||
Эти методы принимают на вход `uuid` кода регистрации.
|
||
Этот UUID можно получить из ответа, полученного при отправке документа на регистрацию:
|
||
|
||
```php
|
||
$sell_result = $kkt->sell($document);
|
||
$kkt->pollDocumentStatus($sell_result->uuid);
|
||
$kkt->getDocumentStatus($sell_result->uuid);
|
||
```
|
||
|
||
Метод `pollDocumentStatus()` многократно опрашивает ККТ на предмет состояния документа.
|
||
Метод может принимать до трёх параметров:
|
||
* uuid;
|
||
* количество попыток (по умолчанию — 5);
|
||
* время между попытками в секундах (по умолчанию — 1).
|
||
|
||
```php
|
||
// Проверять статус 10 раз на протяжении 20 секунд — каждые две секунды
|
||
$kkt->pollDocumentStatus($sell_result->uuid, 10, 20);
|
||
```
|
||
|
||
Учитывайте, что метод вернёт результат как только сменится статус регистрации на успешный или ошибочный.
|
||
|
||
Использовать его лучше сразу после отправки документа на регистрацию (как в примере выше).
|
||
|
||
> Как правило, полная регистрация одного документа занимает 4-5 секунд.
|
||
|
||
Метод `getDocumentStatus()` принимает на вход только `uuid` и запрашивает состояние документа лишь единожды.
|
||
Использовать его целесообразнее в те моменты, когда нет необходимости знать успех регистрации сразу после отправки документа.
|
||
|
||
> Обратите внимание, что АТОЛ позволяет получать статус документа в течение 32 суток с момента его регистрации.
|
||
|
||
Методы `pollDocumentStatus()` и `getDocumentStatus()` возвращают объект `AtolOnline\Api\KktResponse`.
|
||
Оба выбрасывают исключение `AtolUuidValidateException` (если переданная строка UUID невалидна).
|
||
|
||
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
|
||
|
||
```php
|
||
echo $item;
|
||
$json_string = (string)$item;
|
||
```
|
||
|
||
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
|
||
|
||
```php
|
||
$json_array = $item->jsonSerialize();
|
||
```
|
||
|
||
---
|
||
|
||
[Вернуться к содержанию](readme.md)
|