# DigiPOS — техничко упутство (ЕСИР)

**Произвођач:** С.О.К. доо, Краљево  
**ПИБ:** 105320485 · **Матични број:** 20354747  
**Седиште:** Мирко Луковића 2, Краљево  
**Контакт:** sok@sokdoo.com · 063 683 093 · Срђан Драгојловић  

**Назив производа:** DigiPOS  
**Верзија:** 2.0  
**Датум документа:** јул 2026.

---

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

DigiPOS је софтверски ЕСИР (ПОС на рачунару) за **малопродају** и **угоститељство**.
Програм евидентира фискалне рачуне, комуницира са Л-ПФР или В-ПФР преко **API v3**,
штампа фискални исечак на ESC/POS штампачу и чува JSON захтев/одговор у бази.

DigiPOS је **нови, самостални производ**. Постојећи одобрени софтверски ЕСИР **KasaB**
остаје у употреби за кориснике који су навикли на њега — DigiPOS га не замењује
ни искључује.

У режиму **самосталном** (локална SQLite), са **унесеним параметрима за В-ПФР**
(URL, ПАК, клијентски PFX сертификат), DigiPOS може **самостално да ради и на
мобилном уређају** (телефон / таблет — веб / PWA), без локалног Л-ПФР уређаја и
без сталне везе са ERP-ом. Фискализација иде преко В-ПФР API; каса ради локално.

**Технологија:** Node.js, Express, MySQL или SQLite; кориснички интерфејс у веб
прегледачу (Chrome, Edge, Safari) на рачунару, таблету или телефону. Подаци о
артиклима, купцима и пореским стопама могу се делити са постојећим књиговодственим
софтвером (табеле `sifre`, `firme`, `porstope`, `esir`).

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

DigiPOS се инсталира и користи у **сва три** следећа режима. Фискализација, штампа,
извештаји и увоз/извоз **морају радити у сваком** од њих (види `docs/REZIMI-RADA.md`):

| # | Режим | Опис | База / веза |
|---|--------|------|-------------|
| **1** | **Самостални** | Каса ради самостално на рачунару **и/или мобилном телефону** (PWA); увоз шифарника (DBF, CSV) и извоз шифарника (CSV); **без** ERP-а; са **В-ПФР** и преко мобилног интернета | Уграђена **SQLite** (`digipos.db`) |
| **2** | **ERP у облаку — стална конекција** | Стална веза са ERP-ом у облаку; **само када нема везе** ради локално (прво офлајн), па се поново синхронизује | ERP у облаку / VPS + локална резерва |
| **3** | **ERP на захтев** | Самостална каса која са ERP-ом комуницира **на захтев** — није стално онлајн | Локално + повремена синхронизација |

**Нагласак — мобилни телефон:** у режиму 1 каса се **користи** на телефону/таблету (PWA) са В‑ПФР.
**Самостална инсталација сервера на iPhone-у није могућа** (iOS); на Android-у је могућ Termux,
иначе сервер на PC или у облаку. Види §3.2 и упутство за инсталацију.

Унутар сваког режима UI касе може бити **`restoran`** (столови, кухиња) или **`prodavnica`**
(брза каса) — то је тип објекта, не замена за горња три режима инсталације/радне средине.

---

## 2. Подаци за одобрење ЕСИР-а

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

### 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 (режим књиговодства) **или** уграђена 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. Повезати ПФР: у Админ → Подешавања унети `vpfr_url` + `lpfr_cert` (В-ПФР, предност)
   и/или `lpfr_url` + `lpfr_pin` (Л-ПФР / DEMO). При пријави каса/админ **аутоматски** зове
   `GET /api/lpfr/status` (+ PIN/PAC);
   при неуспеху трака са поновним покушајем кликом. Ручно: **Провери LPFR**.
   При **првом успешном** повезивању ESIR одмах преузима пореске стопе (`currentTaxRates`)
   и локални приказ обвезника (назив, ПИБ, објекат, адреса) — види упутство за конфигурацију.
   Фискални исечак увек штампа **само** поља из одговора ПФР-а на рачун (`lib/receipt.js`).

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

**Типично вишекорисничко:** рачунар са сервером и телефони на **истом LAN/Wi‑Fi**.
Конобари отварају `http://<IP-рачунара>:3000`. За PWA инсталацију на телефон
препоручен је HTTPS (видети README).

**Самостални рад на мобилном (употреба):** каса на **Android / iOS** преко прегледача / PWA:

1. Сервер у режиму **самостални** (SQLite) — рачунар у објекту, хост / облак, или (само Android) Termux.
2. У Подешавањима: **В-ПФР** (URL API v3, ПАК, PFX) — предност над Л-ПФР.
3. На телефону отворити адресу касе и **Додај на почетни екран** (PWA).
4. Веза ка В-ПФР: Wi‑Fi или **мобилни интернет**. Без локалног Л-ПФР и без ERP-а.

> **Самостална инсталација на iPhone-у није могућа.** iPhone је само клијент (Safari PWA);
> Node сервер + PFX не инсталирају се на iOS. За iPhone без PC у објекту обавезан је хостовани сервер.

Тако каса на телефону ради **исти фискални ток** као на рачунару.

---

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

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

| Параметар | Опис |
|-----------|------|
| `esir_broj` | **Уграђен у верзију** (`lib/esir.js`) — број из регистра ПУ: **1614/2.0**; **не може се мењати** у подешавањима |
| `vpfr_url` | Адреса В-ПФР API v3 (нпр. `https://vsdc.sandbox.suf.purs.gov.rs/api/v3/`) — ако је попуњена уз `lpfr_cert`, **увек се користи прва** |
| `lpfr_url` | Адреса Л-ПФР API v3 или `DEMO` — користи се кад нема В-ПФР |
| `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` | Фирма и продајно место |
| `mode` | UI тип објекта: `restoran` или `prodavnica` (независно од три режима рада из §1.1) |
| `uloga_servera` / `central_url` | Режим 2 (стална веза са ERP) / режим 3 (ERP на захтев) |
| `tezinski_prefiks` | Префикс ваге (подразумевано `28`) |

Пореске стопе се преузимају са ПФР-а (`/status` → `currentTaxRates`) при првом повезивању
и мапирају на ERP групе у `pos_settings.tax_labels` (касније и ручно у Админ →
Шифарник пореских стопа). Локални подаци обвезника у `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`](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 | Унос производа/услуга | Админ → Артикли; MySQL `sifre` |
| 11-П3 | Промена цене на каси | Ручни rabat / цена на ставци (командна конзола, API) |
| 11-П4 | Заокруживање цене PLU | Две децимале, банкарско правило |
| 12-П1 | Пореске стопе из ПФР/СУФ | `porstope` + `tax_labels` |
| 12-П5 | Заокруживање пореза | Две децимале пре слања на ПФР |
| 12-П6 | Само стопе из ПФР | Нема ручног уноса неовлашћених стопа |
| — | Журнал рачуна | Админ → Рачуни; табела `pos_racuni` + JSON |

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

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

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

---

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

**Напомена:** Овај документ **не садржи скениране примере фискалних исечака**.
Садржај сваког типа рачуна описан је текстуално; за тестирање у sandbox-у користити
званично упутство ПУ (*Ручно тестирање ESIR-а*).

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

| # | Врста | Тип | Идент. купца | DigiPOS | Начин издавања |
|---|-------|-----|--------------|---------|----------------|
| 1 | Промет | Продаја | Не | ✅ | Каса → НАПЛАТИ / prodavnica |
| 2 | Промет | Продаја | Да (`buyerId`) | ✅ | Наплата → ПИБ купца |
| 3 | Промет | Рефундација | Не | ✅ | Рачуни → Рефундација |
| 4 | Промет | Рефундација | Да | ✅ | Исто, са оригиналним купцем |
| 5 | Предрачун | Продаја | Не/Да | ✅ | Restoran → Предрачун |
| 6 | Копија | Продаја / Рефундација | — | ✅ | Рачуни → Копија |
| 7 | Аванс | Продаја / Рефундација | Да | ✅ | Каса → **Аванс** (Узми аванс / Затвори робом) |
| 8 | Обука | Продаја / Рефундација | Не/Да | ✅ | Наплата → **Обука** → ИЗДАЈ ОБУКУ; Рачуни → Рефундација (Обука/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. Штампа

DigiPOS штампа рачун на **два начина**; бира се подешавањем **`stampa_driver`**
(Админ → Подешавања).

### 8.1 ESC/POS (термални штампач) — подразумевано

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

### 8.2 Штампа кроз драјвер оперативног система (`stampa_driver = 1`)

Рачун се исписује као графика кроз **драјвер ОС-а** — Windows GDI (`scripts/gdiprint.ps1`)
или Linux CUPS. Намењено штампачима без ћирилице или са непознатим ESC/POS командама,
и **обичним канцеларијским штампачима**.

- **Величина папира:** `driver_papir` — `A4`, `Letter`, или **празно** = подразумевана
  за изабрани штампач (ролна код термалног). Маргине 8 pt.
- Фонт: `driver_font` (подр. Consolas), величина `driver_font_size` (подр. 9).
- QR: слика из ПФР одговора (`verificationQRCode`); `driver_qr_mm` ограничава ширину.

> Без `driver_papir` величина зависи од подразумеваног подешавања штампача — а оно ume
> да буде **Letter** (регионално подешавање Windows-а), не А4. Зато је А4 изричит избор.

### 8.3 Подржане величине рачуна

| Величина | Како | Подешавање |
|----------|------|------------|
| **Ролна до 57 mm** | ESC/POS термални | `kolona` ≈ **32** |
| **Ролна 57–80 mm** | ESC/POS термални | `kolona` **40–48** (подр. 34) |
| **А4** | штампа кроз драјвер ОС-а на канцеларијски (ласерски/inkjet) штампач | `stampa_driver=1` + **`driver_papir=A4`** |

Садржај рачуна је у све три величине **исти** — мења се само ширина исписа. Пример
А4 излаза су и PDF исечци у делу 17 досијеа: направљени су баш овим путем, штампом
кроз драјвер на *Microsoft Print to PDF*.

---

## 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-а*
