ESIR za agencije i developere: fiskalizacija web shopa klijenta za dan

Za svaki API projekat postoji dokumentacija sa primerima u curl, Node, PHP, C# i Python, OpenAPI opis iz kojeg se generiše klijent i tekstualna verzija dokumentacije koju možete dati AI asistentu zajedno sa opisom vaše platforme.

1. 1

   Token

   OAuth 2.0 client credentials sa client id i tajnom na https://auth.bokapos.rs/realms/boka/protocol/openid-connect/token. Token važi 300 sekundi; keširajte ga i obnovite pre isteka. Tajna živi samo na serveru.

2. 2

   Poreske oznake

   GET /v1/tax-rates za obveznika i poslovni prostor. Oznake iz odgovora su jedine koje račun sme da nosi. Sandbox i produkcija imaju različit skup, pa ih nikad ne ugrađujte u kod.

3. 3

   Fiskalni dokument

   POST /v1/fiscal-documents sa zaglavljem Idempotency-Key izvedenim iz porudžbine, stavkama, plaćanjima i po potrebi kupcem. Odgovor 201 sa fiscalized: true je račun; sve ostalo nije.

4. 4

   Prikaz računa

   Iz odgovora uzmite pfr.verificationUrl i adresu PDF-a ili slike, sačuvajte id dokumenta uz porudžbinu i prikažite ili pošaljite račun kupcu.

Refundacija, avans, predračun i kopija su posebni pozivi koje BokaPOS vodi na serveru sa ispravnim referencama, pa vaš kod šalje poslovni zahtev, ne fiskalne detalje. Koje vrste dokumenata postoje: Vrste fiskalnih računa.

• Sandbox kredencijal počinje sa boka-sbx-, produkcioni sa boka-prod-. Adresa API-ja je ista; okruženje određuje kredencijal.
• Svaki ključ vidi samo obveznike, poslovne prostore, elemente i dokumente svog okruženja; objekat drugog okruženja je za njega nepostojeći (404).
• Idempotentni ključevi su jedinstveni po organizaciji u oba okruženja, pa ključ potrošen u sandbox testu ne može da se ponovi u produkciji.
• U sandboxu račun nosi PIB probnog obveznika BOKA GROUP DOO i proverava se na sandbox.suf.purs.gov.rs; u produkciji nosi PIB klijenta i proverava se na suf.purs.gov.rs.
• Produkcija traži važeću licencu za prodaju, kopiju, predračun, obuku i avans; refundacija i storno rade uvek. Sandbox nikad ne blokira.
• Tajna kredencijala je u tajnama okruženja klijentovog servera; logovi ne sadrže token ni tajnu.

• Jedna prodaja sa više stavki, popustom i dva načina plaćanja; provera računa preko verifikacionog linka.
• Delimična refundacija po stavkama originala, sa identifikacijom kupca; refundacija gotovinom sa kopijom za potpis.
• Avansni lanac, ako klijent prima uplate pre isporuke: uplata, storno, zatvaranje završnim računom.
• Prekid veze: isti zahtev istim ključem posle 503 sa retryable: true; ponašanje na OUTCOME_UNKNOWN bez novog zahteva.
• Odbijanje na 422: poruka stiže do operatera, podaci se ispravljaju, zahtev ide sa novim ključem.
• Osvežavanje oznaka posle TAX_LABEL_NOT_CURRENT i mapiranje bez ijedne ugrađene oznake.
• Dostava računa kupcu: link, PDF ili slika, iz sistema ili preko modula E-mail.
• Pretraga dnevnika po referenci porudžbine i izvoz za knjigovođu.
• Velikodušan HTTP timeout na fiskalnim pozivima, da prekid sa vaše strane ne pretvori siguran ishod u nepoznat.

Greške koje se najčešće provuku kroz testiranje, sa rešenjima: Najčešće greške pri fiskalizaciji web shopa.

Projekat je gotov kada klijent može da radi bez vas. Na dan prelaska u produkciju ostavite mu sledeće:

• produkcioni kredencijal upisan u tajne servera, sa zabeleženim mestom gde se menja;
• dokumentovano mapiranje poreskih klasa i načina plaćanja, potvrđeno od knjigovođe;
• vlasnički pristup BokaPOS portalu kod klijenta, sa ulogama za operatere i pregled;
• dogovor ko prati upozorenja o isteku sertifikata i o stanju licence, i ko reaguje na greške 401, 403 i 503;
• kontakt za podršku: BokaPOS administracija na office@bokagroup.rs, uz identifikator operacije i referencu porudžbine, nikad tajnu ili sertifikat.

Redosled koraka od prijave poslovnog prostora do prvog računa, sa stanovišta klijenta: Fiskalizacija web shopa korak po korak. Šta klijent plaća, a šta ne: Koliko košta fiskalizacija web shopa.