API dokumentacija

Prikazi i dostava računa

Jedan fiskalizovan dokument, sedam prikaza: zvanični tekst, JSON paket, QR kod, PDF za A4, 80 mm i 58 mm, PNG pregled. Plus dostava kupcu e-poštom sa platforme.

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

Prikazi

GET /v1/fiscal-documents/{fiscalDocumentId}/representations/{representationFormat}. Adrese svih prikaza su već u odgovoru na izdavanje (receipt.*). Svaki prikaz se generiše iz nepromenljivog paketa (kanonski zahtev plus originalni odgovor V-PFR-a) tek pošto se ponovo provere njihovi otisci, pa je uvek isti; odgovor nosi ETag i Boka-Receipt-Representation-Version.

`representationFormat`	Content-Type	Šta je	Kada
`official-text`	`text/plain`	tačan zvanični tekst žurnala V-PFR-a, bez ijednog dodatog znaka	termalni štampači, tekstualni prikaz u aplikaciji, arhiva
`canonical-json`	`application/json`	ceo paket: zahtev, PFR podaci po stavkama poreza, žurnal, otisci	sopstveni prikaz računa, knjigovodstvo, provera
`qr-svg`	`image/svg+xml`	QR kod sa verifikacionim linkom	vaš dizajn računa ili strane porudžbine
`pdf-a4`, `pdf-80mm`, `pdf-58mm`	`application/pdf`	gotov PDF	štampa (iz pregledača ili direktno na štampač), prilog e-pošte, preuzimanje, arhiva
`preview-png`	`image/png`	slika računa u formatu 80 mm	e-mail bez PDF-a, pregled u admin panelu

receipt.preferredPaperFormat (a4, 80mm, 58mm) je format koji je obveznik izabrao u portalu u trenutku izdavanja; koristite ga kada ne znate šta da ponudite.

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

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

curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/official-text" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200 OK · text/plain

============ ФИСКАЛНИ РАЧУН ============
115711881
BOKA GROUP DOO
BokaPOS sandbox
Роза Луксембург 16
Београд-Раковица
Касир:                          web-shop
ЕСИР број:                    1656/1.0.0
-------------ПРОМЕТ ПРОДАЈА-------------
Артикли
========================================
Назив   Цена         Кол.         Укупно
Bluetooth slušalice/kom (F)
       8.990,00          1       8.990,00
----------------------------------------
Укупан износ:                   8.990,00
Платна картица:                 8.990,00
========================================
Ознака       Име      Стопа        Порез
F           ECAL   11,00%         890,90
----------------------------------------
Укупан износ пореза:              890,90
========================================
ПФР време:          01.09.2026. 10:15:32
ПФР број рачуна:      JWX4K9PL-JWX4K9PL-1042
Бројач рачуна:                 897/1042ПП
========================================
======== КРАЈ ФИСКАЛНОГ РАЧУНА =========

Kanonski JSON je koristan kada želite da sami iscrtate račun ili proknjižite porez po stavkama: sadrži pfr.taxItems (oznaka, stopa, porez i osnovica), pfr.invoiceCounter, brojače i officialJournal. Porez po oznaci potpisuje V-PFR; osnovicu (taxableAmountPerLabel) izračunava BokaPOS iz stavki računa (zbir stavki sa tom oznakom umanjen za porez te oznake), jer je odgovor V-PFR-a ne sadrži.

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

curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/9f8e7d6c-5b4a-4321-8765-0fedcba98761/representations/canonical-json" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200 OK

{
  "schemaVersion": "boka-receipt-representation-v21",
  "sourceSha256": "5d41402abc4b2a76b9719d911017c592e99f0d3b4a7c1e6f8b2d9a0c3e5f7a1b",
  "canonicalRequestSha256": "9b74c9897bac770ffc029102a200c5de3a4b1c6d7e8f9a0b1c2d3e4f5a6b7c8d",
  "originalPfrResponseSha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
  "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127",
  "invoiceType": "NORMAL",
  "transactionType": "SALE",
  "request": {
    "cashierId": "web-shop",
    "cashierDisplayName": "Web shop",
    "buyer": null,
    "items": [
      {
        "name": "Bluetooth slušalice",
        "unitOfMeasure": "kom",
        "quantity": 1,
        "unitPrice": 8990,
        "gtin": "8606012345678",
        "taxLabels": [
          "F"
        ]
      }
    ],
    "payments": [
      {
        "type": "CARD",
        "amount": 8990
      }
    ],
    "reference": null,
    "transactionOccurredAt": null,
    "commercialFooter": null
  },
  "pfr": {
    "invoiceNumber": "JWX4K9PL-JWX4K9PL-1042",
    "sdcTime": "2026-09-01T10:15:32.483+02:00",
    "requestedBy": "JWX4K9PL",
    "signedBy": "JWX4K9PL",
    "invoiceCounter": "897/1042ПП",
    "invoiceCounterExtension": "ПП",
    "totalCounter": 1042,
    "transactionTypeCounter": 897,
    "totalAmount": 8990,
    "taxGroupRevision": 8,
    "taxItems": [
      {
        "categoryType": 0,
        "label": "F",
        "amount": 890.9009,
        "rate": 11,
        "categoryName": "ECAL",
        "taxableAmountPerLabel": 8099.0991
      }
    ],
    "businessName": "BOKA GROUP DOO",
    "tin": "115711881",
    "locationName": "BokaPOS sandbox",
    "address": "Роза Луксембург 16",
    "district": "Београд-Раковица",
    "mrc": null,
    "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
    "officialJournal": "============ ФИСКАЛНИ РАЧУН ============\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======== КРАЈ ФИСКАЛНОГ РАЧУНА =========",
    "officialJournalSha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "opaqueFiscalDataStored": true
  },
  "branding": null
}

Šta kupac mora da dobije

Kod prodaje na daljinu račun se dostavlja u elektronskom obliku: najmanje verifikacioni link (pfr.verificationUrl) ili QR kod, a u praksi PDF ili slika računa u e-pošti i na strani porudžbine.
Fiskalni deo računa se ne menja: ne sme se prepisivati, prevoditi ni skraćivati. Vaš logo, zahvalnica i kontakt idu izvan njega (brendiranje u portalu ili commercialFooter).
Kupcu prikazujte samo dokumente sa fiscalized: true. Prikaz za odbijen ili nepoznat ishod ne postoji (404/409).

Keširanje

Prikazi su nepromenljivi: možete ih trajno keširati po ETag-u. Ako ipak želite samo jedan poziv, sačuvajte PDF u trenutku izdavanja; svaki kasniji poziv vraća bajt-po-bajt isti sadržaj dokle god je verzija prikaza (Boka-Receipt-Representation-Version) ista.

Dostava e-poštom sa platforme

Umesto da sami šaljete poruku, možete zatražiti da BokaPOS pošalje račun kupcu: poruka na jeziku obveznika (sr-Cyrl, sr-Latn ili en), sa verifikacionim linkom kao aktivnim linkom i izabranim prilozima (a4, 80mm, 58mm, png). Uslovi: dokument je fiskalizovan, obveznik je uključio dostavu u portalu (Dokumenti, E-mail računi) i, u produkciji, organizacija ima modul E-mail. Dostava se stavlja u red i šalje u pozadini; njen status nikad nije dokaz fiskalizacije. Račun Avans-Refundacija se po Tehničkom uputstvu ne izdaje kupcu, pa se on i njegova kopija odbijaju sa RECEIPT_DELIVERY_DOCUMENT_NOT_ISSUED_TO_BUYER; kupcu šaljete završni račun avansnog slučaja.

POST /v1/receipt-deliveries

curl -X POST "https://api.bokapos.rs/v1/receipt-deliveries" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-email-1" \
  -H "Content-Type: application/json" \
  -d '{
  "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
  "channel": "EMAIL",
  "recipient": "kupac@example.com",
  "language": "sr-Latn",
  "attachments": [
    "a4"
  ]
}'

202 Accepted

{
  "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b90",
  "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
  "channel": "EMAIL",
  "recipient": "kupac@example.com",
  "language": "sr-Latn",
  "attachments": [
    "a4"
  ],
  "status": "QUEUED",
  "attempts": 0,
  "failureCode": null,
  "createdAt": "2026-09-01T08:15:40.000Z",
  "deliveredAt": null,
  "updatedAt": "2026-09-01T08:15:40.000Z"
}

GET /v1/receipt-deliveries/{receiptDeliveryId}

curl -X GET "https://api.bokapos.rs/v1/receipt-deliveries/f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b90" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

200 OK

{
  "id": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b90",
  "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
  "channel": "EMAIL",
  "recipient": "kupac@example.com",
  "language": "sr-Latn",
  "attachments": [
    "a4"
  ],
  "status": "DELIVERED",
  "attempts": 1,
  "failureCode": null,
  "createdAt": "2026-09-01T08:15:40.000Z",
  "deliveredAt": "2026-09-01T08:15:52.418Z",
  "updatedAt": "2026-09-01T08:15:52.418Z"
}

`status`	Značenje
`QUEUED`	primljeno, čeka slanje
`SENDING`	u toku
`DELIVERED`	predato mail serveru primaoca (`deliveredAt`)
`FAILED`	odbijeno posle pokušaja; `failureCode` kaže zašto (na primer nevažeća adresa)

language i attachments su opcioni i podrazumevano prate podešavanja obveznika. Sadržaj i izgled poruke se podešavaju u portalu; za tim postoji pregled i test poruka.

Greške kod prikaza i dostave

HTTP	Kod	Značenje	Šta uraditi	Ponavljanje
403	`MODULE_NOT_LICENSED`	Osnovna licenca važi, ali modul iz polja `module` (advance ili email) nije uključen.	Uključite modul preko BokaPOS administracije ili ne koristite tu funkciju u produkciji.	kasnije
404	`FISCAL_DOCUMENT_NOT_FOUND`	Dokument ne postoji u vašoj organizaciji i okruženju.	Proverite identifikator; dokumenti druge organizacije i drugog okruženja su nevidljivi.	ispravi zahtev
422	`RECEIPT_DELIVERY_DISABLED`	Obveznik nije uključio dostavu e-poštom u podešavanjima portala.	Uključite dostavu u portalu (Dokumenti, E-mail računi) ili šaljite račun iz svog sistema.	kasnije
422	`RECEIPT_DELIVERY_DOCUMENT_NOT_FISCALIZED`	Dokument nije fiskalizovan, pa nema šta da se dostavi.	Šaljite samo dokumente sa `fiscalized: true`.	nikad
422	`RECEIPT_DELIVERY_DOCUMENT_NOT_ISSUED_TO_BUYER`	Račun Avans-Refundacija se ne izdaje kupcu, pa ga BokaPOS ne šalje na adresu kupca. Isto važi i za njegovu kopiju.	Pošaljite završni račun avansnog slučaja (Promet-Prodaja). Avans-Refundacija ostaje dostupna za štampu i u elektronskom dnevniku.	nikad
503	`RECEIPT_DELIVERY_UNAVAILABLE`	Platformski e-mail transport nije konfigurisan ili nije dostupan. Ništa nije stavljeno u red.	Ponovite kasnije istim ključem ili pošaljite račun iz svog sistema; fiskalizacija je već završena.	isti ključ