atol-online/docs/documents.md

168 lines
7.3 KiB
Markdown
Raw Normal View History

2020-01-11 06:30:25 +00:00
# Работа с документами
[Вернуться к содержанию](readme.md)
---
2020-01-11 06:30:25 +00:00
Объект документа инициализируется следующим образом:
```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();
```
---
[Вернуться к содержанию](readme.md)