Sandbox za fiskalizaciju: od testnog naloga do produkcije za jedan dan

Sandbox za fiskalizaciju je testni nalog u Tezga eKasi čiji računi idu u sandbox Poreske uprave i nisu fiskalni. Developer na njemu gradi i testira integraciju sa pravim API-jem i pravim odgovorima, a prelazak u produkciju je zamena API ključa u okruženju, jer je okruženje osobina naloga, ne ključa. Ceo put staje u jedan radni dan.

Šta je sandbox Poreske uprave i šta u njemu nije fiskalno?

Poreska uprava održava testno okruženje sistema za fiskalizaciju, u kome ESIR i PFR razmenjuju iste poruke kao u produkciji, ali dokumenti nemaju pravno dejstvo. Tezga eKasa, odobreni ESIR pod brojem ИБ 1597, u sandbox šalje sve što bi u produkciji slala V-PFR-u: račune, avanse, refundacije, storna, kopije. Odgovori su isti po obliku, pa integracija koja radi u sandboxu radi i u produkciji. Razlika je jedino u tome kuda dokument ide.

Iz ugla developera to znači da nema „lažnog” API-ja koji imitira kasu. Poziv na POST /api/integrations/order?provider=custom sa testnim ključem prolazi kroz istu validaciju tela, istu proveru externalId, isto grananje na 200, 202, 400, 401, 402 i 429. Ono što ne možeš da testiraš u sandboxu je stvarna nedostupnost V-PFR-a, jer nju ne izazivaš ti; to simuliraš u sopstvenom kodu, o čemu pišemo dalje. Zvanična dokumentacija testnog okruženja je na sajtu Poreske uprave, a opis Tezga API-ja na strani API za fiskalizaciju i u OpenAPI dokumentu.

Kako izgleda testni nalog i kako se traži?

Testni nalog integratoru otvara Go Simple na zahtev, kad integrator kaže da je spreman da počne. U nalogu je sve isto kao u produkciji: katalog, kupci, podešavanja integracija, odlazna obaveštenja, izveštaji. Jedina vidljiva razlika je oznaka okruženja u zaglavlju i to što računi idu u sandbox. Strana za integratore sa uputstvom je na pos.narbiz.com/za-integratore.

Kartica testnog okruženja pokazuje oznaku sandboxa, ključ koji se vidi samo jednom i listu testnih dokumenata sa HTTP kodom svakog.

Ključ se pravi u toj kartici, počinje sa tzg_ i nosi 48 heksadecimalnih znakova. Vidi se samo jednom; kasa ga čuva kao heš, pa ako ga izgubiš, praviš nov. Ključu daješ ime po sistemu koji ga koristi („shop-next-test”, „n8n-test”), opciono ga vezuješ za IP adresu i uključuješ HMAC potpis tela kroz zaglavlje X-Tezga-Signature. Ista kartica postoji na produkcionom nalogu; razlika je samo oznaka okruženja.

Kada koristiti račun obuke umesto sandboxa?

Pravilnik o vrstama fiskalnih računa poznaje tip računa „obuka”, a Tehničko uputstvo za ESIR traži da svaki dokument koji nije fiskalni račun nosi napomenu „ОВО НИЈЕ ФИСКАЛНИ РАЧУН”. Račun obuke se izdaje na produkcionom nalogu, prolazi kroz pravi V-PFR i pojavljuje se u evidenciji kao obuka, bez poreskog dejstva. To je alat za dva slučaja: kad klijent već ima produkcioni nalog, pa hoćeš da proveriš ceo lanac pre prve prave porudžbine, i kad obučavaš osobu koja će kasu koristiti ručno.

Sandbox je za razvoj, obuka je za poslednju proveru u produkciji. Ne obrnuto: razvoj na produkcionom nalogu, čak i sa tipom obuke, ostavlja trag u evidenciji klijenta, a greška u jednom polju (tip računa zaboravljen u kodu) daje pravi fiskalni račun. Kako režim obuke izgleda iz ugla korisnika kase opisao je autor kase u tekstu režim obuke: fiskalna kasa za vežbanje.

Zašto je okruženje osobina naloga, a ne ključa?

U mnogim API-jima okruženje se bira prefiksom ključa ili drugom adresom. Tezga to radi drugačije: okruženje je vezano za nalog. Testni nalog je testni bez obzira na to koji od njegovih ključeva koristiš, a produkcioni je produkcioni. Adresa je uvek https://pos.narbiz.com. Posledica za tebe je jednostavna: kod nema ni jednu granu tipa „ako je test, onda...”. Postoji jedna promenljiva okruženja, na primer TEZGA_API_KEY, i njena vrednost odlučuje sve.

To nosi i obavezu. Pošto se ne vidi iz adrese kuda dokument ide, ključeve držiš u odvojenim okruženjima: lokalno i staging sa ključem testnog naloga, produkcija sa ključem produkcionog naloga. Nikad ista datoteka sa oba ključa, nikad ključ u repozitorijumu. Kad tim to jednom uredi, prelazak u produkciju je zamena jedne vrednosti u tajnama hosting platforme.

Prva tri koraka rade u sandboxu Poreske uprave, poslednja tri u produkciji; kod se ne menja, menja se ključ.

Kako podeliti ključeve između sistema i okruženja?

Firma može da ima do 20 ključeva, a to nije ograničenje nego poziv da ih koristiš. Pravilo koje primenjujemo: jedan ključ po sistemu po okruženju. Web shop, n8n, ERP i CRM svaki dobijaju svoj ključ, i to zasebno za test i za produkciju. Ime ključa u kasi kaže ko ga koristi. Kad jedan sistem treba da se ugasi ili kad ključ procuri, gasi se samo taj ključ, ostali rade.

• Vezivanje za IP. Za sistem sa stalnom adresom (VPS, server klijenta) uključi. Za cloud funkcije i n8n cloud, čije adrese se menjaju, ostavi isključeno i osloni se na HMAC.
• HMAC potpis. Kad je uključen, svaki zahtev nosi X-Tezga-Signature: sha256=... nad telom. Tajna za potpis je zasebna od ključa i takođe živi u okruženju.
• Rotacija. Ključ se rotira na 90 dana. Postupak bez prekida: napravi nov ključ, upiši ga u okruženje, potvrdi da prvi zahtev prolazi, ugasi stari. Kasa vodi dnevnik pristupa, pa se vidi kad je stari ključ poslednji put korišćen.
• Ko drži ključ. Ključ pripada firmi klijenta. Agencija ga drži u svom okruženju dok održava sajt, a pri predaji klijent dobija uputstvo kako da napravi nov ključ i ugasi agencijski.

Ovaj raspored ključeva je i osnova za više klijenata: svaki klijent ima svoj nalog i svoje ključeve, agencija nikad ne deli ključ između klijenata. O bezbednosnim merama kase (HTTPS, ključ kao heš, ograničenje broja zahteva, dnevnik pristupa, podaci u EU regionu) piše strana sigurnost i zaštita podataka.

Kako izgleda jedan radni dan od naloga do produkcije?

Naslov obećava jedan dan, pa evo kako ga delimo. Pretpostavka je da shop već postoji i da je naplata rešena; ovde se dodaje fiskalizacija.

Pet blokova jednog radnog dana: sandbox do ranog popodneva, kontrolna lista sa klijentom, pa zamena ključa i prvi pravi račun.

1. 9:00 do 9:30, nalog i ključ. Testni nalog je već otvoren (zatražen dan ranije). Praviš ključ „shop-test”, upisuješ ga u lokalno i staging okruženje, zoveš GET /api/integrations/tax-labels da proveriš da ključ radi i da uzmeš poreske oznake za katalog.
2. 9:30 do 12:00, integracija. Poziv iz reda čekanja posle potvrde naplate, externalId iz broja porudžbine, grananje po HTTP kodu, prijem odlaznog webhooka racun.fiskalizovan sa proverom potpisa. Isečke za Next.js, Laravel i WordPress ima u tekstu fiskalizacija za custom sajt.
3. 13:00 do 14:00, ružne probe. Isti callback tri puta, prekid mreže usred zahteva, simulirano 202, porudžbina u 23:59, delimičan povraćaj, PIB sa 8 cifara. Spisak proba i šta svaka otkriva je u tekstu 10 grešaka pri fiskalizaciji web shopa.
4. 14:00 do 15:30, kontrolna lista sa klijentom. Klijent na stagingu napravi tri porudžbine i jedan povraćaj, gleda mejl koji stiže kupcu, gleda dokumente u kasi. Prolazite 15 tačaka iz sledećeg odeljka.
5. 15:30 do 17:00, produkcija. Klijent pravi produkcioni ključ „shop-prod” (ili ga praviš ti uz njega), upisuješ u tajne hostinga, izdaješ jedan račun tipa obuka, proveravaš da stigne mejl i webhook, i puštaš prvu pravu porudžbinu.

Kontrolna lista predaje klijentu: 15 tačaka

Lista je pisana tako da svaka tačka ima jasan odgovor „da” ili „ne”. Prelazak u produkciju traži 15 puta „da”.

1. Ključ se ne nalazi ni u repozitorijumu ni u klijentskom bundlu (pretraga za nizom tzg_ daje nula pogodaka).
2. Testni i produkcioni ključ su u odvojenim okruženjima pod istim imenom promenljive.
3. Poziv ka kasi ide sa servera, iz reda čekanja, ne iz zahteva koji odgovara procesoru.
4. Poziv se šalje tek posle potvrde naplate (kartica), viđene uplate (prenos) ili isporuke (pouzeće), u skladu sa Zakonom o fiskalizaciji.
5. externalId potiče iz broja porudžbine i isti je u svakom ponovljenom pokušaju.
6. Tri istovremena callbacka daju tačno jedan dokument.
7. Odgovor 202 ne pokreće novi zahtev; porudžbina čeka webhook.
8. Odgovor 400 ide čoveku, ne u ponavljanje; 5xx i istek vremena se ponavljaju sa rastućim razmakom.
9. Način plaćanja je usklađen: kartica je „Platna kartica”, pouzeće i uplata su „Prenos na račun”, PayPal i slično „Drugo bezgotovinsko”.
10. Dostava koju kupac plaća je stavka na računu sa svojom poreskom oznakom.
11. Poreske oznake u katalogu su uzete iz GET /api/integrations/tax-labels, ne prepisane iz drugog projekta.
12. Refundacija pokazuje na original po documentId ili externalId, radi po stavkama, i traži kupacIdBroj kad original nema kupca.
13. Mejl sa računom kupcu šalje kasa posle fiskalizacije; shop šalje samo potvrdu porudžbine.
14. Odlazni webhook prima se sa proverom X-Tezga-Signature, a X-Tezga-Delivery se pamti radi idempotentnosti primaoca.
15. Klijent ima pisano uputstvo: gde je ključ, kako se rotira na 90 dana, šta znače 401 i 402, koga zove ([email protected] za kasu, agenciju za sajt).

Tačka 15 je ta koja razdvaja predaju od napuštanja. Klijent koji zna da 402 znači potrošen kredit u paketu „Po računu” (4 RSD po fiskalnom računu i refundaciji, dopuna unapred 2.000 do 20.000 RSD, kredit važi 12 meseci; posle potrošenog kredita još 100 računa, pa API vraća 402) sam dopuni i ne zove agenciju u subotu. Klijent koji zna da 401 posle 90 dana znači da ključ treba rotirati, ne misli da je sajt „pukao”.

Kako simulirati ono što sandbox ne može?

Sandbox je stabilan, a produkcija nije uvek. Tri stvari ne možeš da izazoveš spolja, pa ih izazivaš u sopstvenom kodu, prekidačem koji postoji samo u test okruženju.

• Nedostupan PFR (202). Klijent ka kasi u testu vraća 202 na zahtev, pa proveravaš da porudžbina prelazi u stanje čekanja, da se ne šalje novi zahtev i da naknadni webhook zatvara stanje. Isto za refundaciju: kad PFR padne, POST /api/integrations/refund vraća 202 i ponovljeni zahtev ne pravi dupli dokument.
• Istek vremena. Zahtev je otišao, odgovor nije stigao. Ponavljanje sa istim externalId mora da vrati isti dokument. Proveravaš da se u bazi ne pojavi drugi red.
• Ograničenje broja zahteva (429). Radnik čeka i ponavlja, ne odbacuje porudžbinu.

Sve tri probe postaju automatski testovi koji se pokreću pre svakog puštanja izmene. Integracija koja ih nema, po našem iskustvu, radi do prvog zastoja PFR-a, a onda pravi posao knjigovođi. Ako se web shop gradi kao headless na Next.js, mesto za te testove i za red čekanja opisano je u tekstu headless web shop na Next.js sa fiskalizacijom; pregled kase iz ugla agencije je na strani fiskalna kasa za klijente agencije. Kad je shop na WooCommerce ili Shopify, dvosmerna veza kase pokriva red čekanja i idempotentnost bez vašeg koda, o čemu piše Trek u vodiču Tezga eKasa API, integracije i automatizacije.

Poslednja napomena o obimu: sandbox i sve gore važe za online prodaju i prodaju na daljinu, gde je V-PFR dozvoljen. Za prodaju na licu mesta u fizičkom objektu Zakon o fiskalizaciji traži L-PFR, a sopstveni L-PFR Tezge je u pripremi bez obećanog datuma. Ako klijent ima i radnju, to je zaseban razgovor. Za SEF tok (e-fakture za B2B) testni nalog takođe radi, a pravila sistema su na efaktura.mfin.gov.rs.

Izvori: Zakon o fiskalizaciji (Sl. glasnik RS 153/2020, 96/2021, 138/2022); Pravilnik o vrstama fiskalnih računa, tipovima transakcija, načinima plaćanja; Tehničko uputstvo za ESIR i dokumentacija testnog okruženja Poreske uprave (purs.gov.rs); Sistem e-faktura (efaktura.mfin.gov.rs); uputstvo za integratore, strana za integratore i OpenAPI opis Tezga eKase (odobreni ESIR, ИБ 1597). Tekst nije pravni savet; poreske situacije klijenta proverite sa njegovim knjigovođom.

Ako vaš tim danas počinje integraciju, zatražite testni nalog preko strane API za fiskalizaciju ili otvorite nalog na strani probaj fiskalnu kasu; za kontrolnu listu i pitanja pišite na [email protected].