/api/v1/invoice/order
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.
Regjistron konsumin që ka nisur pa e mbyllur pagesën, si tavolina e një restoranti. Punon në çift me faturën përmbledhëse: porosia hap tavolinën, përmbledhësja e paguan. Lëshohet nga TCR-ja e përdoruesit, si një faturë cash.
- Mos dërgoni
payment_method: vendoset vetëORDER. - Ruani
iic-në që ju kthehet: me të mbyllet porosia tePOST /invoice/summary. - Një tavolinë mund të ketë disa porosi të hapura njëherësh.
- Zbritja mbi të gjithë faturën nuk pranohet këtu; ajo vendoset te përmbledhësja, e cila i
kopjon rreshtat nga porositë. Zbritja e rreshtit,
lines[].discount, ruhet mbi rreshtin e porosisë dhe kalon te përmbledhësja, kështu që tavolina paguan saktësisht sa tregoi porosia.
URL-ja e plotë: https://fature.al/api/v1/invoice/order
Body parameters
| Name | Tipi | E detyrueshme | Përshkrimi |
|---|---|---|---|
| internalId | string | yes | Identifikuesi i faturës në sistemin tuaj; shërben edhe si çelës idempotence. I detyrueshëm. |
| client | object, nullable | no | Blerësi. Opsional, si te fatura cash: pa të porosia 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 cilëndo fushë 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. |
| client.id | object, nullable | no | Dokumenti i identifikimit të blerësit, si objekt me `type` dhe `id`. |
| client.id.type | string, 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 porosisë, të paktën një, me të njëjtat fusha si te fatura cash. |
| 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 | yes | Norma e TVSH-së në përqindje, si te fatura cash: `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, 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`. |
| currency | string, nullable | no | Monedha e porosisë, kod ISO 4217; pa të merret ALL. |
| exchange_rate | number, nullable | no | Sa lekë vlen një njësi e monedhës së porosisë. Pa të merret 1. |
| supply_start_date | string, nullable | no | Fillimi i periudhës së furnizimit, `YYYY-MM-DD`, për porosi që mbulojnë një interval. |
| supply_end_date | string, nullable | no | Fundi i periudhës së furnizimit, `YYYY-MM-DD`. |
| notes | string, nullable | no | Shënime që shfaqen në porosi, p.sh. tavolina. |
Përgjigjet
200 Kur përdoruesi nuk ka pajisje fiskale, ose kur porosia 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.isOrderInvoice | boolean | Gjithmonë true; çelësi e shënon faturën si porosi |
| data.invoice.summaryInvoiceId | integer, nullable | Id-ja e faturës përmbledhëse që e mbylli këtë porosi. Çelësi shfaqet vetëm pasi porosia është mbyllur, ndaj një porosi e sapolëshuar nuk e mban |
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/order' \
-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": "ORD-001",
"client": {
"internal_id": 1,
"name": "Klient i rastit",
"id": {
"type": "type",
"id": "L62221018T"
},
"address": "1 Example Street",
"city": "Berlin",
"country": "US"
},
"lines": [
{
"product_name": "Kafe",
"product_code": "KAF-001",
"unit": "cope",
"quantity": 2,
"price": 1999,
"total": 4200,
"discount": 10,
"vat": 20,
"vat_exempt_type": "vat exempt type"
}
],
"currency": "ALL",
"exchange_rate": 100.5,
"supply_start_date": "2026-09-01",
"supply_end_date": "2026-09-30",
"notes": "Tavolina 4"
}'
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/order', [
'internalId' => 'ORD-001',
'client' => [
'internal_id' => 1,
'name' => 'Klient i rastit',
'id' => [
'type' => 'type',
'id' => 'L62221018T',
],
'address' => '1 Example Street',
'city' => 'Berlin',
'country' => 'US',
],
'lines' => [
[
'product_name' => 'Kafe',
'product_code' => 'KAF-001',
'unit' => 'cope',
'quantity' => 2,
'price' => 1999,
'total' => 4200,
'discount' => 10,
'vat' => 20,
'vat_exempt_type' => 'vat exempt type',
],
],
'currency' => 'ALL',
'exchange_rate' => 100.5,
'supply_start_date' => '2026-09-01',
'supply_end_date' => '2026-09-30',
'notes' => 'Tavolina 4',
]);
$data = $response->json();
use GuzzleHttp\Client;
$client = new Client();
$response = $client->request('POST', 'https://fature.al/api/v1/invoice/order', [
'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' => 'ORD-001',
'client' => [
'internal_id' => 1,
'name' => 'Klient i rastit',
'id' => [
'type' => 'type',
'id' => 'L62221018T',
],
'address' => '1 Example Street',
'city' => 'Berlin',
'country' => 'US',
],
'lines' => [
[
'product_name' => 'Kafe',
'product_code' => 'KAF-001',
'unit' => 'cope',
'quantity' => 2,
'price' => 1999,
'total' => 4200,
'discount' => 10,
'vat' => 20,
'vat_exempt_type' => 'vat exempt type',
],
],
'currency' => 'ALL',
'exchange_rate' => 100.5,
'supply_start_date' => '2026-09-01',
'supply_end_date' => '2026-09-30',
'notes' => 'Tavolina 4',
],
]);
$data = json_decode((string) $response->getBody(), true);
const response = await fetch('https://fature.al/api/v1/invoice/order', {
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": "ORD-001",
"client": {
"internal_id": 1,
"name": "Klient i rastit",
"id": {
"type": "type",
"id": "L62221018T"
},
"address": "1 Example Street",
"city": "Berlin",
"country": "US"
},
"lines": [
{
"product_name": "Kafe",
"product_code": "KAF-001",
"unit": "cope",
"quantity": 2,
"price": 1999,
"total": 4200,
"discount": 10,
"vat": 20,
"vat_exempt_type": "vat exempt type"
}
],
"currency": "ALL",
"exchange_rate": 100.5,
"supply_start_date": "2026-09-01",
"supply_end_date": "2026-09-30",
"notes": "Tavolina 4"
})
});
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",
"isOrderInvoice": true,
"summaryInvoiceId": 40330
}
}
}
{
"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"
]
}