Освежил документацию в части работы с объектом Kkt

Также появился новый класс с константами тестовых параметров

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, если ошибок нет
 ```
 
 ## Проверка статуса документа

src/AtolOnline/Api/Kkt.php

@@ -9,7 +9,9 @@
 
 namespace AtolOnline\Api;
 
-use AtolOnline\{Entities\Document,
+use AtolOnline\{Constants\TestEnvParams,
+    Entities\Company,
+    Entities\Document,
     Exceptions\AtolCorrectionInfoException,
     Exceptions\AtolInvalidUuidException,
     Exceptions\AtolKktLoginEmptyException,
@@ -172,7 +174,7 @@ class Kkt extends Client
      */
     public function setCallbackUrl(string $url)
     {
-        $this->kkt_config['prod']['callback_url'] = $url;
+        $this->kkt_config[$this->isTestMode() ? 'test' : 'prod']['callback_url'] = $url;
         return $this;
     }
     
@@ -222,104 +224,115 @@ class Kkt extends Client
      * Регистрирует документ прихода
      *
      * @param \AtolOnline\Entities\Document $document
+     * @param string|null                   $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
      * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
      * @throws \AtolOnline\Exceptions\AtolCorrectionInfoException В документе есть данные коррекции
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    public function sell(Document $document)
+    public function sell(Document $document, ?string $external_id = null)
     {
         if ($document->getCorrectionInfo()) {
             throw new AtolCorrectionInfoException('Некорректная операция над документом коррекции');
         }
-        return $this->registerDocument('sell', 'receipt', $document);
+        return $this->registerDocument('sell', 'receipt', $document, $external_id);
     }
     
     /**
      * Регистрирует документ возврата прихода
      *
      * @param \AtolOnline\Entities\Document $document
+     * @param string|null                   $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
      * @throws \AtolOnline\Exceptions\AtolPriceTooHighException Слишком большая сумма
      * @throws \AtolOnline\Exceptions\AtolTooManyVatsException Слишком много ставок НДС
      * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
      * @throws \AtolOnline\Exceptions\AtolCorrectionInfoException В документе есть данные коррекции
      */
-    public function sellRefund(Document $document)
+    public function sellRefund(Document $document, ?string $external_id = null)
     {
         if ($document->getCorrectionInfo()) {
             throw new AtolCorrectionInfoException('Некорректная операция над документом коррекции');
         }
-        return $this->registerDocument('sell_refund', 'receipt', $document->clearVats());
+        return $this->registerDocument('sell_refund', 'receipt', $document->clearVats(), $external_id);
     }
     
     /**
      * Регистрирует документ коррекции прихода
      *
      * @param \AtolOnline\Entities\Document $document
+     * @param string|null                   $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
      * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
      * @throws \AtolOnline\Exceptions\AtolCorrectionInfoException В документе отсутствуют данные коррекции
      * @throws \AtolOnline\Exceptions\AtolTooManyItemsException Слишком много предметов расчёта
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    public function sellCorrection(Document $document)
+    public function sellCorrection(Document $document, ?string $external_id = null)
     {
         if (!$document->getCorrectionInfo()) {
             throw new AtolCorrectionInfoException();
         }
         $document->setClient(null)->setItems([]);
-        return $this->registerDocument('sell_correction', 'correction', $document);
+        return $this->registerDocument('sell_correction', 'correction', $document, $external_id);
     }
     
     /**
      * Регистрирует документ расхода
      *
      * @param \AtolOnline\Entities\Document $document
+     * @param string|null                   $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
      * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
      * @throws \AtolOnline\Exceptions\AtolCorrectionInfoException В документе есть данные коррекции
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    public function buy(Document $document)
+    public function buy(Document $document, ?string $external_id = null)
     {
         if ($document->getCorrectionInfo()) {
             throw new AtolCorrectionInfoException('Некорректная операция над документом коррекции');
         }
-        return $this->registerDocument('buy', 'receipt', $document);
+        return $this->registerDocument('buy', 'receipt', $document, $external_id);
     }
     
     /**
      * Регистрирует документ возврата расхода
      *
      * @param \AtolOnline\Entities\Document $document
+     * @param string|null                   $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
      * @throws \AtolOnline\Exceptions\AtolPriceTooHighException Слишком большая сумма
      * @throws \AtolOnline\Exceptions\AtolTooManyVatsException Слишком много ставок НДС
      * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
      * @throws \AtolOnline\Exceptions\AtolCorrectionInfoException В документе есть данные коррекции
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    public function buyRefund(Document $document)
+    public function buyRefund(Document $document, ?string $external_id = null)
     {
         if ($document->getCorrectionInfo()) {
             throw new AtolCorrectionInfoException('Некорректная операция над документом коррекции');
         }
-        return $this->registerDocument('buy_refund', 'receipt', $document->clearVats());
+        return $this->registerDocument('buy_refund', 'receipt', $document->clearVats(), $external_id);
     }
     
     /**
      * Регистрирует документ коррекции расхода
      *
      * @param Document    $document
+     * @param string|null $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
      * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
      * @throws \AtolOnline\Exceptions\AtolCorrectionInfoException В документе отсутствуют данные коррекции
      * @throws \AtolOnline\Exceptions\AtolTooManyItemsException Слишком много предметов расчёта
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    public function buyCorrection(Document $document)
+    public function buyCorrection(Document $document, ?string $external_id = null)
     {
         if (!$document->getCorrectionInfo()) {
             throw new AtolCorrectionInfoException();
         }
         $document->setClient(null)->setItems([]);
-        return $this->registerDocument('buy_correction', 'correction', $document);
+        return $this->registerDocument('buy_correction', 'correction', $document, $external_id);
     }
     
     /**
@@ -364,6 +377,28 @@ class Kkt extends Client
         return $response;
     }
     
+    /**
+     * Возвращает текущий токен авторизации
+     *
+     * @return string
+     */
+    public function getAuthToken(): ?string
+    {
+        return $this->auth_token;
+    }
+    
+    /**
+     * Устанавливает заранее известный токен авторизации
+     *
+     * @param string|null $auth_token
+     * @return $this
+     */
+    public function setAuthToken(?string $auth_token)
+    {
+        $this->auth_token = $auth_token;
+        return $this;
+    }
+    
     /**
      * Сбрасывает настройки ККТ по умолчанию
      */
@@ -374,9 +409,9 @@ class Kkt extends Client
         $this->kkt_config['prod']['pass'] = '';
         $this->kkt_config['prod']['url'] = 'https://online.atol.ru/possystem/v4';
         $this->kkt_config['prod']['callback_url'] = '';
-        $this->kkt_config['test']['group'] = 'v4-online-atol-ru_4179';
+        $this->kkt_config['test']['group'] = TestEnvParams::GROUP;
-        $this->kkt_config['test']['login'] = 'v4-online-atol-ru';
+        $this->kkt_config['test']['login'] = TestEnvParams::LOGIN;
-        $this->kkt_config['test']['pass'] = 'iGFFuihss';
+        $this->kkt_config['test']['pass'] = TestEnvParams::PASSWORD;
         $this->kkt_config['test']['url'] = 'https://testonline.atol.ru/possystem/v4';
         $this->kkt_config['test']['callback_url'] = '';
     }
@@ -390,7 +425,7 @@ class Kkt extends Client
     {
         $headers['Content-type'] = 'application/json; charset=utf-8';
         if ($this->getAuthToken()) {
-            $headers['Token'] = $this->auth_token;
+            $headers['Token'] = $this->getAuthToken();
         }
         return $headers;
     }
@@ -429,6 +464,7 @@ class Kkt extends Client
      * @param mixed      $data        Данные для передачи
      * @param array|null $options     Параметры Guzzle
      * @return \AtolOnline\Api\KktResponse
+     * @throws \GuzzleHttp\Exception\GuzzleException
      * @see https://guzzle.readthedocs.io/en/latest/request-options.html
      */
     protected function sendAtolRequest(string $http_method, string $api_method, $data = null, array $options = null)
@@ -449,6 +485,7 @@ class Kkt extends Client
      * Производит авторизацию на ККТ и получает токен доступа для дальнейших HTTP-запросов
      *
      * @return bool
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
     protected function auth()
     {
@@ -471,33 +508,30 @@ class Kkt extends Client
      * @param string                        $api_method  Метод API
      * @param string                        $type        Тип документа: receipt, correction
      * @param \AtolOnline\Entities\Document $document    Объект документа
+     * @param string|null                   $external_id Уникальный код документа (если не указан, то будет создан UUID)
      * @return \AtolOnline\Api\KktResponse
-     * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException Некорректный тип документа
+     * @throws \AtolOnline\Exceptions\AtolWrongDocumentTypeException
-     * @throws \Exception
+     * @throws \GuzzleHttp\Exception\GuzzleException
      */
-    protected function registerDocument(string $api_method, string $type, Document $document)
+    protected function registerDocument(string $api_method, string $type, Document $document, ?string $external_id = null)
     {
         $type = trim($type);
         if (!in_array($type, ['receipt', 'correction'])) {
             throw new AtolWrongDocumentTypeException($type);
         }
         $this->auth();
-        $data = [
+        if ($this->isTestMode()) {
-            'timestamp' => date('d.m.y H:i:s'),
+            $document->setCompany(($document->getCompany() ?: new Company())
-            'external_id' => Uuid::uuid4()->toString(),
+                ->setInn(TestEnvParams::INN)
-            'service' => ['callback_url' => $this->getCallbackUrl()],
+                ->setSno(TestEnvParams::SNO)
-            $type => $document,
+                ->setPaymentAddress(TestEnvParams::PAYMENT_ADDRESS));
-        ];
+        }
+        $data['timestamp'] = date('d.m.y H:i:s');
+        $data['external_id'] = $external_id ?: Uuid::uuid4()->toString();
+        $data[$type] = $document;
+        if ($this->getCallbackUrl()) {
+            $data['service'] = ['callback_url' => $this->getCallbackUrl()];
+        }
         return $this->sendAtolRequest('POST', trim($api_method), $data);
     }
-    
-    /**
-     * Возвращает текущий токен авторизации
-     *
-     * @return string
-     */
-    protected function getAuthToken()
-    {
-        return $this->auth_token;
-    }
 }

src/AtolOnline/Constants/TestEnvParams.php

@@ -0,0 +1,49 @@
+<?php
+/**
+ * Copyright (c) Антон Аксенов (aka Anthony Axenov)
+ *
+ * This code is licensed under MIT.
+ * Этот код распространяется по лицензии MIT.
+ * https://github.com/anthonyaxenov/atol-online/blob/master/LICENSE
+ */
+
+namespace AtolOnline\Constants;
+
+/**
+ * Константы, определяющие параметры тестовой среды
+ *
+ * @see     https://online.atol.ru/files/ffd/test_sreda.txt
+ * @package AtolOnline\Constants
+ */
+class TestEnvParams
+{
+    /**
+     * Логин
+     */
+    const LOGIN = 'v4-online-atol-ru';
+    
+    /**
+     * Пароль
+     */
+    const PASSWORD = 'iGFFuihss';
+    
+    /**
+     * Группа
+     */
+    const GROUP = 'v4-online-atol-ru_4179';
+    
+    /**
+     * Система налогообложения
+     */
+    const SNO = SnoTypes::OSN;
+    
+    /**
+     * ИНН
+     */
+    const INN = '5544332219';
+    
+    /**
+     * Адрес места расчётов
+     */
+    const PAYMENT_ADDRESS = 'https://v4.online.atol.ru';
+}

src/AtolOnline/Entities/Document.php

@@ -405,7 +405,7 @@ class Document extends Entity
             $json['company'] = $this->getCompany()->jsonSerialize(); // обязательно
         }
         if ($this->getPayments()) {
-            $json['payments'] = $this->getPayments()->jsonSerialize(); // обязательно
+            $json['payments'] = $this->payments->jsonSerialize(); // обязательно
         }
         if ($this->getCashier()) {
             $json['cashier'] = $this->getCashier();
@@ -417,7 +417,7 @@ class Document extends Entity
                 $json['client'] = $this->getClient()->jsonSerialize(); // обязательно для некоррекционных
             }
             if ($this->getItems()) {
-                $json['items'] = $this->getItems()->jsonSerialize(); // обязательно для некоррекционных
+                $json['items'] = $this->items->jsonSerialize(); // обязательно для некоррекционных
             }
             $json['total'] = $this->calcTotal(); // обязательно для некоррекционных
         }

src/AtolOnline/Entities/ItemArray.php

@@ -106,7 +106,7 @@ class ItemArray extends Entity
     protected function validateCount(?array $items = null): bool
     {
         if ((!empty($items) && count($items) >= self::MAX_COUNT) || count($this->items) >= self::MAX_COUNT) {
-            throw new AtolTooManyItemsException(self::MAX_COUNT);
+            throw new AtolTooManyItemsException(count($items), self::MAX_COUNT);
         }
         return true;
     }

src/AtolOnline/Entities/PaymentArray.php

@@ -9,7 +9,6 @@
 
 namespace AtolOnline\Entities;
 
-use AtolOnline\Api\SellSchema;
 use AtolOnline\Exceptions\AtolTooManyPaymentsException;
 
 /**
@@ -19,6 +18,11 @@ use AtolOnline\Exceptions\AtolTooManyPaymentsException;
  */
 class PaymentArray extends Entity
 {
+    /**
+     * Максимальное количество элементов массива
+     */
+    public const MAX_COUNT = 10;
+    
     /**
      * @var Payment[] Массив оплат
      */
@@ -99,9 +103,8 @@ class PaymentArray extends Entity
      */
     protected function validateCount(?array $payments = null): bool
     {
-        $max_items = SellSchema::get()->properties->receipt->properties->payments->maxItems;
+        if ((!empty($payments) && count($payments) >= self::MAX_COUNT) || count($this->payments) >= self::MAX_COUNT) {
-        if ((!empty($payments) && count($payments) >= $max_items) || count($this->payments) >= $max_items) {
+            throw new AtolTooManyPaymentsException(count($payments), self::MAX_COUNT);
-            throw new AtolTooManyPaymentsException($max_items);
         }
         return true;
     }

src/AtolOnline/Entities/VatArray.php

@@ -9,7 +9,6 @@
 
 namespace AtolOnline\Entities;
 
-use AtolOnline\Api\SellSchema;
 use AtolOnline\Exceptions\AtolTooManyVatsException;
 
 /**
@@ -19,6 +18,11 @@ use AtolOnline\Exceptions\AtolTooManyVatsException;
  */
 class VatArray extends Entity
 {
+    /**
+     * Максимальное количество элементов массива
+     */
+    public const MAX_COUNT = 6;
+    
     /**
      * @var Vat[] Массив ставок НДС
      */
@@ -103,9 +107,8 @@ class VatArray extends Entity
      */
     protected function validateCount(?array $vats = null): bool
     {
-        $max_items = SellSchema::get()->properties->receipt->properties->vats->maxItems;
+        if ((!empty($vats) && count($vats) >= self::MAX_COUNT) || count($this->vats) >= self::MAX_COUNT) {
-        if ((!empty($vats) && count($vats) >= $max_items) || count($this->vats) >= $max_items) {
+            throw new AtolTooManyVatsException(count($vats), self::MAX_COUNT);
-            throw new AtolTooManyVatsException(count($vats), $max_items);
         }
         return true;
     }