docs/client.md

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

docs/correction_info.md

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

docs/monitoring.md

@@ -1,116 +0,0 @@
-# Мониторинг ККТ
-
-[Вернуться к содержанию](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,7 +9,6 @@
 6. [Работа с данными коррекции](correction_info.md)
 7. [Работа с документами](documents.md)
 8. [Работа с ККТ](kkt.md)
-9. [Мониторинг ККТ](monitoring.md)
 
 ---
 

src/Entities/Client.php

@@ -53,23 +53,22 @@ 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
-     * @throws InvalidEmailException
-     * @throws InvalidInnLengthException
+     * @throws TooLongNameException Слишком длинное имя
+     * @throws TooLongPhoneException Слишком длинный телефон
+     * @throws TooLongEmailException Слишком длинный email
+     * @throws InvalidEmailException Невалидный email
+     * @throws InvalidInnLengthException Некорректная длина ИНН
      */
     public function __construct(
         ?string $name = null,
         ?string $email = null,
         ?string $phone = null,
         ?string $inn = null
-    )
-    {
-        !is_null($name) && $this->setName($name);
-        !is_null($email) && $this->setEmail($email);
-        !is_null($phone) && $this->setPhone($phone);
-        !is_null($inn) && $this->setInn($inn);
+    ) {
+        $name && $this->setName($name);
+        $email && $this->setEmail($email);
+        $phone && $this->setPhone($phone);
+        $inn && $this->setInn($inn);
     }
 
     /**
@@ -93,7 +92,7 @@ class Client extends Entity
      * @return $this
      * @throws TooLongNameException
      */
-    public function setName(?string $name): self
+    public function setName(?string $name): Client
     {
         if (is_string($name)) {
             $name = preg_replace('/[\n\r\t]/', '', trim($name));
@@ -158,7 +157,7 @@ class Client extends Entity
      * @return $this
      * @throws TooLongPhoneException
      */
-    public function setPhone(?string $phone): self
+    public function setPhone(?string $phone): Client
     {
         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): self
+    public function setSno(string $sno): Company
     {
         $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): self
+    public function setPaymentAddress(string $payment_address): Company
     {
         $payment_address = trim($payment_address);
         if (empty($payment_address)) {

src/Entities/Kkt.php

@@ -126,6 +126,19 @@ 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,4 +133,21 @@ 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());
+    }
 }