atol-online/docs/documents.md

# Работа с документами

Объект документа инициализируется следующим образом:

```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();
```