API dokumentacija

Predračun i obuka

Предрачун je ponuda koja izgleda kao račun, ali nema poreski efekat; Обука je vežba za operatere i testove. Oba idu kroz jedan ograničeni tok sa jasnim pravilima referenci.

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

Kada se koriste

Predračun (PROFORMA): ponuda ili profaktura kupcu pre plaćanja, na primer za B2B porudžbinu koja se plaća virmanom. Štampa ОВО НИЈЕ ФИСКАЛНИ РАЧУН. Kada kupac plati i roba se isporuči, izdaje se pravi račun za promet (koji se ne poziva na predračun).
Obuka (TRAINING): probni dokument za obuku operatera ili testiranje toka. Nema poreski efekat i takođe štampa ОВО НИЈЕ ФИСКАЛНИ РАЧУН. U produkciji je to dokument kojim BokaPOS dokazuje aktivaciju vašeg sertifikata.

Pravila

Dokument	Referenca (`original`)
Предрачун Продаја	bez reference, ili na BokaPOS predračun (prodaju ili refundaciju)
Предрачун Рефундација	obavezno na BokaPOS Предрачун Продају; ponavlja sve stavke i plaćanja i identifikuje kupca
Обука Продаја	bez reference
Обука Рефундација	obavezno na BokaPOS Обука Продају; ponavlja ceo izvorni dokument

Izvor može biti refundiran samo jednom u celosti; drugi pokušaj vraća 409. Spoljni dokumenti nisu podržani. Poreske oznake, iznosi i plaćanja prate ista pravila kao račun za promet.

Predračun

POST /v1/proforma-training-workflows

curl -X POST "https://api.bokapos.rs/v1/proforma-training-workflows" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: quote-2210-proforma-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "QUOTE-2210",
  "invoiceType": "PROFORMA",
  "transactionType": "SALE",
  "cashier": {
    "id": "web-shop"
  },
  "buyer": {
    "id": "10:106952811"
  },
  "items": [
    {
      "name": "Bluetooth slušalice",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 8990,
      "gtin": "8606012345678",
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "WIRE_TRANSFER",
      "amount": 8990
    }
  ],
  "commercialFooter": "Ponuda važi 7 dana."
}'

201 Created

{
  "id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d",
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "QUOTE-2210",
  "invoiceType": "PROFORMA",
  "transactionType": "SALE",
  "state": "COMPLETED",
  "original": null,
  "document": {
    "id": "1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e",
    "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
    "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
    "idempotencyKey": "quote-2210-proforma-1",
    "clientReference": "QUOTE-2210",
    "invoiceType": "PROFORMA",
    "transactionType": "SALE",
    "cashierId": "web-shop",
    "buyerId": "10:106952811",
    "buyerDetails": null,
    "status": "FISCALIZED",
    "fiscalized": true,
    "failureCode": null,
    "retryable": false,
    "pfr": {
      "invoiceNumber": "JWX4K9PL-JWX4K9PL-1047",
      "sdcTime": "2026-09-01T10:15:32.483+02:00",
      "requestedBy": "JWX4K9PL",
      "signedBy": "JWX4K9PL",
      "transactionTypeCounter": 902,
      "totalCounter": 1047,
      "invoiceCounterExtension": "ПрП",
      "totalAmount": 8990,
      "totalTax": 890.9009,
      "verificationUrl": "https://sandbox.suf.purs.gov.rs/v/?vl=A0pXWDRLOVBMSldYNEs5UEwSBAAAEAQAAKCLPAAAAAAAAAABnAqJa1EAAAA...",
      "journal": "============ ФИСКАЛНИ РАЧУН ============\n...\nПФР број рачуна:      JWX4K9PL-JWX4K9PL-1047\nБројач рачуна:                902/1047ПрП\n========================================\n======== КРАЈ ФИСКАЛНОГ РАЧУНА ========="
    },
    "receipt": {
      "textUrl": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/representations/official-text",
      "jsonUrl": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/representations/canonical-json",
      "pdfA4Url": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/representations/pdf-a4",
      "pdf80mmUrl": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/representations/pdf-80mm",
      "pdf58mmUrl": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/representations/pdf-58mm",
      "previewImageUrl": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/representations/preview-png",
      "qrImageUrl": "/v1/fiscal-documents/1b2c3d4e-5f6a-4b7c-8d9e-0f1a2b3c4d5e/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"
  },
  "failureCode": null,
  "createdAt": "2026-09-02T07:02:10.000Z",
  "updatedAt": "2026-09-02T07:02:11.204Z"
}

Obuka

POST /v1/proforma-training-workflows

curl -X POST "https://api.bokapos.rs/v1/proforma-training-workflows" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN" \
  -H "Idempotency-Key: training-2026-09-02-1" \
  -H "Content-Type: application/json" \
  -d '{
  "taxpayerId": "3f9c2a8e-6b1d-4e5a-9c47-1d2b8e6f0a11",
  "businessPremiseId": "b7d4e2c1-9a3f-4c8e-8f21-6e5a0c9d3b22",
  "clientReference": "TRAINING-1",
  "invoiceType": "TRAINING",
  "transactionType": "SALE",
  "cashier": {
    "id": "operater-1"
  },
  "items": [
    {
      "name": "Test artikal",
      "unitOfMeasure": "kom",
      "quantity": 1,
      "unitPrice": 100,
      "taxLabels": [
        "F"
      ]
    }
  ],
  "payments": [
    {
      "type": "CASH",
      "amount": 100
    }
  ]
}'

Stanja toka

`state`	HTTP	Značenje
`COMPLETED`	201 (200 pri ponavljanju)	dokument je potpisan; `document` nosi PFR podatke i prikaze
`PENDING`	202 ili 503	rezervisano, nije poslato; ponovite istim ključem
`OUTCOME_UNKNOWN`	503	poslato, odgovor nije stigao; ne ponavljajte, čitajte `GET /v1/proforma-training-workflows/{id}`
`REJECTED`	422	V-PFR odbio; ispravite i pošaljite sa novim ključem
`FAILED`	503	greška pre slanja; `failureCode`

GET /v1/proforma-training-workflows/{proformaTrainingWorkflowId}

curl -X GET "https://api.bokapos.rs/v1/proforma-training-workflows/0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d" \
  -H "Authorization: Bearer $BOKAPOS_TOKEN"

Greške kod predračuna i obuke

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
422	`TAX_LABEL_NOT_CURRENT`	Bar jedna poreska oznaka nije u svežoj konfiguraciji V-PFR-a (polje `invalidLabels`).	Pročitajte `GET /v1/tax-rates` i koristite samo oznake koje vrati; sandbox i produkcija imaju različit skup.	ispravi zahtev
422	`REFERENCE_DOCUMENT_NOT_FOUND`	Referentni dokument (`reference.fiscalDocumentId`) ne postoji.	Proverite identifikator iz odgovora originalnog računa.	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
409	`PROFORMA_TRAINING_WORKFLOW_RESERVATION_CONFLICT`	Izvorni dokument već ima nerazrešenu ili završenu refundaciju.	Pročitajte tok iz `workflowId` u odgovoru.	nikad
409	`PROFORMA_TRAINING_SOURCE_ALREADY_REFUNDED`	Predračun ili obuka je već refundirana u celosti.	Nema dalje akcije.	nikad