README

Библиотека для разбора чеков (фискальных документов), экспортированных из мобильного приложения «Чеки ФНС России».

Установка

Установите библиотеку с помощью Composer:

composer require fsa/fns

Требования: PHP ^8.1, расширение ext-json.

Быстрый старт

use FSA\FNS\CheckDecoder;

$decoder = new CheckDecoder();
$decoder->load($json); // содержимое экспортированного файла чеков

foreach ($decoder as $check) {
    echo $check->getUser() . "\n";          // наименование продавца
    echo $check->getTotalSum() / 100 . " руб.\n";

    foreach ($check as $item) {
        echo $item->getName() . " x" . $item->getQuantity() . "\n";
    }
}

API

CheckDecoder

Декодирует JSON-массив чеков. Реализует Countable и Iterator.

Метод	Описание
`load(string $json): void`	Загружает и разбирает JSON. Бросает `CheckFormatException` при битом JSON, неверном формате (не массив) или при структуре, не похожей на массив чеков.
`tryLoad(string $json): bool`	Проверяет и загружает. Возвращает `true`, если JSON — массив чеков (после чего можно итерировать), иначе `false` без исключения.
`getRaw(): ?string`	Возвращает исходный JSON, переданный в `load()`/`tryLoad()`, либо `null`, если ничего не передавалось.
`count(): int`	Число чеков. До успешной загрузки бросает `CheckFormatException`.
`isLoaded(): bool`	`true`, если данные успешно загружены (через `load()` или `tryLoad()`), иначе `false`.
`current(): Check`	Текущий чек (кешируется). До загрузки бросает `CheckFormatException`.
`key(): int`	Индекс текущего чека.
`next(): void`	Переход к следующему чеку.
`rewind(): void`	Сброс итератора к началу.
`valid(): bool`	Есть ли текущий чек.

Итерация возвращает объекты Check. До загрузки методы итератора бросают CheckFormatException.

Пример tryLoad() во внешней программе:

use FSA\FNS\CheckDecoder;

$decoder = new CheckDecoder();
if (!$decoder->tryLoad($incoming)) {
    // это не чек ФНС — просто игнорируем
    return;
}
foreach ($decoder as $check) {
    // обрабатываем чек
}

Check

Один чек. Реализует Countable (число позиций) и Iterator по позициям.

Метод	Описание
`getUser(): string`	Наименование продавца (`user`).
`getUserInn(): string`	ИНН продавца (`userInn`, обрезается).
`getDateTime(): DateTimeImmutable`	Дата и время чека в UTC (`dateTime`).
`getRetailPlace(): ?string`	Место расчётов (`retailPlace`) или `null`.
`getRetailPlaceAddress(): ?string`	Адрес места расчётов (`retailPlaceAddress`) или `null`.
`getOperator(): ?string`	Оператор (`operator`) или `null`.
`getTotalSum(): int`	Сумма чека в копейках (`totalSum`).
`getFiscalDriveNumber(): string`	Номер фискального накопителя.
`getFiscalDocumentNumber(): int`	Номер фискального документа.
`getFiscalSign(): int`	Фискальный признак.
`__toString(): string`	JSON исходного документа.

Итерация по объекту Check возвращает позиции (CheckItem).

CheckItem

Одна позиция чека.

Метод	Описание
`getId(): string`	Идентификатор чека-родителя.
`getName(): string`	Наименование товара/услуги.
`getPrice(): int`	Цена в копейках.
`getQuantity(): float`	Количество.
`getSum(): int`	Стоимость позиции в копейках.
`getNds(): ?int`	Ставка НДС или `null`, если не указана.
`getNdsSum(): ?int`	Сумма НДС в копейках или `null`.
`getPaymentType(): int`	Тип оплаты.
`getProductType(): ?int`	Тип товара или `null`.
`getProductCodeData(): ?CheckItemProductCodeData`	Данные кода товара (DataMatrix) или `null`.
`getProductCodeDataError(): ?string`	Ошибка разбора кода товара или `null`.
`get(): object`	Все типизированные поля позиции как объект.
`getOther(): ?object`	Неизвестные (не обработанные) поля или `null`.
`__toString(): string`	JSON исходной позиции.

CheckItemProductCodeData

Данные кода товара (DataMatrix).

Метод	Описание
`getGtin(): int`	GTIN товара.
`getRawProductCode(): string`	Сырой код товара.
`getProductIdType(): int`	Тип идентификатора товара.
`getSernum(): string`	Серийный номер.
`get(): object`	Все поля как объект.

CheckFormatException

Исключение (наследует \Exception), бросаемое при ошибках формата данных: битый JSON, отсутствие обязательных полей, несоответствие типов значений.

Тесты

composer install
vendor/bin/phpunit

Лицензия

Библиотека распространяется под лицензией GPL-3.0-or-later.

fsa / fns

Maintainers

Package info

Statistics

Security