API dokumentacija

Refundacija

Потпуна или делимична Промет Рефундација računa koji je BokaPOS izdao. Vi navodite koje linije i koliko se vraća; BokaPOS proverava izvorni račun, upisuje referencu i, kod povraćaja gotovine, odmah izdaje i kopiju sa linijom za potpis.

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

Pravila

Izvor je uvek račun koji je BokaPOS izdao (original.source: BOKA, fiscalDocumentId), tipa Промет Продаја, na istom obvezniku i prodajnom mestu. Refundacija računa drugog ESIR-a nije podržana, jer se ne može proveriti koliko je već vraćeno.
Svaka stavka refundacije pokazuje na liniju izvornog računa (originalLineIndex, od nule) i mora da ponovi njen naziv, jedinicu, cenu, oznake i GTIN. Količina može biti manja (delimična refundacija); zbir svih refundacija te linije nikad ne prelazi izvornu količinu.
buyer.id je obavezan: propis traži identifikaciju kupca na svakoj refundaciji (na primer 20: broj lične karte ili 10: PIB).
payments su vraćena sredstva; zbir mora biti jednak zbiru refundiranih stavki. Ako je bilo koje plaćanje CASH, BokaPOS odmah izdaje i Копију Рефундације sa linijom za potpis kupca, kao što propis traži.
Refundacija nikad nije blokirana licencom: već izdat račun uvek može da se poništi.

Zahtev

POST /v1/refund-workflows

curl -X POST "https://api.bokapos.rs/v1/refund-workflows" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-refund-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761"
  },
  "cashier": {
    "id": "web-shop"
  },
  "buyer": {
    "id": "20:001234567"
  },
  "items": [
    {
      "originalLineIndex": 0,
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CARD",
      "amount": 8990
    }
  ]
}'

Odgovor

201 Created

{
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "status": "COMPLETED",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
    "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
    "pfrTime": "2026-09-01T10:15:32.483+02:00",
    "invoiceType": "NORMAL",
    "transactionType": "SALE"
  },
  "refund": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "order-4127-refund-1",
    "clientReference": "ORDER-4127-R1",
    "invoiceType": "NORMAL",
    "transactionType": "REFUND",
    "cashierId": "web-shop",
    "buyerId": "20:001234567",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1045",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 900,
      "totalCounter": 1045,
      "invoiceCounterExtension": "ПР",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1045\nБројач рачуна:                900/1045ПР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/qr-svg",
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "preferredPaperFormat": "a4"
    },
    "reference": {
      "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
      "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
      "pfrTime": "2026-09-01T10:15:32.483+02:00"
    },
    "createdAt": "2026-09-01T14:40:04.310Z",
    "updatedAt": "2026-09-01T08:15:32.611Z"
  },
  "cashRefundCopy": null,
  "failureCode": null,
  "createdAt": "2026-09-01T14:40:04.300Z",
  "updatedAt": "2026-09-01T14:40:05.120Z"
}

`status`	Značenje	Šta uraditi
`COMPLETED`	refundacija (i kopija, ako je bila potrebna) je fiskalizovana	sačuvajte `refund.id` i `refund.pfr.*`; ako postoji `cashRefundCopy`, odštampajte je za potpis
`REFUND_PENDING`	refundacija nije poslata (V-PFR nedostupan), HTTP 503	ponovite isti zahtev istim ključem
`REFUND_OUTCOME_UNKNOWN`	refundacija poslata, odgovor nije stigao, HTTP 503	ne ponavljajte; pratite `GET /v1/operations/{refund.id}`
`COPY_PENDING`, `COPY_OUTCOME_UNKNOWN`	refundacija postoji, kopija nije završena, HTTP 503	ponovite istim ključem (pending) ili sačekajte (unknown); refundacija je već važeća
`FAILED`	V-PFR odbio; `failureCode` i `refund.pfrRejection` kažu zašto	ispravite i pošaljite sa novim ključem

Refundacija gotovinom

POST /v1/refund-workflows

curl -X POST "https://api.bokapos.rs/v1/refund-workflows" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: order-4127-refund-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761"
  },
  "cashier": {
    "id": "web-shop"
  },
  "buyer": {
    "id": "20:001234567"
  },
  "items": [
    {
      "originalLineIndex": 0,
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CASH",
      "amount": 8990
    }
  ]
}'

201 Created

{
  "id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "ORDER-4127-R1",
  "status": "COMPLETED",
  "original": {
    "source": "BOKA",
    "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
    "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
    "pfrTime": "2026-09-01T10:15:32.483+02:00",
    "invoiceType": "NORMAL",
    "transactionType": "SALE"
  },
  "refund": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "order-4127-refund-1",
    "clientReference": "ORDER-4127-R1",
    "invoiceType": "NORMAL",
    "transactionType": "REFUND",
    "cashierId": "web-shop",
    "buyerId": "20:001234567",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1045",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 900,
      "totalCounter": 1045,
      "invoiceCounterExtension": "ПР",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1045\nБројач рачуна:                900/1045ПР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d/representations/qr-svg",
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "preferredPaperFormat": "a4"
    },
    "reference": {
      "fiscalDocumentId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761",
      "pfrNumber": "JWX4K9PL-JWX4K9PL-1042",
      "pfrTime": "2026-09-01T10:15:32.483+02:00"
    },
    "createdAt": "2026-09-01T08:15:31.902Z",
    "updatedAt": "2026-09-01T08:15:32.611Z"
  },
  "cashRefundCopy": {
    "id": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "order-4127-refund-1:copy",
    "clientReference": "COPY-ORDER-4127-R1",
    "invoiceType": "COPY",
    "transactionType": "REFUND",
    "cashierId": "web-shop",
    "buyerId": "20:001234567",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1046",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 901,
      "totalCounter": 1046,
      "invoiceCounterExtension": "КР",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1046\nБројач рачуна:                901/1046КР\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c/representations/qr-svg",
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "preferredPaperFormat": "a4"
    },
    "reference": {
      "fiscalDocumentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "pfrNumber": "JWX4K9PL-JWX4K9PL-1045",
      "pfrTime": "2026-09-01T16:40:05.120+02:00"
    },
    "createdAt": "2026-09-01T08:15:31.902Z",
    "updatedAt": "2026-09-01T08:15:32.611Z"
  },
  "failureCode": null,
  "createdAt": "2026-09-01T14:40:04.300Z",
  "updatedAt": "2026-09-01T14:40:06.902Z"
}

Kod povraćaja gotovine BokaPOS odmah izdaje i kopiju refundacije (`cashRefundCopy`) sa linijom za potpis kupca; odštampajte je i dajte kupcu na potpis.

Delimična refundacija

Za povraćaj dela porudžbine pošaljite samo linije koje se vraćaju, sa količinom koja se vraća. Ako je izvorni račun imao dve linije i kupac vraća jedan od dva komada prve, items sadrži jednu stavku sa originalLineIndex: 0 i quantity: 1. Sledeća refundacija iste linije može da vrati najviše preostali komad. Cene i oznake se ne menjaju: refundira se ono što je bilo na računu.

Refundacija ostalih vrsta

Avans: storno pogrešne avansne uplate i zatvaranje slučaja su Аванс Рефундација, kroz /v1/advance-cases (Avans).
Predračun i obuka: refundacija mora da ponovi ceo izvorni dokument, kroz /v1/proforma-training-workflows (Predračun i obuka).
Kopija postojeće refundacije: POST /v1/fiscal-documents/{refund.id}/copies.

Greške kod refundacije

HTTP	Kod	Značenje	Šta uraditi	Ponavljanje
422	`REFERENCE_DOCUMENT_NOT_FOUND`	Referentni dokument (`reference.fiscalDocumentId`) ne postoji.	Proverite identifikator iz odgovora originalnog računa.	ispravi zahtev
422	`REFERENCE_DOCUMENT_NOT_FISCALIZED`	Referentni dokument nije fiskalizovan, pa ne može biti referenca.	Referenca sme da pokazuje samo na dokument sa statusom FISCALIZED.	ispravi zahtev
422	`REFERENCE_DOCUMENT_SCOPE_MISMATCH`	Referentni dokument pripada drugom obvezniku ili prodajnom mestu.	Referenca mora biti na istom obvezniku i prodajnom mestu.	ispravi zahtev
422	`REFERENCE_DOCUMENT_TYPE_NOT_ALLOWED`	Kombinacija vrste računa i transakcije ne sme da se poziva na tu vrstu izvornog dokumenta (zvanična matrica referenci).	Pogledajte tabelu referenci na stranici Konvencije.	ispravi zahtev
422	`REFUND_QUANTITY_EXCEEDS_ORIGINAL`	Vraćena količina je veća od količine na izvornoj liniji.	Smanjite količinu; delimična refundacija je dozvoljena.	ispravi zahtev
422	`REFUND_CUMULATIVE_QUANTITY_EXCEEDED`	Zbir svih dosadašnjih refundacija te linije premašio bi izvornu količinu.	Proverite ranije refundacije u dnevniku.	nikad
422	`REFUND_ITEM_MUST_MATCH_ORIGINAL_LINE`	Naziv, cena, oznake ili GTIN se ne poklapaju sa izvornom linijom `originalLineIndex`.	Prepišite stavku iz izvornog računa (`GET /v1/fiscal-documents/{id}/representations/canonical-json`).	ispravi zahtev
422	`REFUND_ORIGINAL_LINE_NOT_FOUND`	`originalLineIndex` ne postoji na izvornom računu.	Indeksi su od nule, po redosledu stavki originala.	ispravi zahtev