Konvencije

Identifikatori u svakom zahtevu

Idempotency-Key

Svaka fiskalna izmena (POST na /v1/fiscal-documents, /copies, /v1/refund-workflows, /v1/advance-cases*, /v1/proforma-training-workflows, /v1/receipt-deliveries) zahteva zaglavlje Idempotency-Key dužine 16 do 200 znakova. Ključ je jedinstven unutar vaše organizacije i vezuje se za kanonski sadržaj zahteva:

• isti ključ, isti sadržaj: API vraća originalnu operaciju (200 umesto 201) i ne izdaje drugi račun, ma koliko puta ponovili;
• isti ključ, drugačiji sadržaj: 409 IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST sa operationId originala;
• nov ključ: nova operacija, i potencijalno nov račun.

{
  "code": "IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST",
  "operationId": "9f8e7d6c-5b4a-4321-8765-0fedcba98761"
}

Statusi dokumenta

Svaki fiskalni zahtev postaje trajna operacija sa statusom. Status je istina; HTTP kod je samo njegov sažetak.

Kako tumačiti odgovor

1. 01

   201 i fiscalized: true

   Račun postoji. Sačuvajte id, pfr.invoiceNumber, pfr.sdcTime, pfr.verificationUrl i, po potrebi, PDF. Porudžbina je fiskalizovana.

2. 02

   503 i retryable: true

   Ništa nije poslato (NOT_FISCALIZED, na primer PFR_SUBMISSION_FAULT ili CURRENT_TAX_CONFIGURATION_UNAVAILABLE). Sačekajte nekoliko sekundi i pošaljite isti zahtev sa istim ključem. Ograničite broj pokušaja i posle toga prepustite operateru.

3. 03

   503 i status OUTCOME_UNKNOWN

   Ne šaljite nov zahtev za istu prodaju. Zapamtite id i proveravajte GET /v1/operations/{id} (na primer na 30 sekundi, pa ređe). BokaPOS u pozadini razrešava ishod isključivo čitanjem kod V-PFR-a; kada ga nađe, status postaje FISCALIZED. Ako ishod ostane nepoznat, operater odlučuje u portalu.

4. 04

   422

   Zahtev krši pravilo (naše ili V-PFR-ovo). Ništa nije izdato. Ispravite zahtev i pošaljite ga sa novim ključem, jer je stari ključ vezan za pogrešan sadržaj.

5. 05

   403

   Okruženje ili licenca. Ništa nije izdato. Sandbox nikad ne dobija 403 zbog licence.

6. 06

   409

   Sukob: ključ ponovo upotrebljen sa drugim sadržajem, ili radnja koja nije dozvoljena u trenutnom stanju toka (avans, predračun). Pročitajte stanje i nastavite od njega.

Iznosi, količine i zaokruživanje

• Sve cene i iznosi su bruto, u dinarima, sa najviše dve decimale (8990.00). Više decimala V-PFR odbija (šifra 2804).
• unitPrice je konačna jedinična cena posle popusta. Porez ne šaljete: BokaPOS ga računa iz poreske oznake po zvaničnim pravilima i V-PFR ga potpisuje.
• unitPriceBeforeDiscount je opciona cena pre popusta, samo za prikaz izvan fiskalnog dela računa; mora biti veća od unitPrice.
• quantity ima do tri decimale (1.5), minimum 0.001.
• Zbir quantity × unitPrice po stavkama, zaokružen na dve decimale, mora biti jednak zbiru payments. Inače 422 sa greškom u polju totals.
• Više načina plaćanja na istom računu je dozvoljeno (payments je lista).

Vreme

• Sva vremena su ISO 8601. createdAt i updatedAt su u UTC (Z). pfr.sdcTime je vreme potpisa V-PFR-a sa pomakom koji je V-PFR poslao (+02:00 ili +01:00); to je zvanično vreme računa.
• Filteri pfrFrom/pfrTo u dnevniku i izveštajima se odnose na sdcTime; createdFrom/createdTo na trenutak kada je BokaPOS primio zahtev. Donja granica je uključena, gornja isključena.
• Ne šaljete vreme računa. Jedini izuzetak je avansna uplata virmanom primljena ranije (paymentOccurredAt), po zvaničnom pravilu; vidite Avans.

Vrste računa i transakcija

POST /v1/fiscal-documents prihvata samo NORMAL SALE; sve ostalo ima svoj tok koji BokaPOS vodi na serveru, sa ispravnim referencama i redosledom.

Reference između dokumenata

Refundacija, kopija i konačni račun posle avansa moraju da se pozovu na izvorni dokument (PFR broj i vreme). Kada je izvor dokument koji je BokaPOS izdao, šaljete samo njegov fiscalDocumentId ({ "source": "BOKA", "fiscalDocumentId": "..." }) i BokaPOS upisuje tačne PFR podatke; na istom obvezniku i prodajnom mestu. Referenca na dokument drugog ESIR-a (source: EXTERNAL) traži tačan PFR broj, vreme i vrstu i podržana je samo za kopiju kroz POST /v1/fiscal-documents; refundacija i avans spoljne dokumente ne prihvataju.

Načini plaćanja

Prodajno mesto može da radi u ograničenom režimu plaćanja (samo OTHER, CASH, WIRE_TRANSFER, VOUCHER); tada ostali načini vraćaju 422 PAYMENT_TYPE_NOT_ALLOWED_ON_PREMISE. Režim se vidi u polju paymentMode prodajnog mesta.

Identifikacija kupca

buyer.id je zvanični prefiks:vrednost. Obavezan je na svakoj refundaciji, kod prodaje firmi koje traže PIB na računu, i u drugim slučajevima koje propisi nabrajaju. Za domaću firmu (10:, 12: ili 14: sa važećim PIB-om) BokaPOS automatski dodaje naziv i adresu kupca iz registra NBS ispod identifikacije, na svim prikazima; vraća ih i u buyerDetails.

buyer.optionalField je opciono polje kupca, takođe prefiks:vrednost: 20: SNPDV, 21: LNPDV, 30: do 33: PPO-PDV obrasci, 50: broj korporativne kartice (plaćanje je VOUCHER), 60: period refundacije korporativne kartice ddMMyyyy_ddMMyyyy. Isti prefiks znači različite stvari u dva polja.

Paginacija

Liste dnevnika koriste stabilan keyset: odgovor nosi nextCursor, koji šaljete kao cursor za sledeću stranicu; null je kraj. pageSize je do 200 (podrazumevano 50). Lista proizvoda koristi isti obrazac sa UUID cursor-om. Redosled je po createdAt pa id, opadajuće, pa nova stranica nikad ne preskače i ne ponavlja zapis.

Oblik grešaka

Potpun katalog kodova sa preporukom šta uraditi je na stranici Greške.