# DigiPOS

Uputstvo za korišćenje · administrator, konobar, kasir, kuvar

Generisano iz UPUTSTVO.md

# DigiPOS — техничко упутство (ESIR)

Произвођач: С.О.К. доо, Краљево

ПИБ: 105320485 · Матични број: 20354747

Седиште: Мирко Луковића 2, Краљево

Контакт: sok@sokdoo.com · 063 683 093 · Срђан Драгојловић

Назив производа: DigiPOS

Верзија: 2.0

Датум документа: јул 2026.

## 1. Опис производа

DigiPOS је софтверски ESIR (ПОС на рачунару) за малопродају и угоститељство.

Програм евидентира фискалне рачуне, комуницира са Л-ПФР или В-ПФР преко API v3,

штампа фискални исечак на ESC/POS штампачу и чува JSON захтев/одговор у бази.

DigiPOS је нови, самостални производ. Постојећи одобрени софтверски ESIR KasaB

остаје у употреби за кориснике који су навикли на њега — DigiPOS га не замењује

ни искључује.

У режиму standalone (локална SQLite), са унесеним параметрима за В-ПФР

(URL, ПАК, клијентски PFX сертификат), DigiPOS може **самостално да ради и на

мобилном уређају** (телефон / таблет — веб / PWA), без локалног Л-ПФР уређаја и

без сталне везе са ERP-ом. Фискализација иде преко В-ПФР API; каса ради локално.

Технологија: Node.js, Express, MySQL или SQLite; кориснички интерфејс у веб

прегледачу (Chrome, Edge, Safari) на рачунару, таблету или телефону. Подаци о

артиклима, купцима и пореским стопама могу се делити са постојећим knjigovodstvenim

софтвером (табеле `sifre`, `firme`, `porstope`, `esir`).

### 1.1 Три режима рада касе (обавезно)

DigiPOS се инсталира и користи у сва три следећа режима. Фискализација, штампа,

извештаји и увоз/извоз морају радити у сваком од њих (види `docs/REZIMI-RADA.md`):

# | Режим | Опис | База / веза
--- | --- | --- | ---
1 | Standalone | Каса ради самостално; увоз/извоз (DBF, JSON/CSV); без везе са ERP-ом | Уграђена SQLite (`digipos.db`)
2 | ERP у cloudu — стална конекција | Стална веза са ERP-ом у cloudu; само када нема везе ради локално (offline-first), па се поново sync | Cloud ERP / VPS + локална резерва
3 | ERP на захтев | Самостална каса која са ERP-ом комуницира на захтев — није стално online | Локално + повремени sync

Унутар сваког режима UI касе може бити `restoran` (столови, кухиња) или `prodavnica`

(брза каса) — то је тип објекта, не замена за горња три режима инсталације/радне средине.

## 2. Подаци за одобрење ESIR-а

Параметар | Вредност
--- | ---
Врста одобрења | Преносиво
Тип ESIR-а | Напредни
Класа | Софтвер на рачунару (ПОС); иста апликација као PWA на мобилном
Инсталација | Директно у пословном простору
Подржани ПФР | Л-ПФР; В-ПФР (паметна картица); В-ПФР (дигитални сертификат)
Повезивање са ПФР | Ethernet, Wi‑Fi, локална мрежа; мобилна мрежа (В-ПФР)
Оперативни систем | Microsoft Windows 10/11 (32/64 бита); опционо Linux сервер; клијент: Android / iOS (прегледач / PWA)
Мрежно окружење | Вишекорисничко (више касира/конобара преко LAN-а) или самостална каса на мобилном (standalone + В-ПФР)

### 2.1 Хардверске препоруке

Компонента | Минимум | Препорука
--- | --- | ---
Процесор | Celeron / dual-core | Intel i3 или новији
RAM | 2 GB | 4 GB или више
Диск | 1 GB слободно | SSD
Штампач | ESC/POS, 58 или 80 mm, CP1251, QR | POS термални (Epson compatible)
Баркод читач | Опционо (USB HID као тастатура) | Да, за продавницу
LPFR | Л-ПФР или В-ПФР у складу са упутством произвођача ПФР-а | Исто

### 2.2 Софтверске зависности

- Node.js LTS (20.x или новији)
- MySQL 8 (режим knjigovodstva) или уграђена SQLite база (`digipos.db`)
- Инсталирани Windows штампач за фискални исечак

## 3. Инсталација

Инсталацију и прво пуштање у рад обавља С.О.К. доо или овлашћени инсталатер у

пословном простору. Корисник покреће програм преко `start.bat` или `node server.js`.

### 3.1 Кораци (Windows)

1. Распаковати дистрибуцију DigiPOS у фолдер (нпр. `C:\DigiPOS`).
2. Инсталирати Node.js LTS ако није присутан.
3. У фолдеру пројекта: `npm install` (једном).
4. Подесити `config.json` (база, порт, опционо HTTPS).
5. Покренути `start.bat` — сервер слуша на порту 3000 (и опционо 3443 HTTPS).
6. У прегледачу: `http://localhost:3000` (каса), `http://localhost:3000/admin` (админ).
7. Повезати LPFR према упутству произвођача ПФР-а; у Admin → Подешавања унети `lpfr_url`

и `lpfr_pin`. При пријави каса/админ аутоматски зове `GET /api/lpfr/status` (+ PIN/PAC);

при неуспеху трака са поновним покушајем кликом. Ручно: Провери LPFR.

При првом успешном повезивању ESIR одмах преузима пореске стопе (`currentTaxRates`)

и локални приказ обвезника (назив, ПИБ, објекат, адреса) — види упутство за конфигурацију.

Фискални исечак увек штампа само поља из одговора ПФР-а на рачун (`lib/receipt.js`).

### 3.2 Мрежа (телефони / таблети)

Типично вишекорисничко: рачунар са сервером и телефони на истом LAN/Wi‑Fi.

Конобари отварају `http://:3000`. За PWA инсталацију на телефон

препоручен је HTTPS (видети README).

Самостални рад на мобилном: у режиму standalone са подешеним В-ПФР

параметрима (URL API v3, ПАК, PFX) каса може да ради самостално на телефону /

таблету — без локалног Л-ПФР и без ERP-а. Потребна је веза ка В-ПФР (Wi‑Fi или

мобилни интернет).

## 4. Конфигурација

Конфигурацију система обавља администратор у Admin → Подешавања (улога `admin`).

Параметар | Опис
--- | ---
`esir_broj` | Уграђен у верзију (`lib/esir.js`) — број из регистра ПУ након одобрења; не може се мењати у подешавањима
`lpfr_url` | Адреса ПФР API v3 или `DEMO` за тест (В-ПФР sandbox: `https://vsdc.sandbox.suf.purs.gov.rs/api/v3/`)
`lpfr_pin` | Л-ПФР: PIN за `/pin`. В-ПФР дигитални сертификат: ПАК → шаље се као `PAC` заглавље
`lpfr_cert` | В-ПФР: путања до клијентског PFX сертификата (празно = Л-ПФР режим)
`lpfr_cert_pass` | В-ПФР: лозинка PFX сертификата
`lpfr_ca` | В-ПФР: опциони CA bundle (празно = системски CA / Let’s Encrypt)
`printer` | Име Windows штампача, `FILE` или `NONE`
`vlasnik` / `objekat` | Фирма и prodajno mesto
`mode` | UI тип објекта: `restoran` или `prodavnica` (независно од три режима рада из §1.1)
`uloga_servera` / `central_url` | Режим 2 (стална веза са ERP) / режим 3 (ERP на захтев)
`tezinski_prefiks` | Префикс ваге (подразумевано `28`)

Пореске стопе се преузимају са ПФР-а (`/status` → `currentTaxRates`) при првом повезивању

и мапирају на ERP групе у `pos_settings.tax_labels` (касније и ручно у Admin →

Шифарник пореских стопа). Локални подаци обвезника у `vlasnik`/`objekti` могу се мењати

у Admin-у; на фискалном исечку иду искључиво `tin`, `businessName`, `locationName`,

`address` из одговора ПФР-а. ESIR не измишља стопе ни заглавље исечка.

## 5. Комуникација ESIR ↔ ПФР

- Протокол: HTTP(S) REST, API v3 Пореске управе.
- Ендпоинти: `GET /status`, `POST /pin`, `POST /invoices`, `GET /invoices/{requestId}` (опоравак).
- Заглавље: `RequestId` (32 алфанумеричка знака), `Accept-Language: sr-Cyrl-RS`.
- Л-ПФР: PIN се шаље на `POST /pin`; сервер је често self-signed (не верификује се).
- В-ПФР (дигитални сертификат): mutual-TLS клијентским PFX сертификатом, ПАК се

шаље као `PAC` заглавље на сваки захтев, сервер се верификује преко системског CA.

Активира се подешавањем `lpfr_cert`. За sandbox поступак види

`SERTIFIKACIJA-SANDBOX.md`.

- Тело рачуна: JSON (`cashier`, `invoiceType`, `transactionType`, `items[]`,

`payment[]`, опционо `buyerId`, `referentDocumentNumber`, …).

- Одговор: JSON са `invoiceNumber`, `invoiceCounter`, `sdcDateTime`, `totalAmount`,

`taxItems[]`, `verificationUrl`, …

При успешном одговору ESIR штампа текстуални приказ рачуна (ESC/POS) и QR код

верификације (`verificationUrl`).

## 6. Испуњавање техничких захтева (преглед)

Реф. | Захтев | Реализација у DigiPOS
--- | --- | ---
10-П2 | Аутентификација ESIR ↔ ПФР при старту | Аутоматски `GET /api/lpfr/status` (+ PIN/PAC) на каси/админ-у; трака + поновни покушај кликом; блокаде фискалних радњи док нема везе
10-П11 | GTIN на ставци | Поље `gtin` у JSON-у (8–13 цифара) из `sifre.barcode`
11-П1 | Унос производа/услуга | Admin → Артикли; MySQL `sifre`
11-П3 | Промена цене на каси | Ручни rabat / цена на ставци (командна конзола, API)
11-П4 | Заокруживање цене PLU | Две децимале, банкарско правило
12-П1 | Пореске стопе из ПФР/СУФ | `porstope` + `tax_labels`
12-П5 | Заокруживање пореза | Две децимале пре слања на ПФР
12-П6 | Само стопе из ПФР | Нема ручног уноса неовлашћених стопа
— | Журнал рачуна | Admin → Рачуни; табела `pos_racuni` + JSON

### 6.1 Правила заокруживања

Пре слања на фискализацију:

- Цена, продајна вредност, пореска вредност: 2 децимале (≥5 нагоре, <5 надоле).
- Количина: до 3 децимале (kg, m², …).
- Порез по ставци рачуна се заокружује на 2 децимале.

## 7. Подржани типови и врсте рачуна

Напомена: Овај документ не садржи скениране примере фискалних исечака.

Садржај сваког типа рачуна описан је текстуално; за тестирање у sandbox-у користити

званично упутство ПУ (*Ручно тестирање ESIR-а*).

### 7.1 Матрица подршке (DigiPOS 2.0)

# | Врста | Тип | Идент. купца | DigiPOS | Начин издавања
--- | --- | --- | --- | --- | ---
1 | Промет | Продаја | Не | ✅ | Kasa → NAPLATI / prodavnica
2 | Промет | Продаја | Да (`buyerId`) | ✅ | Naplata → PIB kupca
3 | Промет | Рефундација | Не | ✅ | Рачуни → Refundacija
4 | Промет | Рефундација | Да | ✅ | Исто, са оригиналним купцем
5 | Предрачун | Продаја | Не/Да | ✅ | Restoran → Predračun
6 | Копија | Продаја / Рефундација | — | ✅ | Рачуни → Kopija
7 | Аванс | Продаја / Рефундација | Да | ✅ | Kasa → Avans (Uzmi avans / Zatvori robom)
8 | Обука | Продаја / Рефундација | Не/Да | ✅ | Naplata → Obuka → ИЗДАЈ ОБУКУ; Računi → Refundacija (Обука/REF)

### 7.2 Текстуални садржај фискалног исечка (промет — продаја)

Без приложених слика, исечак садржи:

1. Наслов ФИСКАЛНИ РАЧУН (или „ОВО НИЈЕ ФИСКАЛНИ РАЧУН” за предрачун/обуку).
2. ПИБ, назив обвезника, место продаје, општина.
3. Касир; опционо ИД купца (`10:PIB`, …).
4. Бројач рачуна и extension (нпр. `…/…ПП`).
5. ESIR број — увек уграђени сертификациони број (`lib/esir.js`), не из подешавања касе.
6. Листа артикала: назив/ЈМ, јед. цена, количина, укупно, пореска ознака.
7. За уплату; распоред плаћања (готовина, картица, …).
8. Порез по ознакама.
9. PFR број, датум/време (SDC), QR верификације.

Рефундација: исти layout, тип трансакције Р, референтни PFR број и датум оригинала.

Копија: invoiceType К, референца на оригинал. Предрачун: invoiceType Р (proforma).

## 8. Штампа

- Формат: ESC/POS, ширина 32–48 колона (подешиво).
- Ћирилица: CP1251 (`ESC t`); опционо грчки CP737 за туристичке објекте.
- QR код: генерише се на штампачу из `verificationUrl`.

## 9. Безбедност и одговорност

- PIN корисника се чува као HMAC-SHA256 (`pos_users.pin_hash`).
- API захтева Bearer токен после пријаве.
- Инсталацију и конфигурацију LPFR-а и безбедносног елемента (smart card) обавља

овлашћено лице у складу са упутством произвођача ПФР-а.

## 10. Прилози (за подношење ПУ)

Документ | Локација
--- | ---
Корисничко (ћирилица, ESIR) | `docs/ESIR-KORISNICKO-UPUTSTVO.md`
Техничко (ESIR) | овај документ

Напомена: упутства за инсталацију и употребу (`UPUTSTVO-ZA-INSTALACIJU.md`, `UPUTSTVO-ZA-UPOTREBU.md`) не припадају пакету за подношење пре одобрења — служе за терен и обуку после одобрења нове верзије. Фискална инсталација и рад у продукцији не смеју пре одобрења ПУ.

Документ (после одобрења) | Локација
--- | ---
Упутство за инсталацију | `docs/UPUTSTVO-ZA-INSTALACIJU.md`
Упутство за употребу | `docs/UPUTSTVO-ZA-UPOTREBU.md`
Корисничко (латиница) | `docs/UPUTSTVO.md`

*С.О.К. доо Краљево · DigiPOS · техничко упутство за поступак одобрења ESIR-а*