Pređi na sadržaj

API dokumentacija

Dnevnik, izveštaji i stanje

Sve što je BokaPOS uradio za vašu organizaciju je pretraživo: elektronski dnevnik sa svakim pokušajem, CSV izvoz, izveštaj o prometu po PFR vremenu, stanje pojedinačne operacije, sertifikati i licenca.

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

Pretraga dnevnika

GET /v1/fiscal-documents vraća operacije svih vrsta (promet, avans, kopija, predračun, obuka; prodaja i refundacija), uključujući odbijene i nepoznate ishode. Sve filtere možete kombinovati.

FilterZnačenje
taxpayerId, businessPremiseIdsuženje na obveznika ili prodajno mesto
statusjedan od statusa dokumenta (FISCALIZED, REJECTED, OUTCOME_UNKNOWN...)
invoiceType, transactionTypevrsta računa i transakcije
createdFrom, createdTovreme prijema u BokaPOS (uključeno, isključeno)
pfrFrom, pfrTovreme potpisa V-PFR-a; isključuje zapise bez računa
clientReference, idempotencyKey, pfrNumber, cashierId, buyerIdtačna vrednost
searchsadrži, bez razlike velikih i malih slova, po bezbednim identifikatorima
cursor, pageSizepaginacija; pageSize do 200
GET /v1/fiscal-documents
curl -X GET "https://api.bokapos.rs/v1/fiscal-documents?businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22&status=FISCALIZED&createdFrom=2026-09-01T00%3A00%3A00Z&pageSize=50" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"
200 OK
{
  "items": [
    {
      "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"
    }
  ],
  "nextCursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA5LTAxVDA4OjE1OjMyLjQ4M1oiLCJpZCI6IjlmOGU3ZDZjIn0"
}

Pošaljite `nextCursor` kao `cursor` za sledeću stranicu; `null` znači kraj.

Lista nikad ne vraća pfrRejection; za dijagnozu odbijenog dokumenta pročitajte ga pojedinačno.

GET /v1/fiscal-documents/{fiscalDocumentId}
curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"
200 OK
{
  "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "idempotencyKey": "order-4129-sale-1",
  "clientReference": "ORDER-4129",
  "invoiceType": "NORMAL",
  "transactionType": "SALE",
  "cashierId": "web-shop",
  "buyerId": null,
  "buyerDetails": null,
  "status": "REJECTED",
  "fiscalized": false,
  "failureCode": "PFR_VALIDATION_REJECTED",
  "retryable": false,
  "pfr": null,
  "receipt": null,
  "createdAt": "2026-09-01T08:15:31.902Z",
  "updatedAt": "2026-09-01T08:15:32.611Z",
  "pfrRejection": {
    "items": [
      {
        "property": "items[0].unitPrice",
        "codes": [
          "2804"
        ]
      }
    ]
  }
}

Šifra 2804 (format) je ono što sandbox vraća za cenu sa više od dve decimale. Odbijen dokument nije račun; ispravite zahtev i pošaljite ga sa novim ključem.

Izvoz dnevnika (CSV)

Isti filteri, deterministički CSV do 10.000 redova, bez sirovih PFR podataka i bez tajni. Zaglavlje Boka-Export-Schema-Version nosi verziju formata (boka-fiscal-journal-csv-v2). Ako filteri hvataju više od 10.000 redova, zahtev pada u celini (422), pa suzite period.

GET /v1/fiscal-documents/export
curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/export?businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22&createdFrom=2026-09-01T00%3A00%3A00Z&createdTo=2026-10-01T00%3A00%3A00Z" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  --output dnevnik-2026-09.csv
200 OK · text/csv
schemaVersion,fiscalDocumentId,taxpayerId,businessPremiseId,idempotencyKey,clientReference,invoiceType,transactionType,cashierId,buyerId,status,fiscalized,failureCode,pfrInvoiceNumber,pfrTime,createdAt,updatedAt,retryable,esirNumber,issuingSoftwareVersion,issuingReceiptRepresentationVersion,issuingBuildCommit
boka-fiscal-journal-csv-v2,9f8e7d6c-5b4a-4321-8765-0fedcba98761,3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11,b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22,order-4127-sale-1,ORDER-4127,NORMAL,SALE,web-shop,,FISCALIZED,true,,JWX4K9PL-JWX4K9PL-1042,2026-09-01T08:15:32.483Z,2026-09-01T08:15:31.902Z,2026-09-01T08:15:32.611Z,false,,1.0.0,boka-receipt-representation-v21,1f0d454e8b2c9a7d6f5e4c3b2a1908f7e6d5c4b3

Zaglavlje `Boka-Export-Schema-Version: boka-fiscal-journal-csv-v2` označava verziju formata.

Izveštaj o prometu

Lokalni nepromenljivi zbir fiskalizovanih računa za promet i avans po vremenu potpisa V-PFR-a, za jedno prodajno mesto i period. Prodaja i refundacija su odvojeni pozitivni iznosi; iznosi po načinu plaćanja dolaze iz proverenog kanonskog zahteva, porez po oznaci iz proverenog originalnog odgovora V-PFR-a, a osnovica i ukupno po oznaci iz stavki računa koje nose tu oznaku (ukupno je bruto tih stavki, osnovica je ukupno umanjeno za porez). Iznosi nose četiri decimale, kao i porez koji V-PFR potpisuje; zaokružite ih na dve za prikaz. Ovo je vaš izveštaj, ne zamena za dnevni izveštaj na SUF portalu Poreske uprave. Vremenske granice primaju bilo koji RFC 3339 pomak (Z, +00:00, +02:00) i porede se kao trenuci.

GET /v1/fiscal-documents/turnover-report
curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/turnover-report?taxpayerId=3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11&businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22&pfrFrom=2026-09-01T00%3A00%3A00%2B02%3A00&pfrTo=2026-09-02T00%3A00%3A00%2B02%3A00" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"
200 OK
{
  "source": "BOKA_LOCAL_IMMUTABLE_PFR",
  "periodBasis": "PFR_SDC_TIME",
  "amountConvention": "SALE_REFUND_SEPARATE",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "pfrFrom": "2026-08-31T22:00:00Z",
  "pfrTo": "2026-09-01T22:00:00Z",
  "documentCount": 2,
  "firstDocument": {
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
    "pfrInvoiceNumber": "JWX4K9PL-JWX4K9PL-1042",
    "pfrTime": "2026-09-01T10:15:32.483+02:00"
  },
  "lastDocument": {
    "fiscalDocumentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "pfrInvoiceNumber": "JWX4K9PL-JWX4K9PL-1045",
    "pfrTime": "2026-09-01T16:40:05.120+02:00"
  },
  "paymentTotals": [
    {
      "securityElementJid": "JWX4K9PL",
      "paymentType": "CARD",
      "saleAmount": 8990,
      "refundAmount": 8990
    }
  ],
  "taxTotals": [
    {
      "invoiceType": "NORMAL",
      "categoryType": 0,
      "label": "F",
      "rate": 11,
      "categoryName": "ECAL",
      "saleTaxableAmount": 8099.0991,
      "saleTaxAmount": 890.9009,
      "saleTotalAmount": 8990,
      "refundTaxableAmount": 8099.0991,
      "refundTaxAmount": 890.9009,
      "refundTotalAmount": 8990
    }
  ]
}
GET /v1/fiscal-documents/turnover-report/export
curl -X GET "https://api.bokapos.rs/v1/fiscal-documents/turnover-report/export?taxpayerId=3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11&businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22&pfrFrom=2026-09-01T00%3A00%3A00%2B02%3A00&pfrTo=2026-09-02T00%3A00%3A00%2B02%3A00" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  --output promet-2026-09-01.csv

Stanje operacije

GET /v1/operations/{operationId} je lakši oblik dokumenta, iz baze, bez kontakta sa V-PFR-om. Identifikator operacije je isti kao id dokumenta. Koristite ga kada 409 vrati operationId, i kao poziv koji pratite posle OUTCOME_UNKNOWN.

GET /v1/operations/{operationId}
curl -X GET "https://api.bokapos.rs/v1/operations/9f8e7d6c-5b4a-4321-8765-0fedcba98761" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"
200 OK
{
  "id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f70",
  "kind": "FISCAL_DOCUMENT",
  "status": "OUTCOME_UNKNOWN",
  "fiscalized": false,
  "failureCode": "PFR_RESPONSE_NOT_OBSERVED",
  "retryable": false,
  "resourceUrl": "/v1/fiscal-documents/4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f70",
  "createdAt": "2026-09-01T09:00:00.000Z",
  "updatedAt": "2026-09-01T09:00:31.000Z"
}

resourceUrl vodi na pun dokument. Kada se nepoznat ishod razreši, status postaje FISCALIZED (račun je postojao kod V-PFR-a) i tada je porudžbina fiskalizovana bez ijednog novog zahteva.

Bezbednosni elementi

Bezbedni metapodaci sertifikata po prodajnom mestu: JID, okruženje, važenje, certificateExpiryStatus (current, warning 30 dana pre isteka, critical 7 dana, expired) i replacementRecommended. Tajne se nikad ne vraćaju. Korisno za nadzor: upozorite vlasnika pre isteka, jer zamenu sertifikata radi on u portalu Poreske uprave i u BokaPOS portalu.

GET /v1/security-elements
curl -X GET "https://api.bokapos.rs/v1/security-elements?businessPremiseId=b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"
200 OK
{
  "items": [
    {
      "id": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a80",
      "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
      "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
      "environment": "sandbox",
      "jid": "JWX4K9PL",
      "certificateThumbprint": "A1B2C3D4E5F60718293A4B5C6D7E8F9012345678",
      "certificateSubject": "CN=JWX4K9PL, O=BOKA GROUP DOO, C=RS",
      "certificateIssuer": "CN=Sandbox ICA, O=Poreska uprava Republike Srbije, C=RS",
      "certificateSerialNumber": "3F9C2A8E6B1D",
      "certificateNotBefore": "2026-08-20T00:00:00Z",
      "certificateNotAfter": "2028-08-20T00:00:00Z",
      "certificateExpiryStatus": "current",
      "replacementRecommended": false,
      "status": "active",
      "createdAt": "2026-08-21T09:10:00.000Z",
      "updatedAt": "2026-08-21T09:12:00.000Z"
    }
  ]
}

Licenca

GET /v1/license kaže da li je produkciona fiskalizacija trenutno dozvoljena, koji su moduli uključeni i koje cene važe. Pozovite ga pri pokretanju i posle svakog 403 LICENSE_*. Sandbox se nikad ne naplaćuje i nikad ne blokira.

GET /v1/license
curl -X GET "https://api.bokapos.rs/v1/license" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"
200 OK
{
  "state": "active",
  "productionFiscalizationAllowed": true,
  "modules": {
    "advance": true,
    "email": false
  },
  "startsOn": "2026-09-01",
  "endsOn": null,
  "prices": {
    "basePricePerElement": 1600,
    "includedDocuments": 600,
    "overageDocumentPrice": 1,
    "advanceModulePrice": 600,
    "emailModulePrice": 600,
    "vatRate": 0.2
  }
}