10. Integrimi me UJP (e-Faturë)¶
I aktivizuar në mjedisin e provës
Më 1 qershor 2026 kaluan me sukses faturat e para përmes integrimit: /JSONReceiver/sales-invoices/send kthen EUID + QR link për faturat e dërguara nga eFakturaWin. Ende po punohet në llogarinë e provës (efakturatest.ujp.gov.mk); aktivizimi në prodhim do të vijë sapo UJP ta hapë versionin e API-it të validuar në provë për përdorim të gjerë. Synimi mbetet jo më vonë se tetori 2026, kur sipas projektligjit hapet regjistrimi vullnetar.
10.1. Çfarë është e-Fatura?¶
e-Fatura është një sistem elektronik i Drejtorisë së të Ardhurave Publike (UJP) të Maqedonisë së Veriut, përmes të cilit firmat dërgojnë të gjitha faturat e tyre te UJP për regjistrim dhe verifikim. Sistemi:
- ✅ i zëvendëson faturat letër me dokumente JSON të nënshkruara,
- ✅ mundëson shkëmbim automatik midis firmave (lëshuesi dërgon, blerësi merr përmes të njëjtit sistem),
- ✅ automatikisht i përfshin të dhënat në deklaratat e TVSH-së,
- ✅ mundëson verifikim me „QR" — çdo faturë legjitime ka kod QR që çon në faqen e UJP-së për verifikim.
Datat e detyrueshme (sipas Projektligjit për faturimin elektronik — ende i pamiratuar):
| Nga | Kush përfshihet |
|---|---|
| 1 tetor 2026 | Regjistrim vullnetar. Ligji fillon të zbatohet, por askush nuk është ende i detyruar. |
| 1 prill 2027 | Personat juridikë dhe fizikë të regjistruar për TVSH, ndërmarrjet publike, shoqëritë në pronësi shtetërore ose komunale. |
| 1 korrik 2027 | Personat juridikë që nuk janë të regjistruar për TVSH, por ushtrojnë veprimtari ekonomike. |
| 1 tetor 2027 | Shfrytëzuesit buxhetorë, organizatat jofitimprurëse, organet nën kontrollin e shtetit ose të komunave, Banka Popullore. |
| 1 janar 2028 | Të gjithë subjektet e tjera që kryejnë transaksione. |
Regjistrimi vullnetar është i pakthyeshëm
Nga dita kur regjistroheni vullnetarisht, duhet të faturoni ekskluzivisht përmes sistemit — nuk ka kthim te faturat në letër deri në fillimin e fazës suaj. Nga data e fillimit të fazës suaj, një faturë e lëshuar jashtë sistemit konsiderohet e palëshuar.
10.2. Si funksionon e-Fatura (në nivel të lartë)¶
┌────────────────┐ JSON + JWS ┌──────────┐
│ eFakturaWin │ ───────────────▶ │ UJP │
│ (lëshuesi) │ e nënshkruar │ Serveri │
└────────────────┘ └──────────┘
│
│ JSON
▼
┌────────────────┐
│ eFakturaWin │
│ (blerësi) │
└────────────────┘
- Lëshuesi krijon faturën në eFakturaWin.
- eFakturaWin e serializon në format JSON të përcaktuar nga UJP.
- JSON-i nënshkruhet me certifikatë digjitale të kualifikuar (p.sh. token KIBS ose token Telekomi i Maqedonisë).
- Dokumenti i nënshkruar (
JWS) dërgohet te UJP përmes HTTPS. - UJP validon — nëse gjithçka është në rregull, kthen EUID (identifikues unik) dhe QR link.
- Blerësi, nëse punon në sistemin e-Faktura, e merr faturën automatikisht dhe duhet ta pranojë ose refuzojë brenda 8 ditësh.
10.3. Çfarë nevojitet për aktivizim¶
10.3.1. Nga ju (lëshuesi)¶
| Kërkesa | Ku ta merrni |
|---|---|
| Certifikatë për nënshkrim digjital | Çdo lëshues i kualifikuar në MK — KIBS, Telekomi i Maqedonisë (MT), Maqedonia Onlajn etj. — në token ose smart card |
| EUJP-ID | Regjistrohuni në portalin eujp.gov.mk me certifikatën tuaj — merrni një ID personal |
| Delegim i autorizimit | Përmes portalit të UJP-së, delegoni nga firma te personi fizik (Ju me certifikatën tuaj), që të mund të dërgoni në emër të firmës |
10.3.2. Regjistrimi i certifikatës në portalin eUJP¶
Pasi ta keni marrë tokenin, certifikata duhet një herë të regjistrohet në portalin eUJP. Pa këtë regjistrim eFakturaWin mund të nënshkruajë me sukses lokalisht, por UJP do të refuzojë çdo faturë të dërguar me kodin E1012 (ose E5004 për skenare delegimi).
- Lidhni tokenin dhe verifikoni që drejtuesi (SafeNet për KIBS, Gemalto Classic Client për Telekomin e Maqedonisë etj.) e njeh.
- Hapni Chrome ose Edge (jo Firefox — shih udhëzimin më poshtë) dhe shkoni te
https://efakturatest.ujp.gov.mk/certificates. Adresa përkatëse e prodhimit do të publikohet sapo UJP ta hapë mjedisin e prodhimit. - Hyni me kredencialet tuaja eUJP.
- Shtypni Regjistro certifikatën — shfletuesi hap listën e Windows të certifikatave.
- Zgjidhni certifikatën e kualifikuar nga tokeni dhe konfirmoni zgjedhjen. Nëse merrni mesazhin „certifikata ekziston tashmë" (
E1020), regjistrimi është bërë tashmë — nuk ka hapa shtesë.
Pas regjistrimit të suksesshëm, vazhdoni në Shërbim → Certifikatë në eFakturaWin për të vendosur EUJP-ID dhe numrin serial (shih §10.3.3).
Listë boshe certifikatash në „Regjistro certifikatën"
Nëse shfletuesi e hap listën por ajo është boshe, kontrolloni një nga një (sipas prioritetit):
- Vendoseni certifikatën si „Default" në token. Hapni SafeNet Authentication Client → Advanced View (ikona ⚙) → zgjeroni tokenin → Certificates → klik i djathtë mbi certifikatën → Set as Default Certificate, dhe rifreskoni shfletuesin.
- Instaloni zinxhirin e lëshuesit. Për KIBS, klikoni dy herë mbi
rootg2.crtdheKIBSTrustIssuingQsigCAG3.crtnga dosjatekstovi/e instalimit (ose shkarkojini nga kibstrust.mk/en/repository) për t'i shtuar në Trusted Root dhe Intermediate CA përkatësisht. - Mbylleni shfletuesin plotësisht. Chrome/Edge e lexojnë listën e Windows të certifikatave vetëm gjatë nisjes — Task Manager → End task në të gjitha proceset
chrome.exe/msedge.exe, dhe hapni një dritare të re. - Verifikoni EKU-në e certifikatës. Në
certmgr.msc→ Personal → klik i dyfishtë mbi certifikatën → tab Details → Enhanced Key Usage duhet të jetë listuar Client Authentication. Certifikatat KIBS Qsig G3 e kanë atë zgjerim dhe kalojnë; certifikatat vetëm për nënshkrim dokumenti fshihen nga filtri i UJP-së.
Shënime shtesë: Firefox nuk i sheh certifikatat e Windows (ka NSS store të vetin) — përdorni Chrome ose Edge. Pas instalimit të freskët të drejtuesit, ndonjëherë nevojitet edhe rinisja e kompjuterit që ofruesi i store-it të regjistrohet plotësisht.
10.3.3. Nga eFakturaWin (tashmë i përgatitur)¶
Të dhënat për firmën (emri, adresa, EDB) i plotësoni në Shifrarët → Profili i Firmës Sime — një herë për firmë.
Të dhënat për nënshkrim janë të veçanta dhe të përbashkëta për të gjithë instalimin — një token i shërben të gjithë lëshuesve. Vendosen në Shërbim → Certifikatë:

Dritarja ka dy pjesë:
Të dhënat për nënshkrim (fusha e sipërme):
- EUJP-ID — identifikues i marrë gjatë regjistrimit si përdorues në portalin eUJP (
eujp.gov.mk). Deri në 16 karaktere. - Numri serial i certifikatës — numri serial i certifikatës digjitale të kualifikuar që përdoret për nënshkrim (p.sh. KIBS, Telekomi i Maqedonisë, Maqedonia Onlajn). Karaktere heksadecimale.
- Butoni Lexo automatikisht gjen certifikatën e vlefshme të kualifikuar në Windows certificate store (
Cert:\CurrentUser\My) dhe plotëson numrin serial. Filtri nuk varet nga lëshuesi — njeh çdo certifikatë të kualifikuar për nënshkrim sipas bitit Non-Repudiation të vendosur në zgjeriminkeyUsage. Nëse ka disa certifikata të vlefshme, zgjidhet më e reja; nëse nuk ka — shfaqet mesazhi për të lidhur tokenin.
Cilësimet e tokenit (fusha e poshtme — tre butona që kontrollojnë numrin e pyetjeve për PIN):
-
Instalo mbështetjen PKCS#11 — në një instalim të freskët DLL-i është tashmë i bundled me Setup.exe, kështu që ky buton vetëm konfirmon se
Pkcs11Interop.dllqëndron pranë eFakturaWin.exe. Nëse DLL-i fshihet rastësisht, butoni ofron shkarkim rezervë nga NuGet (kërkon internet). Pas aktivizimit, eFakturaWin vetë kërkon PIN një herë për sesion (përmes dritares së vet) dhe drejtuesi i tokenit hesht:
Funksionon në tokena me politikë lejuese (Telekomi i Maqedonisë/Gemalto etj.); në tokena KIBS drejtuesi mund të kërkojë ende PIN pas çdo operacioni për shkak të politikës harduerike — në atë rast përdorni „Aktivizo SafeNet Single Logon" në vend të kësaj. - Çinstalo mbështetjen PKCS#11 — fshin
Pkcs11Interop.dlldhe kthen në rrjedhën standarde (drejtuesi kërkon PIN). E dobishme nëse PKCS#11 në tokenin tuaj ka sjellë më shumë pyetje, jo më pak. - Aktivizo SafeNet Single Logon — shkruan një çelës regjistri që i thotë SafeNet Authentication Client të kesh-ojë PIN-in për kohëzgjatjen e sesionit (vetëm për tokena SafeNet/KIBS). Alternativë e PKCS#11 kur PKCS#11 nuk ndihmon në tokenin KIBS.
Djathtas butonit për Single Logon qëndron një etiketë statusi që tregon nëse PKCS#11 është aktive (1 PIN/sesion) ose joaktive (PIN për operacion). Detajet për strategjitë e reduktimit të pyetjeve për PIN: §10.3.4.
Për shtëpitë e kontabilitetit
Nëse mbani faturim për disa klientë me një token të vetëm dhe një delegim në eUJP, EUJP-ID dhe numrin serial i vendosni vetëm një herë në Shërbim → Certifikatë, pavarësisht se sa lëshues të ndryshëm keni në bazë.
Kjo është gjithçka. Vetë integrimin (ndërtimin e JSON-it, nënshkrimin JWS, thirrjen HTTPS) e bën eFakturaWin.
10.3.4. Reduktimi i pyetjeve për PIN („Single Logon")¶
Me konfigurimin standard, drejtuesi i tokenit (qoftë SafeNet për KIBS, qoftë Gemalto Classic Client për Telekomin e Maqedonisë) kërkon PIN për çdo operacion nënshkrimi. Disa operacione në eFakturaWin bëjnë disa nënshkrime në një thirrje:
| Operacioni | Sa nënshkrime (standardisht) |
|---|---|
| Dërgo në UJP faturë dalëse | 1 |
| Rifresko statusin (klik i djathtë mbi një faturë) | 1 për ditë në dritaren e skanimit — deri në 7 |
| Statusi i të dërguarave (Shërbim → bulk) | Deri në 7 — pavarësisht se sa fatura ka |
| Sinkronizo faturat hyrëse | 1 për EUID që shkarkohet |
Freskimi i statusit për një faturë 5 ditë të vjetër atëherë kërkon 5 pyetje për PIN. Opsioni bulk „Statusi i të dërguarave" bën një thirrje /sales-invoice/changes për ditë për lëshuesin aktiv dhe nga përgjigja i mapon të gjithë EUID-të menjëherë — prandaj ajo variant gjithmonë qëndron në më së shumti 7 pyetje për PIN, pavarësisht se keni 5 apo 500 fatura të dërguara. Ky është rruga e rekomanduar pas një periudhe më të gjatë joaktive. Kjo është ende sjellje e drejtuesit — aplikacioni tashmë bën sa mund për të zvogëluar numrin e thirrjeve.
Zgjidhja: aktivizoni kesh-imin e PIN-it në drejtues. Me këtë cilësim PIN-i mbahet gjatë kohëzgjatjes së sesionit dhe kërkohet vetëm një herë — pavarësisht se sa nënshkrime nevojiten. Hapat varen nga lloji i tokenit tuaj.
SafeNet Authentication Client (për KIBS)¶
- Hapni SafeNet Authentication Client Tools (nga system tray ose menuja Start → SafeNet → SafeNet Authentication Client).
- Klikoni mbi ikonën ⚙ Advanced View në këndin e sipërm djathtas.
- Në panelin e majtë zgjidhni tokenin.
- Shkoni te Client Settings → tab Advanced.
- Në disa versione shtegu është Token Settings → Private Data Caching, ose Tools → Settings → Client Settings → Advanced.
- Gjeni opsionin "Single Logon" (në versionet e vjetra e shënuar si "Password caching mode" ose "Always prompt user for password").
- Vendoseni në „Enable Single Logon" — ose, në versionet e vjetra, çaktivizoni „Always prompt".
- Shtypni Save, hiqeni tokenin dhe vendoseni përsëri.
Gemalto Classic Client (për Telekomin e Maqedonisë etj.)¶
- Hapni Gemalto Classic Client Toolbox (menuja Start → Gemalto → Classic Client Toolbox).
- Në panelin e majtë zgjidhni Card Administration (ose Smart Card në disa versione).
- Hapni Settings / Configuration → tab PIN Caching (ose Session Settings, në varësi të versionit).
- Aktivizoni opsionin „Cache PIN for session" (ose „Single Sign-On", „Remember PIN until card removal").
- Ruani, hiqeni tokenin dhe vendoseni përsëri.
Pas aktivizimit (në cilindo nga dy drejtuesit), PIN kërkohet një herë për sesion të eFakturaWin, jo një herë për nënshkrim. I njëjti efekt vlen edhe për aplikacionet e tjera që përdorin tokenin në të njëjtin sesion Windows.
Çfarë duhet të dini
- Konfigurimi është për makinë — çdo përdorues duhet ta bëjë në PC-në e vet.
- PIN-i i kesh-uar pastrohet kur mbyllet eFakturaWin (ose dilni nga Windows), kur e hiqni tokenin, ose pas një timeout-i të konfigurueshëm — sesioni i ardhshëm përsëri kërkon PIN një herë.
- Disa tokena të menaxhuar nga korporata kanë politikë të rreptë që e çaktivizon këtë opsion. Nëse „Single Logon" / „Cache PIN" është i gri/i padisponueshëm, kontaktoni administratorin e IT për të zbutur profilin.
- Siguria nuk është e komprometuar — tokeni vazhdon të kërkojë prani fizike (USB) + njohjen e PIN-it; vetëm shmanget rifutja e të njëjtit PIN në të njëjtin sesion.
10.4. Statusi aktual¶
Çfarë funksionon (mjedisi i provës, 1 qershor 2026)¶
- ✅ Dërgimi i faturës dalëse — butoni Dërgo në UJP në listën e faturave thërret
/JSONReceiver/sales-invoices/send; UJP ktheneuid+qr_link+timestampqë ruhen në bazë. - ✅ Shkarkimi i PDF-së UJP — nga kontekst-menuja (klik i djathtë) e një fature të dërguar: Shkarko UJP PDF. Thirret
/einvoice_api/documents/sales-invoice/pdf, dekodohetbase64dhe skedari ruhet siFaktura_UJP_<BR_FAK>.pdfdhe hapet automatikisht në lexuesin standard PDF. - ✅ Anulim (storno) i faturës së dërguar — butoni Anulo (Storno) (ose klik i djathtë → Anulo (Storno)) kërkon arsye nga shifrari
cb_void_reason(S-1 deri S-5), krijon një regjistër storno me shuma negative dhedocReferencesdrejt origjinalit, dhe e dërgon në UJP. Kolona „Statusi" në listë i shënon faturat e prekura me „E anuluar" (origjinali) dhe „STORNO" (regjistri storno). Detajet për rrjedhën e përdoruesit: §5.7. - ✅ Ndërtimi i JSON-it — plotësisht i përputhur me shembujt zyrtarë të UJP-së (
primer_za_json_2.pdf). - ✅ Nënshkrimi JWS me token të kualifikuar (KIBS, Telekomi i Maqedonisë, etj.) — përmes Windows CryptoAPI (CNG); drejtuesi i tokenit e shfaq dialogun e PIN-it.
- ✅ Klienti HTTP për API-in e UJP-së —
curl.exeme skedar konfigurimi për shmangien e problemeve me quoting. - ✅ Parsimi i përgjigjeve të UJP-së (EUID, statusi, gabimet, QR linku).
- ✅ Shifrarët (normat e TVSH-së, monedhat, llojet e pagesave, arsyet e refuzimit/anulimit) — të sinkronizuara me mjedisin e provës të UJP-së. Lista e plotë e të gjitha shifrave: Shtojca A; për mekanizmin e përditësimit shih §A.0.
- ✅ Gating i subjektit të TVSH-së në
sellerVatNumberdhebuyerVatNumber— për jo-subjektet e TVSH-së në JSON dërgohetnullnë vend të"MK"+EDB. Pa këtë UJP e refuzon faturën meE10003. Shih §3.2 dhe §4.1.4 për vendosjen. - ✅ Verifikim automatik i blerësit para dërgimit. Kur të klikoni Dërgo në UJP, aplikacioni fillimisht pyet regjistrin e UJP-së për blerësin (
/companies/{edb}) dhe i krahason emrin, rrugën, numrin e shtëpisë, kodin postar, vendin dhe statusin e TVSH-së me rreshtin lokal nëShifrarët → Partnerët. Nëse diçka ndryshon, shfaqet një dialog me kolonat „Lokale" dhe „UJP" për çdo fushë që ndryshon dhe një pyetje nëse partneri lokal duhet të përditësohet me versionin nga UJP. Kjo parandalonE10001/E10002/E1012(mospërputhje case-sensitive) para se të shpenzohet pyetja për PIN për JWS. Verifikimi anashkalohet për partnerët e huaj dhe për partnerët, EDB-ja e të cilëve nuk ka 13 shifra.
Çfarë mbetet¶
-
✅ Freskimi i statusit nga UJP për faturën e dërguar. Dy rrugë drejt të njëjtit operacion:
- Një faturë: në Lista e Faturave zgjidhni një rresht me EUID → klik i djathtë → Rifresko statusin nga UJP. Dialogu tregon një emër të lexueshëm për kodet e njohura (
00 Draft,01 E dërguar (E re),03 E pranuar,05 E refuzuar,07 E anuluar); të tjerët shfaqen si „Statusi kod N" derisa të konfirmohet mapimi nga UJP. -
Të gjitha të dërguarat: Shërbim → Statusi i të dërguarave. Opsioni fillimisht tregon një dialog konfirmimi (sepse aktivizon deri në 7 pyetje për PIN):

Për lëshuesin aktiv pastaj skanon
/sales-invoice/changespër ditë për 7 ditët e fundit dhe nga përgjigja përditësonfakturu.buyer_status/fakturu.buyer_status_atpër çdo EUID që ka marrë një ngjarje të re. Kolona „Statusi" në listë rifreskohet automatikisht. Përmbledhja në fund tregon „U përditësuan N statuse nga M fatura të dërguara":
- Implementimi kalon përmes /sales-invoice/changesnë vend të/sales-invoice/status(endpoint-i i dytë kthenE5000në mjedisin e provës nga 2026-06-05; kjo është një rrugë e tërthortë e konfirmuar të funksionojë).
- Një faturë: në Lista e Faturave zgjidhni një rresht me EUID → klik i djathtë → Rifresko statusin nga UJP. Dialogu tregon një emër të lexueshëm për kodet e njohura (
-
✅ Arsyeja e refuzimit nga blerësi. Kur blerësi e refuzon faturën e dërguar,
/sales-invoice/changese bart arsyen dhe komentin e mundshëm në të njëjtën ngjarje që bart statusin05. Aplikacioni i nxjerr dhe i ruan nëfakturu.buyer_reject_reason_code,buyer_reject_reason_text,buyer_reject_comment. Në formën „Hyrje e faturës", nën rreshtin e fundit të panelit UJP, shfaqen dy rreshta shtesë:- Arsyeja e refuzimit: — paraqitje e kombinuar në format „O-3 — Shumë e gabuar" (kodi + teksti siç i kthen UJP, ose vetëm njëri nga ata nëse tjetri është bosh).
- Komenti: — teksti i lirë që blerësi eventualisht ka shkruar.
Për faturat që nuk janë të refuzuara, këto dy rreshta mbeten bosh (vetëm etiketat janë të dukshme). Kodet e refuzimit vijnë nga shifrari
cb_reject_reason(O-1…O-7) — shih Shtojcën A.8. - 🚧 Faturat hyrëse — Prano / Refuzo. Kodi është shkruar (/purchase-invoice/accept-rejectme të njëjtën formë envelope JWS), por ende e paverifikuar kundrejt një fature provë të gjallë. Pritet të funksionojë sapo të vijë fatura e parë e pranueshme hyrëse për testim. - 🚧 Shfaqja e QR-kodit në PDF-në e printuar — ruhetqr_linknga UJP, por ende nuk është vizatuar në nxjerrjen lokale PDF. - 🚧 Problem delegimi për përdorues specifikë — kur certifikata është e lidhur me një firmë, dhe ju dërgoni në emër të një tjetre, kërkohet procedurë zyrtare delegimi me dy hapa në eUJP. Nuk ndikon në të gjithë përdoruesit. - 🚧 Prodhimi — kur UJP ta hapë mjedisin e prodhimit për përdorim të gjerë.
10.5. Çfarë të bëni tani¶
Para fillimit të fazës suaj (më së shpejti 1 prill 2027 për subjektet e TVSH-së), mundësisht ende gjatë periudhës vullnetare:
- Regjistrohuni në eujp.gov.mk. Nëse ende nuk keni një certifikatë të kualifikuar, siguroni atë tani — procesi zgjat 1-2 javë.
- Vendosni certifikatën. Nga Shërbim → Certifikatë shtypni Lexo për të plotësuar automatikisht numrin serial; vendosni edhe EUJP-ID. Këto të dhëna do të presin derisa integrimi me UJP të bëhet aktiv.
- Testoni rrjedhën lokale. Krijoni fatura, verifikoni se PDF-ja duket mirë, eksportoni CSV — e gjithë kjo funksionon pavarësisht nga UJP.
- Ndiqni blogun. Aktivizimi i UJP-së do të publikohet në efakturawin.mk.
10.6. Pyetjet e bëra shpesh¶
P: A duhet të përdor eFakturaWin për e-Faturë?
P: Jo. UJP ka portalin e vet web (eujp.gov.mk) ku mund të futni manualisht çdo faturë. eFakturaWin e automatizon këtë procedurë.
P: A janë faturat e mia aktuale (të lëshuara lokalisht, jo në UJP) të vlefshme? P: Po, deri në fillimin e fazës suaj nga tabela në §10.1 — për subjektet e TVSH-së kjo është 1 prilli 2027. Nga ajo ditë, çdo faturë e re duhet të kalojë përmes UJP-së. Nëse regjistroheni vullnetarisht më herët, detyrimi vlen menjëherë nga dita e regjistrimit.
P: Çfarë ndodh me faturat e lëshuara para aktivizimit të UJP-së? P: Ato janë „historike" dhe nuk duhen ndryshuar. UJP nuk kërkon regjistrim retroaktiv.
P: A mund të vazhdoj të lëshoj fatura në eFakturaWin pa i dërguar në UJP? P: Po, deri në fillimin e fazës suaj — 1 prilli 2027 për subjektet e TVSH-së. Pas asaj, dërgimi në UJP është i detyrueshëm.
← Kthehu te përmbajtja | Më parë: Faturat hyrëse ← | Më pas: Siguria dhe kopjet rezervë →