API dokumentacija

Katalog, obveznici i poreske stope

Podaci koje fiskalni zahtev pretpostavlja: obveznik i prodajno mesto (čitaju se), aktuelne poreske oznake (čitaju se sveže) i katalog proizvoda (vodi se kroz API ili CSV, opciono).

Ažurirano: 29. 8. 2026. · Verzija ugovora 1.0.0

Obveznici i prodajna mesta

Obveznika (PIB, naziv, PDV status) i prodajna mesta (identifikator poslovnog prostora Poreske uprave, naziv, režim plaćanja) kreira BokaPOS pri otvaranju organizacije, a vlasnik ih održava u portalu. API ih čita; identifikatori su stabilni i mogu da stoje u konfiguraciji vašeg sistema.

GET /v1/taxpayers

curl -X GET "https://api.bokapos.rs/v1/taxpayers" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200 OK

{
  "items": [
    {
      "id": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "taxIdentifier": "115711881",
      "legalName": "BOKA GROUP DOO",
      "environment": "sandbox",
      "status": "active",
      "registrationNumber": "22196456",
      "address": "Roze Luksemburg 16",
      "city": "Beograd",
      "municipality": "Rakovica",
      "activityCode": "6201",
      "activityName": "Računarsko programiranje",
      "vatStatus": "in_vat",
      "createdAt": "2026-08-21T09:00:00.000Z",
      "updatedAt": "2026-08-21T09:00:00.000Z"
    }
  ]
}

GET /v1/taxpayers/{taxpayerId}/business-premises

curl -X GET "https://api.bokapos.rs/v1/taxpayers/3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11/business-premises" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200 OK

{
  "items": [
    {
      "id": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
      "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "puIdentifier": "1234567",
      "name": "Web shop",
      "commerceMode": "distance",
      "environment": "sandbox",
      "paymentMode": "all",
      "status": "active",
      "createdAt": "2026-08-21T09:05:00.000Z",
      "updatedAt": "2026-08-21T09:05:00.000Z"
    }
  ]
}

Polje prodajnog mesta	Značenje
`puIdentifier`	identifikator poslovnog prostora iz evidencije Poreske uprave; nepromenljiv
`commerceMode`	uvek `distance` (prodaja na daljinu); drugi režim nije dozvoljen na V-PFR-u
`paymentMode`	`all` (svi načini plaćanja) ili `restricted` (samo OTHER, CASH, WIRE_TRANSFER, VOUCHER)
`status`	`active`, `suspended`, `closed`; fiskalizacija traži `active`

vatStatus obveznika (in_vat, not_in_vat, null) je izjava vlasnika: obveznik van sistema PDV-a sme da koristi samo oznaku bez PDV-a, a pokušaj sa PDV oznakom vraća 422 TAX_LABEL_NOT_ALLOWED_OUTSIDE_VAT.

Poreske stope

GET /v1/tax-rates svaki put pita V-PFR, sa tačnim bezbednosnim elementom prodajnog mesta, i vraća aktuelnu grupu oznaka. BokaPOS nema ugrađenu listu i ne pamti staru; ako V-PFR ne odgovori, odgovor je 503. Pozovite ga pri pokretanju i osvežavajte razumno (na primer na sat vremena ili kad dobijete TAX_LABEL_NOT_CURRENT), ne pre svakog računa.

GET /v1/tax-rates

curl -X GET "https://api.bokapos.rs/v1/tax-rates?taxpayerId=3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11&businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200 OK

{
  "source": "PFR",
  "environment": "sandbox",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "currentTaxGroupId": 8,
  "validFrom": "2022-05-01T00:00:00",
  "fetchedAt": "2026-09-01T08:14:02.118Z",
  "labels": [
    {
      "label": "F",
      "category": "ECAL",
      "categoryType": 0,
      "rate": 11,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "N",
      "category": "N-TAX",
      "categoryType": 0,
      "rate": 0,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "P",
      "category": "PBL",
      "categoryType": 2,
      "rate": 0.5,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "E",
      "category": "STT",
      "categoryType": 0,
      "rate": 6,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "T",
      "category": "TOTL",
      "categoryType": 1,
      "rate": 2,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "A",
      "category": "VAT",
      "categoryType": 0,
      "rate": 10,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "B",
      "category": "VAT",
      "categoryType": 0,
      "rate": 0,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "Ж",
      "category": "VAT",
      "categoryType": 0,
      "rate": 19,
      "activeFrom": "2022-05-01T00:00:00"
    },
    {
      "label": "C",
      "category": "VAT-EXCL",
      "categoryType": 0,
      "rate": 0,
      "activeFrom": "2022-05-01T00:00:00"
    }
  ]
}

Sandbox Poreske uprave nosi generički test skup oznaka. U produkciji dobijate zvanične srpske oznake (na primer Ђ 20%, Е 10%, Г 0%, А bez PDV-a). Nikad ne ugrađujte oznake u kod.

Polje oznake	Značenje
`label`	oznaka koja ide u `taxLabels` stavke, tačno kako je napisana (razlikuje ćirilicu i latinicu)
`category`	naziv kategorije poreza kako ga V-PFR štampa (`VAT`, `N-TAX`...)
`categoryType`	0 obična stopa, 1 zbirna, 2 iznos po jedinici
`rate`	stopa u procentima
`currentTaxGroupId`, `validFrom`	identitet grupe; menja se kad Poreska uprava promeni stope

Katalog proizvoda

Katalog je opcion: stavka računa može biti potpuno slobodna (naziv, jedinica, cena, oznake). Ako želite da BokaPOS vodi šifarnik (isti podaci za cloud POS operatere i za API), koristite /v1/products. Stavka koja pošalje catalogProductId i dalje nosi sve svoje vrednosti; katalog je izvor za vaš sistem, ne zamena za polja.

POST /v1/products

curl -X POST "https://api.bokapos.rs/v1/products" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "sku": "BT-HP-001",
  "gtin": "8606012345678",
  "name": "Bluetooth slušalice",
  "unitOfMeasure": "kom",
  "grossUnitPrice": 8990,
  "taxLabels": [
    "F"
  ]
}'

201 Created

{
  "id": "d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f60",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "sku": "BT-HP-001",
  "gtin": "8606012345678",
  "name": "Bluetooth slušalice",
  "unitOfMeasure": "kom",
  "grossUnitPrice": 8990,
  "taxLabels": [
    "F"
  ],
  "isActive": true,
  "createdAt": "2026-08-22T10:00:00.000Z",
  "updatedAt": "2026-08-22T10:00:00.000Z"
}

GET /v1/products

curl -X GET "https://api.bokapos.rs/v1/products?taxpayerId=3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11&search=slu%C5%A1alice&isActive=true" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

PUT /v1/products/{productId}

curl -X PUT "https://api.bokapos.rs/v1/products/d2e3f4a5-b6c7-4d8e-9f0a-1b2c3d4e5f60" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "sku": "BT-HP-001",
  "gtin": "8606012345678",
  "name": "Bluetooth slušalice Pro",
  "unitOfMeasure": "kom",
  "grossUnitPrice": 9490,
  "taxLabels": [
    "F"
  ],
  "isActive": true
}'

PUT zamenjuje sva uređiva polja; isActive: false sklanja proizvod iz izbora, a računi koji su ga već koristili ostaju nepromenjeni.

Uvoz i izvoz CSV

Sve ili ništa: do 1.000 redova ili 5 MB po zahtevu. Kolone su tačno sku,name,gtin,unitOfMeasure,grossUnitPrice,taxLabels,isActive; više oznaka se razdvaja sa |. Postojeći sku se ažurira, nov se kreira. Prihvata se i CSV kakav pravi srpski Excel (BOM, sep=;, tačka-zarez i decimalni zarez).

POST /v1/products/import

curl -X POST "https://api.bokapos.rs/v1/products/import?taxpayerId=3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Content-Type: text/csv" \
  --data-binary @katalog.csv

200 OK

{
  "created": 1,
  "updated": 1,
  "total": 2
}

GET /v1/products/export

curl -X GET "https://api.bokapos.rs/v1/products/export?taxpayerId=3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  --output katalog.csv

200 OK · text/csv

sku,name,gtin,unitOfMeasure,grossUnitPrice,taxLabels,isActive
BT-HP-001,Bluetooth slušalice,8606012345678,kom,8990.00,F,true
SRV-INST,Instalacija,,h,4000.00,F,true

Greške

HTTP	Kod	Značenje	Šta uraditi	Ponavljanje
404	`TAXPAYER_NOT_FOUND`	Obveznik ne postoji u vašoj organizaciji i okruženju ili nije aktivan.	Pročitajte `GET /v1/taxpayers` istim ključem i koristite tačan `id`; obveznik drugog okruženja je nevidljiv.	ispravi zahtev
404	`BUSINESS_PREMISE_NOT_FOUND`	Prodajno mesto ne postoji u vašem okruženju ili ne pripada navedenom obvezniku.	Pročitajte `GET /v1/taxpayers/{taxpayerId}/business-premises`.	ispravi zahtev
409	`CATALOGUE_SKU_ALREADY_EXISTS`	Šifra (`sku`) već postoji kod tog obveznika.	Izmenite postojeći proizvod (`PUT`) ili upotrebite drugu šifru.	ispravi zahtev
422	`CATALOGUE_IMPORT_TOO_MANY_ROWS`	CSV ima više od 1.000 redova.	Podelite uvoz na više datoteka.	ispravi zahtev
422	`CATALOGUE_IMPORT_HEADERS_INVALID`	Zaglavlje CSV-a nema očekivane kolone.	Preuzmite `GET /v1/products/export` kao šablon.	ispravi zahtev
503	`CURRENT_TAX_CONFIGURATION_UNAVAILABLE`	V-PFR nije vratio svežu poresku konfiguraciju, pa zahtev nije ni rezervisan.	Ponovite kasnije istim ključem.	isti ključ