API
Detaljna objasnjenja upotrebe našeg api servisa za korisnike koji sami razvijaju aplikacije a koriste naš API za fiskalizaciju i efakture.
Integracije: API ključ, webhookovi i log fiskalizacije
Meni Integracije (API) služi za povezivanje spoljnih sistema, kao što su WooCommerce, WHMCS, Shopify, POS ili vaš ERP, koji preko API-ja izdaju fiskalne račune. Tehnička uputstva za programere su u portalu API dokumentacija našeg centra za pomoć. Integracije i API ključevi Integracija i API ključ 1. Kliknite Nova integracija. 2. Unesite Naziv (npr. „WooCommerce - web prodavnica“) i izaberite Tip. 3. Opciono izaberite Poslovnu lokaciju. Tada sistem koji šalje račune ne mora da je navodi u svakom zahtevu. 4. Kliknite Sačuvaj. Forma za novu integraciju Zatim u kartici integracije kliknite Novi ključ. Ključ ima oblik fk_live_... i prikazuje se samo jednom. Kopirajte ga odmah i unesite u sistem koji povezujete. Ako ga izgubite, napravite nov. Pravila: - Firma može imati samo jedan aktivan API ključ, u svim integracijama zajedno. - Rotiraj (kružna strelica) opoziva stari ključ i odmah izdaje nov. - Opozovi (kanta) gasi ključ. Sistem koji ga koristi odmah prestaje da radi. - Opozvan ključ se može trajno obrisati. - Deaktiviraj gasi celu integraciju. Webhookovi Tab Webhookovi Webhook obaveštava vaš sistem kada se promeni stanje računa, pa taj sistem ne mora sam da proverava. Kliknite Novo webhook odredište, unesite URL i izaberite događaje: fiskalizacija uspela, fiskalizacija neuspela, dokument otkazan, dokument storniran. Tajni ključ (whsec_...) se prikazuje samo jednom. Koristi se za proveru potpisa u zaglavlju X-Finora-Signature. Firma može imati jedan aktivan webhook. Ako isporuka ne uspe, HAFiscal pokušava ponovo. Isporuka se pokušava najviše 8 puta ukupno, u razmacima do dva sata. Log fiskalizacije Tab Log fiskalizacije Poslednjih 10 pokušaja fiskalizacije preko API-ja: vreme, integracija, broj narudžbine (External ID), iznos, status i fiskalni broj, ili poruka greške. Log se osvežava sam na 15 sekundi. Koristan je kada proveravate da li web prodavnica ispravno šalje račune. Mrežni uređaji Tab Mrežni uređaji prikazuje POS uređaje sa promenljivom IP adresom koji se javljaju preko API-ja. Uređaj koji se ne javi 30 minuta dobija status Neaktivan.
Shopify integracija
Kada povežete Shopify prodavnicu, HAFiskal sam izdaje fiskalni račun za svaku plaćenu narudžbinu. Za povraćaj novca sam radi storno i izdaje nov račun. Ne morate ništa da prekucavate. Šta vam treba - Modul za API fiskalizaciju u vašem paketu (vidi Moj paket i Moji računi). Shopify nema poseban modul ni cenu. - Podešenu kasu, odnosno sertifikat i PAK (vidi Povezivanje kase sa PFR). - Valutu prodavnice RSD. Narudžbine u drugoj valuti se ne fiskalizuju. - Ulogu vlasnika ili administratora u HAFiskal-u. 1. Povežite prodavnicu 1. U HAFiskal panelu otvorite Integracije (API) i karticu Shopify. 2. Upišite adresu prodavnice, na primer moja-prodavnica.myshopify.com, i kliknite Poveži. 3. Otvara se Shopify. Odobrite aplikaciju HAFiskal. 4. Vraćate se u panel sa porukom da je prodavnica povezana. Na kartici prodavnice proverite oznake: Povezano, Licenca aktivna i Webhookovi registrovani. Ako neka oznaka nije zelena, kliknite Webhookovi i polja kupca. Jedna Shopify prodavnica može biti povezana samo sa jednom firmom. 2. Povežite načine plaćanja (obavezno) Za svaki način plaćanja iz Shopify-a izaberite kako se vodi na računu: Platna kartica, Prenos na račun, IPS (instant plaćanje) ili Gotovina / pouzeće. Sistem predlaže izbor, a predlog prihvatate klikom na (primeni). Na kraju kliknite Sačuvaj podešavanja. Važno: - Spisak načina plaćanja se pojavljuje tek posle prve plaćene narudžbine. Ta narudžbina čeka sa statusom Nemapirano plaćanje dok ne sačuvate izbor, a zatim se fiskalizuje sama. - Narudžbina sa nepovezanim načinom plaćanja se ne fiskalizuje. - Poklon kartica nema predlog, pa je povežite ručno ako je koristite. 3. Ostala podešavanja Na istoj kartici možete da podesite: | Podešavanje | Podrazumevano | |---|---| | Fiskalni račun za pravno lice / za fizičko lice | Da / Da | | Pouzeće fiskalizuj tek kad je isporučeno | Da | | Pošalji fiskalni račun kupcu mejlom | Da | | Upiši firmu, PIB i MB u polja kupca u Shopify adminu | Da | | Preskoči test narudžbine | Da | | PDV stopa za stavke bez Shopify poreza | 20% | | Poslovna lokacija | podrazumevana lokacija firme | Kada se izdaje račun - Kad je narudžbina plaćena u celosti. Delimično plaćena narudžbina čeka. - Za pouzeće se račun izdaje kad označite da je narudžbina isporučena, ako je to podešavanje uključeno. - Na računu su svi proizvodi, a dostava je posebna stavka. Popusti se prikazuju kao popust na stavkama. - Otkazane narudžbine, test narudžbine i narudžbine od 0 dinara se preskaču. - Isti račun se nikad ne izdaje dvaput. Gde se vidi račun - Fiskalizacija → Poslednji računi: tu je svaki izdat račun, kao i računi sa kase. Odatle ga štampate, šaljete mejlom ili pravite kopiju (vidi Pregled izdatih fiskalnih računa). - Integracije (API) → Log fiskalizacije: poslednji pokušaji fiskalizacije iz svih integracija, i uspešni i neuspešni. - U Shopify-u, na narudžbini: dobija oznaku fiskalizovano, a broj računa i link za proveru su upisani u podatke narudžbine. - Kupac dobija račun mejlom, u PDF prilogu, ako je to podešavanje uključeno. Mejl ide sa vaše adrese ako ste podesili slanje mejlova (vidi Slanje mejlova (SMTP) i izgled mejla). Na kartici Shopify, u tabeli Narudžbine, vidite stanje svake narudžbine (npr. Fiskalizovano, Nemapirano plaćanje, Ponovni pokušaj) i poruku ako nešto nije u redu. Povraćaj novca Kad u Shopify-u vratite novac: - ceo iznos: račun se stornira; - deo iznosa: ceo račun se stornira i odmah se izdaje nov račun za ono što kupac zadržava. Više povraćaja na istoj narudžbini obrađuje se redom. Ako je vraćena i dostava, ona ne ide na nov račun. Storno i nov račun se vide u Poslednji računi, a stanje povraćaja u tabeli Refundacije na kartici Shopify. Kupac posle povraćaja za sada ne dobija mejlom storno ni nov račun. Podaci firme kupca (PIB i matični broj) Kupac koji kupuje kao firma može sam da unese naziv firme, PIB i matični broj, i tada račun glasi na firmu. Na korpi (svi Shopify planovi): 1. U Shopify-u otvorite Online Store → Themes → Customize i stranicu korpe. 2. Kliknite Add block → Apps i izaberite blok HAfiscal - podaci. 3. Kupac bira Fizičko lice ili Pravno lice. Za pravno lice unosi Naziv firme, PIB i Matični broj. PIB i matični broj se proveravaju odmah. Dok podaci nisu ispravni, kupac ne može da pređe na plaćanje; to se može isključiti u podešavanjima bloka. Na stranici za plaćanje (samo Shopify Plus): ista polja dodajete u Settings → Checkout → Customize. U editoru dozvolite aplikaciji da zaustavi plaćanje kad podaci nisu ispravni. Brza dugmad za plaćanje (Shop Pay, Apple Pay i slično) preskaču korpu. Za takve narudžbine se koriste podaci firme sačuvani u profilu kupca, ako postoje, a inače se račun izdaje bez podataka kupca. Podatke firme kupca vidite u Shopify adminu, u profilu kupca. Kupci ih ne vide javno. Ako račun nije izdat Razlog vidite u Log fiskalizacije i na kartici Shopify, u tabeli Narudžbine, u koloni Poruka. U Shopify-u narudžbina dobija oznaku fiskalizacija-greska. - Ako fiskalni servis nije dostupan, sistem sam pokušava ponovo, do 10 puta, sa sve dužim pauzama. - Ako je potrebna vaša provera, ispravite razlog i kliknite Fiskalizuj ponovo. - Za povraćaje postoji dugme Ponovi. Ako modul za API fiskalizaciju nije u paketu, narudžbine čekaju i fiskalizuju se same čim se modul aktivira. Šta za sada nije podržano - Prodaja poklon kartica, napojnice, carine i dodatne naknade. Takve narudžbine traže ručnu obradu. - Prikaz računa na stranici statusa narudžbine i u nalogu kupca. - eFaktura za Shopify narudžbine. Prekid veze Na kartici prodavnice kliknite Prekini vezu. Zatim obrišite aplikaciju i u Shopify adminu, u Settings → Apps. Već izdati računi ostaju sačuvani u HAFiskal-u.
WooCommerce konektor: artikli, cene i slike sa sajta na kasi
Čemu služi Ako imate WooCommerce prodavnicu, kasa u HAFiskalu može da čita artikle direktno sa sajta. Ne morate ručno da prepisujete nazive, cene i slike. - Artikal već postoji u HAFiskalu: kada ga dodate na račun, kasa sa sajta uzima trenutni naziv i cenu. Ako promenite cenu na sajtu, kasa odmah kuca novu cenu. - Artikal ne postoji u HAFiskalu: kada na kasi skenirate ili ukucate šifru, kasa ga pronađe na sajtu i sama napravi nov artikal sa nazivom, šifrom, cenom sa PDV-om i slikom, pa ga odmah stavi na račun. Artikli se povezuju preko šifre artikla (SKU). Ista šifra mora postojati na sajtu. Kada koristite HAFiskal dodatak za WordPress, kasa traži i po barkodu (GTIN). Konektor samo čita podatke sa sajta i ništa ne menja u prodavnici. Pre nego što počnete WooCommerce konektor je dodatak. Ako ga nemate u paketu, u HAFiskalu otvorite Integracije → WooCommerce konektor i kliknite Aktiviraj dodatak. Napravi se ponuda koju plaćate u delu Moji računi, a stanje paketa vidite u Moj paket. Povezivanje (preporučeno: HAFiskal dodatak za WordPress) Ovaj način je najjednostavniji i ne traži nikakvo tehničko znanje. 1. U HAFiskalu otvorite Integracije → WooCommerce konektor i preuzmite fajl hafiskal-woo-connector.zip (link je na samom ekranu). 2. U WordPress-u vaše prodavnice otvorite Dodaci → Dodaj novi → Otpremi dodatak, izaberite preuzeti fajl, pa kliknite Instaliraj i Aktiviraj. 3. U WordPress-u otvorite WooCommerce → HAFiskal konektor. Tu su Adresa sajta i Ključ povezivanja. Kliknite na polje da ga označite i kopirajte. 4. Vratite se u HAFiskal (Integracije → WooCommerce konektor), izaberite Pomoću HAFiskal plugina (preporučeno), nalepite adresu sajta i ključ i kliknite Sačuvaj. 5. Kliknite Testiraj vezu. Za probu možete upisati šifru nekog artikla sa sajta. Ako sve radi, piše „Veza radi" i naziv i cena tog artikla. Pazite da je uključena opcija Uključeno. Drugi način: WooCommerce ključevi Koristite ga ako ne želite da instalirate dodatak. 1. U WordPress-u otvorite WooCommerce → Podešavanja → Napredno → REST API. 2. Kliknite Dodaj ključ, upišite naziv (npr. HAFiskal) i u polju Dozvole izaberite Čitanje. 3. Kliknite Generiši API ključ. WooCommerce ključeve prikazuje samo jednom, zato ih odmah kopirajte. 4. U HAFiskalu izaberite Pomoću WooCommerce ključeva, upišite adresu sajta, Korisnički ključ (ck_) i Tajni ključ (cs_), pa kliknite Sačuvaj i Testiraj vezu. Ovim načinom kasa traži artikle samo po šifri (SKU), ne i po barkodu. Rad na kasi - Postojeći artikal: izaberite ga ili skenirajte kao i do sada. Na računu se pojavljuju naziv i cena sa sajta. - Nov artikal: u polje Skenirajte ili unesite barkod upišite šifru i pritisnite Enter. Ako šifre nema u HAFiskalu, a postoji na sajtu, artikal se napravi i odmah ide na račun. Posle toga ga vidite i u spisku artikala, sa slikom. - Nov artikal dobija jedinicu mere kom i podrazumevanu poresku stopu firme. Ako je potrebno, to promenite u Artikli. - Ako šifre nema ni na sajtu, kasa javlja da artikal nije pronađen. Kada sajt ne odgovara Ako sajt ne odgovori za 5 sekundi ili je nedostupan, kasa nastavlja da radi sa nazivom i cenom koje su upisane u HAFiskalu, pa kucanje računa ne staje. Vreme poslednje provere i eventualnu grešku vidite na dnu ekrana Integracije → WooCommerce konektor. Slika artikla Kada se artikal pravi sa sajta, preuzima se njegova glavna slika (JPG, PNG, WebP ili GIF, do 3 MB). Ako slika ne može da se preuzme, artikal se svejedno napravi, samo bez slike. Ako koristite HAFiskal dodatak za WordPress, za preuzimanje slika potrebna je verzija 1.1.0 ili novija. Ako ste dodatak instalirali ranije, preuzmite ga ponovo sa ekrana konektora i instalirajte preko starog. Novi ključ i uklanjanje - Novi ključ: u WordPress-u, na strani WooCommerce → HAFiskal konektor, kliknite Napravi novi ključ. Stari ključ odmah prestaje da radi, pa novi upišite u HAFiskal i kliknite Sačuvaj. Uradite ovo ako sumnjate da je neko video ključ. - Privremeno isključivanje: u HAFiskalu isključite Uključeno i kliknite Sačuvaj. - Uklanjanje: u HAFiskalu kliknite Ukloni. Artikli koji su već napravljeni ostaju u HAFiskalu. Česta pitanja Da li konektor menja nešto na mom sajtu? Ne. Konektor samo čita naziv, cenu i sliku artikla. Da li prodaja na kasi menja stanje zaliha na sajtu? Ne, konektor služi samo za čitanje artikala. Test kaže da artikal nije pronađen, a postoji na sajtu. Proverite da li artikal na sajtu ima upisanu šifru (SKU) i da li je ona ista kao ona koju kucate. Ako koristite WooCommerce ključeve, kasa ne traži po barkodu. Test javlja grešku veze. Proverite da adresa sajta počinje sa https:// i da je ključ prepisan ceo. Sajt mora biti dostupan sa interneta.