Abandoned/atol-online
Archived
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Initial commit, v0.1.0-b

Browse Source
This commit is contained in:
Anthony Axenov
2020-01-11 14:30:25 +08:00
commit 1db2d5b49f
67 changed files with 7680 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

75
docs/client.md Normal file
View File

@@ -0,0 +1,75 @@
# Работа с клиентами (покупателями)
Объект покупателя инициализируется следующим образом:
```php
$customer = new AtolOnline\Entities\Client();
```
У объекта покупателя могут быть указаны любые из следующих атрибутов:
* email (тег ФФД 1008);
* ИНН (тег ФФД 1128);
* наименование (тег ФФД 1127);
* номер телефона (тег ФФД 1008).
> Все эти атрибуты являются **необязательными**.
> Если указаны одновременно и email, и номер телефона, то ОФД отправит чек только на email.
Указать эти атрибуты можно двумя способами:
```php
// 1 способ - через конструктор
$customer = new AtolOnline\Entities\Client(
'John Doe', // наименование
'+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') // 3399013928
->setName('John Doe')
->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
$customer->getInn();
$customer->getEmail();
$customer->getName();
$customer->getPhone();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $customer;
$json_string = (string)$customer;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $customer->jsonSerialize();
```

72
docs/company.md Normal file
View File

@@ -0,0 +1,72 @@
# Работа с компанией (продавцом)
Объект компании инициализируется следующим образом:
```php
$customer = new AtolOnline\Entities\Company();
```
У объекта компании должны быть указаны все следующие атрибуты:
* email (тег ФФД 1117);
* ИНН (тег ФФД 1018);
* тип системы налогообложения (тег ФФД 1055) - все типы перечислены в классе `AtolOnline\Constants\SnoTypes`;
* адрес места расчётов (тег ФФД 1187) - для интернет-сервисов указывается URL с протоколом.
> Все эти атрибуты являются **обязательными**.
> Для тестового режима используйте значения ИНН и адреса места расчётов, [указанные здесь](https://online.atol.ru/files/ffd/test_sreda.txt).
Указать эти атрибуты можно двумя способами:
```php
// 1 способ - через конструктор
$company = new AtolOnline\Entities\Company(
AtolOnline\Constants\SnoTypes::OSN, // тип СНО
'5544332219', // номер ИНН
'https://v4.online.atol.ru', // адрес места расчётов
'company@example.com' // email
);
// 2 способ - через сеттеры
$company = (new AtolOnline\Entities\Company())
->setEmail('company@example.com')
->setInn('5544332219')
->setSno(AtolOnline\Constants\SnoTypes::USN_INCOME)
->setPaymentAddress('https://v4.online.atol.ru');
// либо комбинация этих способов
```
Метод `setEmail()` проверяет входную строку на длину (до 64 символов) и валидность формата email.
Выбрасывает исключения:
* `AtolEmailTooLongException` (если слишком длинный email);
* `AtolEmailValidateException` (если email невалиден).
Метод `setInn()` чистит входную строку от всех символов, кроме цифр, и проверяет длину (либо 10, либо 12 цифр).
Выбрасывает исключение `AtolInnWrongLengthException` (если длина строка ИНН некорректна).
Метод `setPaymentAddress()` проверяет длину (до 256 символов).
Выбрасывает исключение `AtolPaymentAddressTooLongException` (если слишком длинный адрес места расчётов).
Конструктор может выбрасывать любое из указанных выше исключений, если в него передаются параметры.
Получить установленные значения параметров можно через геттеры:
```php
$company->getInn();
$company->getEmail();
$company->getPaymentAddress();
$company->getSno();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $company;
$json_string = (string)$company;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $company->jsonSerialize();
```

65
docs/correction_info.md Normal file
View File

@@ -0,0 +1,65 @@
# Работа с данными коррекции
Объект для данных коррекции инициализируется следующим образом:
```php
$info = new AtolOnline\Entities\CorrectionInfo();
```
У объекта должны быть указаны все следующие обязательные атрибуты:
* тип коррекции (тег ФФД 1173) - все типы перечислены в классе `AtolOnline\Constants\CorrectionTypes`;
* дата документа основания для коррекции в формате `d.m.Y` (тег ФФД 1178);
* номер документа основания для коррекции (тег ФФД 1179);
* описание коррекции (тег ФФД 1177).
Указать эти атрибуты можно двумя способами:
```php
use AtolOnline\{Entities\CorrectionInfo, Constants\CorrectionTypes};
// 1 способ - через конструктор
$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');
// либо комбинация этих способов
```
Получить установленные значения атрибутов можно через геттеры:
```php
$info->getType();
$info->getDate();
$info->getName();
$info->getNumber();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $customer;
$json_string = (string)$customer;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $customer->jsonSerialize();
```

159
docs/documents.md Normal file
View File

@@ -0,0 +1,159 @@
# Работа с документами
Объект документа инициализируется следующим образом:
```php
$doc = new AtolOnline\Entities\Document();
```
Для документов **прихода, возврата прихода, расхода и возврата расхода** должны быть указаны все следующие обязательные атрибуты:
* [клиент](/docs/client.md);
* [компания](/docs/company.md);
* [предметы расчёта](/docs/items.md);
* [оплаты](/docs/payments.md).
Для документов **коррекции прихода и коррекции расхода** должны быть указаны все следующие обязательные атрибуты:
* [компания](/docs/company.md);
* [оплаты](/docs/payments.md);
* [ставки НДС](/docs/vats.md);
* [данные коррекции](/docs/correction_info.md).
Для любых документов также могут быть указаны следующие необязательные атрибуты:
* ФИО кассира (тег ФФД - 1021).
Установка атрибутов документа происходит через сеттеры.
## Работа с клиентом
Для этого существуют следующие методы:
```php
$doc->setClient($client);
$doc->getClient();
```
> О работе с клиентами более подробно читайте [здесь](/docs/client.md).
## Работа с компанией
Для этого существуют следующие методы:
```php
$doc->setCompany($company);
$doc->getCompany();
```
> О работе с компаниями более подробно читайте [здесь](/docs/company.md).
## Работа с предметами расчёта
Внутри документа существует [массив предметов расчёта](/docs/items.md#array).
По умолчанию он пуст.
Напрямую для манипуляций объект массива недоступен.
Работа с ним происходит через методы документа:
```php
$doc->setItems([$item1, $item2]);
$doc->addItem($item3);
$doc->getItems();
```
Соответственно, эти методы выбрасывают те же исключения, что методы самого массива.
## Работа с оплатами
Внутри документа существует [массив оплат](/docs/payments.md#array).
По умолчанию он пуст.
Напрямую для манипуляций объект массива недоступен.
Работа с ним происходит через методы документа:
```php
$doc->setPayments([$payment1, $payment2]);
$doc->addPayment($payment3);
$doc->getPayments();
```
Соответственно, эти методы выбрасывают те же исключения, что методы самого массива.
Следует отметить, что если при выполнении метода `addPayment()` выполняются следующие условия:
* аргументом передан объект оплаты, у которого не задана сумма,
* ранее документу не задавались оплаты,
то автоматически этому объекту оплаты задаётся полная сумма чека.
## Работа со ставками НДС
Внутри документа существует [массив ставок НДС](/docs/vats.md#array).
По умолчанию он пуст.
Напрямую для манипуляций объект массива недоступен.
Работа с ним происходит через методы документа:
```php
$doc->setVats([$vat1, $vat2]);
$doc->addVat($vat3);
$doc->getVats();
```
Соответственно, эти методы выбрасывают те же исключения, что методы самого массива.
Также существует метод `clearVats()`, который удаляет все вложенные объекты ставок НДС - из предметов расчёта и самого документа.
Следует отметить, что если при выполнении метода `addVat()` выполняются следующие условия:
* аргументом передан объект ставки, у которого не задана сумма,
* ранее документу не задавались ставки,
то автоматически этому объекту налога задаётся полная сумма чека, от которой расчитывается итоговый размер налога.
## Общая сумма документа
Расчёт происходит автоматически в следующих случаях:
* изменение предметов расчёта (`setItems()`, `addItem()`);
* добавление оплат (`addPayment()` в случае, когда оплата передана без суммы);
* изменение ставок НДС (`setVats()`, `clearVats()`, `addVat()` в случае, когда ставка передана без суммы);
* приведение объекта документа к строке.
Также можно вызвать вручную метод `calcTotal()`.
Он расчитывает полную сумму чека по предметам расчёта и пересчитывает **все** налоговые ставки.
Получить итог можно с помощью метода `getTotal()`.
Всё в рублях.
<a name='correction'></a>
## Работа с данными коррекции
Если документ создаётся с целью коррекции прихода или расхода, то он обязательно должен содержать [данные коррекции](/docs/correction_info.md).
Задать и получить эти данные очень просто:
```php
$doc->setCorrectionInfo(new AtolOnline\Entities\CorrectionInfo(
AtolOnline\Constants\CorrectionTypes::SELF, // тип коррекции
'01.01.2019', // дата документа коррекции
'12345', // номер документа коррекции
'test' // описание коррекции
));
$doc->getCorrectionInfo();
```
## Работа с кассиром
Для этого существуют следующие методы:
```php
$doc->setCashier('Иванова Лариса Васильевна');
$doc->getCashier();
```
## Прочее
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $doc;
$json_string = (string)$doc;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $doc->jsonSerialize();
```

194
docs/items.md Normal file
View File

@@ -0,0 +1,194 @@
# Работа с предметами расчёта
## Один объект
Объект предмета расчёта инициализируется следующим образом:
```php
$vat = new AtolOnline\Entities\Item();
```
У объекта предмета расчёта должны быть указаны все следующие обязательные атрибуты:
* наименование (тег ФФД - 1030);
* цена (тег ФФД - 1079);
* количество, вес (тег ФФД - 1023).
У объекта предмета расчёта также могут быть указаны следующие необязательные атрибуты:
* единица измерения количества (тег ФФД - 1197);
* признак способа оплаты (тег ФФД - 1214) - перечислены в классе `AtolOnline\Constants\PaymentMethods`;
* признак предмета расчёта (тег ФФД - 1212) - перечислены в классе `AtolOnline\Constants\PaymentObjects`;
* [ставка НДС](/docs/vats.md);
* дополнительный реквизит (тег ФФД - 1191).
Установить многие (но не все) атрибуты можно следующими способами:
```php
use AtolOnline\{
Constants\PaymentMethods,
Constants\PaymentObjects,
Constants\VatTypes,
Entities\Item
};
// 1 способ - через конструктор
$item = new Item(
'Банан', // наименование
100, // цена
1, // количество, вес
'кг', // единица измерения
VatTypes::VAT20, // ставка НДС
PaymentObjects::SERVICE, // признак предмета расчёта
PaymentMethods::FULL_PAYMENT // признак способа расчёта
);
// 2 способ - через сеттеры
$item = new Item();
$item->setName('Банан');
$item->setPrice(100);
$item->setQuantity(2.41);
//$item->setQuantity(2.41, 'кг');
$item->setMeasurementUnit('кг');
$item->setVatType(VatTypes::VAT20);
$item->setPaymentObject(PaymentObjects::COMMODITY);
$item->setPaymentMethod(PaymentMethods::FULL_PAYMENT);
```
Метод `setName()` проверяет входную строку на длину (до 128 символов).
Выбрасывает исключение `AtolNameTooLongException` (если слишком длинное наименование).
Метод `setPrice()` проверяет аргумент на величину (до 42949672.95) и пересчитывает общую стоимость.
Выбрасывает исключение `AtolPriceTooHighException` (если цена слишком высока).
Метод `setMeasurementUnit()` проверяет входную строку на длину (до 16 символов).
Выбрасывает исключение `AtolUnitTooLongException` (если слишком длинная строка единицы измерения).
Метод `setQuantity()` проверяет первый аргумент на величину (до 99999.999) и пересчитывает общую стоимость.
Выбрасывает исключения:
* `AtolQuantityTooHighException` (если количество слишком велико);
* `AtolPriceTooHighException` (если общая стоимость слишком велика).
Также вторым аргументом может принимать единицу измерения количества.
В этом случае дополнительно работает сеттер `setMeasurementUnit()`.
Метод `setVatType()` задаёт тип ставки НДС, пересчитывает размер налога и общую стоимость.
Выбрасывает исключение `AtolPriceTooHighException` (если цена слишком высока).
Может принимать `null` для удаления налога.
Дополнительный реквизит устанавливается отдельным методом `setUserData()`:
```php
$item->setUserData('some data');
```
Он проверяет строку на длину (до 64 символов).
Выбрасывает исключение `AtolUserdataTooLongException` (если слишком длинный дополнительный реквизит).
Для установки признака предмета расчёта существует метод `setPaymentObject()`.
На вход следует передавать одной из значений, перечисленных в классе `AtolOnline\Constants\PaymentObjects`.
```php
$item->setPaymentObject(AtolOnline\Constants\PaymentObjects::JOB);
```
Для установки признака способа оплаты существует метод `setPaymentMethod()`.
На вход следует передавать одной из значений, перечисленных в классе `AtolOnline\Constants\PaymentMethods`.
```php
$item->setPaymentMethod(AtolOnline\Constants\PaymentMethods::FULL_PAYMENT);
```
Для получения заданных значений атрибутов реализованы соответствующие геттеры:
```php
$item->getName();
$item->getPrice();
$item->getQuantity();
$item->getMeasurementUnit();
$item->getPaymentMethod();
$item->getPaymentObject();
$item->getVat(); // возвращает объект ставки НДС либо null
$item->getUserData();
```
Для пересчёта общей стоимости и размера налога существует метод `calcSum()`.
```php
$item->calcSum();
```
Этот метод отрабатывает при вызове `setPrice()`, `setQuantity()` и `setVatType()`.
Выбрасывает исключение `AtolPriceTooHighException` (если общая сумма слишком высока).
Получить уже расчитанную общую сумму можно простым геттером:
```php
$item->getSum();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $item;
$json_string = (string)$item;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $item->jsonSerialize();
```
<a name="array"></a>
## Массив объектов предметов расчёта
> Максимальное количество объектов в массиве - 100.
Массив инициализируется следующим образом:
```php
$item_array = new AtolOnline\Entities\ItemArray();
```
Чтобы задать содержимое массива, используйте метод `set()`:
```php
$item_array->set([
$item_object1,
$item_object2
]);
```
Очистить его можно передачей в сеттер пустого массива:
```php
$item_array->set([]);
```
Чтобы добавить объект к существующим элементам массива, используйте метод `add()`:
```php
$item = new AtolOnline\Entities\Item('Банан', 100, 1);
$item_array->add($item);
```
Методы `set()` и `add()` проверяют количество элементов в массиве перед его обновлением.
Выбрасывают исключение `AtolTooManyItemsException` (если в массиве уже максимальное количество объектов).
Чтобы получить содержимое массива, используйте метод `get()`:
```php
$item_array->get();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $item_array;
$json_string = (string)$item_array;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $item_array->jsonSerialize();
```

217
docs/kkt.md Normal file
View File

@@ -0,0 +1,217 @@
# Работа с ККТ
Объект ККТ инициализируется следующим образом:
```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), который будет передаваться в документах через эту ККТ.
## Тестовый режим
На самом деле, в АТОЛ Онлайн нет понятия *тестовая операция* или чего-то в этом духе.
АТОЛ предоставляет нам отдельную тестовую ККТ.
[Её настройки](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 и последствия ложится только на вас.
## Регистрация документа
Для регистрации документа **прихода** необходимо вызвать метод `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).
Тогда как для операций коррекции, которые описаны ниже, эти данные должны присутствовать.
Для регистрации документа **коррекции прихода** необходимо вызвать метод `sellRefund()`:
```php
$result = $kkt->sellCorrection($document);
```
Для регистрации документа **коррекции расхода** необходимо вызвать метод `buyRefund()`:
```php
$result = $kkt->buyCorrection($document);
```
### Передача callback_url
Перед регистрацией документа можно указать `callback_url`.
АТОЛ отправит на указанный URL результат регистрации.
Вам необходимо расположить по этому адресу скрипт, обрабатывающий этот результат.
```php
$kkt->setCallbackUrl('http://example.com/process-kkt-result');
$kkt->getCallbackUrl();
```
## Обработка результата регистрации
Методы `sell()`, `sellRefund()`, `sellCorrection()`, `buy()`, `buyRefund()` и `buyCorrection()` возвращают объект `AtolOnline\Api\KktResponse`.
Этот же объект можно получить через геттер `getLastResponse()`.
Этот объект содержит в себе HTTP-код ответа, массив заголовков и JSON-декодированные данные тела ответа.
```php
$result = $kkt->getLastResponse();
$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->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();
```

126
docs/payments.md Normal file
View File

@@ -0,0 +1,126 @@
# Работа с оплатами
## Один объект
Объект оплаты инициализируется следующим образом:
```php
$payment = new AtolOnline\Entities\Payment();
```
У объекта оплаты должны быть указаны все следующие атрибуты:
* тип оплаты (теги ФФД: 1031, 1081, 1215, 1216, 1217) - все типы перечислены в классе `AtolOnline\Constants\PaymentTypes` (по умолчанию `ELECTRON`)
* сумма оплаты (теги ФФД: 1031, 1081, 1215, 1216, 1217; по умолчанию 0)
> Все эти атрибуты являются **обязательными**.
Установить атрибуты можно следующими способами:
```php
// 1 способ - через конструктор
$payment = new AtolOnline\Entities\Payment(
AtolOnline\Constants\PaymentTypes::OTHER, // тип оплаты
123.45 // сумма оплаты
);
// 2 способ - через сеттер
$payment = (new AtolOnline\Entities\Payment())
->setType(AtolOnline\Constants\PaymentTypes::OTHER) // тип оплаты
->setSum(123.45); // сумма оплаты
```
Размер налога высчитывается автоматически из общей суммы.
Сумму, от которой нужно расчитать размер налога, можно передать следующими способами:
```php
// 1 способ - через конструктор
$payment = new AtolOnline\Entities\Payment(
AtolOnline\Constants\PaymentTypes::CASH, // тип оплаты
1234.56 // сумма оплаты в рублях
);
// 2 способ - через сеттер
$payment = (new AtolOnline\Entities\Payment())
->setType(AtolOnline\Constants\PaymentTypes::CASH) // тип оплаты
->setSum(1234.56); // сумма оплаты в рублях
```
Получить установленную сумму оплаты в рублях можно через геттер `getSum()`:
```php
var_dump($payment->getSum());
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $payment;
$json_string = (string)$payment;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $payment->jsonSerialize();
```
<a name="array"></a>
## Массив объектов оплат
> Максимальное количество объектов в массиве - 10.
Массив инициализируется следующим образом:
```php
$payment_array = new AtolOnline\Entities\PaymentArray();
```
Чтобы задать содержимое массива, используйте метод `set()`:
```php
use AtolOnline\{Constants\PaymentTypes, Entities\Payment};
$payment_array->set([
new Payment(PaymentTypes::ELECTRON, 123),
new Payment(PaymentTypes::ELECTRON, 53.2),
new Payment(PaymentTypes::ELECTRON, 23.99),
new Payment(PaymentTypes::ELECTRON, 11.43)
]);
```
Очистить его можно передачей в сеттер пустого массива:
```php
$payment_array->set([]);
```
Чтобы добавить объект к существующим элементам массива, используйте метод `add()`:
```php
use AtolOnline\{Constants\PaymentTypes, Entities\Payment};
$payment = new Payment(PaymentTypes::PRE_PAID, 20);
$payment_array->add($payment);
```
Методы `set()` и `add()` проверяют количество элементов в массиве перед его обновлением.
Выбрасывают исключение `AtolTooManyPaymentsException` (если в массиве уже максимальное количество объектов).
Чтобы получить содержимое массива, используйте метод `get()`:
```php
$payment_array->get();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $payment_array;
$json_string = (string)$payment_array;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $payment_array->jsonSerialize();
```

14
docs/readme.md Normal file
View File

@@ -0,0 +1,14 @@
# Документация к библиотеке atol-online
Содержание:
1. [Работа с клиентами (покупателями)](client.md)
2. [Работа с компанией (продавцом)](company.md)
3. [Работа с оплатами](payments.md)
4. [Работа со ставками НДС](vats.md)
5. [Работа с предметами расчёта](items.md)
6. [Работа с документами](documents.md)
7. [Работа с ККТ](kkt.md)
---
Если вы нашли опечатку или какое-то несоответствие — делайте pull-request.

186
docs/vats.md Normal file
View File

@@ -0,0 +1,186 @@
# Работа со ставками НДС
## Один объект
Объект ставки НДС инициализируется следующим образом:
```php
$vat = new AtolOnline\Entities\Vat();
```
У объекта ставки должны быть указаны все следующие атрибуты:
* тип ставки (теги ФФД: 1199 для предмета расчёта; 1105, 1104, 1103, 1102, 1107, 1106 для чека) - все типы перечислены в классе `AtolOnline\Constants\VatTypes` (по умолчанию `NONE`)
* размер налога (теги ФФД: 1200 для предмета расчёта; 1105, 1104, 1103, 1102, 1107, 1106 для чека)
> Все эти атрибуты являются **обязательными**.
Установить тип ставки НДС можно следующими способами:
```php
// 1 способ - через конструктор
$vat = new AtolOnline\Entities\Vat(
AtolOnline\Constants\VatTypes::VAT20 // тип ставки
);
// 2 способ - через сеттер
$vat = (new AtolOnline\Entities\Vat())
->setType(AtolOnline\Constants\VatTypes::VAT20); // тип ставки
```
Размер налога высчитывается автоматически из общей суммы.
Сумму, от которой нужно расчитать размер налога, можно передать следующими способами:
```php
// 1 способ - через конструктор
$vat = new AtolOnline\Entities\Vat(
AtolOnline\Constants\VatTypes::VAT10, // тип ставки
1234.56 // общая сумма в рублях
);
// 2 способ - через сеттер
$vat = (new AtolOnline\Entities\Vat())
->setType(AtolOnline\Constants\VatTypes::VAT10) // тип ставки
->setSum(150); // общая сумма в рублях
```
Сумму можно установить и до установки типа ставки.
Объект её запомнит и пересчитает итоговый размер налога при смене типа ставки:
```php
$vat = (new AtolOnline\Entities\Vat())
->setSum(150) // общая сумма в рублях
->setType(AtolOnline\Constants\VatTypes::VAT10); // тип ставки
```
Получить установленную расчётную сумму в рублях можно через геттер `getSum()`:
```php
var_dump($vat->getSum());
// double(150)
```
Получить расчитанный размер налога в рублях можно через геттер `getFinalSum()`:
```php
var_dump($vat->getFinalSum());
// double(15): для примера выше это 10% от 150р = 15р
```
Общую сумму, из которой расчитывается размер налога, можно увеличить, используя метод `addSum()`.
Указанная в рублях сумма увеличится и итоговый размер налога пересчитается.
Для уменьшения суммы следует передать отрицательное число.
Разберём комплексный пример изменения типа ставки и расчётной суммы:
```php
use AtolOnline\{Entities\Vat, Constants\VatTypes};
$vat = new Vat(VatTypes::VAT20, 120);
echo "НДС20 от 120р: ";
var_dump($vat->getFinalSum());
echo "НДС10 от 120р: ";
$vat->setType(VatTypes::VAT10);
var_dump($vat->getFinalSum());
$vat->addSum(40);
echo "НДС10 от {$vat->getSum()}р: ";
var_dump($vat->getFinalSum());
$vat->setType(VatTypes::VAT20)->addSum(-20);
echo "НДС20 от {$vat->getSum()}р: ";
var_dump($vat->getFinalSum());
$vat->setType(VatTypes::VAT120);
echo "НДС20/120 от {$vat->getSum()}р: ";
var_dump($vat->getFinalSum());
```
Результат будет следующим:
```
НДС20 от 120р:
double(24)
НДС10 от 120р:
double(12)
НДС10 от 160р:
double(16)
НДС20 от 140р:
double(28)
НДС20/120 от 140р:
double(23.33)
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $vat;
$json_string = (string)$vat;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $vat->jsonSerialize();
```
<a name="array"></a>
## Массив объектов ставок НДС
> Максимальное количество в массиве - 6.
Массив инициализируется следующим образом:
```php
$vat_array = new AtolOnline\Entities\VatArray();
```
Чтобы задать содержимое массива, используйте метод `set()`:
```php
use AtolOnline\{Constants\VatTypes, Entities\Vat};
$vat_array->set([
new Vat(VatTypes::VAT10, 123),
new Vat(VatTypes::VAT110, 53.2),
new Vat(VatTypes::VAT20, 23.99),
new Vat(VatTypes::VAT120, 11.43)
]);
```
Очистить его можно передачей в сеттер пустого массива:
```php
$vat_array->set([]);
```
Чтобы добавить объект к существующим элементам массива, используйте метод `add()`:
```php
use AtolOnline\{Constants\VatTypes, Entities\Vat};
$vat = new Vat(VatTypes::VAT20, 20);
$vat_array->add($vat);
```
Методы `set()` и `add()` проверяют количество элементов в массиве перед его обновлением.
Выбрасывают исключение `AtolTooManyVatsException` (если в массиве уже максимальное количество объектов).
Чтобы получить содержимое массива, используйте метод `get()`:
```php
$vat_array->get();
```
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
```php
echo $vat_array;
$json_string = (string)$vat_array;
```
Чтобы получить те же данные в виде массива, нужно вызвать метод `jsonSerialize()`:
```php
$json_array = $vat_array->jsonSerialize();
```