Integracija sa BokaLPFR-om (POS-to-SDC v3)

BokaLPFR povezuje kasu (ESIR) sa bezbednosnim elementom Poreske uprave (pametna kartica) i Sistemom za upravljanje fiskalizacijom (SUF). ESIR ne potpisuje račune sam i ne komunicira direktno sa karticom niti sa SUF-om: sve ide kroz lokalni HTTP API BokaLPFR-a.

Za integraciju nije potreban proizvođački SDK. Dovoljan je HTTP klijent koji ume da pošalje GET i POST zahteve sa JSON telom.

Van opsega su komunikacija BokaLPFR-a sa SUF-om, potpisivanje na kartici, iščitavanje i konfiguracija servisa. Ti procesi su transparentni za ESIR i opisani su u Korisničkom uputstvu i Uputstvu za instalaciju.

• Ako ESIR radi na istom računaru kao BokaLPFR (preporučeno), koristi loopback adresu iznad, bez dodatne konfiguracije, odmah po instalaciji.
• Ako ESIR radi na drugom uređaju u lokalnoj mreži, pristup mora biti eksplicitno omogućen (vidi ispod) i ESIR koristi IP adresu računara na kome je BokaLPFR.
• Port je podesiv u konfiguraciji; u tom slučaju uskladite i ESIR i pravilo zaštitnog zida.

Bezbednosna granica POS API-ja je loopback interfejs. Na samom API-ju nema tokena ni lozinke: pretpostavka je da je pristup 127.0.0.1 već ograničen na aplikacije na istom računaru.

• Nazivi polja. Odgovori su u camelCase. Nazivi polja u zahtevu su neosetljivi na velika i mala slova (prihvata se i InvoiceType i invoiceType). Referentna tela iz Tehničkog vodiča PU koriste PascalCase, pa su tako dati i primeri zahteva ovde.
• Enumeracije. U zahtevu: naziv člana ("Normal", case-insensitive) ili ceo broj (0). U odgovoru: uvek ceo broj.
• Prazne vrednosti. Polja sa vrednošću null izostavljaju se iz JSON odgovora.
• Brojevi. Decimalni razdvajač je tačka. Novčani iznosi najviše 4 decimale; količina najviše 3 decimale.
• Datum i vreme. ISO 8601 (2026-07-05T01:05:02) ili oblik sa razmakom (2026-07-05 01:05:02). Bez pomeraja se tumači kao lokalno vreme.
• Zaglavlje RequestId (idempotencija). Opciono, najviše 32 karaktera. Ako je poslato, vraća se u istoimenom zaglavlju odgovora i koristi za idempotenciju i oporavak. Duže od 32 karaktera: 400 + 2801.

Najlakša provera da li servis radi. Ne dodiruje karticu, ne troši brojače i nije ograničena brzinom. Odgovor je 200 OK sa praznim telom; bilo koji drugi ishod znači da servis nije dostupan sa te adrese.

GET http://127.0.0.1:8443/api/v3/attention
-> 200 OK

Vraća trenutni status L-PFR-a. ESIR ga poziva pre izdavanja računa da proveri da li je uređaj spreman i da pročita aktuelne poreske stope.

Šema odgovora (LpfrStatus)

Opšti statusni kodovi (gsc)

{
  "isPinRequired": false,
  "auditRequired": false,
  "sdcDateTime": "2026-07-11T10:22:41.512+02:00",
  "lastInvoiceNumber": "8ZBU67JM-8ZBU67JM-41",
  "protocolVersion": "3.0",
  "secureElementVersion": "1.0",
  "hardwareVersion": "1.0",
  "softwareVersion": "1.4.0",
  "deviceSerialNumber": "8ZBU67JM",
  "make": "BOKA GROUP DOO",
  "model": "BokaLPFR Windows",
  "mssc": [],
  "gsc": ["0100", "0210"],
  "supportedLanguages": ["sr-Cyrl-RS", "sr-Latn-RS", "en-US"],
  "uid": "8ZBU67JM",
  "taxCoreApi": "https://sandbox.suf.purs.gov.rs/api/v3",
  "currentTaxRates": {
    "groupId": 6,
    "validFrom": "2022-05-01T00:00:00+02:00",
    "taxCategories": [
      {
        "orderId": 0,
        "name": "О-ПДВ",
        "categoryType": 0,
        "taxRates": [{ "label": "А", "name": "20%", "rate": 20.0 }]
      }
    ]
  },
  "allTaxRates": []
}

Vraća parametre okruženja (podaci obveznika i lokacije, adrese servisa, NTP server). Sva polja su opciona i izostaju kada nisu konfigurisana.

Prosleđuje PIN kod bezbednosnom elementu. PIN je potreban posle svakog restarta servisa ili računara, kao i posle vađenja ili promene kartice (tada GET /status prijavljuje 1500).

• Telo: JSON string sa PIN-om, npr. "1234"(prihvata se i goli oblik 1234).
• PIN mora imati tačno 4 cifre.
• PIN se nikada ne upisuje na disk ni u dnevnike.

Uspešan i neuspešan pokušaj vraćaju 200 OK, a telo je JSON string sa šifrom ishoda:

Greške na nivou HTTP zahteva vraćaju 400: pogrešan Content-Type daje 2806, prazno telo 2800.

POST http://127.0.0.1:8443/api/v3/pin
Content-Type: application/json

"1234"

-> 200 OK
"0100"

Glavni endpoint: fiskalizuje jedan račun. Zahtev opisuje stavke, plaćanja i tip računa; odgovor sadrži fiskalizovane podatke, žurnal i verifikacioni URL / QR kod.

Šema zahteva (InvoiceRequest)

InvoiceItem

Payment i InvoiceOptions

Šema odgovora (InvoiceResult)

TaxItem: categoryType (number), rateId (number), label (string), amount (number), rate (number), categoryName (string).

Primer: prodaja (Normal / Sale)

POST http://127.0.0.1:8443/api/v3/invoices
Content-Type: application/json
RequestId: 8f3c1a92e7b04f5c9a1d

{
  "InvoiceType": "Normal",
  "TransactionType": "Sale",
  "Payment": [
    { "Amount": 121.00, "PaymentType": "Cash" }
  ],
  "Items": [
    {
      "Name": "Test artikal",
      "Quantity": 1,
      "UnitPrice": 121.00,
      "Labels": ["А"],
      "TotalAmount": 121.00
    }
  ]
}

{
  "requestedBy": "8ZBU67JM",
  "signedBy": "8ZBU67JM",
  "sdcDateTime": "2026-07-11T10:24:03+02:00",
  "invoiceNumber": "8ZBU67JM-8ZBU67JM-42",
  "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0ha...HcQ",
  "verificationQRCode": "iVBORw0KGgoAAAANSUhEUgAA...",
  "messages": "Success",
  "totalCounter": 43,
  "transactionTypeCounter": 42,
  "totalAmount": 121.00,
  "taxItems": [
    { "categoryType": 0, "rateId": 0, "label": "А", "amount": 20.17, "rate": 20.0, "categoryName": "О-ПДВ" }
  ],
  "tin": "100000000",
  "mrc": "9A-0001-8ZBU67JM"
}

Primer: refundacija (Normal / Refund)

Refundacija referiše broj računa originala kroz ReferentDocumentNumber (vrednost invoiceNumber iz odgovora na originalni račun).

{
  "InvoiceType": "Normal",
  "TransactionType": "Refund",
  "Payment": [
    { "Amount": 121.00, "PaymentType": "Cash" }
  ],
  "ReferentDocumentNumber": "8ZBU67JM-8ZBU67JM-42",
  "Items": [
    {
      "Name": "Test artikal",
      "Quantity": 1,
      "UnitPrice": 121.00,
      "Labels": ["А"],
      "TotalAmount": 121.00
    }
  ]
}

Idempotencija

• Isti RequestId + isto telo vraća keširani prethodni odgovor (račun se ne potpisuje ponovo). Bezbedno za automatske ponovljene pokušaje.
• Isti RequestId + drugačije telo vraća grešku 2899 (konflikt identifikatora).
• Bez RequestId račun se potpisuje bez idempotencije. Za pouzdanu integraciju uvek šaljite RequestId.

Dohvata ranije fiskalizovan račun po njegovom RequestId. Namenjeno oporavku ESIR-a posle prekida veze: ako ESIR nije primio odgovor na POST /invoices, ponavlja isti RequestId ovde i dobija (već potpisan) rezultat, bez rizika od dvostruke fiskalizacije.

• Odgovor: 200 OK sa InvoiceResult telom ako zapis postoji za dati RequestId i aktivnu karticu.
• Ako zapis ne postoji ili nema kartice, vraća se 200 OK sa telom null.

GET http://127.0.0.1:8443/api/v3/invoices/8f3c1a92e7b04f5c9a1d

Enumeracije se u zahtevu šalju nazivom člana (case-insensitive) ili celim brojem; u odgovoru se vraćaju kao celi brojevi.

Tip računa (invoiceType)

Tip transakcije (transactionType)

Način plaćanja (paymentType)

Svaka stavka nosi jednu ili više poreskih oznaka (labels), npr. А. Skup važećih oznaka i stopa ne definiše ESIR nego dolazi sa kartice i iz komandi SUF-a; ESIR ih čita iz GET /status (currentTaxRates). Nepostojeća ili neaktivna oznaka odbija se greškom 2310.

Tip kategorije (categoryType)

Obračun poreza po stavci radi L-PFR na osnovu oznaka i iznosa iz zahteva; rezultat je u taxItems odgovora. ESIR ne mora sam da računa porez: dovoljno je da pošalje ispravne oznake i totalAmount.

Sve poslovne i validacione greške vraćaju HTTP 400 sa jedinstvenim telom greške. Izuzetak je POST /pin, koji ishod uvek vraća kao 200 sa golom šifrom.

{
  "message": "Request validation failed.",
  "modelState": [
    { "property": "items[0].quantity", "errors": ["2800"] }
  ]
}

• message: kratak opis (nije za prikaz kasiru).
• modelState: lista grešaka; svaki element ima property (camelCase putanja polja, prazno za greške na nivou zahteva) i errors (niz šifara).
• ESIR prikazuje poruku na osnovu šifre iz errors, a ne teksta iz message.

Mapiranje HTTP statusa

BokaLPFR vraća isključivo kodove iz šifarnika Tehničkog vodiča PU, uz jedan dodatni kod definisan proizvodom (2410). Sve šifre su tačno četiri cifre.

Informativni i statusni kodovi (GSC)

Greške

Kod specifičan za proizvod

Pravila koja POST /invoices primenjuje pre potpisivanja. Kada je obavezno numeričko polje odsutno vraća se 2800, a kada je prisutno ali neispravno 2805.

Za svaki uspešno fiskalizovan račun odgovor sadrži verificationUrl i verificationQRCode. ESIR ih samo štampa na računu i ne gradi ih sam.

• verificationUrl vodi na stranicu za proveru računa u sistemu Poreske uprave. Oblik je {adresa-za-verifikaciju}/v/?vl={podaci}, gde adresa dolazi sa kartice / iz komandi SUF-a, a podaci su base64url zapis potpisanih podataka računa sa kontrolnim zbirom.
• verificationQRCode je isti sadržaj spreman za štampu kao QR kod.

Adrese za verifikaciju nikada nisu unapred upisane u proizvod niti ih korisnik menja.

• Provera pre prvog računa. Pozovite GET /status i proverite da gsc ne sadrži blokirajuće kodove (1300, 1500, 2110, 2210, 2400).
• PIN. Posle restarta ili promene kartice bezbednosnom elementu je potreban PIN (1500). Pošaljite ga preko POST /pin ili ga korisnik unosi u BokaLPFR Monitor.
• Idempotencija i oporavak. Uz svaki POST /invoices šaljite jedinstveni RequestId. Posle prekida veze ponovite isti zahtev ili pozovite GET /invoices/{requestId}. Tako izbegavate dvostruku fiskalizaciju.
• Vremensko ograničenje. Preporučeni HTTP timeout za POST /invoices je najmanje 30 sekundi. Prvi zahtev posle ubacivanja kartice može trajati duže.
• Obrada grešaka. Prikažite kasiru poruku na osnovu šifre iz šifarnika, a ne na osnovu message.
• Bez zaobilaženja. Sva komunikacija ide kroz navedene endpointe; ESIR ne priča direktno sa karticom ni sa SUF-om.
• Poreske oznake iz statusa. Skup važećih oznaka i stopa čitajte iz GET /status; ne upisujte ih fiksno u ESIR.

Windows i macOS izdanje dele isto fiskalno jezgro i isti API, ali se kod Poreske uprave vode kao dva odvojena elementa, pa svako ima svoj registracioni kod i IB broj. Identitet izdanja (make, model, hardwareVersion, registracioni kod) je fiksan i vezan za prijavu; softwareVersion se menja sa svakom verzijom proizvoda. ESIR ne treba da tumači mrc: prosleđuje ga u odgovoru onako kako ga dobije.