01 · Kërkesa e parë

Nga token-i te fatura fiskale

Përdorni fillimisht mjedisin e zhvillimit. Biznesi dhe pajisja fiskale merren nga token-i, ndaj trupi i kërkesës përmban vetëm të dhënat e dokumentit.

01
Merrni kredencialet
Kërkoni token të regjistruar për mjedisin, biznesin dhe pajisjen që do të përdorni.
02
Krijoni docId
Gjeneroni dhe ruani një identifikues të qëndrueshëm para kërkesës së parë.
03
Regjistroni dhe verifikoni
Dërgoni faturën dhe kontrolloni kodet e përfundimit, jo vetëm HTTP 200.

Faturë e zakonshme minimale

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123",
  "articles": [
    {
      "articleId": "ART-1",
      "name": "Kafe",
      "vatCode": "B",
      "price": 120,
      "units": 2,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 240
    }
  ]
}'

Përgjigje e përfunduar

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 240
}

02 · Aksesi

Autentikimi dhe kokat HTTP

Çdo endpoint kërkon token Bearer. Zëvendësoni vlerën shembull të integration-app me identifikuesin e qëndrueshëm që i është caktuar integrimit tuaj dhe përdoreni të pandryshuar në çdo kërkesë.

Koka HTTP	Kërkesa	Qëllimi
`Authorization`	I detyrueshëm	Token Bearer për mjedisin e zgjedhur.
`Content-Type`	I detyrueshëm	Përdorni application/json për çdo kërkesë.
`integration-app`	I rekomanduar	Zëvendësoni your-client-name ose erp-x me identifikuesin e caktuar integrimit tuaj.

03 · Protokolli i rikuperimit

docId parandalon dublikimin

Zgjidheni docId në sistemin tuaj para dërgimit. Ripërdorimi vazhdon të njëjtin operacion fiskal dhe kthen të njëjtin rezultat; nuk duhet të krijojë faturë të dytë.

Gjenerojeni një herë: 5–200 karaktere, unik për çdo dokument biznesi.
Ruajeni para POST: Ruani atomikisht docId, trupin e pandryshueshëm të kërkesës dhe ID-në lokale.
Ripërdoreni në rikuperim: Timeout, humbje lidhjeje, 502/503 dhe e-faturë e papërfunduar mbajnë të njëjtin docId.
Vetëm një kërkesë: Mos ekzekutoni register dhe status paralelisht për të njëjtin docId.

Rrjedha e sigurt e rikuperimit

same docId · same body

01
POST register
02
E paqartë / papërfunduar
03
Pritje + jitter
04
POST status
05
Përfundoi?
06
Ridërgo të njëjtën kërkesë

1Kontrolloni përfundimin: fatura normale kërkon fic; fatura elektronike kërkon fic dhe eic.
2Për timeout, gabim rrjeti, 502/503 ose rezultat të papërfunduar, përdorni pritje eksponenciale me jitter, maksimumi 30 sekonda.
3Thirrni /invoice/status me të njëjtin docId. Nëse dokumenti nuk ekziston, ridërgoni /invoice/register me të njëjtin trup kërkese dhe të njëjtin docId.
4Mos riprovoni gabimet e validimit ose cisError.faultEnv=env:CLIENT pa korrigjuar kërkesën.

Anulimi është dokument i ri fiskal: krijoni docId të ri për anulimin. Çdo riprovim i anulimit përdor docId e anulimit.

Skema e vendimmarrjes së klientit

const docId = await persistOperation(payload)

const result = await register({ ...payload, docId })
if (result.fic && (!payload.isEinvoice || result.eic)) return complete(result)

await backoffWithJitter()
const recovered = await status({ docId })

if (recovered.notFound) {
  return register({ ...payload, docId }) // exact same body
}

return evaluate(recovered)

04 · Modeli i dokumentit

Shembujt e kërkesave për faturë

Hapni llojin e dokumentit për të parë kërkesën, përgjigjen dhe identifikuesit që klienti duhet të kontrollojë.

POST NORMALArtikuj, pagesa të kombinuara dhe blerës opsional. documentType mund të mungojë. fic

/invoice/registerPërfundimi: fic #invoice-type-normal

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123",
  "articles": [
    {
      "articleId": "ART-COFFEE",
      "name": "Kafe ekspres",
      "vatCode": "B",
      "price": 120,
      "units": 2,
      "soldIn": "XPP"
    },
    {
      "articleId": "ART-WATER",
      "name": "Ujë natyral",
      "vatCode": "B",
      "price": 100,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 200
    },
    {
      "type": "CARD",
      "amount": 140
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 340
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ORDERVetëm artikuj; payment nuk dërgohet dhe krijohet si ORDER. fic

/invoice/registerPërfundimi: fic #invoice-type-order

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "ORDER-2026-000124",
  "documentType": "ORDER",
  "articles": [
    {
      "articleId": "ORD-1",
      "name": "Drekë biznesi",
      "vatCode": "B",
      "price": 1200,
      "units": 1,
      "soldIn": "XPP"
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "ORDER-2026-000124",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "13/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 1200
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`documentType`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SUMMARYPërdor iic-të ORDER të papërdorura; articles nuk dërgohet. fic

/invoice/registerPërfundimi: fic #invoice-type-summary

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SUMMARY-2026-000125",
  "documentType": "SUMMARY",
  "summaryInvoices": [
    "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
    "A11EBF3F7B7C502D6AAF2321A7CE2CE9"
  ],
  "total": 1800,
  "payment": [
    {
      "type": "CASH",
      "amount": 1800
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "SUMMARY-2026-000125",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "14/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 1800
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`documentType`	`string`
`summaryInvoices`	`string[]`
`total`	`number`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST SELFISSUEKërkon selfIssueType dhe të dhënat e furnitorit te buyer. fic

/invoice/registerPërfundimi: fic #invoice-type-selfissue

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SELFISSUE-2026-000126",
  "documentType": "SELFISSUE",
  "selfIssueType": "DOMESTIC",
  "reverseCharge": true,
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{supplierNipt}}",
    "buyerName": "Furnitor SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "SVC-1",
      "name": "Shërbim profesional",
      "vatCode": "B",
      "price": 10000,
      "units": 1,
      "soldIn": "HUR"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 10000
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "SELFISSUE-2026-000126",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "15/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 10000
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`documentType`	`string`
`selfIssueType`	`string`
`reverseCharge`	`boolean`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST EXPORTKërkon blerës të huaj dhe kodin e TVSH-së së eksportit të biznesit. fic

/invoice/registerPërfundimi: fic #invoice-type-export

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EXPORT-2026-000127",
  "documentType": "EXPORT",
  "supplyPeriod": {
    "start": "2026-08-01",
    "end": "2026-08-28"
  },
  "buyer": {
    "buyerIDType": "VAT",
    "buyerIDNum": "IT12345678901",
    "buyerName": "Acquirente Demo SRL",
    "buyerAddress": "Via Roma 1",
    "buyerTown": "Bari",
    "buyerCountry": "ITA",
    "buyerCountryCode": "IT"
  },
  "articles": [
    {
      "articleId": "EXP-1",
      "name": "Mall për eksport",
      "vatCode": "J",
      "price": 25000,
      "units": 4,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": 100000
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "EXPORT-2026-000127",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "16/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 100000
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`documentType`	`string`
`supplyPeriod`	`object`
`supplyPeriod.start`	`string`
`supplyPeriod.end`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`buyer.buyerCountryCode`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ELEKTRONIKE · P1Faturë elektronike standarde me blerës NUIS dhe pagesë pa para në dorë. fic + eic

/invoice/registerPërfundimi: fic + eic #invoice-type-electronic-p1

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P1-2026-000128",
  "isEinvoice": true,
  "selectedProcess": "P1",
  "payDeadline": "2026-09-30",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB",
    "buyerCountryCode": "AL"
  },
  "articles": [
    {
      "articleId": "SVC-CLOUD",
      "name": "Shërbim cloud",
      "vatCode": "B",
      "price": 10000,
      "units": 1,
      "soldIn": "HUR"
    }
  ],
  "payment": [
    {
      "type": "ACCOUNT",
      "amount": 10000,
      "details": [
        {
          "idNumber": "{{sellerIban}}",
          "name": "Shitësi SHPK",
          "bankName": "Banka",
          "swift_code": "ABCDEFGH",
          "country": "Shqipëri",
          "countryCode": "AL",
          "currency": "ALL"
        }
      ]
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "EINVOICE-P1-2026-000128",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "17/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": 10000,
  "eic": "2a8d91cf-8fea-4d86-b79d-4bcb0b153e78"
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`payDeadline`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`buyer.buyerCountryCode`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`
`payment[].details`	`object[]`
`payment[].details[].idNumber`	`string`
`payment[].details[].name`	`string`
`payment[].details[].bankName`	`string`
`payment[].details[].swift_code`	`string`
`payment[].details[].country`	`string`
`payment[].details[].countryCode`	`string`
`payment[].details[].currency`	`string`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELEKTRONIKE · P4Faturë parapagimi; prepaidAmount duhet të jetë brenda totalit. fic + eic

/invoice/registerPërfundimi: fic + eic #invoice-type-electronic-p4

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P4-2026-000129",
  "isEinvoice": true,
  "selectedProcess": "P4",
  "prepaidAmount": 5000,
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "ADV-1",
      "name": "Parapagim shërbimi",
      "vatCode": "B",
      "price": 10000,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": 10000
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "EINVOICE-P4-2026-000129",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "18/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": 10000,
  "eic": "0543e84b-6108-48b2-a2af-5db66bb80616"
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`prepaidAmount`	`number`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELEKTRONIKE · P9/P10Notë krediti ose korrigjim që referon iic elektronike. fic + eic

/invoice/registerPërfundimi: fic + eic #invoice-type-electronic-p9-p10

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P9-2026-000130",
  "isEinvoice": true,
  "selectedProcess": "P9",
  "correctiveInvoice": {
    "iicRef": "{{electronicIic}}"
  },
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "CORR-1",
      "name": "Korrigjim shërbimi",
      "vatCode": "B",
      "price": -1000,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": -1000
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "EINVOICE-P9-2026-000130",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "19/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": -1000,
  "eic": "6df80aec-f690-43ce-a2f2-45ee0cb948ce"
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ELEKTRONIKE · P11Rrjedhë faturimi elektronik të pjesshëm. fic + eic

/invoice/registerPërfundimi: fic + eic #invoice-type-electronic-p11

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "EINVOICE-P11-2026-000131",
  "isEinvoice": true,
  "selectedProcess": "P11",
  "buyer": {
    "buyerIDType": "NUIS",
    "buyerIDNum": "{{buyerNipt}}",
    "buyerName": "Blerës SHPK",
    "buyerAddress": "Tiranë",
    "buyerTown": "Tiranë",
    "buyerCountry": "ALB"
  },
  "articles": [
    {
      "articleId": "PART-1",
      "name": "Faturim i pjesshëm",
      "vatCode": "B",
      "price": 25000,
      "units": 1,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "TRANSFER",
      "amount": 25000
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "EINVOICE-P11-2026-000131",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "20/2026/xx123xx123",
  "invoiceType": "NONCASH",
  "totalPrice": 25000,
  "eic": "55df7eaf-126f-41b7-8270-6fa57080703e"
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`buyer`	`object`
`buyer.buyerIDType`	`string`
`buyer.buyerIDNum`	`string`
`buyer.buyerName`	`string`
`buyer.buyerAddress`	`string`
`buyer.buyerTown`	`string`
`buyer.buyerCountry`	`string`
`articles`	`object[]`
`articles[].articleId`	`string`
`articles[].name`	`string`
`articles[].vatCode`	`string`
`articles[].price`	`number`
`articles[].units`	`number`
`articles[].soldIn`	`string`
`payment`	`object[]`
`payment[].type`	`string`
`payment[].amount`	`number`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

POST ANULIM · FATURE NORMALEdocId i ri për anulimin, me referencë te iic e faturës origjinale. fic

/invoice/cancelPërfundimi: fic #invoice-type-cancellation

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "CANCEL-2026-000132",
  "correctiveInvoice": {
    "iicRef": "D21EBF3F7B7C502D6AAF2321A7CE2CE8"
  },
  "invoiceNotes": "Anulim me kërkesë të klientit"
}'

Shembull përgjigjeje

{
  "orderId": "CANCEL-2026-000132",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "21/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": -340
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`

POST ANULIM · FATURE ELEKTRONIKEAnulim korrigjues P10 për një faturë që ka tashmë eic. fic + eic

/invoice/cancelPërfundimi: fic + eic #invoice-type-electronic-cancellation

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "CANCEL-EINVOICE-2026-000133",
  "isEinvoice": true,
  "selectedProcess": "P10",
  "correctiveInvoice": {
    "iicRef": "{{electronicIic}}"
  },
  "invoiceNotes": "Anulim i faturës elektronike"
}'

Shembull përgjigjeje

{
  "orderId": "CANCEL-EINVOICE-2026-000133",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "22/2026",
  "invoiceType": "NONCASH",
  "totalPrice": -10000,
  "eic": "d59ef857-47df-4a80-a7d8-22ce70577df3"
}

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`isEinvoice`	`boolean`
`selectedProcess`	`string`
`correctiveInvoice`	`object`
`correctiveInvoice.iicRef`	`string`
`invoiceNotes`	`string`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string`
`iic`	`string`
`invoiceNumber`	`string`
`invoiceType`	`string`
`totalPrice`	`number`
`eic`	`string`

Harta e proceseve të faturës elektronike

Faturat elektronike mund të zgjasin më shumë sepse fiskalizimi dhe dorëzimi eInvoice janë faza të ndara. Janë të përfunduara vetëm kur kanë të dy kodet.

Procesi	Lloji standard	Rregull shtesë
`P1`	`380`	Faturim i dërgesave kundrejt porosive të blerjes, bazuar në kontratë.
`P2`	`380`	Faturim i dërgesave të mallrave ose shërbimeve bazuar në kontratë.
`P3`	`380`	Faturim i dorëzimit për një porosi blerjeje të rastësishme.
`P4`	`386`	Parapagim; prepaidAmount duhet të jetë mbi 0 dhe jo më i madh se totali.
`P5`	`380`	Pagesë në vend.
`P6`	`380`	Pagesë para dorëzimit.
`P7`	`380`	Faturë me referencë te dokumenti i dërgesës.
`P8`	`380`	Faturë me referencë te dokumentet e dërgesës dhe marrjes.
`P9`	`384`	Notë krediti ose faturë me vlera negative; correctiveInvoice.iicRef duhet të referojë faturë me eic.
`P10`	`384`	Korrigjim ose anulim; correctiveInvoice.iicRef duhet të referojë faturë me eic.
`P11`	`326`	Faturim i pjesshëm dhe përfundimtar.

Kodet UNTDID të llojit të faturës

Përdorni selectedInvoiceType vetëm kur ju duhet një klasifikim i posaçëm i dokumentit. Kur mungon, selectedProcess cakton kodin standard të treguar më sipër.

Kodi	Përshkrimi
`82`	Faturë për shërbime të matura
`84`	Notë debiti për rregullime financiare
`325`	Faturë paraprake
`326`	Faturë e pjesshme
`380`	Faturë tregtare
`383`	Notë debiti
`386`	Faturë parapagimi
`393`	Faturë e faktorizuar
`394`	Faturë qiraje
`395`	Faturë dërgese
`575`	Faturë e siguruesit
`623`	Faturë e shpërndarësit
`780`	Faturë mallrash

Kodet 80, 381, 384, 385 dhe 389 janë të rezervuara për lloje dokumentesh që caktohen automatikisht nga procesi dhe nuk mund të zgjidhen drejtpërdrejt.

05 · Referenca HTTP

Endpoint-et

Të gjitha endpoint-et përdorin POST me JSON dhe të njëjtat koka HTTP për autentikim.

POST/invoice/registerRegjistro faturë · Krijon dokument të ri ose vazhdon dokumentin e identifikuar nga docId.

Faturat#register-invoice

Të detyrueshme: docId · articles[]* · payment[]*
Rregullat: NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT | eInvoice

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`operatorCode`	`string?`
`currency`	`Currency?`
`articles`	`Article[] (conditional)`
`payment`	`Payment[] (conditional)`
`invoiceRebate`	`Rebate?`
`buyer`	`Buyer (conditional)`
`correctiveInvoice`	`CorrectiveInvoiceRef (conditional)`
`invoiceNotes`	`string?`
`documentType`	`NORMAL \| ORDER \| SUMMARY \| SELFISSUE \| EXPORT?`
`selfIssueType`	`AGREEMENT \| DOMESTIC \| ABROAD \| SELF \| OTHER (conditional)`
`reverseCharge`	`boolean?`
`summaryInvoices`	`string[] (conditional)`
`total`	`number (conditional)`
`supplyPeriod`	`{ start: date; end: date }?`
`isEinvoice`	`boolean?`
`selectedProcess`	`P1 \| P2 \| P3 \| P4 \| P5 \| P6 \| P7 \| P8 \| P9 \| P10 \| P11?`
`selectedInvoiceType`	`UNTDID code?`
`payDeadline`	`string(date)?`
`prepaidAmount`	`number (conditional)`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string?`
`eic`	`string?`
`iic`	`string?`
`link`	`string(uri)?`
`error`	`FiscalError?`
`invoiceNumber`	`string?`
`invoiceOrderNumber`	`integer?`
`invoiceType`	`CASH \| NONCASH?`
`totalPrice`	`number?`
`totalPriceWithoutVat`	`number?`
`totalVatAmount`	`number?`
`taxFreeAmount`	`number?`
`goodsExport`	`number?`
`markUpAmount`	`number?`
`operatorCode`	`string?`
`businessUnitCode`	`string?`
`tcrCode`	`string?`
`sellerName`	`string?`
`sellerNuis`	`string?`
`sellerAddress`	`string?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123",
  "articles": [
    {
      "articleId": "ART-1",
      "name": "Kafe",
      "vatCode": "B",
      "price": 120,
      "units": 2,
      "soldIn": "XPP"
    }
  ],
  "payment": [
    {
      "type": "CASH",
      "amount": 240
    }
  ]
}'

Shembull përgjigjeje

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 240
}

POST/invoice/cancelAnulo faturë · Krijon anulim korrigjues për iic e një fature ekzistuese.

Faturat#cancel-invoice

Të detyrueshme: new docId · correctiveInvoice.iicRef
Rregullat: no articles · no payment

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`operatorCode`	`string?`
`correctiveInvoice`	`CorrectiveInvoiceRef`
`invoiceNotes`	`string?`
`isEinvoice`	`boolean?`
`selectedProcess`	`P1–P11?`
`selectedInvoiceType`	`UNTDID code?`
`payDeadline`	`string(date)?`
`prepaidAmount`	`number?`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string?`
`eic`	`string?`
`iic`	`string?`
`link`	`string(uri)?`
`error`	`FiscalError?`
`invoiceNumber`	`string?`
`invoiceOrderNumber`	`integer?`
`invoiceType`	`CASH \| NONCASH?`
`totalPrice`	`number?`
`totalPriceWithoutVat`	`number?`
`totalVatAmount`	`number?`
`taxFreeAmount`	`number?`
`goodsExport`	`number?`
`markUpAmount`	`number?`
`operatorCode`	`string?`
`businessUnitCode`	`string?`
`tcrCode`	`string?`
`sellerName`	`string?`
`sellerNuis`	`string?`
`sellerAddress`	`string?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123-CANCEL",
  "correctiveInvoice": {
    "iicRef": "D21EBF3F7B7C502D6AAF2321A7CE2CE8"
  },
  "invoiceNotes": "Customer cancellation"
}'

Shembull përgjigjeje

{
  "orderId": "SHOP-2026-000123-CANCEL",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "13/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": -240
}

POST/invoice/statusStatusi i faturës · Lexon statusin me docId dhe vazhdon një operacion të papërfunduar.

Faturat#invoice-status

Të detyrueshme: docId
Rregullat: same docId · may continue processing

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fic`	`string?`
`eic`	`string?`
`iic`	`string?`
`link`	`string(uri)?`
`error`	`FiscalError?`
`invoiceNumber`	`string?`
`invoiceOrderNumber`	`integer?`
`invoiceType`	`CASH \| NONCASH?`
`totalPrice`	`number?`
`totalPriceWithoutVat`	`number?`
`totalVatAmount`	`number?`
`taxFreeAmount`	`number?`
`goodsExport`	`number?`
`markUpAmount`	`number?`
`operatorCode`	`string?`
`businessUnitCode`	`string?`
`tcrCode`	`string?`
`sellerName`	`string?`
`sellerNuis`	`string?`
`sellerAddress`	`string?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/status' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHOP-2026-000123"
}'

Shembull përgjigjeje

{
  "orderId": "SHOP-2026-000123",
  "fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "invoiceNumber": "12/2026/xx123xx123",
  "invoiceType": "CASH",
  "totalPrice": 240
}

POST/invoice/pdfPDF-ja e faturës · Gjeneron A4 PDF, kupon PNG ose PDF zyrtare elektronike në base64.

Faturat#invoice-pdf

Të detyrueshme: iic
Rregullat: A4 | receipt | eInvoice

Fushat e kërkesës

Fusha	Tipi
`iic`	`string`
`pdfType`	`'A4' \| 'receipt' \| 'eInvoice'`
`paperWidth`	`58 \| 80 \| 110?`
`lang`	`'sq' \| 'en'?`

Fushat e përgjigjes

Fusha	Tipi
`base64`	`string`
`lang`	`string?`
`eic`	`string?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/pdf' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
  "pdfType": "A4",
  "lang": "sq"
}'

Shembull përgjigjeje

{
  "base64": "JVBERi0xLjQKJcfsj6IK...",
  "lang": "sq"
}

POST/balance/initiateHap gjendjen · Raporton gjendjen fillestare të arkës në ALL.

Gjendja e arkës#initiate-balance

Të detyrueshme: docId · amount
Rregullat: once per business day and fiscal device · before the first cash invoice · amount in ALL

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/initiate' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHIFT-2026-08-28-OPEN",
  "amount": 10000
}'

Shembull përgjigjeje

{
  "orderId": "SHIFT-2026-08-28-OPEN",
  "fcdc": "b5c3e1a2-9f44-4c3a-9c1e-2f0d7a5b8e10"
}

POST/balance/depositDepozito para · Raporton para të shtuara në arkë në ALL.

Gjendja e arkës#deposit-balance

Të detyrueshme: docId · amount
Rregullat: amount in ALL

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/deposit' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHIFT-2026-08-28-IN-1",
  "amount": 5000,
  "notes": "Cash added to till"
}'

Shembull përgjigjeje

{
  "orderId": "SHIFT-2026-08-28-IN-1",
  "fcdc": "d6a4e2b3-8e55-4d2b-8b2f-3a1e6b4c9f21"
}

POST/balance/withdrawTërhiq para · Raporton para të hequra nga arka në ALL.

Gjendja e arkës#withdraw-balance

Të detyrueshme: docId · amount
Rregullat: amount in ALL

Fushat e kërkesës

Fusha	Tipi
`docId`	`string`
`amount`	`number`
`notes`	`string?`
`operatorCode`	`string?`

Fushat e përgjigjes

Fusha	Tipi
`orderId`	`string`
`fcdc`	`string?`
`error`	`FiscalError?`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/withdraw' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "docId": "SHIFT-2026-08-28-OUT-1",
  "amount": 2500,
  "notes": "Bank deposit"
}'

Shembull përgjigjeje

{
  "orderId": "SHIFT-2026-08-28-OUT-1",
  "fcdc": "e7b5f3c4-7d66-5e3c-9a3e-4b2f7c5d0a32"
}

POST/utilities/get-taxpayersKërko tatimpagues · Kërkon tatimpagues shqiptarë me NIPT ose emër biznesi.

Utilitetet#get-taxpayers

Të detyrueshme: searchTerm (3–200)
Rregullat: NIPT or business name · searchTerm minimum 3 characters · no activity-status field

Fushat e kërkesës

Fusha	Tipi
`searchTerm`	`string (3–200)`

Fushat e përgjigjes

Fusha	Tipi
`[]`	`Taxpayer[]`
`[].Tin`	`string`
`[].Name`	`string`
`[].Address`	`string`
`[].Town`	`string`
`[].Country`	`string (ISO 3166-1 alpha-3)`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/get-taxpayers' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{
  "searchTerm": "Vodafone"
}'

Shembull përgjigjeje

[
  {
    "Address": "Rruga Pavaresia, kodi postal 1050, Kashar 61",
    "Country": "ALB",
    "Name": "FONDACIONI VODAFONE ALBANIA",
    "Tin": "K72118452F",
    "Town": "Tirane"
  },
  {
    "Address": "Autostrada Tirane-Durres, Rruga Pavaresia, Nr.61, Kashar",
    "Country": "ALB",
    "Name": "VODAFONE ALBANIA",
    "Tin": "K11715005L",
    "Town": "Kashar"
  }
]

POST/utilities/get-operatorsListo operatorët · Kthen operatorët e biznesit dhe pajisjes së autentikuar.

Utilitetet#get-operators

Të detyrueshme: none
Rregullat: authenticated business + device

Fushat e kërkesës

Fusha	Tipi
`body`	`{}`

Fushat e përgjigjes

Fusha	Tipi
`[]`	`Operator[]`
`[].name`	`string`
`[].opCode`	`string`

Trupi i kërkesës

curl --request POST \
  --url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/get-operators' \
  --header 'Authorization: Bearer {{accessToken}}' \
  --header 'Content-Type: application/json' \
  --header 'integration-app: your-client-name' \
  --data '{}'

Shembull përgjigjeje

[
  {
    "name": "test3",
    "opCode": "gh537ez280"
  },
  {
    "name": "User A",
    "opCode": "aa111aa222"
  }
]

06 · Referenca e fushave

Katalogu i skemave të API-së

Hapni një skemë për të parë çdo fushë, tipin e saktë, detyrimin dhe kufizimet e validimit.

RegisterInvoiceRequest22

Fusha	Tipi	Detyrimi	Rregullat
`docId`	`string`	E detyrueshme	5–200 chars · unique per business document
`operatorCode`	`string`	Opsionale	^[a-z]{2}\d{3}[a-z]{2}\d{3}$
`currency`	`Currency`	Opsionale	default: ALL / 1
`articles`	`Article[]`	Me kusht	required except SUMMARY · minItems: 1
`payment`	`Payment[]`	Me kusht	required except ORDER · minItems: 1
`invoiceRebate`	`Rebate`	Opsionale	percentage or value, never both
`buyer`	`Buyer`	Me kusht	required for eInvoice and EXPORT
`correctiveInvoice`	`CorrectiveInvoiceRef`	Me kusht	required for P9 / P10
`invoiceNotes`	`string`	Opsionale	maxLength: 500
`documentType`	`enum`	Opsionale	NORMAL \| ORDER \| SUMMARY \| SELFISSUE \| EXPORT
`selfIssueType`	`enum`	Me kusht	AGREEMENT \| DOMESTIC \| ABROAD \| SELF \| OTHER
`reverseCharge`	`boolean`	Opsionale	true only for SELFISSUE
`summaryInvoices`	`string[]`	Me kusht	SUMMARY only · minItems: 1 · each iic is 32 hex chars
`total`	`number`	Me kusht	SUMMARY only · exact referenced ORDER total
`supplyPeriod`	`object`	Opsionale	start/end in one calendar month
`supplyPeriod.start`	`string(date)`	Me kusht	YYYY-MM-DD
`supplyPeriod.end`	`string(date)`	Me kusht	YYYY-MM-DD
`isEinvoice`	`boolean`	Opsionale	default: false
`selectedProcess`	`enum`	Opsionale	P1–P11 · default: P1
`selectedInvoiceType`	`string(enum)`	Opsionale	82 \| 84 \| 325 \| 326 \| 380 \| 383 \| 386 \| 393 \| 394 \| 395 \| 575 \| 623 \| 780
`payDeadline`	`string(date)`	Opsionale	YYYY-MM-DD · current year · not in the past
`prepaidAmount`	`number`	Me kusht	required for P4 · >= 0 · max 2 decimals

Article8

Fusha	Tipi	Detyrimi	Rregullat
`articleId`	`string`	E detyrueshme	maxLength: 100
`name`	`string`	E detyrueshme	maxLength: 100
`vatCode`	`string(enum)`	E detyrueshme	A \| B \| C \| D \| E \| F \| G \| H \| I \| J \| K \| L · must match the business fiscal configuration
`price`	`number`	E detyrueshme	unit price including VAT
`units`	`number`	E detyrueshme	quantity
`soldIn`	`string`	E detyrueshme	UN/CEFACT unit code, e.g. XPP \| KGM \| LTR \| HUR
`totalPrice`	`number`	Opsionale	default: price × units
`rebate`	`Rebate`	Opsionale	line-level discount

Rebate2

Fusha	Tipi	Detyrimi	Rregullat
`inPercentage`	`number`	Me kusht	mutually exclusive with inValue
`inValue`	`number`	Me kusht	mutually exclusive with inPercentage

Payment3

Fusha	Tipi	Detyrimi	Rregullat
`type`	`string(enum)`	E detyrueshme	CASH \| BANKNOTE \| CARD \| CHECK \| SVOUCHER \| COMPANY \| ORDER \| ACCOUNT \| FACTORING \| COMPENSATION \| TRANSFER \| WAIVER \| KIND \| OTHER
`amount`	`number`	E detyrueshme	payment sum must equal calculated invoice total
`details`	`PaymentDetail[]`	Me kusht	required and non-empty for ACCOUNT

PaymentDetail7

Fusha	Tipi	Detyrimi	Rregullat
`idNumber`	`string`	E detyrueshme	IBAN or account number
`name`	`string`	E detyrueshme	account holder
`bankName`	`string`	E detyrueshme	bank name
`swift_code`	`string`	E detyrueshme	SWIFT / BIC
`country`	`string`	E detyrueshme	country name
`countryCode`	`string`	E detyrueshme	ISO 3166-1 alpha-2 · exactly 2 chars
`currency`	`string`	E detyrueshme	ISO 4217 · exactly 3 chars

Buyer7

Fusha	Tipi	Detyrimi	Rregullat
`buyerIDType`	`string(enum)`	E detyrueshme	NUIS \| ID \| PASS \| VAT \| TAX \| SOC \| POINTS
`buyerIDNum`	`string`	E detyrueshme	when buyerIDType=NUIS: ^[A-Za-z][0-9]{8}[A-Za-z]$ · normalize to uppercase
`buyerName`	`string`	E detyrueshme	buyer legal/display name
`buyerAddress`	`string`	E detyrueshme	buyer address
`buyerTown`	`string`	E detyrueshme	buyer town
`buyerCountry`	`string`	E detyrueshme	ISO 3166-1 alpha-3, e.g. ALB
`buyerCountryCode`	`string`	Opsionale	ISO 3166-1 alpha-2 · default: AL

Currency2

Fusha	Tipi	Detyrimi	Rregullat
`code`	`string`	Opsionale	ISO 4217 · default: ALL
`exRate`	`number`	Me kusht	required when code != ALL · rate against ALL

CorrectiveInvoiceRef2

Fusha	Tipi	Detyrimi	Rregullat
`iicRef`	`string`	E detyrueshme	existing invoice iic · 32 hex chars
`issueDateTime`	`string(date)`	Opsionale	defaults to original invoice date

CancelInvoiceRequest9

Fusha	Tipi	Detyrimi	Rregullat
`docId`	`string`	E detyrueshme	new cancellation id · 5–200 chars
`operatorCode`	`string`	Opsionale	^[a-z]{2}\d{3}[a-z]{2}\d{3}$
`correctiveInvoice`	`CorrectiveInvoiceRef`	E detyrueshme	iicRef points to original invoice
`invoiceNotes`	`string`	Opsionale	maxLength: 500
`isEinvoice`	`boolean`	Opsionale	inherits from original when omitted
`selectedProcess`	`enum`	Opsionale	P1–P11 · electronic default: P10
`selectedInvoiceType`	`string(enum)`	Opsionale	same values as RegisterInvoiceRequest
`payDeadline`	`string(date)`	Opsionale	YYYY-MM-DD
`prepaidAmount`	`number`	Opsionale	>= 0 · max 2 decimals

StatusInvoiceRequest1

Fusha	Tipi	Detyrimi	Rregullat
`docId`	`string`	E detyrueshme	same invoice docId · 5–200 chars

InvoicePdfRequest4

Fusha	Tipi	Detyrimi	Rregullat
`iic`	`string`	E detyrueshme	exactly 32 hexadecimal chars
`pdfType`	`string(enum)`	Opsionale	A4 \| receipt \| eInvoice · default: A4
`paperWidth`	`integer(enum)`	Opsionale	58 \| 80 \| 110 · receipt only · default: 80
`lang`	`string(enum)`	Opsionale	sq \| en

BalanceRequest4

Fusha	Tipi	Detyrimi	Rregullat
`docId`	`string`	E detyrueshme	5–200 chars · unique per balance operation · no prescribed naming convention
`amount`	`number`	E detyrueshme	amount in ALL
`notes`	`string`	Opsionale	operation note
`operatorCode`	`string`	Opsionale	^[a-z]{2}\d{3}[a-z]{2}\d{3}$

GetTaxpayersRequest1

Fusha	Tipi	Detyrimi	Rregullat
`searchTerm`	`string`	E detyrueshme	NIPT or business name · 3–200 chars

InvoiceResponse21

Fusha	Tipi	Detyrimi	Rregullat
`orderId`	`string`	E detyrueshme	echoes request docId
`fic`	`string`	Me kusht	normal completion identifier
`eic`	`string`	Me kusht	required with fic for electronic completion
`iic`	`string`	Me kusht	invoice identifier · 32 hex chars
`link`	`string(uri)`	Opsionale	public verification URL
`error`	`FiscalError`	Opsionale	present when incomplete or failed
`invoiceNumber`	`string`	Opsionale	fiscal invoice number
`invoiceOrderNumber`	`integer`	Opsionale	fiscal sequence number
`invoiceType`	`string(enum)`	Opsionale	CASH \| NONCASH
`totalPrice`	`number`	Opsionale	gross total
`totalPriceWithoutVat`	`number`	Opsionale	net total
`totalVatAmount`	`number`	Opsionale	VAT total
`taxFreeAmount`	`number`	Opsionale	tax-free total
`goodsExport`	`number`	Opsionale	export amount
`markUpAmount`	`number`	Opsionale	markup amount
`operatorCode`	`string`	Opsionale	fiscal operator code
`businessUnitCode`	`string`	Opsionale	fiscal business-unit code
`tcrCode`	`string`	Opsionale	empty for electronic invoices
`sellerName`	`string`	Opsionale	seller name
`sellerNuis`	`string`	Opsionale	seller NIPT
`sellerAddress`	`string`	Opsionale	seller address

InvoiceIncompleteResponse2

Fusha	Tipi	Detyrimi	Rregullat
`orderId`	`string`	E detyrueshme	echoes request docId
`error`	`FiscalError`	E detyrueshme	fiscalization or eInvoice delivery has not completed

Error2

Fusha	Tipi	Detyrimi	Rregullat
`message`	`string`	E detyrueshme	validation, authorization or domain error message
`field`	`string`	Opsionale	field that failed validation

CisError3

Fusha	Tipi	Detyrimi	Rregullat
`faultEnv`	`string(enum)`	Opsionale	env:CLIENT \| env:SERVER
`faultString`	`string`	Opsionale	message returned by the tax platform
`faultCode`	`string`	Opsionale	tax-platform error code

FiscalError2

Fusha	Tipi	Detyrimi	Rregullat
`cisError`	`CisError`	Opsionale	tax platform error
`otherError`	`string`	Opsionale	temporary processing error

PdfResponse2

Fusha	Tipi	Detyrimi	Rregullat
`base64`	`string`	E detyrueshme	base64 PDF or PNG
`lang`	`string`	Opsionale	document language

EinvoicePdfResponse2

Fusha	Tipi	Detyrimi	Rregullat
`base64`	`string`	E detyrueshme	official eInvoice PDF encoded as base64
`eic`	`string`	E detyrueshme	electronic invoice identifier

BalanceResponse3

Fusha	Tipi	Detyrimi	Rregullat
`orderId`	`string`	E detyrueshme	echoes request docId
`fcdc`	`string`	Me kusht	balance-operation completion identifier
`error`	`FiscalError`	Opsionale	processing error

Taxpayer5

Fusha	Tipi	Detyrimi	Rregullat
`Tin`	`string`	E detyrueshme	taxpayer NIPT
`Name`	`string`	E detyrueshme	registered name
`Address`	`string`	E detyrueshme	registered address
`Town`	`string`	E detyrueshme	registered town
`Country`	`string`	E detyrueshme	ISO 3166-1 alpha-3

Operator2

Fusha	Tipi	Detyrimi	Rregullat
`name`	`string`	E detyrueshme	operator display name
`opCode`	`string`	E detyrueshme	use as operatorCode in fiscal requests

Harta e kodeve të TVSH-së

vatCode varet nga statusi i TVSH-së dhe konfigurimi fiskal i biznesit, jo vetëm nga artikulli. Për një biznes subjekt të TVSH-së, kategoria standarde 20% është B; A është kategoria 0% për një biznes jo subjekt të TVSH-së.

Kodi	Norma	Trajtimi fiskal
`A`	`0%`	Biznes jo subjekt i TVSH-së
`B`	`20%`	Norma standarde
`C`	`0%`	Furnizim i përjashtuar
`D`	`10%`	Norma e reduktuar
`E`	`6%`	Norma e reduktuar
`J`	`0%`	Eksport mallrash

API-ja aktualisht nuk e kthen këtë mapping. Ruajeni në konfigurimin e integrimit tuaj. Mos përdorni kode të tjera A–L pa një konfigurim fiskal të konfirmuar.

Pagesë e plotë ACCOUNT

details duhet të jetë listë jo bosh. Çdo element përshkruan një llogari bankare të shitësit dhe kërkon të shtatë fushat e paraqitura këtu.

Fragmenti i pagesës

{
  "payment": [
    {
      "type": "ACCOUNT",
      "amount": 10000,
      "details": [
        {
          "idNumber": "AL47212110090000000235698741",
          "name": "Shitësi SHPK",
          "bankName": "Banka XYZ",
          "swift_code": "ABCDEFGH",
          "country": "Shqipëri",
          "countryCode": "AL",
          "currency": "ALL"
        }
      ]
    }
  ]
}

Sqarime operacionale

Fusha	Rregullat
`buyerIDNum · NUIS`	Formati i pranuar: një shkronjë, tetë shifra, një shkronjë (^[A-Za-z][0-9]{8}[A-Za-z]$). Normalizojeni në shkronja të mëdha. Kontrata nuk përfshin format tjetër të vjetër NIPT-i.
`get-taxpayers`	Country përdor ISO 3166-1 alpha-3 (ALB për Shqipërinë). Përgjigjja nuk ka fushë për statusin aktiv, pasiv ose të çregjistruar; përdoreni endpoint-in për kërkim dhe plotësim të të dhënave të blerësit, jo si verifikim përfundimtar të statusit tatimor.
`Kufizimi i kërkesave`	Aktualisht nuk është publikuar një kufi numerik. Përdorni debounce gjatë kërkimit dhe mos dërgoni kërkesë për çdo tast të shtypur.
`balance/initiate`	Dërgoni një hapje gjendjeje të suksesshme për çdo ditë pune dhe pajisje fiskale/TCR të autentikuar, para faturës së parë me para në dorë. Turni i aplikacionit nuk është kufiri fiskal dhe nuk ka endpoint për mbylljen e gjendjes.
`docId e gjendjes`	Vlerat SHIFT-… janë vetëm shembuj. Përdorni çdo identifikues të qëndrueshëm unik me 5–200 karaktere dhe ripërdoreni vetëm për të rikuperuar të njëjtin veprim gjendjeje.

Kodet e njësive matëseShkarkoni listën e njësive matëse të mbështetura dhe përdorni vlerën e kodit si soldIn, p.sh. XPP, KGM, LTR ose HUR.Shkarko listën e njësive (.xlsx)

Vlerat enum të lejuara

soldIn: XPP · KGM · LTR · HUR · other UN/CEFACT unit codes
vatCode: A · B · C · D · E · F · G · H · I · J · K · L
payment.type: CASH · BANKNOTE · CARD · CHECK · SVOUCHER · COMPANY · ORDER · ACCOUNT · FACTORING · COMPENSATION · TRANSFER · WAIVER · KIND · OTHER
buyerIDType: NUIS · ID · PASS · VAT · TAX · SOC · POINTS
selectedProcess: P1 · P2 · P3 · P4 · P5 · P6 · P7 · P8 · P9 · P10 · P11
selectedInvoiceType: 82 · 84 · 325 · 326 · 380 · 383 · 386 · 393 · 394 · 395 · 575 · 623 · 780
selfIssueType: AGREEMENT · DOMESTIC · ABROAD · SELF · OTHER
pdfType: A4 · receipt · eInvoice

07 · Kriteret e përfundimit

Kontrolloni identifikuesit para se ta konsideroni operacionin të përfunduar

Një përgjigje HTTP e suksesshme mund të përshkruajë një operacion ende të papërfunduar. Ruani përgjigjen dhe vendosni sipas identifikuesve të kthyer.

Operacioni	Përfundon kur	Kur nuk ka përfunduar
Faturë normale / anulim	`ekziston fic`	Rikuperoni me të njëjtin docId.
Faturë elektronike / anulim	`ekzistojnë fic dhe eic`	Kontrolloni statusin me të njëjtin docId.
Transaksion arke	`ekziston fcdc`	Riprovoni të njëjtin operacion dhe docId.
PDF	`ekziston base64`	Riprovoni pasi fatura burim të përfundojë.

Tabela e vendimit për gabimet

Error	Mund të riprovohet	Veprimi
`400 validim / fushë`	Jo	Korrigjoni kërkesën; fushat e panjohura refuzohen.
`401 Unauthorized`	Pas kredencialeve	Rinovoni token-in e mjedisit dhe ruani docId.
`cisError env:CLIENT`	Jo	Korrigjoni së pari të dhënat fiskale ose kërkesën.
`cisError env:SERVER / otherError`	Po	Pritni dhe rikuperoni me të njëjtin docId.
`Timeout / lidhje / 502 / 503`	Po	Kontrolloni fillimisht statusin; ridërgoni vetëm kur dokumenti nuk gjendet.
`Po përpunohet kërkesë tjetër`	Po, më vonë	Ndalni kërkesat paralele, prisni dhe kontrolloni statusin.