easyInvoice - Udhëzues integrimi

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

1. Integrimi me Local API: Kërkesa HTTP me payload JSON
2. 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ë

2.2 Headers

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

2.3 Endpoint-et e API

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

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

4.5 Metodat e pagesës

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

6. Referenca e fushave

6.1 Detajet bankare

6.2 Periudha e furnizimit

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

6.3 Kodet e gabimeve

© ESDP - easyInvoice Udhëzues integrimi v2.3.0