atol-online/docs/items.md

Работа с предметами расчёта

Один объект

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

$vat = new AtolOnline\Entities\Item();

У объекта предмета расчёта должны быть указаны все следующие обязательные атрибуты:

• наименование (тег ФФД - 1030);
• цена (тег ФФД - 1079);
• количество, вес (тег ФФД - 1023).

У объекта предмета расчёта также могут быть указаны следующие необязательные атрибуты:

• единица измерения количества (тег ФФД - 1197);
• признак способа оплаты (тег ФФД - 1214) - перечислены в классе AtolOnline\Constants\PaymentMethods;
• признак предмета расчёта (тег ФФД - 1212) - перечислены в классе AtolOnline\Constants\PaymentObjects;
• ставка НДС;
• дополнительный реквизит (тег ФФД - 1191).

Установить многие (но не все) атрибуты можно следующими способами:

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():

$item->setUserData('some data');

Он проверяет строку на длину (до 64 символов). Выбрасывает исключение AtolUserdataTooLongException (если слишком длинный дополнительный реквизит).

Для установки признака предмета расчёта существует метод setPaymentObject(). На вход следует передавать одной из значений, перечисленных в классе AtolOnline\Constants\PaymentObjects.

$item->setPaymentObject(AtolOnline\Constants\PaymentObjects::JOB);

Для установки признака способа оплаты существует метод setPaymentMethod(). На вход следует передавать одной из значений, перечисленных в классе AtolOnline\Constants\PaymentMethods.

$item->setPaymentMethod(AtolOnline\Constants\PaymentMethods::FULL_PAYMENT);

Для получения заданных значений атрибутов реализованы соответствующие геттеры:

$item->getName();
$item->getPrice();
$item->getQuantity();
$item->getMeasurementUnit();
$item->getPaymentMethod();
$item->getPaymentObject();
$item->getVat(); // возвращает объект ставки НДС либо null
$item->getUserData();

Для пересчёта общей стоимости и размера налога существует метод calcSum().

$item->calcSum();

Этот метод отрабатывает при вызове setPrice(), setQuantity() и setVatType(). Выбрасывает исключение AtolPriceTooHighException (если общая сумма слишком высока).

Получить уже расчитанную общую сумму можно простым геттером:

$item->getSum();

Объект класса приводится к JSON-строке автоматически или принудительным приведением к string:

echo $item;
$json_string = (string)$item;

Чтобы получить те же данные в виде массива, нужно вызвать метод jsonSerialize():

$json_array = $item->jsonSerialize();

Массив объектов предметов расчёта

Максимальное количество объектов в массиве - 100.

Массив инициализируется следующим образом:

$item_array = new AtolOnline\Entities\ItemArray();

Чтобы задать содержимое массива, используйте метод set():

$item_array->set([
    $item_object1,
    $item_object2
]);

Очистить его можно передачей в сеттер пустого массива:

$item_array->set([]);

Чтобы добавить объект к существующим элементам массива, используйте метод add():

$item = new AtolOnline\Entities\Item('Банан', 100, 1);
$item_array->add($item);

Методы set() и add() проверяют количество элементов в массиве перед его обновлением. Выбрасывают исключение AtolTooManyItemsException (если в массиве уже максимальное количество объектов).

Чтобы получить содержимое массива, используйте метод get():

$item_array->get();

Объект класса приводится к JSON-строке автоматически или принудительным приведением к string:

echo $item_array;
$json_string = (string)$item_array;

Чтобы получить те же данные в виде массива, нужно вызвать метод jsonSerialize():

$json_array = $item_array->jsonSerialize();