/api/v2/invoice/cash
Requires authentication
Rate limited by the `api-global` limiter
v2
Send a bearer token, plus the X-Client-Id and X-Client-Secret headers in the Authorization header.
E njëjta faturë si te v1, me pagesën si listë. Për blerësin, rreshtat, zbritjet dhe
vetëfaturimin vlejnë rregullat e POST /api/v1/invoice/cash.
Pagesa#
payment_methods mban një element për çdo mënyrë dhe është i detyrueshëm edhe kur fatura
paguhet e gjitha me një mënyrë.
"payment_methods": [
{"type": "BANKNOTE", "amount": 1200},
{"type": "CARD", "amount": 800}
]
| Rregulli | Kufiri |
|---|---|
| Sa mënyra mban një faturë | 10 |
| E njëjta mënyrë dy herë | Nuk lejohet |
Shuma e amount |
Sa totali i faturës, me zbritjen tashmë të zbatuar |
Elementi COMPANY mban vetë company_card, dhe elementi SVOUCHER mban vetë vouchers.
Një listë që nuk e mbledh totalin refuzohet me 400, sepse shuma kontrollohet vetëm pasi
zbritja mbi faturën është zbatuar.
Vetëfaturimi paguhet nga arka, si te v1: kur arka nuk mbulon totalin, fatura nuk ruhet dhe
përgjigja vjen me HTTP 200 dhe status: false.
URL-ja e plotë: https://fature.al/api/v2/invoice/cash
Ndryshuar që nga v1:
| What changed | v1 | v2 |
|---|---|---|
body payment_method |
string, one of BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY, ORDER, required | — |
body company_card |
string, maxLength 50, nullable, required | — |
body vouchers |
array, nullable, required | — |
body payment_methods |
— | array, required |
200 data.invoice.payment_methods |
— | array |
200 data.invoice.payment_methods[].type |
— | string |
200 data.invoice.payment_methods[].amount |
— | number |
200 data.invoice.payment_methods[].company_card |
— | string, nullable |
200 data.invoice.payment_methods[].vouchers |
— | array |
Body parameters
| Name | Tipi | E detyrueshme | Përshkrimi |
|---|---|---|---|
| internalId | string | yes | Identifikuesi i faturës në sistemin tuaj, unik brenda kompanisë për vitin; shërben edhe si çelës idempotence. I detyrueshëm. |
| client | object, nullable | no | Blerësi. Opsional: pa të fatura lëshohet për klientin e rastit. Me `client.internal_id` merret një klient i ruajtur në fature.al; ndryshe `client.name` bëhet i detyrueshëm sapo dërgoni çfarëdo fushe tjetër të `client`. |
| client.internal_id | integer, nullable | no | Id-ja e një klienti të ruajtur në fature.al. Kur e dërgoni, blerësi merret prej saj dhe fushat e tjera të `client` nuk lexohen. |
| client.name | string, nullable | no | Emri i blerësit. I detyrueshëm sapo dërgoni çfarëdo fushe tjetër të `client`. |
| client.id | object, nullable | no | Dokumenti i identifikimit të blerësit, si objekt me `type` dhe `id`. |
| client.id.type | string, one of NUIS, VAT, TAX, ID, PASS, SOC, nullable | no | Lloji i dokumentit: `NUIS` për një biznes shqiptar, `VAT` ose `TAX` për një biznes të huaj, `ID`, `PASS` ose `SOC` për një person. Pa të merret `NUIS`. |
| client.id.id | string, nullable | no | Numri i dokumentit të identifikimit, p.sh. NIPT-i kur `type` është `NUIS`. |
| client.address | string, nullable | no | Adresa e blerësit; shkon te CIS-i. Një klient i emëruar e kërkon, ose në këtë kërkesë ose të ruajtur më parë te klienti në fature.al. |
| client.city | string, nullable | no | Qyteti i blerësit; shkon te CIS-i. Një klient i emëruar e kërkon, ose në këtë kërkesë ose të ruajtur më parë te klienti në fature.al. |
| client.country | string, nullable | no | Shteti i blerësit, kod ISO 3166-1 alpha-3, p.sh. `ALB`, `RKS`, `ITA`. Pa të merret `ALB`. |
| lines | array | yes | Rreshtat e faturës, të paktën një. |
| lines[].product_name | string | yes | Emri i produktit ose i shërbimit. |
| lines[].product_code | string | yes | Kodi i produktit në katalogun tuaj. |
| lines[].unit | string | yes | Njësia matëse, si tekst që lexon njeriu. |
| lines[].quantity | number | yes | Sasia. |
| lines[].price | number | yes | Çmimi për njësi, me TVSH. |
| lines[].total | number | yes | Totali i rreshtit, me TVSH. |
| lines[].discount | number, min 0, max 100, nullable | no | Zbritja e rreshtit, në përqindje mbi çmimin e njësisë, nga 0 deri në 100. Opsionale: pa të, ose me vlerë bosh, rreshti kalon siç e dërgoni. `price` mbetet çmimi i plotë i njësisë, ndërsa `total` dërgohet tashmë i ulur: `price` herë `quantity`, me zbritjen e hequr. Një `total` që nuk përputhet me atë shifër e refuzon kërkesën me `400`, dhe `errors` thotë cili rresht dhe cila vlerë pritej. |
| lines[].vat | integer, one of 0, 6, 10, 20 | yes | Norma e TVSH-së në përqindje: `0`, `6`, `10` ose `20`. E detyrueshme. Kur biznesi juaj nuk është në skemën e TVSH-së, rreshti regjistrohet me TVSH `0` dhe përjashtim `TAX_FREE`, sido që ta dërgoni këtë fushë; kërkesa nuk refuzohet. |
| lines[].vat_exempt_type | string, one of TYPE_1, TYPE_2, EXPORT_OF_GOODS, TAX_FREE, nullable | no | Lloji i përjashtimit nga TVSH-ja, kur rreshti është i përjashtuar: `TYPE_1`, `TYPE_2`, `EXPORT_OF_GOODS` ose `TAX_FREE`. |
| invoice_discount_type | string, one of percent, amount, nullable | no | Si lexohet `invoice_discount_value`: `percent` si përqindje, `amount` si vlerë fikse me TVSH. Zbritja zbatohet mbi të gjithë faturën: rreshtat ruhen siç i dërgoni dhe ulet vetëm totali. Punon vetëm në çift me `invoice_discount_value`. Njëra pa tjetrën injorohet në heshtje dhe fatura del pa zbritje. |
| invoice_discount_value | number, min 0, nullable | no | Vlera e zbritjes, e lexuar sipas `invoice_discount_type`: përqindje deri në 100 kur tipi është `percent`; vlerë me TVSH në monedhën e faturës, deri në totalin e faturës, kur tipi është `amount`. Zeroja e lë faturën pa zbritje. Zbritja shpërndahet mbi grupet e TVSH-së sipas peshës së secilit në total dhe TVSH-ja rillogaritet mbi vlerën e ulur. |
| currency | string, nullable | no | Monedha e faturës, kod ISO 4217; pa të merret `ALL`. |
| exchange_rate | number, nullable | no | Sa lekë vlen një njësi e monedhës së faturës. Pa të, ose me vlerë jo pozitive, merret 1. Për monedha që vlejnë më pak se një lek, si JPY ose HUF, dërgoni vlerë nën 1. |
| due_date | string, nullable | no | Afati i pagesës, `YYYY-MM-DD`. |
| supply_start_date | string, nullable | no | Fillimi i periudhës së furnizimit, `YYYY-MM-DD`, për fatura që mbulojnë një interval. |
| supply_end_date | string, nullable | no | Fundi i periudhës së furnizimit, `YYYY-MM-DD`. |
| reverse_charge | boolean, nullable | no | Ngarkesa e kundërt: TVSH-ja deklarohet nga blerësi, jo nga shitësi. |
| notes | string, nullable | no | Shënime që shfaqen në faturë. |
| periodic_invoice | boolean, nullable | no | Shënon një faturë të një cikli të përsëritur faturimi. |
| self_issue_type | string, one of DOMESTIC, ABROAD, OTHER, nullable | no | Vetëfaturim: `DOMESTIC`, `ABROAD` ose `OTHER`. Kur e dërgoni, `client` është shitësi dhe i duhet identifikimi (`client.id`) bashkë me shtetin. Pa të fatura është e zakonshme. |
| payment_methods | array | yes | Mënyrat e pagesës, një element për secilën. E detyrueshme edhe kur fatura paguhet me një mënyrë të vetme; atëherë lista ka një element. Deri në 10 elemente, e njëjta mënyrë nuk përsëritet dhe shuma e `amount` duhet të jetë sa totali i faturës, me zbritjen tashmë të zbatuar; ndryshe kërkesa refuzohet me `400`. |
| payment_methods[].type | string, one of BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY, ORDER | yes | Mënyra e pagesës e këtij elementi: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` ose `ORDER`. E detyrueshme. |
| payment_methods[].amount | number | yes | Sa paguhet me këtë mënyrë, me TVSH, në monedhën e faturës. E detyrueshme. Pranon çdo vlerë që pranon CIS-i: edhe 0, për një faturë me vlerë 0, dhe negative. |
| payment_methods[].company_card | string, maxLength 50, nullable | no | Karta e kompanisë. E detyrueshme vetëm në elementin `COMPANY` dhe e refuzuar në çdo element tjetër. Deri në 50 karaktere. |
| payment_methods[].vouchers | array, nullable | no | Numrat seriale të tollonave, në formën numër-vit-NIPT, pa përsëritje, deri në 20. Të detyrueshëm vetëm në elementin `SVOUCHER` dhe të refuzuar në çdo element tjetër. |
Përgjigjet
200 Kur përdoruesi nuk ka pajisje fiskale, kur arka nuk mbulon një vetëfaturim, ose kur fatura refuzohet pas validimit nga CIS-i ose gjatë ruajtjes, përgjigja kthehet me HTTP 200 dhe `status: false`; arsyeja është te `message`.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | |
| data | object | |
| data.invoice | object | |
| data.invoice.id | integer | Id-ja e faturës në fature.al. Ruajeni pranë `internalId` tuaj |
| data.invoice.number | string, nullable | Numri i faturës, si `12/2026` |
| data.invoice.iic | string, nullable | Kodi identifikues i faturës, IIC (NSLF) |
| data.invoice.fic | string, nullable | Kodi që kthen CIS-i kur regjistron faturën, FIC (NIVF). Null sa kohë fatura pret fiskalizimin e shtyrë |
| data.invoice.tcrCode | string, nullable | Kodi TCR i pajisjes fiskale që e lëshoi; null te faturat që nuk lëshohen nga një TCR |
| data.invoice.businessCode | string, nullable | Kodi i njësisë së biznesit nën të cilën u lëshua fatura |
| data.invoice.operatorCode | string, nullable | Kodi i operatorit që e lëshoi faturën |
| data.invoice.fiscalizedAt | string | Data dhe ora e krijimit të faturës, `YYYY-MM-DD HH:MM:SS`, orë lokale |
| data.invoice.verifyURL | string, nullable | URL-ja e verifikimit te administrata tatimore, ajo që hap kodi QR |
| data.invoice.pdf | string | URL-ja për të shkarkuar dokumentin. Te një e-faturë që ka tashmë EIC, tregon PDF-në zyrtare të platformës së e-faturave në vend të asaj të fature.al |
| data.invoice.eic | string, nullable | Kodi i e-faturës në platformën e e-faturave, EIC. Çelësi është i pranishëm vetëm te një e-faturë që e ka tashmë; te çdo faturë tjetër mungon fare, nuk vjen null |
| data.invoice.payment_methods | array | Një element për çdo mënyrë pagese, me shumën që u shlye me secilën. E njëjta listë që kthen `GET /invoice/{id}/details` |
| data.invoice.payment_methods[].type | string | Mënyra e pagesës, p.sh. `BANKNOTE` ose `CARD` |
| data.invoice.payment_methods[].amount | number | Shuma e shlyer me këtë mënyrë, me TVSH, në monedhën e faturës |
| data.invoice.payment_methods[].company_card | string, nullable | Numri i kartës së kompanisë; i plotësuar vetëm kur `type` është `COMPANY`, përndryshe null |
| data.invoice.payment_methods[].vouchers | array | Numrat serialë të tollonave; të plotësuar vetëm kur `type` është `SVOUCHER`, përndryshe listë bosh |
400 Të dhëna të paplota ose të pavlefshme për fiskalizim. `errors` thotë saktë çfarë duhet plotësuar. Fatura nuk u ruajt; riprovoni me të njëjtin `internalId`.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data` |
| message | string | Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin |
| errors | array | Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message` |
401 Unauthenticated
| Field | Tipi | Përshkrimi |
|---|---|---|
| message | string |
403 Abonimi ka mbaruar, ose veprimi nuk lejohet për këtë llogari.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data` |
| message | string | Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin |
| errors | array | Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message` |
409 Një kërkesë me këtë `internalId` është ende në proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `POST /invoice/details/{internalId}`.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data` |
| message | string | Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin |
| errors | array | Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message` |
422 Të dhënat nuk kaluan validimin. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës. Vetëm `internalId` që mungon kthehet me formatin standard të gabimit.
| Field | Tipi | Përshkrimi |
|---|---|---|
| success | boolean | Gjithmonë false |
| message | string | Një rresht përmbledhës, i njëjtë për çdo dështim validimi |
| errors | object | Fushat që nuk kaluan validimin, secila me mesazhet e veta. Çelësat me pikë tregojnë brenda objekteve dhe elementëve të array-ve, p.sh. `lines.0.quantity` |
429 Kufiri i kërkesave u arrit. Nga kufiri i përgjithshëm përgjigja mban vetëm `message` dhe header-in `Retry-After`; nga kufiri i endpoint-it mban formatin standard të gabimit.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data` |
| message | string | Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin |
| errors | array | Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message` |
500 Gabim i papritur në server.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data` |
| message | string | Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin |
| errors | array | Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message` |
503 Shërbimi i fiskalizimit nuk u arrit dhe fatura nuk u ruajt. Riprovoni me të njëjtin `internalId`.
| Field | Tipi | Përshkrimi |
|---|---|---|
| status | boolean | Gjithmonë false. Një përgjigje e suksesshme mban `status: true` dhe objektin `data` |
| message | string | Përshkrimi i gabimit. Bosh kur dështimi nuk mban ndonjë mesazh të vetin |
| errors | array | Mesazhe për t'u shfaqur te përdoruesi ose për t'u ruajtur në log. Mungon kur nuk ka gjë për të shtuar përtej `message` |
Shembull kërkese
curl -X POST 'https://fature.al/api/v2/invoice/cash' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-H 'X-Client-Id: YOUR_CLIENT_ID' \
-H 'X-Client-Secret: YOUR_CLIENT_SECRET' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"internalId": "CASH-001",
"client": {
"internal_id": 1,
"name": "Klient i rastit",
"id": {
"type": "NUIS",
"id": "L62221018T"
},
"address": "1 Example Street",
"city": "Berlin",
"country": "US"
},
"lines": [
{
"product_name": "Kafe",
"product_code": "KAF-001",
"unit": "cope",
"quantity": 2,
"price": 150,
"total": 300,
"discount": 10,
"vat": 20,
"vat_exempt_type": "TYPE_1"
}
],
"invoice_discount_type": "percent",
"invoice_discount_value": 10,
"currency": "ALL",
"exchange_rate": 100.5,
"due_date": "2026-10-04",
"supply_start_date": "2026-09-01",
"supply_end_date": "2026-09-30",
"reverse_charge": false,
"notes": "Faleminderit per blerjen",
"periodic_invoice": false,
"self_issue_type": "DOMESTIC",
"payment_methods": [
{
"type": "BANKNOTE",
"amount": 1200,
"company_card": "4111-2233",
"vouchers": [
"vouchers"
]
}
]
}'
use Illuminate\Support\Facades\Http;
$response = Http::withHeaders([
'Authorization' => 'Bearer YOUR_TOKEN',
'X-Client-Id' => 'YOUR_CLIENT_ID',
'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
'Accept' => 'application/json',
'Content-Type' => 'application/json',
])->post('https://fature.al/api/v2/invoice/cash', [
'internalId' => 'CASH-001',
'client' => [
'internal_id' => 1,
'name' => 'Klient i rastit',
'id' => [
'type' => 'NUIS',
'id' => 'L62221018T',
],
'address' => '1 Example Street',
'city' => 'Berlin',
'country' => 'US',
],
'lines' => [
[
'product_name' => 'Kafe',
'product_code' => 'KAF-001',
'unit' => 'cope',
'quantity' => 2,
'price' => 150,
'total' => 300,
'discount' => 10,
'vat' => 20,
'vat_exempt_type' => 'TYPE_1',
],
],
'invoice_discount_type' => 'percent',
'invoice_discount_value' => 10,
'currency' => 'ALL',
'exchange_rate' => 100.5,
'due_date' => '2026-10-04',
'supply_start_date' => '2026-09-01',
'supply_end_date' => '2026-09-30',
'reverse_charge' => false,
'notes' => 'Faleminderit per blerjen',
'periodic_invoice' => false,
'self_issue_type' => 'DOMESTIC',
'payment_methods' => [
[
'type' => 'BANKNOTE',
'amount' => 1200,
'company_card' => '4111-2233',
'vouchers' => [
'vouchers',
],
],
],
]);
$data = $response->json();
use GuzzleHttp\Client;
$client = new Client();
$response = $client->request('POST', 'https://fature.al/api/v2/invoice/cash', [
'headers' => [
'Authorization' => 'Bearer YOUR_TOKEN',
'X-Client-Id' => 'YOUR_CLIENT_ID',
'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
'Accept' => 'application/json',
'Content-Type' => 'application/json',
],
'json' => [
'internalId' => 'CASH-001',
'client' => [
'internal_id' => 1,
'name' => 'Klient i rastit',
'id' => [
'type' => 'NUIS',
'id' => 'L62221018T',
],
'address' => '1 Example Street',
'city' => 'Berlin',
'country' => 'US',
],
'lines' => [
[
'product_name' => 'Kafe',
'product_code' => 'KAF-001',
'unit' => 'cope',
'quantity' => 2,
'price' => 150,
'total' => 300,
'discount' => 10,
'vat' => 20,
'vat_exempt_type' => 'TYPE_1',
],
],
'invoice_discount_type' => 'percent',
'invoice_discount_value' => 10,
'currency' => 'ALL',
'exchange_rate' => 100.5,
'due_date' => '2026-10-04',
'supply_start_date' => '2026-09-01',
'supply_end_date' => '2026-09-30',
'reverse_charge' => false,
'notes' => 'Faleminderit per blerjen',
'periodic_invoice' => false,
'self_issue_type' => 'DOMESTIC',
'payment_methods' => [
[
'type' => 'BANKNOTE',
'amount' => 1200,
'company_card' => '4111-2233',
'vouchers' => [
'vouchers',
],
],
],
],
]);
$data = json_decode((string) $response->getBody(), true);
const response = await fetch('https://fature.al/api/v2/invoice/cash', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_TOKEN',
'X-Client-Id': 'YOUR_CLIENT_ID',
'X-Client-Secret': 'YOUR_CLIENT_SECRET',
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({
"internalId": "CASH-001",
"client": {
"internal_id": 1,
"name": "Klient i rastit",
"id": {
"type": "NUIS",
"id": "L62221018T"
},
"address": "1 Example Street",
"city": "Berlin",
"country": "US"
},
"lines": [
{
"product_name": "Kafe",
"product_code": "KAF-001",
"unit": "cope",
"quantity": 2,
"price": 150,
"total": 300,
"discount": 10,
"vat": 20,
"vat_exempt_type": "TYPE_1"
}
],
"invoice_discount_type": "percent",
"invoice_discount_value": 10,
"currency": "ALL",
"exchange_rate": 100.5,
"due_date": "2026-10-04",
"supply_start_date": "2026-09-01",
"supply_end_date": "2026-09-30",
"reverse_charge": false,
"notes": "Faleminderit per blerjen",
"periodic_invoice": false,
"self_issue_type": "DOMESTIC",
"payment_methods": [
{
"type": "BANKNOTE",
"amount": 1200,
"company_card": "4111-2233",
"vouchers": [
"vouchers"
]
}
]
})
});
const data = await response.json();
Shembull përgjigjeje
{
"status": true,
"data": {
"invoice": {
"id": 40323,
"number": "12/2026",
"iic": "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35",
"fic": "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91",
"tcrCode": "xb131xb131",
"businessCode": "bb123bb123",
"operatorCode": "aa123aa123",
"fiscalizedAt": "2026-09-13 10:15:00",
"verifyURL": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/verify?iic=3C7E9A1F52B84D0E6A2C4F8B1D9E7A35&tin=L81306019C&crtd=2026-09-13T10:15:00+02:00&prc=53190.00",
"pdf": "https://fature.al/api/v1/invoice/print/40323",
"eic": "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65",
"payment_methods": [
{
"type": "ACCOUNT",
"amount": 540,
"company_card": "company card",
"vouchers": []
}
]
}
}
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"message": "Unauthenticated."
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"success": false,
"message": "Te dhena jo te sakta",
"errors": []
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}
{
"status": false,
"message": "Te dhenat jo te sakta.",
"errors": [
"errors"
]
}