/api/v1/invoice/cash
Requires authentication
Rate limited by the `api-global` limiter
v1
Send a bearer token, plus the X-Client-Id and X-Client-Secret headers in the Authorization header.
Lëshon një faturë me pagesë në çast nga pajisja fiskale (TCR) e lidhur me përdoruesin e
token-it: para në dorë, kartë, çek, kartë kompanie ose tollona. Nëse dita në arkë nuk është
hapur ende, hapet vetë me balancë 0.
Përdoruesi i token-it duhet të ketë një TCR; pa të, kërkesa refuzohet me 200 dhe
status: false.
Blerësi është opsional#
Pa client fatura lëshohet për klientin e rastit, që është rasti normal i një arke. Sapo
dërgoni qoftë edhe një të dhënë të klientit, duhen client.name, client.address dhe
client.city, sepse adresa dhe qyteti shkojnë te CIS-i. Adresën dhe qytetin mund t'i ketë
edhe klienti i ruajtur më parë në fature.al, kështu që nuk ka nevojë t'i dërgoni në çdo
faturë. Kur mungon njëra, kërkesa refuzohet me 400 dhe errors thotë saktë çfarë duhet
plotësuar.
Fusha që varen nga mënyra e pagesës#
Dy fusha kërkohen vetëm për një mënyrë pagese, dhe refuzohen për çdo tjetër:
payment_method |
Fusha e detyrueshme | Kufiri |
|---|---|---|
COMPANY |
company_card |
Deri në 50 karaktere |
SVOUCHER |
vouchers |
Deri në 20, në formën numër-vit-NIPT, pa përsëritje |
company_card me BANKNOTE, ose vouchers me CARD, refuzohen: nuk kanë vend në
dokumentin fiskal, prandaj nuk pranohen në heshtje.
Zbritja#
Zbritja mbi të gjithë faturën dërgohet me invoice_discount_type dhe invoice_discount_value
bashkë; zbritja e një rreshti me lines[].discount, si përqindje mbi çmimin e njësisë, me
price të plotë dhe total tashmë të ulur. Të dyja mund të jenë në të njëjtën faturë, dhe
rregullat e plota janë te fushat e kërkesës.
Vetëfaturimi paguhet nga arka#
Me self_issue_type fatura i paguhet shitësit me para nga arka, ndaj arka duhet të ketë të
paktën sa totali i faturës, në monedhën e faturës. Kur nuk ka, fatura nuk ruhet dhe nuk
fiskalizohet: përgjigja vjen me HTTP 200, status: false dhe një message me gjendjen e arkës
dhe shumën e faturës. Bëni një hyrje në arkë dhe dërgojeni përsëri faturën me të njëjtin
internalId.
Pas lëshimit#
Përgjigja mban iic, fic, tcrCode dhe pdf. Kur CIS-i nuk arrihet, fatura ruhet dhe
fic është null derisa fiskalizimi të përfundojë vetë.
URL-ja e plotë: https://fature.al/api/v1/invoice/cash
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. |
| payment_method | string, one of BANKNOTE, CARD, CHECK, SVOUCHER, COMPANY, ORDER | yes | Mënyra e pagesës: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` ose `ORDER`. E detyrueshme. |
| company_card | string, maxLength 50, nullable | yes | Karta e kompanisë. E detyrueshme vetëm me `COMPANY` dhe e refuzuar me çdo mënyrë tjetër pagese. Deri në 50 karaktere. Required depending on payment_method. |
| vouchers | array, nullable | yes | Numrat seriale të tollonave, në formën numër-vit-NIPT, pa përsëritje, deri në 20. Të detyrueshëm vetëm me `SVOUCHER` dhe të refuzuar me çdo mënyrë tjetër pagese. Required depending on payment_method. |
| 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. |
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 |
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/v1/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",
"payment_method": "BANKNOTE",
"company_card": "4111-2233",
"vouchers": [
"vouchers"
],
"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"
}'
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/v1/invoice/cash', [
'internalId' => 'CASH-001',
'payment_method' => 'BANKNOTE',
'company_card' => '4111-2233',
'vouchers' => [
'vouchers',
],
'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',
]);
$data = $response->json();
use GuzzleHttp\Client;
$client = new Client();
$response = $client->request('POST', 'https://fature.al/api/v1/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',
'payment_method' => 'BANKNOTE',
'company_card' => '4111-2233',
'vouchers' => [
'vouchers',
],
'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',
],
]);
$data = json_decode((string) $response->getBody(), true);
const response = await fetch('https://fature.al/api/v1/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",
"payment_method": "BANKNOTE",
"company_card": "4111-2233",
"vouchers": [
"vouchers"
],
"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"
})
});
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"
}
}
}
{
"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"
]
}