# ESIR za agencije i developere: fiskalizacija web shopa klijenta za dan

> Ako gradite web shopove za klijente, fiskalizacija je deo svake isporuke u Srbiji. Ovaj vodič je za agencije i developere: šta je vaše, a šta ostaje klijentu, koliko posla ima za koju platformu, koja četiri poziva čine minimalnu integraciju i šta testirati pre nego što prvi pravi račun ode Poreskoj upravi.

Izvor: https://bokapos.rs/vodic/esir-za-agencije-i-developere · Ažurirano: 3. 9. 2026. · 6 min čitanja · Autor: BOKA GROUP DOO (BokaPOS)

**Ukratko**

- Sandbox je besplatan, sa probnim obveznikom, probnim bezbednosnim elementom i probnim skupom poreskih oznaka, bez roka trajanja.
- Sandbox i produkcija dele istu adresu API-ja; razlikuju se po kredencijalu, a svaki ključ vidi samo podatke svog okruženja.
- Bezbednosni element i portal Poreske uprave ostaju kod klijenta; agencija ih nikad ne dobija u ruke.
- WooCommerce prodavnica ne traži programiranje: postoji besplatan BokaPOS dodatak.
- Minimalna integracija za druge platforme su četiri poziva: token, poreske oznake, fiskalni dokument i prikaz računa.
- Tipičan projekat traje dan ili dva, uključujući test refundacije.

## Ko šta radi

| Korak | Klijent | Agencija ili developer |
| --- | --- | --- |
| Prijava poslovnog prostora za prodaju na daljinu | sa knjigovođom, na portalu Poreske uprave | podseća i proverava da je prijava urađena pre produkcije |
| Bezbednosni element (sertifikat) | ovlašćeno lice ga traži i preuzima na portalu Poreske uprave; vlasnik ga otprema u BokaPOS portal | ne dobija ga i ne treba mu |
| BokaPOS organizacija i kredencijali | vlasnik organizacije; kredencijale izdaje BokaPOS administracija | dobija sandbox kredencijal za razvoj; produkcioni čuva u tajnama servera klijenta |
| Integracija ili dodatak | odobrava | gradi, podešava, testira |
| Mapiranje poreskih klasa na oznake | knjigovođa potvrđuje | podešava prema oznakama iz V-PFR-a |
| Prvi produkcioni račun | proverava na sajtu Poreske uprave | prati odgovor i dnevnik |
| Tekući nadzor | vidi dnevnik i upozorenja u portalu | prati greške 401, 403 i 503 u svom sistemu |

> **Sertifikat je klijentov.** Bezbednosni element identifikuje obveznika pred Poreskom upravom. Traži ga i preuzima isključivo ovlašćeno lice obveznika, a u BokaPOS ga otprema vlasnik organizacije kroz šifrovanu sesiju u pregledaču. Nikad ga ne tražite od klijenta e-poštom ni porukom i nikad ga ne čuvajte u repozitorijumu. Kako se dobija i čuva: [Bezbednosni element za V-PFR](https://bokapos.rs/vodic/bezbednosni-element-za-v-pfr).

## Opcije po platformi, po uloženom trudu

| Platforma | Način | Trud |
| --- | --- | --- |
| WooCommerce | [besplatan BokaPOS dodatak](https://bokapos.rs/woocommerce): instalacija, kredencijal, mapiranje poreza i plaćanja | sat ili dva podešavanja, bez koda |
| Shopify | [sopstvena aplikacija koja poziva API](https://bokapos.rs/integracije/shopify) pri plaćanju porudžbine | dan ili dva |
| Magento, PrestaShop, OpenCart | [modul ili ekstenzija nad API-jem](https://bokapos.rs/integracije), po uzoru na tok WooCommerce dodatka | dan ili dva |
| Sopstveni web shop, ERP, SaaS platforma | [direktan API](https://bokapos.rs/integracije/sopstveni-sistem) iz servisa koji već zna kada je porudžbina plaćena | dan ili dva |

Za svaki API projekat postoji [dokumentacija](https://bokapos.rs/api) sa primerima u curl, Node, PHP, C# i Python, [OpenAPI opis](https://api.bokapos.rs/openapi.yaml) iz kojeg se generiše klijent i [tekstualna verzija dokumentacije](https://bokapos.rs/api/llms.txt) koju možete dati AI asistentu zajedno sa opisom vaše platforme.

## Četiri poziva minimalne integracije

1. **Token** OAuth 2.0 client credentials sa client id i tajnom na `https://auth.bokapos.rs/realms/boka/protocol/openid-connect/token`. Token važi 300 sekundi; keširajte ga i obnovite pre isteka. Tajna živi samo na serveru.
2. **Poreske oznake** `GET /v1/tax-rates` za obveznika i poslovni prostor. Oznake iz odgovora su jedine koje račun sme da nosi. Sandbox i produkcija imaju različit skup, pa ih nikad ne ugrađujte u kod.
3. **Fiskalni dokument** `POST /v1/fiscal-documents` sa zaglavljem `Idempotency-Key` izvedenim iz porudžbine, stavkama, plaćanjima i po potrebi kupcem. Odgovor 201 sa `fiscalized: true` je račun; sve ostalo nije.
4. **Prikaz računa** Iz odgovora uzmite `pfr.verificationUrl` i adresu PDF-a ili slike, sačuvajte `id` dokumenta uz porudžbinu i prikažite ili pošaljite račun kupcu.

Refundacija, avans, predračun i kopija su posebni pozivi koje BokaPOS vodi na serveru sa ispravnim referencama, pa vaš kod šalje poslovni zahtev, ne fiskalne detalje. Koje vrste dokumenata postoje: [Vrste fiskalnih računa](https://bokapos.rs/vodic/vrste-fiskalnih-racuna).

## Okruženja i kredencijali

- Sandbox kredencijal počinje sa `boka-sbx-`, produkcioni sa `boka-prod-`. Adresa API-ja je ista; okruženje određuje kredencijal.
- Svaki ključ vidi samo obveznike, poslovne prostore, elemente i dokumente svog okruženja; objekat drugog okruženja je za njega nepostojeći (404).
- Idempotentni ključevi su jedinstveni po organizaciji u oba okruženja, pa ključ potrošen u sandbox testu ne može da se ponovi u produkciji.
- U sandboxu račun nosi PIB probnog obveznika BOKA GROUP DOO i proverava se na `sandbox.suf.purs.gov.rs`; u produkciji nosi PIB klijenta i proverava se na `suf.purs.gov.rs`.
- Produkcija traži važeću licencu za prodaju, kopiju, predračun, obuku i avans; refundacija i storno rade uvek. Sandbox nikad ne blokira.
- Tajna kredencijala je u tajnama okruženja klijentovog servera; logovi ne sadrže token ni tajnu.

## Šta testirati pre produkcije

- Jedna prodaja sa više stavki, popustom i dva načina plaćanja; provera računa preko verifikacionog linka.
- Delimična refundacija po stavkama originala, sa identifikacijom kupca; refundacija gotovinom sa kopijom za potpis.
- Avansni lanac, ako klijent prima uplate pre isporuke: uplata, storno, zatvaranje završnim računom.
- Prekid veze: isti zahtev istim ključem posle 503 sa `retryable: true`; ponašanje na `OUTCOME_UNKNOWN` bez novog zahteva.
- Odbijanje na 422: poruka stiže do operatera, podaci se ispravljaju, zahtev ide sa novim ključem.
- Osvežavanje oznaka posle `TAX_LABEL_NOT_CURRENT` i mapiranje bez ijedne ugrađene oznake.
- Dostava računa kupcu: link, PDF ili slika, iz sistema ili preko modula E-mail.
- Pretraga dnevnika po referenci porudžbine i izvoz za knjigovođu.
- Velikodušan HTTP timeout na fiskalnim pozivima, da prekid sa vaše strane ne pretvori siguran ishod u nepoznat.

Greške koje se najčešće provuku kroz testiranje, sa rešenjima: [Najčešće greške pri fiskalizaciji web shopa](https://bokapos.rs/vodic/greske-pri-fiskalizaciji-web-shopa).

## Primopredaja klijentu

Projekat je gotov kada klijent može da radi bez vas. Na dan prelaska u produkciju ostavite mu sledeće:

- produkcioni kredencijal upisan u tajne servera, sa zabeleženim mestom gde se menja;
- dokumentovano mapiranje poreskih klasa i načina plaćanja, potvrđeno od knjigovođe;
- vlasnički pristup BokaPOS portalu kod klijenta, sa ulogama za operatere i pregled;
- dogovor ko prati upozorenja o isteku sertifikata i o stanju licence, i ko reaguje na greške 401, 403 i 503;
- kontakt za podršku: BokaPOS administracija na office@bokagroup.rs, uz identifikator operacije i referencu porudžbine, nikad tajnu ili sertifikat.

Redosled koraka od prijave poslovnog prostora do prvog računa, sa stanovišta klijenta: [Fiskalizacija web shopa korak po korak](https://bokapos.rs/vodic/fiskalizacija-web-shopa-korak-po-korak). Šta klijent plaća, a šta ne: [Koliko košta fiskalizacija web shopa](https://bokapos.rs/vodic/koliko-kosta-fiskalizacija-web-shopa).

## Česta pitanja

**Može li agencija da ima jedan nalog za više klijenata?**

Svaki klijent je posebna organizacija sa svojim obveznikom, bezbednosnim elementom i kredencijalima. Agencija može da bude dodata kao korisnik u portalu klijenta, sa ulogom koju klijent izabere, a za razvoj koristi sandbox kredencijal te organizacije.

**Koliko traje integracija fiskalizacije?**

Za WooCommerce sat ili dva podešavanja dodatka. Za API integraciju tipično dan ili dva, uključujući testiranje prodaje i refundacije u sandboxu.

**Da li sandbox ističe ili se naplaćuje?**

Ne. Sandbox je besplatan, nema rok trajanja i nikad se ne blokira, pa ostaje dostupan i posle prelaska u produkciju za dalje testiranje.

**Postoji li gotov dodatak za Shopify, Magento ili PrestaShop?**

Gotov dodatak postoji za WooCommerce. Za ostale platforme integracija ide preko API-ja, po uputstvima za svaku platformu na stranici Integracije.

**Šta se dešava sa pristupom kada klijent promeni agenciju?**

Kredencijali pripadaju organizaciji klijenta, a ne agenciji. Klijent traži opoziv starog i izdavanje novog kredencijala, a korisnički nalog agencije uklanja iz portala.

---

BokaPOS je ESIR u cloudu za prodaju na daljinu, odobren od Poreske uprave (IB 1656, rešenje br. 000-092-00-00171/2026-0000 od 2. septembra 2026). Sve činjenice o proizvodu: https://bokapos.rs/llms.txt