Руководство по установке

Otkucaj, регистровое название «Otkucaj» · версия 1.3.6 · otkucaj.com · Руководство пользователя · Руководство по настройке

Всё, что этот документ говорит о нормах, является нашим пониманием, а не юридической или налоговой консультацией; прежде чем действовать, уточните у бухгалтера или в Налоговой администрации.

Содержание

• 1.Что устанавливается, а что нет
• 2.Способы поставки
• 3.Вариант А: работа через интернет
• 4.Вариант Б: локальная установка в деловом помещении
• 5.Обновление версии
• 6.Резервная копия и восстановление
• 7.Удаление
• 8.Контрольный список после установки

1.Что устанавливается, а что нет

Электронное фискальное устройство состоит из трёх элементов: ЕСИР, ПФР и элемент безопасности. Этим руководством устанавливается только первый из них. Otkucaj является ЕСИР: он собирает позиции, скидки, оплаты и данные покупателя, составляет запрос, отправляет его в ПФР и показывает и печатает чек, который ПФР вернул. Он не фискализирует чеки, не присваивает номер ПФР и счётчик и не подписывает чек.

Л-ПФР приобретается и устанавливается отдельно. Локальный процессор фискальных чеков это отдельная программа или устройство, с собственным одобрением Налоговой администрации и собственным учётным номером. Его устанавливает его поставщик по своей инструкции, до или после Otkucaj, безразлично. Otkucaj к нему только подключается по сети, и это порядок из главы 4.7 настоящего руководства. Если у плательщика Л-ПФР ещё нет, установка Otkucaj доводится до конца и оставляется в демо-режиме, а связь настраивается, когда Л-ПФР появится.

Элемент безопасности выдаёт плательщику Налоговая администрация, и этим руководством он не устанавливается. В виде смарт-карты он стоит в считывателе Л-ПФР, и подписывает им сам Л-ПФР; Otkucaj к карте не обращается. В виде файла (.pfx или .p12) он используется вместе с В-ПФР и ставится через Настройки, что описано в Руководстве по настройке. Ни один элемент безопасности не копируется в каталоги программы вручную.

2.Способы поставки

Otkucaj поставляется тремя способами. Программа во всех трёх одна и та же, база данных и настройки во всех трёх одинаковы, а различаются они только тем, на каком компьютере работает программа и кто её ставит. Плательщик в любой момент может перейти с одного способа на другой, потому что вся установка сводится к базе данных и одному конфигурационному файлу.

Выбор способа поставки связан с выбором ПФР. С В-ПФР Налоговой администрации работают оба способа, потому что постоянная связь с интернетом и так является условием работы. С Л-ПФР работает только локальная установка, потому что Л-ПФР общается с Otkucaj по локальной сети заведения, а сервер в облаке в эту сеть попасть не может. Как мы понимаем ст. 6 п. 4 Закона о фискализации, плательщик, работающий с В-ПФР, обязан иметь Л-ПФР в каждом торговом объекте с присвоенным ЈИД, если только его розничная продажа не идёт исключительно через интернет и не является продажей собственных бывших в употреблении движимых средств; с Л-ПФР Otkucaj работает только как локальная установка.

3.Вариант А: работа через интернет

В этом варианте на сервер не устанавливается ничего: программа уже работает по адресу otkucaj.com. Установка сводится к открытию аккаунта, установке приложения на устройство кассира и проверке печати.

3.1 Открытие и подтверждение аккаунта

Откройте https://otkucaj.com/registracija и заполните наименование фирмы, ПИБ, матични број (МБ), номер телефона, электронную почту, имя пользователя и пароль не менее 10 знаков. ПИБ (9 цифр) и МБ (8 цифр) проверяются по контрольной цифре, а телефон должен быть сербским номером, мобильным или городским. С одного сетевого адреса принимается не более 5 регистраций в час.

Аккаунт открывается неактивным, и вход с ним невозможен, пока администратор его не подтвердит. Это сделано намеренно: вход должен пройти через того, кто знает, что плательщик реален. Если уведомления настроены, администратор получает сообщение о новой регистрации сразу. После активации пользователь входит обычным образом, именем пользователя и паролем.

3.2 Первый вход и вводное обучение

Откройте https://otkucaj.com/prijava и войдите. Форма защищена невидимой проверкой (Cloudflare Turnstile), которая не требует ни головоломок, ни перепечатывания знаков; если сервис проверки сейчас недоступен, вход проходит и без неё. После 8 неудачных попыток за минуту вход с этого сетевого адреса временно блокируется.

Поле Оставаться в системе на этом устройстве отмечено заранее, и на кассе в заведении его следует так и оставить: кассир входит один раз и остаётся в системе даже после выключения компьютера. На чужом или общем компьютере его отключите. Вход на всех устройствах прерывается в Настройках, Пользователи, кнопкой Выйти на всех устройствах, и то же самое происходит при смене пароля или отключении аккаунта.

При первом входе открывается короткое обучение из пяти шагов: основы Кассы, вкладки открытых чеков, виды чеков и оплаты, выдача и печать и, наконец, установка приложения. Обучение можно запустить заново в любой момент: Настройки, Данные плательщика, О приложении, кнопка Обучение.

3.3 Установка приложения на устройство (PWA)

Otkucaj это устанавливаемое веб-приложение: оно получает свою иконку, открывается в отдельном окне и хранит справочник товаров локально, поэтому Касса открывается и тогда, когда связь пропала. Установка не обязательна, но на кассе рекомендуется, ради работы без интернета и более быстрого доступа.

Та же кнопка Установить приложение есть и в верхней панели главной страницы, и в Настройках, Данные плательщика, О приложении. Приложение открывается на экране Кассы и работает в полном окне, без адресной строки.

3.4 Настройка принтера и проверка QR-кода

1. Установите принтер в операционную систему с драйвером производителя и задайте ширину бумаги: рулон 58 мм или 80 мм. Работает и обычный принтер A4.
2. В Настройках, Печать и оплата выберите ту же ширину бумаги и ширину чека в знаках: обычно 40 для рулона 80 мм и 32 для рулона 58 мм. Допустимый диапазон от 32 до 64 знаков.
3. В диалоге печати браузера (Ctrl+P) поставьте поля «без полей», масштаб 100% и отключите колонтитулы. Браузер эти настройки запоминает, поэтому они делаются только один раз на устройство.
4. Напечатайте пробный чек и линейкой измерьте QR-код. Он должен быть квадратом со стороной от 40 до 50 мм. Otkucaj печатает его 41 мм на рулоне 58 мм и 45 мм на рулоне 80 мм и на A4, что в обоих случаях внутри предписанного диапазона.
5. Проверьте, что ни одна строка журнала не выходит за правый край бумаги. Ширина оттиска чека составляет 46 мм на рулоне 58 мм и 68 мм на рулоне 80 мм, а размер шрифта выводится из числа знаков в строке, поэтому на более узкий рулон переходят уменьшением числа знаков с 40 до 32, а не уменьшением масштаба печати.

3.5 Проверка установки

Установка завершена тогда, когда через весь путь пройдёт один чек вида Обучение. Этот вид проходит тот же путь, что и настоящий чек (ПФР, журнал, QR-код, печать), но несёт сообщение, что он не является фискальным чеком, в оборот не входит и исключён из всех отчётов, поэтому для пробы он безопасен.

1. Откройте Кассу, добавьте один товар и выберите вид чека Обучение.
2. Выдайте чек и дождитесь появления журнала с QR-кодом.
3. Нажмите Печать и проверьте оттиск: все строки внутри бумаги, QR-код 40-50 мм, текст читается.
4. Отсканируйте QR-код телефоном и откройте адрес для проверки.
5. Откройте Чеки и убедитесь, что этот чек есть в реестре.

4.Вариант Б: локальная установка в деловом помещении

В этом варианте весь Otkucaj работает на компьютере в заведении плательщика. Это тот вариант, которого требует работа с Л-ПФР и работа без интернета. Порядок ниже ведёт от пустого компьютера до проверенного чека и выполняется один раз на каждую торговую точку.

4.1 Системные требования

• Компьютер с операционной системой Windows или Linux.
• PHP 8.3 или новее (издатель в рабочей среде использует 8.5), с расширениями pdo_mysql, mbstring, openssl и curl. Расширение json с PHP 8 входит в ядро. Проверяется командой php -m.
• MySQL 8.0 или новее, либо MariaDB 10.6 или новее.
• Веб-сервер, исполняющий PHP через FastCGI или подобное (nginx, Apache, IIS).
• Л-ПФР, отдельно одобренный Налоговой администрацией, установленный на том же компьютере или в той же локальной сети, со считывателем карт и элементом безопасности. Он не является частью Otkucaj и приобретается отдельно (глава 1).
• Термопринтер под рулон 58 или 80 мм с драйвером для этой системы либо обычный принтер A4.

Если сервер сам отправляет чеки по электронной почте, ему нужен и выход для почты. Без него всё остальное работает, а отправка чека по почте нет.

4.2 Распаковка и права на каталоги

Поставляемый пакет содержит три каталога и схему базы:

otkucaj/
  app/         программа, настройки, переводы, представления
  public/      единственный каталог, который веб-сервер вправе отдавать
  bin/         консольные утилиты (migrate.php, seed.php)
  schema.sql   схема базы данных

Распакуйте пакет вне каталога, который отдаёт веб-сервер, например в /var/www/otkucaj на Linux или C:\otkucaj на Windows. Веб-сервер позже будет указывать только на подкаталог public.

Права: владельцем всех файлов пусть будет пользователь, под которым работает веб-сервер (на Linux чаще всего www-data). Для работы программе достаточно права на чтение. В своём каталоге она в процессе работы пишет только в один подкаталог, private, рядом с app и public, куда сохраняет цифровой сертификат элемента безопасности. Этот каталог создавать заранее не нужно: приложение создаёт его само при первой установке сертификата, с правами 0750, а сам файл сертификата записывает с правами 0600.

4.3 Создание базы и импорт схемы

Создайте базу и пользователя. Кодировка должна быть utf8mb4, потому что и интерфейс, и названия товаров, и весь журнал идут кириллицей:

CREATE DATABASE kasir CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kasir'@'127.0.0.1' IDENTIFIED BY 'ПАРОЛЬ';
GRANT ALL PRIVILEGES ON kasir.* TO 'kasir'@'127.0.0.1';
FLUSH PRIVILEGES;

Затем импортируйте схему:

mysql -u kasir -p kasir < schema.sql

Схема создаёт таблицы и записывает начальное состояние: налоговые метки Сербии по умолчанию (Ђ 20%, Е 10%, Г 0%, А вне НДС), ширину чека в 40 знаков и обе среды, причём активной является тестовая среда в демо-режиме. Данные плательщика намеренно остаются пустыми: это переносимый продукт, и чек не должен нести имя фирмы, которой не существует. Они вносятся позже, через Настройки.

4.4 Конфигурационный файл

Скопируйте app/config.sample.php в app/config.php и заполните пять значений. Файл возвращает массив и выглядит так:

<?php
return [
    'debug'    => false,
    'base_url' => 'http://localhost:8080',
    'app_key'  => '64 шестнадцатеричные цифры',
    'db' => [
        'host' => '127.0.0.1',
        'name' => 'kasir',
        'user' => 'kasir',
        'pass' => 'ПАРОЛЬ',
    ],
];

Затем закройте файл правами: в нём пароль базы и ключ установки. На Linux достаточно chmod 640 app/config.php с владельцем, пользователем веб-сервера. Он находится вне отдаваемого каталога, поэтому скачать его из сети нельзя; это всё равно проверяется в главе 8.

После заполнения конфигурации запустите миграцию схемы. Она идемпотентна: каждый шаг сначала проверяет текущее состояние, поэтому её можно запускать и на свежей базе, и после каждого обновления:

php bin/migrate.php

Утилита пишет, что она применила и сколько шагов уже были на месте. Здесь же, среди прочего, присваивается серийный номер установки вида OTK-XXXXXXXXXXXX. Он уникален для этой установки, выведен из случайных байтов и не меняется ни после обновления, ни после восстановления резервной копии.

4.5 Веб-сервер, локальный адрес и порт

Веб-сервер настраивается по трём правилам:

1. Корневым каталогом является public, никогда каталог выше него. В нём лежат только файлы, которые разрешено отдавать.
2. Любой запрос, не являющийся существующим файлом, ведёт на public/index.php. У Otkucaj одна точка входа, которая сама решает, какую страницу показать. С программой не поставляется ни одного файла с правилами перенаправления, поэтому это правило записывается в настройки самого сервера. В nginx это try_files $uri /index.php$is_args$args;.
3. PHP исполняется через процесс FastCGI, в версии из главы 4.1.

Порт выбираете свободно; для локальной установки обычно 8080. Тот же адрес и порт должны стоять и в параметре base_url, иначе адреса в письмах и в ссылках для проверки чека будут указывать не туда.

Проверка при входе. Защита формы входа (Cloudflare Turnstile) требует интернета. На установке, работающей без связи, она отключается записью в таблицу настроек:

UPDATE settings SET v = '0' WHERE k = 'turnstile_enforce';

Вход по-прежнему запрашивает имя пользователя и пароль и по-прежнему блокируется после 8 неудачных попыток за минуту. Если проверка останется включённой, а сети нет, вход всё равно проходит, потому что проверка намеренно пропускает пользователя, когда сервис проверки недоступен; на локальной установке её всё же рекомендуется отключить явно.

4.6 Первый аккаунт администратора

В свежеустановленной базе нет ни одного пользователя, а форма регистрации создаёт аккаунт, который неактивен, пока его кто-нибудь не подтвердит. Поэтому первый аккаунт создаётся из командной строки:

php bin/seed.php admin ПАРОЛЬ-НЕ-МЕНЕЕ-10-ЗНАКОВ "Имя Фамилия"

Утилита создаёт аккаунт администратора, а если пользователь с таким именем уже есть, задаёт ему новый пароль и возвращает роль администратора. Третий параметр это имя, которое выводится и печатается на чеке; если его опустить, записывается «Администратор». Если справочник товаров пуст, утилита дополнительно вносит восемь образцовых товаров, чтобы Касса не была пустой при первой пробе; позже они удаляются или заменяются собственным справочником.

Войдите под этим аккаунтом и сразу смените пароль в Настройках, Пользователи. Остальных кассиров заводит администратор через тот же экран, с ролью Кассир.

4.7 Подключение к Л-ПФР

Л-ПФР уже должен быть установлен и запущен, с элементом безопасности в считывателе. Его поставщик даёт адрес и порт, на которых он слушает.

1. Откройте Настройки, вкладку Среда и ПФР, для той среды, в которой вы работаете.
2. В качестве Режима работы выберите Л-ПФР.
3. В поле Адрес Л-ПФР введите адрес, который дал поставщик, например http://localhost:8888, или адрес компьютера в локальной сети, если Л-ПФР работает на другом компьютере.
4. Сохраните и посмотрите статус связи на той же вкладке. Он считывается в реальном времени, при каждом открытии Настроек и главной страницы.

Связь с Л-ПФР идёт по обычному HTTP в локальной сети, как предписывает Техническое руководство, и никакой сертификат по ней не отправляется: перед элементом безопасности аутентифицируется сам Л-ПФР, через считыватель карт. Если статус сообщает, что ПФР недоступен, проверьте, что Л-ПФР запущен, находится в той же сети и что адрес и порт верны. Если он сообщает, что карта не вставлена или что требуется PIN, это решает Л-ПФР, а не Otkucaj.

Если вместо Л-ПФР используется В-ПФР Налоговой администрации, режим ставится в В-ПФР, а адрес обязан начинаться с https://: обычный HTTP отклоняется при сохранении, потому что по нему элемент безопасности не передаётся. Сертификат и ПАК вводятся по Руководству по настройке.

4.8 Проверка установки

1. Откройте /zdravlje в браузере. Ответом должно быть {"ok":true,"app":"kasir","version":"1.3.6"}. Это значит, что работают и программа, и база.
2. Войдите аккаунтом из главы 4.6.
3. Откройте Настройки и убедитесь, что вкладка Среда и ПФР показывает ожидаемый режим и живой статус связи.
4. Выдайте один чек вида Обучение и напечатайте его, ровно как в главе 3.5, включая измерение QR-кода.
5. Попробуйте открыть в браузере адрес приложения с добавлением /app/config.php, затем то же самое с /private/vpfr-sandbox.p12. Оба запроса обязаны вернуть ошибку, а не содержимое: эти файлы находятся вне отдаваемого веб-сервером каталога.

5.Обновление версии

Обновление меняет только программу. Поверх существующей установки переписываются каталоги app, public и bin из нового пакета, затем запускается php bin/migrate.php. Перед этим сделайте резервную копию базы по главе 6.

Что обновление не трогает: app/config.php (его нет в пакете, и он никогда не перезаписывается), каталог private с элементом безопасности, всю базу данных с чеками, товарами, пользователями и настройками, и серийный номер установки, который остаётся тем же и после обновления, и после восстановления резервной копии, потому что записан в базу. Если приложение установлено на устройство кассира, новая версия загружается сама при следующем открытии.

6.Резервная копия и восстановление

Всё состояние установки составляют три вещи: база данных, файл app/config.php и каталог private. Программу всегда можно распаковать заново из пакета, поэтому она не архивируется. Копия базы делается обычной утилитой:

mysqldump -u kasir -p kasir > kasir-2026-08-21.sql

Делайте её не реже раза в день и держите вне этого компьютера. Восстановление идёт в обратном порядке: распакуйте программу, верните app/config.php и private, импортируйте копию базы и запустите php bin/migrate.php. Поскольку app_key из конфигурации открывает пароль сертификата, копии базы без этого файла недостаточно: храните обе.

7.Удаление

Приложение на устройстве кассира. На Windows: Параметры, Приложения, найдите Otkucaj, затем Удалить, либо в Chrome откройте chrome://apps и удалите иконку. На Android: долгое нажатие на иконку, затем Удалить. На iPhone и iPad: долгое нажатие на иконку, затем Удалить приложение. Тем самым удаляется только ярлык и локальная копия; данные остаются в базе на сервере.

Локальная установка. Остановите веб-сервер, удалите каталог программы и удалите базу и её пользователя. Перед удалением базы обязательно сделайте копию по главе 6: в базе лежат все выданные чеки, а фискальный чек не должен исчезать только потому, что программу убрали. Отдельно убедитесь, что вы удалили и каталог private, в котором лежит элемент безопасности.

8.Контрольный список после установки

Установка считается завершённой, когда подтверждена каждая строка ниже. Строки с 5 по 8 относятся только к локальной установке.