easyInvoice - Udhëzues integrimi

Integrimi me API Lokal & skedarë

Fatura elektronike

Versioni 2.3.1 | Përditësuar: 04/2026

Përmbledhje

Ky dokument ofron udhëzime të plota për integrimin me sistemin easyInvoice. Suportohen dy metoda kryesore:

Integrimi me Local API: duke përdorur endpoint-et HTTP me payload JSON
Integrimi me skedarë: duke përdorur skedarë JSON në dosjen e monitoruar

1. Hyrje

easyInvoice është një sistem faturash elektronike i projektuar për transaksionet B2B dhe përputhshmërinë fiskale në Shqipëri. Ky udhëzues demonstron si të integroheni me easyInvoice duke përdorur integrimin me skedarë ose thirrjet RESTful API.

1.1 Metodat e integrimit

Integrimi me Local API: Kërkesa HTTP me payload JSON
Integrimi me Skedarë: Vendosni skedarë JSON në dosjen e monitoruar

1.2 Parakushtet

Sistemi operativ Windows ose MacOS (i nevojshëm për instalimin e easyInvoice)
Instalim dhe konfigurim i vlefshëm i easyInvoice
Stringa e autorizimit të API e konfiguruar (për integrimin me API)
Local API i aktivizuar në cilësimet e easyInvoice (për integrimin me API)
Lidhje rrjeti me serverin easyInvoice (për integrimin me API)
Monitoruesi i skedarëve i konfiguruar (për integrimin me skedarë)

2. Integrimi me Local API

2.1 URL bazë

http://[server-ip]:port/v1/...

2.2 Headers

Content-Type: application/json
Authorization: [your-authorization-string]

2.3 Endpoint-et e API

Method	Endpoint	Përshkrimi
`GET`	`/v1`	Testo lidhjen
`POST`	`/v1/invoices/new`	Krijo faturë(a)
`GET`	`/v1/invoices`	Merr të gjitha faturat
`GET`	`/v1/invoices/:id`	Merr një faturë
`GET`	`/v1/operators`	Merr operatorët
`GET`	`/v1/entities`	Merr entitetet

Dokumentacioni Postman

2.4 Formati i përgjigjes

{
  "status": 0,
  "response": {
    "nslf": "9F01C3580F765D733529ED8C2822CA81",
    "nivf": "9775c78c-1363-4469-9b26-e9a19204a0a4",
    "eic": "aae0770c-0e44-4a0a-b8d1-004c2a6eacf4",
    "link": "https://efiskalizimi-app.tatime.gov.al/invoice-check/...",
    "text": "Sukses"
  },
  "docId": "0384a667-ea97-4e53-9e8e-5a234162ca42"
}

status: 0 = Success, 1 = Error
nslf: IIC (Internal Invoice Counter)
nivf: FIC (Fiscal Invoice Counter)
eic: EIC (Electronic Invoice Counter)
link: Invoice verification URL

3. Integrimi me skedarë

Vendosni skedarët JSON në dosjen e monitoruar. easyInvoice do t'i përpunojë automatikisht.

Faturë bazë me blerës

{
  "operatorCode": "gh537ez280",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "K00000000A",
    "buyerName": "GENERAL DIRECTORATE OF TAXES",
    "buyerAddress": "Rruga Gjin Bue Shpata",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "1412134",
      "vatCode": "B",
      "name": "Water",
      "soldIn": "cope",
      "price": 150,
      "units": 195
    }
  ],
  "bankDetails": {
    "country": "Albania",
    "countryCode": "AL",
    "currency": "ALL",
    "idNumber": "AL70202310040000000011237412"
  }
}

4. Formati i faturës

Shënim i rëndësishëm

operatorCode - Required for all invoices
buyer - Required with valid NUIS
bankDetails - Required for ACCOUNT payment
docId - Recommended (UUIDv4)

4.1 Fatura standarde me blerës

{
  "app": "your-app-name",
  "operatorCode": "gh537ez280",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "K00000000A",
    "buyerName": "GENERAL DIRECTORATE OF TAXES",
    "buyerAddress": "Rruga Gjin Bue Shpata",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "1412134",
      "vatCode": "B",
      "name": "Water",
      "soldIn": "cope",
      "price": 150,
      "units": 195
    },
    {
      "articleId": "2412412",
      "vatCode": "B",
      "name": "Cola",
      "soldIn": "cope",
      "price": 200,
      "units": 120
    }
  ],
  "bankDetails": {
    "country": "Albania",
    "countryCode": "AL",
    "currency": "ALL",
    "idNumber": "AL70202310040000000011237412"
  },
  "paymentDeadline": "2025-01-28",
  "supplyPeriod": {
    "start": "2025-01-01",
    "end": "2025-01-28"
  },
  "invoiceNotes": "Test note"
}

4.2 Faturë me pagesa të shumëfishta

"payment": [
  {
    "type": "FACTORING",
    "amount": 23500
  },
  {
    "type": "ACCOUNT",
    "bankDetails": [{
      "country": "Albania",
      "countryCode": "AL",
      "currency": "ALL",
      "idNumber": "AL70202310040000000011237412"
    }],
    "amount": 35600
  }
]

4.3 Anulim fature

{
  "invoices": [{
    "docId": "ab4f61ac-d812-4939-80f3-e964fd1a041a",
    "operatorCode": "gh537ez280",
    "invoiceType": "CANCEL",
    "iicRef": "3A0029767862ACE2DDCB70C2E4363C09"
  }]
}

4.4 Fushat specifike për easyInvoice

Fusha	Lloji	Përshkrimi
bankDetails	objekt	Detajet bankare të shitësit
paymentDeadline	string	Afati i pagesës (YYYY-MM-DD)
supplyPeriod	objekt	Periudha e furnizimit (start, end)
invoiceNotes	string	Shënime të faturës

4.5 Metodat e pagesës

Lloji	Kategoria	Përshkrimi
`ACCOUNT`	NONCASH	Transfertë bankare
`FACTORING`	NONCASH	Faktoring
`COMPENSATION`	NONCASH	Kompensim
`KIND`	NONCASH	Pagesë në natyrë (klering)
`OTHER`	NONCASH	Të tjera, pa para në dorë

5. Fletë përcjellëse (WTN)

5.1 Struktura e WTN

{
  "app": "your-app-name",
  "invoiceType": "WTN",
  "articles": [
    {
      "articleId": "12344412",
      "name": "Water",
      "soldIn": "cope",
      "cost": 50.4121,
      "units": 10.192
    },
    {
      "articleId": "2341234",
      "name": "Bread",
      "soldIn": "cope",
      "cost": 150.245,
      "units": 3.142
    }
  ],
  "wtnOptions": {
    "transaction": "TRANSFER",
    "vehicleOwnership": "OWNER",
    "vehiclePlate": "AA293BB",
    "startPoint": "STORE",
    "startAddress": "Lunder",
    "startCity": "Tirana",
    "startDate": "2025-01-12",
    "startTime": "22:55",
    "destinationPoint": "STORE",
    "destinationCity": "Durres",
    "destinationAddress": "Test Street",
    "destinationDate": "2025-01-14",
    "destinationTime": "21:32",
    "areGoodsFlammable": true,
    "isEscortRequired": false,
    "packagingType": "Box",
    "packagesNumber": "24",
    "itemsNumber": "12"
  }
}

5.2 Opsionet e WTN

Fusha	Vlerat e mundshme	Përshkrimi
transaction	TRANSFER, SALE, EXAMINATION, DISPOSAL, RETURN	Lloji i transaksionit
vehicleOwnership	OWNER, THIRD_PARTY	Pronësia e automjetit
startPoint	STORE, WAREHOUSE, OTHER	Pika e nisjes
destinationPoint	STORE, WAREHOUSE, OTHER	Pika e mbërritjes

6. Referenca e fushave

6.1 Detajet bankare

Fusha	Përshkrimi	Shembull
country	Emri i vendit	Albania
countryCode	Kodi ISO 2-shkronjësh	AL
currency	Kodi i monedhës	ALL, EUR
idNumber	IBAN	AL70202310040000000011237412

6.2 Periudha e furnizimit

"supplyPeriod": {
  "start": "2025-01-01",
  "end": "2025-01-28"
}

6.3 Kodet e gabimeve

Kodi	Lloji	Mesazhi
E1000	NOT_FOUND_ERROR	Resursi nuk u gjet
E1001	ALREADY_EXISTS_ERROR	Resursi ekziston
E1002	FIELDS_VALIDATION_ERROR	Problem në validimin e fushave
E1300	INVOICE_ERROR	Nuk u krijua fatura
E9800	CIS_ERROR	Gabim nga CIS

7. Praktikat më të mira

7.1 Udhëzime të përgjithshme

Validoni të dhënat: gjithmonë validoni strukturën JSON para dërgimit
Trajtoni gabimet: implementoni trajtim të duhur gabimesh për transaksionet e dështuara
Ruani IIC: ruani IIC-në e kthyer (nslf) për referencë të ardhshme dhe anulime
Besueshmëria e rrjetit: për integrimin me API, implementoni logjikë riprovimi
Llogari demo: kërkoni një llogari demo nga stafi i mbështetjes për të testuar integrimin
ID e dokumentit: përdorni formatin UUIDv4 për fushat e personalizuara docId për të siguruar unikalitetin

7.2 Praktikat më të mira për integrimin me skedarë

Përdorni emra skedarësh unikë për të shmangur konfliktet
Monitoroni skedarët e përgjigjes për rezultatet e përpunimit
Implementoni mekanizma kyçjeje skedarësh për të parandaluar lexime të pjesshme
Pastroni skedarët e përpunuar rregullisht
Gjithmonë përfshini fushën app për të identifikuar aplikacionin tuaj

7.3 Praktikat më të mira për integrimin me Local API

Përdorni pooling lidhjesh për performancë më të mirë
Implementoni backoff eksponencial për riprovimet
Regjistroni të gjitha kërkesat dhe përgjigjet për korrigjim
Konfiguroni timeout-e të duhura rrjeti
Sigurohuni për lidhje rrjeti me Local API të easyPos

8. Zgjidhja e problemeve

8.1 Skedari nuk përpunohet

Kontrolloni lejet e skedarit
Verifikoni vlefshmërinë e sintaksës JSON
Sigurohuni që skedari është shkruar plotësisht para se easyPos ta lexojë
Kontrolloni statusin e shërbimit easyPos
Verifikoni që fusha app është e pranishme

8.2 Gabime lidhje API

Verifikoni lidhjen e rrjetit me serverin easyPos
Kontrolloni cilësimet e firewall-it
Konfirmoni URL-në dhe portin e saktë të endpoint-it
Validoni konfigurimin e stringës së autorizimit
Sigurohuni që Local API është aktivizuar në cilësimet e easyPos

8.3 Gabime të dhënash të pavlefshme

Validoni që të gjitha fushat e detyrueshme janë të pranishme
Kontrolloni që llojet e të dhënave përputhen me specifikimet
Verifikoni që kodet e TVSH janë të vlefshme
Sigurohuni që shumat janë formatuar si duhet

9. Lista e kontrollit

9.1 Setup

☐ Softueri i instaluar dhe konfiguruar
☐ Llogari demo e disponueshme
☐ Stringa e autorizimit e konfiguruar
☐ Metoda e integrimit e zgjedhur (skedar ose API)

9.2 Zhvillimi

☐ Struktura JSON e implementuar
☐ Trajtimi i gabimeve i implementuar
☐ Përpunimi i përgjigjes i implementuar

9.3 Testimi

☐ Fatura bazë e testuar
☐ Fatura me blerës e testuar
☐ Anulimi i testuar
☐ Skenarët e gabimeve të testuar

Shënim i rëndësishëm

Për të testuar integrimin, kërkoni një llogari demo nga stafi i mbështetjes.