Pređi na sadržaj

API za fiskalizaciju: fiskalni račun iz vašeg koda

BokaPOS je REST API za fiskalizaciju u Srbiji. Vaš sistem pošalje stavke i plaćanja jednim pozivom, a BokaPOS izda fiskalni račun preko V-PFR-a Poreske uprave i vrati PFR broj, verifikacioni link, QR kod i PDF. BokaPOS je odobren ESIR (IB 1774) za prodaju na daljinu; probno okruženje je besplatno.

Zatražite demoAPI dokumentacija

Primeri u curl, Node.js, PHP, C# i Python. OpenAPI ugovor je javan.

Odobren od Poreske uprave

IB 1774
Rešenje
000-092-00-00256/2026-0000
Datum
29. oktobra 2026.
Model
BokaPOS 1.0.1, ESIR klase Napredni
Namena
Isključivo prodaja na daljinu, prenosivo
Rešenje (PDF)Registar Poreske uprave

Šta API radi

Vi šaljete poslovni zahtev, BokaPOS sastavlja fiskalni dokument po pravilima Poreske uprave.

  • Izdaje fiskalne račune

    Promet (prodaja i refundacija), avans, predračun, obuka i kopija, sa svim referencama koje propisi traže.

  • Vraća gotov račun

    PFR broj, vreme i brojač, verifikacioni link, zvanični tekst, PDF u A4, 80 mm i 58 mm, PNG pregled i QR kod.

  • Vodi složene tokove

    Refundacija sa kopijom kod gotovine, lanac avansa sa zatvaranjem, predračun sa referencom: BokaPOS ih vodi na serveru.

  • Čuva dnevnik

    Svaka operacija, i odbijena i sa nepoznatim ishodom, sa pretragom, izvozom i izveštajem o prometu.

Prvi račun u tri poziva

Token, poreske oznake, račun. Četvrti poziv preuzima PDF ili drugi prikaz kada vam zatreba; adrese su već u odgovoru.

  1. Uzmite token

    POSTauth.bokapos.rs/realms/boka/protocol/openid-connect/token

    OAuth 2.0 client credentials sa client id i tajnom. Token važi 300 sekundi; keširajte ga i obnovite pre isteka.

  2. Pročitajte poreske oznake

    GET/v1/tax-rates

    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. Izdajte račun

    POST/v1/fiscal-documents

    Sa zaglavljem Idempotency-Key izvedenim iz porudžbine. Odgovor 201 sa fiscalized: true je fiskalni račun; sve ostalo nije.

  4. Preuzmite prikaz (po potrebi)

    GET/v1/fiscal-documents/{id}/representations/pdf-a4

    Kada vam treba sam PDF, slika ili QR kod. Isti dokument ima sedam prikaza.

Pre prvog računa jednom pročitajte taxpayerId i businessPremiseId (GET /v1/taxpayers) i sačuvajte ih u konfiguraciji.

Brzi start u API dokumentaciji

Primer: zahtev za račun i odgovor 201, skraćeno
POST/v1/fiscal-documents
curl -X POST "https://api.bokapos.rs/v1/fiscal-documents" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-sale-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127",
  "invoiceType": "NORMAL",
  "transactionType": "SALE",
  "cashier": {
    "id": "web-shop"
  },
  "items": [
    {
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CARD",
      "amount": 8990
    }
  ]
}'
201Created
{
  "id": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
  "clientReference": "ORDER-4127",
  "status": "FISCALIZED",
  "fiscalized": true,
  "pfr": {
    "invoiceNumber": "JWX4K9PL-JWX4K9PL-1042",
    "sdcTime": "2026-09-01T10:15:32.483+02:00",
    "totalAmount": 8990,
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA..."
  },
  "receipt": {
    "pdfA4Url": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/pdf-a4",
    "qrImageUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/qr-svg"
  }
}

Šta je u odgovoru

Odgovor 201 nosi sve što kupac i knjigovođa traže, iz potpisanog odgovora V-PFR-a.

Polja koja čuvate uz porudžbinu

pfr.invoiceNumber
PFR broj računa, zvanični broj koji dodeljuje V-PFR
pfr.sdcTime
PFR vreme, zvanično vreme računa
pfr.verificationUrl
link za proveru kod Poreske uprave; isti je u QR kodu
pfr.journal
zvanični tekst računa
id
ključ za kopije, refundacije i pretragu dnevnika

Prikazi računa

Prikazi i dostava računa

Svaki fiskalizovan račun ima sedam prikaza. Kupcu šaljete PDF ili link, svom sistemu JSON.

  • Zvanični tekstofficial-text
  • PDF A4pdf-a4
  • PDF 80 mmpdf-80mm
  • PDF 58 mmpdf-58mm
  • Slika za e-mailpreview-png
  • QR kod za proveruqr-svg
  • JSON paketcanonical-json

Bez duplih računa

Svaka fiskalna izmena nosi zaglavlje Idempotency-Key, dužine 16 do 200 znakova, izvedeno iz vaše porudžbine. Ključ se vezuje za sadržaj zahteva, pa ponavljanje ne izdaje drugi račun.

Primer ključa
Idempotency-Key: order-4127-sale-1
  • Isti ključ, isti sadržaj200

    API vraća originalnu operaciju (200 umesto 201) i ne izdaje drugi račun, ma koliko puta ponovili.

  • Isti ključ, drugačiji sadržaj409

    IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST sa operationId originala. Ništa se ne izdaje.

  • Ništa nije poslato503, retryable: true

    Sačekajte nekoliko sekundi i pošaljite isti zahtev sa istim ključem; pokušaj koji izda račun vraća 201 sa istim id.

  • Ishod nepoznatOUTCOME_UNKNOWN

    Ne šaljite nov zahtev za istu prodaju. Pratite GET /v1/operations/{id}; BokaPOS ishod razrešava isključivo čitanjem kod V-PFR-a.

Konvencije: idempotencija i statusi

Za koga

Za svaki sistem koji prodaje na daljinu i zna kada je porudžbina plaćena.

Šta je besplatno, a šta se plaća

Razvoj i testiranje ne koštaju ništa. Plaća se produkcija, po bezbednosnom elementu i po obimu.

Otvorite kalkulator

Besplatno

Sandbox
bez roka trajanja, nikad blokiran licencom
WooCommerce dodatak
bez doplate za instalaciju, ažuriranje i podršku
Pomoć pri integraciji
probni pristup i primeri za vaš sistem, uz podršku BokaPOS administracije

Plaća se mesečno

sa PDV-om
Osnova po produkcionom elementu
1.600 RSD
Uključeno dokumenata po organizaciji
600
Svaki dodatni dokument
1 RSD
Modul Avans
600 RSD
Modul E-mail
600 RSD

Prvi mesec se obračunava srazmerno broju dana. Odbijeni i neuspešni pokušaji se ne naplaćuju.

Tri puta do fiskalnog računa

Račun je isti bez obzira na put: potpisuje ga V-PFR Poreske uprave. Razlikuje se ono što morate da uradite vi.

Šta integrator radi na svakom putu

Besplatna aplikacija Poreske upraveOdobrenje Poreske upravenije vaš posao; aplikaciju objavljuje Poreska upravaBezbednosni elementdatoteka za daljinsku trgovinuRačuni i prikazisvaku porudžbinu unosite ručno i račun šaljete kupcu samiOdržavanjenema integracije ni podrške
Sopstveni ESIR nad V-PFR-omOdobrenje Poreske upravevaš softver postaje ESIR: prijava, dokumentacija i uzorci računa, pa rešenje pre prvog pravog računaBezbednosni elementPFX, lozinku i PAK svakog obveznika čuvate i koristite samiRačuni i prikazizvanični tekst, QR kod, PDF i dostavu gradite sami, po Tehničkom vodičuOdržavanjeizmena fiskalnih funkcija ili izgleda računa se prijavljuje i može da traži novo odobrenje
API odobrenog ESIR-a (BokaPOS)Odobrenje Poreske upraveveć postoji: IB 1774, rešenje je javnoBezbednosni elementvlasnik ga jednom otpremi u portal; čuva se šifrovan i otvara samo za tačan poslovni prostorRačuni i prikazisedam prikaza u svakom odgovoru: zvanični tekst, JSON, QR, PDF A4, 80 mm i 58 mm, PNGOdržavanjeverzije i odobrenja vodi dobavljač ESIR-a; poreske oznake se čitaju od Poreske uprave pre svakog izdavanja

Obveznik sme da koristi samo ESIR koji je Poreska uprava odobrila i upisala u javni registar. Vodič: besplatni ESIR Poreske uprave ili cloud ESIR

Integrišete uz AI?

Dajte asistentu dva izvora: paket dokumentacije za AI i OpenAPI ugovor. Prompt ga upućuje na njih, postavlja mu naša pravila (idempotencija, nepoznat ishod, poreske oznake) i kaže mu koja pitanja da vam postavi pre nego što napiše kod.

Prompt pokazuje na englesku verziju dokumentacije, jer su nazivi polja, kodovi i primeri na engleskom. Asistent razgovara na jeziku na kom mu se obratite.

Pitanja o API-ju

Odgovori iz dokumentacije, ukratko.

Sva pitanja o fiskalizaciji web shopa

Da li postoji besplatno probno okruženje?

Da. Sandbox je besplatan, bez roka trajanja i nikad ga ne blokira licenca. BokaPOS otvara organizaciju, dodeljuje probni bezbednosni element i izdaje sandbox kredencijal; probni računi izlaze pod PIB-om BOKA GROUP DOO i proveravaju se na sandbox.suf.purs.gov.rs.

Na kojim programskim jezicima postoje primeri?

Na pet: curl, Node.js, PHP, C# i Python, za svaku operaciju. API prati javni OpenAPI ugovor (api.bokapos.rs/openapi.yaml) iz kojeg generišete klijent za bilo koji jezik, a dokumentacija postoji na srpskom i engleskom, i kao PDF.

Kako se sistem prijavljuje na API?

OAuth 2.0 client credentials preko TLS-a. Sa client id i tajnom uzimate token koji važi 300 sekundi, keširate ga i šaljete kao Authorization: Bearer. Tajnu vlasnik ili administrator organizacije preuzima jednom u portalu i ona ostaje samo na vašem serveru.

Da li sandbox i produkcija imaju različite adrese?

Ne. Oba okruženja koriste https://api.bokapos.rs; okruženje određuje kredencijal (boka-sbx-... ili boka-prod-...). Svaki ključ vidi samo podatke svog okruženja, pa se probni i pravi računi ne mešaju.

Šta ako isti zahtev pošaljem dva puta?

Ništa se ne izdaje dvaput. Isti Idempotency-Key sa istim sadržajem vraća originalnu operaciju (200 umesto 201), a isti ključ sa drugačijim sadržajem vraća 409. Ključ izvedite iz porudžbine, na primer order-4127-sale-1.

Koliko traje integracija?

Dan ili dva za tipičnu API integraciju, uključujući testiranje prodaje i refundacije u sandboxu. Sa WooCommerce dodatkom podešavanje traje sat ili dva, bez koda.

Može li jedan sistem da izdaje račune za više obveznika ili prodajnih mesta?

Da. Svaki zahtev nosi taxpayerId i businessPremiseId, pa isti kod izdaje račune za sve obveznike i prodajna mesta svoje organizacije, a svako prodajno mesto ima svoj bezbednosni element. Agencija dobija posebnu organizaciju za svakog klijenta.

Kako izgleda prelazak u produkciju?

Kod se ne menja. Vlasnik pribavi bezbednosni element kod Poreske uprave i otpremi ga u portal, BokaPOS ga proveri i aktivira i izda licencu i produkcioni kredencijal, a vi zamenite client id i tajnu u konfiguraciji.

Gde se čuvaju podaci?

U Evropskoj uniji, odvojeni po organizaciji, a svaki račun je trajno sačuvan. Bezbednosni element obveznika je šifrovan u trezoru i otvara se samo za tačan poslovni prostor i tačnu svrhu.

Šta ako Poreska uprava ne odgovori?

Ništa se ne šalje ponovo naslepo. Ako ništa nije poslato, odgovor je 503 sa retryable: true i isti zahtev ponavljate istim ključem. Ako je zahtev možda stigao, status je OUTCOME_UNKNOWN: ne šaljete nov zahtev, pratite GET /v1/operations/{id}, a BokaPOS ishod razrešava isključivo čitanjem kod V-PFR-a.

Postoji li dodatak za Shopify ili druge platforme?

Ne, gotov dodatak postoji samo za WooCommerce i besplatan je. Shopify, Magento, PrestaShop, OpenCart i sopstveni sistemi pozivaju isti API, jednim pozivom po porudžbini, po uputstvu za svaku platformu na stranici Integracije.

Koliko košta?

1.600 RSD mesečno po produkcionom bezbednosnom elementu, sa 600 dokumenata mesečno uključenih po organizaciji i 1 RSD po dodatnom dokumentu, PDV uračunat. Moduli Avans i E-mail su po 600 RSD mesečno; sandbox i WooCommerce dodatak su besplatni.

Mogu li API da pozovem iz pregledača ili mobilne aplikacije?

Ne. Tajna kredencijala nikad ne sme u pregledač, mobilnu aplikaciju, javni repozitorijum ili log; pozive ka BokaPOS-u uvek pravi vaš backend.

Da li šaljem poreske stope i iznos poreza?

Ne. Šaljete bruto cenu i poresku oznaku iz GET /v1/tax-rates; BokaPOS računa porez po zvaničnim pravilima, a V-PFR ga potpisuje. Oznake ne ugrađujte u kod, jer se sandbox i produkcija razlikuju.

Da li API radi i za prodaju u radnji?

Ne. BokaPOS je odobren isključivo za prodaju na daljinu i ne podržava L-PFR. Za promet licem u lice potreban je L-PFR; za to postoji BokaLPFR iste firme.

Probni pristup i primeri, istog radnog dana

Pošaljite nam par rečenica o sistemu. Javljamo se istog radnog dana sa probnim pristupom i primerima za vaš sistem.

Zatražite demoPročitajte API dokumentaciju