API documentation

Receipt representations and delivery

One fiscalized document, seven representations: the official text, the JSON package, the QR code, PDF for A4, 80 mm and 58 mm, a PNG preview. Plus e-mail delivery to the customer from the platform.

Updated: 29 August 2026 · Contract version 1.0.0

Representations

GET /v1/fiscal-documents/{fiscalDocumentId}/representations/{representationFormat}. The URLs of every representation are already in the issuance response (receipt.*). Each is generated from the immutable package (canonical request plus the original V-PFR response) only after their hashes are rechecked, so it is always the same; the response carries ETag and Boka-Receipt-Representation-Version.

`representationFormat`	Content-Type	What it is	When
`official-text`	`text/plain`	the exact official V-PFR journal text, without a single added character	thermal printers, text view in an app, archive
`canonical-json`	`application/json`	the whole package: request, PFR facts per tax item, journal, hashes	your own receipt rendering, accounting, verification
`qr-svg`	`image/svg+xml`	the QR code with the verification link	your own receipt or order-page design
`pdf-a4`, `pdf-80mm`, `pdf-58mm`	`application/pdf`	a finished PDF	printing (from the browser or straight to the printer), e-mail attachment, download, archive
`preview-png`	`image/png`	an image of the receipt in the 80 mm format	e-mail without PDF, admin-panel preview

receipt.preferredPaperFormat (a4, 80mm, 58mm) is the format the taxpayer chose in the portal at issuance; use it when you do not know what to offer.

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ПП
========================================
======== КРАЈ ФИСКАЛНОГ РАЧУНА =========

The canonical JSON is useful when you want to render the receipt yourself or post tax per item: it contains pfr.taxItems (label, rate, tax and base), pfr.invoiceCounter, the counters and officialJournal. The tax per label is signed by the V-PFR; the base (taxableAmountPerLabel) is computed by BokaPOS from the receipt lines (the lines carrying that label, minus that label's tax), because the V-PFR response does not carry it.

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
}

What the customer must receive

In distance commerce the receipt is delivered electronically: at least the verification link (pfr.verificationUrl) or the QR code, and in practice a PDF or an image of the receipt in the e-mail and on the order page.
The fiscal part of the receipt is not altered: it must not be rewritten, translated or shortened. Your logo, thank-you note and contact go outside it (branding in the portal or commercialFooter).
Show the customer only documents with fiscalized: true. No representation exists for a rejected or unknown outcome (404/409).

Caching

Representations are immutable: you may cache them permanently by ETag. If you prefer a single call, store the PDF at issuance; every later call returns byte-identical content as long as the representation version (Boka-Receipt-Representation-Version) is the same.

E-mail delivery from the platform

Instead of sending the message yourself, you can ask BokaPOS to e-mail the receipt to the customer: a message in the taxpayer's language (sr-Cyrl, sr-Latn or en), with the verification link as an active link and the chosen attachments (a4, 80mm, 58mm, png). Conditions: the document is fiscalized, the taxpayer enabled delivery in the portal (Documents, E-mail receipts) and, in production, the organization has the E-mail module. The delivery is queued and sent in the background; its status is never proof of fiscalization. Under the Technical Guideline an advance refund is never issued to the buyer, so it and a copy of it are refused with RECEIPT_DELIVERY_DOCUMENT_NOT_ISSUED_TO_BUYER; send the customer the final receipt of the advance case instead.

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`	Meaning
`QUEUED`	accepted, waiting to be sent
`SENDING`	in progress
`DELIVERED`	handed to the recipient's mail server (`deliveredAt`)
`FAILED`	rejected after the attempts; `failureCode` says why (for example an invalid address)

language and attachments are optional and default to the taxpayer's settings. The message content and look are configured in the portal, which has a preview and a test message.

Representation and delivery errors

HTTP	Code	Meaning	What to do	Retry
403	`MODULE_NOT_LICENSED`	The base licence is valid but the module in `module` (advance or email) is not enabled.	Enable the module through BokaPOS Administration or do not use that feature in production.	later
404	`FISCAL_DOCUMENT_NOT_FOUND`	The document does not exist in your organization and environment.	Check the identifier; documents of another organization or of the other environment are invisible.	fix the request
422	`RECEIPT_DELIVERY_DISABLED`	The taxpayer has not enabled e-mail delivery in the portal settings.	Enable delivery in the portal (Documents, E-mail receipts) or send the receipt from your own system.	later
422	`RECEIPT_DELIVERY_DOCUMENT_NOT_FISCALIZED`	The document is not fiscalized, so there is nothing to deliver.	Send only documents with `fiscalized: true`.	never
422	`RECEIPT_DELIVERY_DOCUMENT_NOT_ISSUED_TO_BUYER`	An advance refund is never issued to the buyer, so BokaPOS does not send it to a buyer address. The same applies to a copy of one.	Send the final receipt of the advance case (the Normal Sale). The advance refund stays available for printing and in the electronic journal.	never
503	`RECEIPT_DELIVERY_UNAVAILABLE`	The platform mail transport is not configured or unavailable. Nothing was queued.	Retry later with the same key or send the receipt from your own system; fiscalization is already complete.	same key