Правки по документации

- в мониторинг добавлено о приведении к строке
- актуализированы Client и Company
- мелочи в соотв. классах

docs/client.md

@@ -25,37 +25,21 @@ $customer = new AtolOnline\Entities\Client();
 // 1 способ - через конструктор
 $customer = new AtolOnline\Entities\Client(
     'John Doe', // наименование
-    '+1/22/99*73s dsdas654 5s6', // номер телефона +122997365456
     'john@example.com', // email
+    '+1/22/99*73s dsdas654 5s6', // номер телефона +122997365456
     '+fasd3\qe3fs_=nac990139928czc' // номер ИНН 3399013928
 );
 
 // 2 способ - через сеттеры
 $customer = (new AtolOnline\Entities\Client())
     ->setEmail('john@example.com')
-    ->setInn('+fasd3\q3fs_=nac9901 3928c-c') // 3399013928
+    ->setInn('+fasd3\q3fs_=nac9901 3928c-c')
     ->setName('John Doe')
-    ->setPhone('+1/22/99*73s dsdas654 5s6'); // +122997365456
+    ->setPhone('+1/22/99*73s dsdas654 5s6');
 
 // либо комбинация этих способов
 ```
 
-Метод `setEmail()` проверяет входную строку на длину (до 64 символов) и валидность формата email.
-Выбрасывает исключения:
-* `AtolEmailTooLongException` (если слишком длинный email);
-* `AtolEmailValidateException` (если email невалиден).
-
-Метод `setInn()` чистит входную строку от всех символов, кроме цифр, и проверяет длину (либо 10, либо 12 цифр).
-Выбрасывает исключение `AtolInnWrongLengthException` (если длина ИНН некорректна).
-
-Метод `setName()` проверяет входную строку на длину (до 256 символов).
-Выбрасывает исключение `AtolNameTooLongException` (если слишком длинное имя).
-
-Метод `setPhone()` чистит входную строку от всех символов, кроме цифр и знака `+`, и проверяет длину (до 64 символов).
-Выбрасывает исключение `AtolPhoneTooLongException` (если слишком длинный номер телефона).
-
-Конструктор может выбрасывать любое из указанных выше исключений, если в него передаются значения.
-
 Получить установленные значения атрибутов можно через геттеры:
 
 ```php
@@ -65,7 +49,7 @@ $customer->getName();
 $customer->getPhone();
 ```
 
-Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
+Объект класса приводится к JSON-строке автоматически или принудительно:
 
 ```php
 echo $customer;

docs/company.md

@@ -22,16 +22,16 @@ $customer = new AtolOnline\Entities\Company();
 Указать эти атрибуты можно двумя способами:
 
 ```php
-// 1 способ - через конструктор
+// 1 способ - через конструктор (все аргументы обязательны)
 $company = new AtolOnline\Entities\Company(
+    'company@example.com' // email
     AtolOnline\Constants\SnoTypes::OSN, // тип СНО
     '5544332219', // номер ИНН
     'https://v4.online.atol.ru', // адрес места расчётов
-    'company@example.com' // email
 );
 
 // 2 способ - через сеттеры
-$company = (new AtolOnline\Entities\Company())
+$company
     ->setEmail('company@example.com')
     ->setInn('5544332219')
     ->setSno(AtolOnline\Constants\SnoTypes::USN_INCOME)
@@ -40,19 +40,6 @@ $company = (new AtolOnline\Entities\Company())
 // либо комбинация этих способов
 ```
 
-Метод `setEmail()` проверяет входную строку на длину (до 64 символов) и валидность формата email.
-Выбрасывает исключения:
-* `AtolEmailTooLongException` (если слишком длинный email);
-* `AtolEmailValidateException` (если email невалиден).
-
-Метод `setInn()` чистит входную строку от всех символов, кроме цифр, и проверяет длину (либо 10, либо 12 цифр).
-Выбрасывает исключение `AtolInnWrongLengthException` (если длина ИНН некорректна).
-
-Метод `setPaymentAddress()` проверяет длину (до 256 символов).
-Выбрасывает исключение `AtolPaymentAddressTooLongException` (если слишком длинный адрес места расчётов).
-
-Конструктор может выбрасывать любое из указанных выше исключений, если в него передаются параметры.
-
 Получить установленные значения параметров можно через геттеры:
 
 ```php
@@ -62,7 +49,7 @@ $company->getPaymentAddress();
 $company->getSno();
 ```
 
-Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
+Объект класса приводится к JSON-строке автоматически или принудительно:
 
 ```php
 echo $company;

docs/correction_info.md

@@ -13,8 +13,7 @@ $info = new AtolOnline\Entities\CorrectionInfo();
 У объекта должны быть указаны все следующие обязательные атрибуты:
 * тип коррекции (тег ФФД 1173) - все типы перечислены в классе `AtolOnline\Constants\CorrectionTypes`;
 * дата документа основания для коррекции в формате `d.m.Y` (тег ФФД 1178);
-* номер документа основания для коррекции (тег ФФД 1179);
-* описание коррекции (тег ФФД 1177).
+* номер документа основания для коррекции (тег ФФД 1179).
 
 Указать эти атрибуты можно двумя способами:
 
@@ -26,14 +25,12 @@ $info = new CorrectionInfo(
     CorrectionTypes::SELF, // тип коррекции
     '01.01.2019', // дата документа коррекции
     '12345', // номер документа коррекции
-    'test' // описание коррекции
 );
 
 // 2 способ - через сеттеры
 $info = (new CorrectionInfo())
     ->setType(CorrectionTypes::INSTRUCTION)
     ->setDate('01.01.2019')
-    ->setName('test')
     ->setNumber('9999');
 
 // либо комбинация этих способов
@@ -44,7 +41,6 @@ $info = (new CorrectionInfo())
 ```php
 $info->getType();
 $info->getDate();
-$info->getName();
 $info->getNumber();
 ```
 

docs/monitoring.md

@@ -0,0 +1,116 @@
+# Мониторинг ККТ
+
+[Вернуться к содержанию](readme.md)
+
+---
+
+Библиотека предоставляет возможность следить за состоянием ваших облачных ККТ через API.
+
+## Инициализация
+
+Для этого следует использовать класс `KktMonitor`:
+
+```php
+// можно передать параметры подключения в конструктор
+$monitor = new AtolOnline\Api\KktMonitor(
+    login: 'mylogin',
+    password: 'qwerty'
+);
+
+// можно - отдельными сеттерами
+$monitor = new AtolOnline\Api\KktMonitor();
+    ->setLogin($credentials['login'])
+    ->setPassword($credentials['password']);
+```
+
+Логин и пароль для мониторинга те же, что для регистрации документов.
+
+**По умолчанию монитор работает в тестовом режиме.**
+Перевести его в боевой режим можно:
+
+```php
+// передачей в конструктор `false` первым параметром:
+$monitor = new AtolOnline\Api\KktMonitor(false, /*...*/);
+
+// или отдельным сеттером
+$monitor->setTestMode(false);
+```
+
+**Тестовый режим** нужен для проверки работоспособности библиотеки и API АТОЛ.
+
+**В боевом режиме** можно получать данные по своим ККТ.
+
+## Получение данных обо всех своих ККТ
+
+Для получения данных обо всех своих ККТ следует вызвать метод `AtolOnline\Api\KktMonitor::getAll()`:
+
+```php
+$kkts = $monitor->getAll();
+```
+
+В ответе будет итерируемая коллекция объектов `AtolOnline\Entities\Kkt`. Каждый из этих объектов содержит атрибуты:
+
+```php
+// для примера получим первую ККТ из всех
+$kkt = $kkts->first();
+
+// посмотрим на её атрибуты:
+$kkt->serialNumber; // Заводской номер ККТ
+$kkt->registrationNumber; // Регистрационный номер машины (РНМ)
+$kkt->deviceNumber; // Номер автоматического устройства (внутренний идентификатор устройства)
+$kkt->fiscalizationDate; // Дата активации (фискализации) ФН с указанием таймзоны
+$kkt->fiscalStorageExpiration; // Дата замены ФН (Срок действия ФН), с указанием таймзоны
+$kkt->signedDocuments; // Количество подписанных документов в ФН
+$kkt->fiscalStoragePercentageUse; // Наполненость ФН в %
+$kkt->fiscalStorageINN; // ИНН компании (указанный в ФН)
+$kkt->fiscalStorageSerialNumber; // Заводской (серийный) номер ФН
+$kkt->fiscalStoragePaymentAddress; // Адрес расчёта, указанный в ФН
+$kkt->groupCode; // Код группы кассы
+$kkt->timestamp; // Время и дата формирования данных, UTC
+$kkt->isShiftOpened; // Признак открыта смена (true) или закрыта (false)
+$kkt->shiftNumber; // Номер смены (или "Номер закрытой смены", когда смена закрыта)
+$kkt->shiftReceipt; // Номер документа за смену (или "Кол-во чеков закрытой смены", когда смена закрыта)
+$kkt->unsentDocs; // Количество неотправленных документов. Указывается, если значение отлично от 0.
+$kkt->firstUnsetDocTimestamp; // Дата первого неотправленного документа. Указывается, если есть неотправленные документы.
+$kkt->networkErrorCode; // Код ошибки сети
+```
+
+Эти поля описаны в документации мониторинга на [стр. 11](https://online.atol.ru/files/API_service_information.pdf)
+
+Сопоставления кодов ошибок и их описаний доступны в массиве `AtolOnline\Entities\Kkt::ERROR_CODES`.
+
+Объект класса приводится к JSON-строке автоматически или принудительно:
+
+```php
+echo $kkt;
+$json_string = (string)$kkt;
+```
+
+Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
+
+```php
+$json_array = $kkt->jsonSerialize();
+```
+
+## Получение данных об одной из своих ККТ
+
+Для этого следует вызвать метод `AtolOnline\Api\KktMonitor::getOne()`, передав на вход серийный номер (`serialNumber`)
+нужной ККТ:
+
+```php
+$kkt = $monitor->getOne($kkts->first()->serialNumber);
+```
+
+Метод вернёт единственный объект `AtolOnline\Entities\Kkt` с атрибутами, описанными выше.
+
+## Получение последнего ответа от сервера
+
+Класс `AtolOnline\Api\KktMonitor` расширяет абстрактный класс `AtolOnline\Api\AtolClient`.
+
+Это значит, что последний ответ от API АТОЛ всегда сохраняется объектом класса `AtolOnline\Api\KktResponse`. К нему
+можно обратиться через метод `AtolOnline\Api\KktMonitor::getResponse()`, независимо от того, что возвращают другие
+методы монитора.
+
+---
+
+[Вернуться к содержанию](readme.md)

docs/readme.md

@@ -1,4 +1,4 @@
-# Документация к библиотеке atol-online
+# Документация к библиотеке
 
 Содержание:
 1. [Работа с клиентами (покупателями)](client.md)
@@ -9,6 +9,7 @@
 6. [Работа с данными коррекции](correction_info.md)
 7. [Работа с документами](documents.md)
 8. [Работа с ККТ](kkt.md)
+9. [Мониторинг ККТ](monitoring.md)
 
 ---
 

src/Entities/Client.php

@@ -53,22 +53,23 @@ class Client extends Entity
      * @param string|null $phone Email. Тег ФФД - 1008.
      * @param string|null $email Телефон покупателя. Тег ФФД - 1008.
      * @param string|null $inn ИНН. Тег ФФД - 1228.
-     * @throws TooLongNameException Слишком длинное имя
-     * @throws TooLongPhoneException Слишком длинный телефон
-     * @throws TooLongEmailException Слишком длинный email
-     * @throws InvalidEmailException Невалидный email
-     * @throws InvalidInnLengthException Некорректная длина ИНН
+     * @throws TooLongNameException
+     * @throws TooLongPhoneException
+     * @throws TooLongEmailException
+     * @throws InvalidEmailException
+     * @throws InvalidInnLengthException
      */
     public function __construct(
         ?string $name = null,
         ?string $email = null,
         ?string $phone = null,
         ?string $inn = null
-    ) {
-        $name && $this->setName($name);
-        $email && $this->setEmail($email);
-        $phone && $this->setPhone($phone);
-        $inn && $this->setInn($inn);
+    )
+    {
+        !is_null($name) && $this->setName($name);
+        !is_null($email) && $this->setEmail($email);
+        !is_null($phone) && $this->setPhone($phone);
+        !is_null($inn) && $this->setInn($inn);
     }
 
     /**
@@ -92,7 +93,7 @@ class Client extends Entity
      * @return $this
      * @throws TooLongNameException
      */
-    public function setName(?string $name): Client
+    public function setName(?string $name): self
     {
         if (is_string($name)) {
             $name = preg_replace('/[\n\r\t]/', '', trim($name));
@@ -157,7 +158,7 @@ class Client extends Entity
      * @return $this
      * @throws TooLongPhoneException
      */
-    public function setPhone(?string $phone): Client
+    public function setPhone(?string $phone): self
     {
         if (is_string($phone)) {
             $phone = preg_replace('/[^\d]/', '', trim($phone));

src/Entities/Company.php

@@ -125,7 +125,7 @@ class Company extends Entity
      * @return $this
      * @throws InvalidSnoException
      */
-    public function setSno(string $sno): Company
+    public function setSno(string $sno): self
     {
         $sno = trim($sno);
         if (empty($sno) || !in_array($sno, SnoTypes::toArray())) {
@@ -188,7 +188,7 @@ class Company extends Entity
      * @throws TooLongPaymentAddressException
      * @throws InvalidPaymentAddressException
      */
-    public function setPaymentAddress(string $payment_address): Company
+    public function setPaymentAddress(string $payment_address): self
     {
         $payment_address = trim($payment_address);
         if (empty($payment_address)) {

src/Entities/Kkt.php

@@ -126,19 +126,6 @@ final class Kkt extends Entity
         return $this->data->$name;
     }
 
-    /**
-     * Возвращает объект с информацией о сетевой ошибке
-     *
-     * @return object
-     */
-    public function getNetworkError(): object
-    {
-        return (object)[
-            'code' => $this->data->networkErrorCode,
-            'text' => self::ERROR_CODES[$this->data->networkErrorCode],
-        ];
-    }
-
     /**
      * @inheritDoc
      */

tests/KktEntityTest.php

@@ -133,21 +133,4 @@ class KktEntityTest extends BasicTestCase
         $this->expectException(Exception::class);
         (new Kkt((object)$this->sample_data))->firstUnsetDocTimestamp;
     }
-
-    /**
-     * Тестирует получение данных о сетевой ошибке
-     *
-     * @covers \AtolOnline\Entities\Kkt::getNetworkError
-     * @throws EmptyMonitorDataException
-     * @throws NotEnoughMonitorDataException
-     */
-    public function testGetNetworkError(): void
-    {
-        $kkt = new Kkt((object)$this->sample_data);
-        $this->assertIsObject($kkt->getNetworkError());
-        $this->assertEquals((object)[
-            'code' => $kkt->networkErrorCode,
-            'text' => $kkt::ERROR_CODES[$kkt->networkErrorCode],
-        ], $kkt->getNetworkError());
-    }
 }