Greške

Oblici odgovora

• { "code": "..." } sa opcionim message i dodatnim poljima (invalidLabels, module, operationId): pravilo BokaPOS-a, licenca ili okruženje.
• RFC 9457 problem sa errors po polju (application/problem+json): validacija oblika zahteva, uvek 422.
• Fiskalni dokument sa fiscalized: false (503): V-PFR nedostupan ili nepoznat ishod; status, failureCode i retryable kažu šta dalje.
• Tok (refundacija, predračun, avans) sa svojim status/state i ugrađenim dokumentima: greška se čita iz stanja toka.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.21",
  "title": "One or more validation errors occurred.",
  "status": 422,
  "errors": {
    "totals": [
      "The item and payment totals must match after the mandated two-decimal currency rounding."
    ]
  }
}

{
  "code": "MODULE_NOT_LICENSED",
  "module": "advance",
  "message": "This module is not included in the organization's licence. Contact BokaPOS Administration to enable it."
}

{
  "code": "TAX_LABEL_NOT_CURRENT",
  "invalidLabels": ["Ђ"],
  "message": "Every tax label must be present in the freshly fetched current PFR configuration."
}

{
  "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": "NOT_FISCALIZED",
  "fiscalized": false,
  "failureCode": "PFR_SUBMISSION_FAULT",
  "retryable": true,
  "pfr": null,
  "receipt": null,
  "createdAt": "2026-09-01T08:15:31.902Z",
  "updatedAt": "2026-09-01T08:15:32.611Z"
}

Katalog kodova

Kolona Ponavljanje: *isti ključ* znači da isti zahtev sa istim Idempotency-Key ima smisla; *ispravi zahtev* znači nov sadržaj i nov ključ; *kasnije* znači da se stanje menja van vašeg sistema (licenca, podešavanja); *nikad* znači da ponavljanje ne može da pomogne.

Šifre odbijanja V-PFR-a

Kada V-PFR odbije zahtev, dokument dobija status REJECTED, failureCode: PFR_VALIDATION_REJECTED, a pojedinačno čitanje (GET /v1/fiscal-documents/{id}) nosi pfrRejection.items sa putanjom polja iz vašeg zahteva i šifrom:

Robusna integracija

• Izvedite Idempotency-Key iz porudžbine i sačuvajte ga pre slanja, da posle prekida možete da ponovite isti zahtev.
• Na 503 sa retryable: true ponovite istim ključem uz eksponencijalno čekanje (na primer 2, 5, 15 sekundi), najviše nekoliko puta; zatim označite porudžbinu za operatera.
• Na OUTCOME_UNKNOWN nikad ne šaljite nov zahtev: zapamtite id i proveravajte GET /v1/operations/{id} sve dok status ne postane FISCALIZED ili operater ne odluči.
• Na 422 i REJECTED beležite errors odnosno pfrRejection uz porudžbinu, ispravite izvor podataka i pošaljite sa novim ključem.
• Na 401 uzmite nov token i ponovite isti zahtev. Na 403 pročitajte GET /v1/license.
• Osvežite poreske oznake kad dobijete TAX_LABEL_NOT_CURRENT, ne pre svakog računa.
• Postavite HTTP timeout na fiskalnim pozivima velikodušno (na primer 60 sekundi): V-PFR odgovara obično za oko dve sekunde, ali prekid veze sa vaše strane pretvara siguran ishod u nepoznat.
• Logujte id, status, failureCode i pfr.invoiceNumber; nikad ne logujte token ni tajnu.