API dokumentacija

BokaPOS API

Jedan HTTP poziv, jedan fiskalni račun. Vaš web shop, ERP ili platforma pošalje stavke i plaćanja, BokaPOS ih fiskalizuje preko V-PFR-a Poreske uprave i vrati broj računa, verifikacioni link, PDF i QR kod. Ovde je sve što integratoru treba: brzi start, pravila, tokovi i referenca svake operacije.

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

Brzi start
Od pristupnih podataka do prvog fiskalizovanog računa u sandboxu, korak po korak.
Autentifikacija i okruženja
OAuth 2.0 client credentials, jedna adresa za sandbox i produkciju, scope-ovi.
Konvencije
Idempotencija, statusi dokumenta, iznosi, vreme, reference, načini plaćanja, kupac.
Referenca operacija
Svaka operacija sa parametrima, telom, odgovorima i primerom u pet jezika.

Šta API radi

Izdaje fiskalne račune za prodaju na daljinu: promet (prodaja), refundacija, avans, predračun, obuka i kopija, sa svim referencama koje propisi traže.
Vraća kompletan paket računa: PFR broj, vreme i brojač, verifikacioni link Poreske uprave, zvanični tekst žurnala, PDF u A4, 80 mm i 58 mm, PNG pregled i QR kod.
Čuva elektronski dnevnik svake operacije, uključujući odbijene i nepoznate ishode, sa pretragom, izvozom i izveštajem o prometu.
Vodi složene tokove umesto vas: refundacija sa automatskom kopijom kod gotovine, lanac avansa sa zatvaranjem, predračun sa referencom. Vi šaljete poslovni zahtev, BokaPOS sastavlja fiskalne dokumente.
Šalje račun kupcu e-poštom sa platforme, ako je uključen modul E-mail.
Ne izmišlja: račun postoji tek kada V-PFR vrati potpisan odgovor i BokaPOS ga trajno sačuva. Nema lažnog uspeha, nema tihog ponavljanja.

Brzi start: prvi račun u sandboxu

01
Zatražite sandbox pristup
Javite se na office@bokagroup.rs ili preko kontakt stranice. BokaPOS otvara organizaciju, dodeljuje sandbox bezbednosni element i izdaje client id (boka-sbx-...) i tajnu. Tajna se prikazuje jednom; sačuvajte je u tajnama servera, nikad u kodu ili pregledaču. Sandbox je besplatan.
02
Uzmite token
OAuth 2.0 client credentials na https://auth.bokapos.rs/realms/boka/protocol/openid-connect/token. Token važi 300 sekundi; keširajte ga i obnovite pre isteka.
03
Proverite pristup
GET /v1/runtime vraća vašu organizaciju, client id i da li je fiskalni adapter spreman.
04
Pronađite obveznika i prodajno mesto
GET /v1/taxpayers, pa GET /v1/taxpayers/{taxpayerId}/business-premises. Ta dva identifikatora idu u svaki fiskalni zahtev; sačuvajte ih u konfiguraciji.
05
Pročitajte poreske oznake
GET /v1/tax-rates sa oba identifikatora. 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.
06
Izdajte račun
POST /v1/fiscal-documents sa Idempotency-Key zaglavljem. Odgovor 201 sa fiscalized: true je fiskalni račun; sve ostalo nije.
07
Preuzmite PDF i link
Iz odgovora uzmite pfr.verificationUrl i receipt.pdfA4Url i sačuvajte id dokumenta uz porudžbinu.

1. Token

POST token

curl -X POST "https://auth.bokapos.rs/realms/boka/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$BOKAPOS_CLIENT_ID" \
  -d "client_secret=$BOKAPOS_CLIENT_SECRET"

Odgovor tokena

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "tenant:read operations:read catalogue:read catalogue:write fiscal:read fiscal:write refund:write proforma-training:write advance:write advance:close configuration:read security-elements:read"
}

Svaki sledeći poziv nosi Authorization: Bearer <access_token>. U primerima ispod token je u promenljivoj okruženja BOKAPOS_TOKEN.

2. Provera pristupa

GET /v1/runtime

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

200 OK

{
  "manufacturer": "BOKA GROUP DOO",
  "productName": "BokaPOS",
  "esirNumber": "",
  "softwareVersion": "1.0.0",
  "buildCommit": "1f0d454e8b2c9a7d6f5e4c3b2a1908f7e6d5c4b3",
  "instanceId": "api-bokapos-rs",
  "organizationId": "7c1e9a4b-2d3f-4e5a-b6c7-8d9e0f1a2b3c",
  "clientId": "boka-sbx-k7m2p9x4q1wz",
  "fiscalEndpointsEnabled": true,
  "pfrAdapter": "configured"
}

3. Obveznik i prodajno mesto

GET /v1/taxpayers

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

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"
    }
  ]
}

4. Poreske oznake

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.

5. Prvi račun

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",
    "displayName": "Web shop"
  },
  "items": [
    {
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CARD",
      "amount": 8990
    }
  ],
  "metadata": {
    "orderId": "4127",
    "channel": "web"
  }
}'

201 Created

{
  "id": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "idempotencyKey": "order-4127-sale-1",
  "clientReference": "ORDER-4127",
  "invoiceType": "NORMAL",
  "transactionType": "SALE",
  "cashierId": "web-shop",
  "buyerId": null,
  "buyerDetails": null,
  "status": "FISCALIZED",
  "fiscalized": true,
  "failureCode": null,
  "retryable": false,
  "pfr": {
    "invoiceNumber": "JWX4K9PL-JWX4K9PL-1042",
    "sdcTime": "2026-09-01T10:15:32.483+02:00",
    "requestedBy": "JWX4K9PL",
    "signedBy": "JWX4K9PL",
    "transactionTypeCounter": 897,
    "totalCounter": 1042,
    "invoiceCounterExtension": "ПП",
    "totalAmount": 8990,
    "totalTax": 890.9009,
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "journal": "============ ФИСКАЛНИ РАЧУН ============\n115711881\nBOKA GROUP DOO\nBokaPOS sandbox\nРоза Луксембург 16\nБеоград-Раковица\nКасир:                          web-shop\nЕСИР број:                    1656/1.0.0\n-------------ПРОМЕТ ПРОДАЈА-------------\nАртикли\n========================================\nНазив   Цена         Кол.         Укупно\nBluetooth slušalice/kom (F)\n       8.990,00          1       8.990,00\n----------------------------------------\nУкупан износ:                   8.990,00\nПлатна картица:                 8.990,00\n========================================\nОзнака       Име      Стопа        Порез\nF           ECAL   11,00%         890,90\n----------------------------------------\nУкупан износ пореза:              890,90\n========================================\nПФР време:          01.09.2026. 10:15:32\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1042\nБројач рачуна:                 897/1042ПП\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
  },
  "receipt": {
    "textUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/official-text",
    "jsonUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/canonical-json",
    "pdfA4Url": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/pdf-a4",
    "pdf80mmUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/pdf-80mm",
    "pdf58mmUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/pdf-58mm",
    "previewImageUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/preview-png",
    "qrImageUrl": "/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/qr-svg",
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "preferredPaperFormat": "a4"
  },
  "createdAt": "2026-09-01T08:15:31.902Z",
  "updatedAt": "2026-09-01T08:15:32.611Z"
}

6. PDF računa

GET /v1/fiscal-documents/{fiscalDocumentId}/representations/{representationFormat}

curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/pdf-a4" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  --output racun-ORDER-4127.pdf

Isti dokument ima sedam prikaza (tekst, JSON, QR, PDF za tri formata papira, PNG). Pogledajte Prikazi i dostava računa.

Šta dalje

Šta se radi u portalu, a ne kroz API

API kredencijal ima fiksan skup ovlašćenja: fiskalizacija, katalog, čitanje obveznika, prodajnih mesta, sertifikata i licence. Sledeće radnje su namerno izvan API-ja i rade se u portalu cloud.bokapos.rs (vlasnik ili administrator organizacije) ili ih obavlja BokaPOS administracija:

kreiranje obveznika i prodajnih mesta (PIB i identifikator poslovnog prostora su nepromenljivi),
otpremanje i aktivacija produkcionog bezbednosnog elementa (sertifikata),
izdavanje i opoziv API kredencijala,
brendiranje računa (logo, kontakt, zahvalnica) i podešavanja dostave e-poštom,
korisnici i uloge, dnevnik aktivnosti, pretplata i fakture.

BokaPOS API

Brzi start

Autentifikacija i okruženja

Konvencije

Referenca operacija

Šta API radi

Brzi start: prvi račun u sandboxu

Zatražite sandbox pristup

Uzmite token

Proverite pristup

Pronađite obveznika i prodajno mesto

Pročitajte poreske oznake

Izdajte račun

Preuzmite PDF i link

1. Token

2. Provera pristupa

3. Obveznik i prodajno mesto

4. Poreske oznake

5. Prvi račun

6. PDF računa

Šta dalje

Račun za promet

Refundacija

Avans

Predračun i obuka

Dnevnik i izveštaji

Prelazak u produkciju

Šta se radi u portalu, a ne kroz API