238 lines
12 KiB
Markdown
238 lines
12 KiB
Markdown
|
# Фискализация документов
|
|||
|
|
|
|||
|
|
[Вернуться к содержанию](readme.md#toc)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Доступ к ККТ
|
|||
|
|
|
|||
|
|
Для работы с облачной ККТ необходимы следующие параметры:
|
|||
|
|
|
|||
|
|
* логин;
|
|||
|
|
* пароль;
|
|||
|
|
* код группы.
|
|||
|
|
|
|||
|
|
Чтоы получить их, нужно:
|
|||
|
|
|
|||
|
|
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\Fiscalizer();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Установить параметры подключения можно двумя путями:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
use AtolOnline\Api\Fiscalizer;
|
|||
|
|
|
|||
|
|
// 1 способ - через конструктор
|
|||
|
|
$kkt = new Fiscalizer(group: 'mygroup', login: 'mylogin', password: 'mypassword');
|
|||
|
|
|
|||
|
|
// 2 способ - через сеттеры
|
|||
|
|
$kkt = (new Fiscalizer())
|
|||
|
|
->setLogin($login)
|
|||
|
|
->setGroup($group)
|
|||
|
|
->setPassword($password);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
<a name="testmode"></a>
|
|||
|
|
|
|||
|
|
## Тестовый режим
|
|||
|
|
|
|||
|
|
По умолчанию фискализатор создаётся для работы в тестовом режиме. Это означает, что работа с АТОЛ Онлайн API будет
|
|||
|
|
происходить [в тестовой среде](https://online.atol.ru/files/ffd/test_sreda.txt).
|
|||
|
|
|
|||
|
|
> Под тестовым режимом работы подразумевается использование тестовых ККТ, которые принадлежат компании АТОЛ.
|
|||
|
|
|
|||
|
|
Управление тестовым режимом происходит следующим образом:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$kkt = new Fiscalizer(); // включен по умолчанию
|
|||
|
|
$kkt = new Fiscalizer(false); // выключен явно
|
|||
|
|
$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->getToken(); // вернёт строку длиной 128 символа
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Этот токен можно сохранить и переиспользовать в течение всего срока его жизни, но далее следует получить новый токен.
|
|||
|
|
|
|||
|
|
Ранее полученный токен следует указывать до отправки запросов следующим образом:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$kkt->setToken($token_string);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Если токен был установлен перед выполнением операции, то при выполнении операции будет использоваться именно он. Если
|
|||
|
|
операция завершится ошибочно из-за истёкшего токена, следует повторить операцию без использования метода `setToken()`,
|
|||
|
|
либо обнулив его следующим образом:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$kkt->setToken(null);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Тогда будет получен новый токен.
|
|||
|
|
|
|||
|
|
## Регистрация документа
|
|||
|
|
|
|||
|
|
Для регистрации документа **прихода** необходимо вызвать метод `sell()`:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->sell($document);
|
|||
|
|
$result2 = $receipt->sell($kkt);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Для регистрации документа **возврата прихода** необходимо вызвать метод `sellRefund()`:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->sellRefund($document);
|
|||
|
|
$result2 = $receipt->sellRefund($kkt);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Для регистрации документа **расхода** необходимо вызвать метод `buy()`:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->buy($document);
|
|||
|
|
$result2 = $receipt->buy($kkt);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Для регистрации документа **возврата расхода** необходимо вызвать метод `buyRefund()`:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->buyRefund($document);
|
|||
|
|
$result2 = $receipt->buyRefund($kkt);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Для регистрации документа **коррекции прихода** необходимо вызвать метод `sellCorrection()`:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->sellCorrect($document);
|
|||
|
|
$result2 = $correction->sellCorrect($kkt);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Для регистрации документа **коррекции расхода** необходимо вызвать метод `buyCorrection()`:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->buyCorrect($document);
|
|||
|
|
$result2 = $correction->buyCorrect($kkt);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Собственный идентификатор документа (`external_id`)
|
|||
|
|
|
|||
|
|
Каждый документ, переданный на ККТ для регистрации, всегда имеет свой идентификатор, абсолютно уникальный среди всех
|
|||
|
|
документов когда-либо регистрировавшихся на ККТ, даже если при регистрации были ошибки. По умолчанию это UUID версии 4.
|
|||
|
|
|
|||
|
|
Чтобы использовать собственный идентификатор, следует передать нужное строковое значение вторым параметром в любой из
|
|||
|
|
шести описанных выше методов, например:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$result = $kkt->sellRefund($document, 'order_' . $order->id);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Если `external_id` не указан явно или имеет пустое значение, то будет сгенерирован новый UUID. Узнать его можно будет
|
|||
|
|
только в ответе от ККТ после регистрации документа в очереди на фискализацию.
|
|||
|
|
|
|||
|
|
### Передача `callback_url`
|
|||
|
|
|
|||
|
|
Перед регистрацией документа можно указать `callback_url`. АТОЛ отправит на указанный URL результат регистрации. По
|
|||
|
|
этому адресу должен располагаться ваш собственный обработчик статуса фискализации.
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$kkt->setCallbackUrl('http://example.com/process-kkt-result');
|
|||
|
|
$kkt->getCallbackUrl();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## Проверка статуса документа
|
|||
|
|
|
|||
|
|
Если перед отправкой документа на регистрацию был задан `callback_url` через метод `setCallbackUrl()`, то ответ придёт
|
|||
|
|
на указанный адрес автоматически, как только документ обработается на стороне ККТ. Ответ может быть как об успешной
|
|||
|
|
регистрации, так и ошибочной.
|
|||
|
|
|
|||
|
|
В любом случае, вам доступны два метода, с помощью которых вы можете проверять статус документа самостоятельно:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$kkt->getDocumentStatus(); // делает единичный запрос
|
|||
|
|
$kkt->pollDocumentStatus(); // делает запросы до получения конечного статуса (не-wait)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Эти методы принимают на вход `uuid` кода регистрации. Этот UUID нужно взять из ответа, полученного при отправке
|
|||
|
|
документа на регистрацию:
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
$sell_result = $kkt->sell($document);
|
|||
|
|
$status = $kkt->pollDocumentStatus($sell_result->uuid);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Метод `pollDocumentStatus()` многократно опрашивает ККТ на предмет состояния документа. Метод может принимать до трёх
|
|||
|
|
параметров:
|
|||
|
|
|
|||
|
|
* uuid;
|
|||
|
|
* количество попыток (по умолчанию — 5);
|
|||
|
|
* время между попытками в секундах (по умолчанию — 1).
|
|||
|
|
|
|||
|
|
```php
|
|||
|
|
// Проверять статус 10 раз на протяжении 20 секунд — каждые две секунды
|
|||
|
|
$kkt->pollDocumentStatus($sell_result->uuid, 10, 20);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Учитывайте, что метод вернёт результат как только сменится статус регистрации на успешный `done` или ошибочный `error`.
|
|||
|
|
|
|||
|
|
Использовать его лучше сразу после отправки документа на регистрацию (как в примере выше).
|
|||
|
|
|
|||
|
|
> Как правило, фискализация одного документа занимает 4-6 секунд с учётом регистрации.
|
|||
|
|
|
|||
|
|
Метод `getDocumentStatus()` принимает на вход только `uuid` и запрашивает состояние документа лишь единожды.
|
|||
|
|
Использовать его целесообразнее в те моменты, когда нет необходимости знать успех регистрации сразу после отправки
|
|||
|
|
документа.
|
|||
|
|
|
|||
|
|
> Обратите внимание, что АТОЛ позволяет получать статус документа в течение 32 суток с момента его регистрации.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
Читай также: [Обработка ответа API](response.md)
|
|||
|
|
|
|||
|
|
[Вернуться к содержанию](readme.md#toc)
|