easyPos - Udhëzues integrimi

1. Hyrje

easyPos është softuer fiskalizimi për fatura normale dhe të thjeshta në Shqipëri. Ky udhëzues demonstron si të integroheni me easyPos 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 ose TXT në dosjen e monitoruar

1.2 Parakushtet

• Sistemi operativ Windows ose MacOS (i nevojshëm për instalimin e easyPos)
• Instalim dhe konfigurim i vlefshëm i easyPos
• Stringa e autorizimit të API e konfiguruar (për integrimin me API)
• Local API i aktivizuar në cilësimet e easyPos (për integrimin me API)
• Lidhje rrjeti me serverin easyPos (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": "C352A1442630779BD016323CB4765331",
    "nivf": "19d7cf18-9f2f-4501-b0d1-48830dfc0750",
    "link": "https://efiskalizimi-app.tatime.gov.al/...",
    "text": "Sukses"
  }
}

• status: 0 = Sukses, 1 = Gabim, 2 = Në pritje
• nslf: NSLF - Numri i Brendshëm i Faturës (IIC)
• nivf: NIVF - Numri Fiskal i Faturës (FIC)
• link: URL-ja e verifikimit të faturës

3. Integrimi me skedarë

3.1 Formati JSON

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

Faturë bazë

{
  "app": "",
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 500,
      "units": 2
    }
  ]
}

Faturë me blerës

{
  "app": "",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "L12345678A",
    "buyerName": "Test Company",
    "buyerAddress": "Test Street 123",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Service",
      "soldIn": "cope",
      "price": 1000,
      "units": 1
    }
  ]
}

3.2 Formatet TXT

easyPos suporton dy formate skedarësh TXT për integrimin e pajisjeve fiskale të vjetra:

3.2.1 Formati AED

CLEAR
KEY REG
SALE DPT=1,QTY=1,PRICE=500,DES='Product'
SALE DPT=1,QTY=2,PRICE=300,DES='Service'
SUBTOT
CLOSE TENDER=1

3.2.2 Formati IVA

Formati IVA përdor një sintaksë të strukturuar me rreshta me parashtesa specifike:

Faturë bazë:

H,1,______,_,__;
S,1,______,_,__;"Artikull";500.00;2.00;1;1;1;
T,1,______,_,__;
F,1,______,_,__;

Faturë me blerës (NUIS):

H,1,______,_,__;
B,1,______,_,__;"NUIS";"L00000000B";"Buyer Name";"Address";"Tirane";"ALB";
S,1,______,_,__;"Artikull";500.00;2.00;1;1;1;
T,1,______,_,__;
F,1,______,_,__;

Pagesë me kartë:

H,1,______,_,__;
$ISWITHCARD=1
S,1,______,_,__;"Artikull";500.00;2.00;1;1;1;
T,1,______,_,__;
F,1,______,_,__;

Me zbritje:

H,1,______,_,__;
S,1,______,_,__;"Product";150.00;2.00;1;1;2;
C,1,______,_,__;2;15.0;
T,1,______,_,__;
F,1,______,_,__;

4. Metodat e pagesës

Shembull me Pagesë OTHER

{
  "app": "",
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 500,
      "units": 2
    }
  ],
  "payment": {
    "type": "OTHER"
  }
}

5. Referenca e fushave

5.1 Kodet e TVSH

5.2 Llojet e ID

5.4 Llojet e faturave

6. Shembuj

6.1 Faturë me pagesa të shumëfishta

{
  "app": "",
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 1000,
      "units": 1
    }
  ],
  "payment": [
    { "type": "CASH", "amount": 600 },
    { "type": "CARD", "amount": 400 }
  ]
}

6.2 Faturë me monedhë të huaj

{
  "app": "",
  "currency": {
    "code": "EUR",
    "exRate": 100.5
  },
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Product",
      "soldIn": "cope",
      "price": 50,
      "units": 2
    }
  ],
  "payment": { "type": "CASH" }
}

6.3 Anulim fature

{
  "app": "",
  "invoiceType": "CANCEL",
  "iicRef": "3CA552F6475201847CF63E3499E74727"
}

6.4 Faturë me transfertë bankare

{
  "app": "",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "L12345678A",
    "buyerName": "Company",
    "buyerTown": "Tirana",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "ART001",
      "vatCode": "B",
      "name": "Service",
      "soldIn": "cope",
      "price": 5000,
      "units": 1
    }
  ],
  "payment": {
    "type": "ACCOUNT",
    "bankDetails": {
      "country": "Albania",
      "countryCode": "AL",
      "currency": "ALL",
      "idNumber": "AL123456789012345678"
    }
  }
}

6.5 Faturë me zbritje artikulli

{
  "app": "",
  "articles": [
    {
      "articleId": "PROD001",
      "vatCode": "B",
      "name": "Product with % Discount",
      "soldIn": "cope",
      "price": 1000,
      "units": 5,
      "rebate": {
        "inPercentage": 10
      }
    }
  ],
  "payment": { "type": "CASH" }
}

© ESDP - easyPos Udhëzues integrimi v2.3.0