fature.al është platforma e faturimit dhe fiskalizimit për bizneset në Shqipëri. Hap një llogari
Skip to content
fature.al API Menu

Lësho fletë shoqëruese

POST /api/v2/invoice/wtn 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.

Lëshon një fletë shoqëruese (WTN) dhe e fiskalizon te CIS-i. Fleta nuk është shitje: shoqëron mallin që lëviz nga një pikë në tjetrën, dhe ligji e kërkon edhe kur asgjë nuk shitet.

Rreshtat dërgohen si invoice_lines, jo lines si te faturat, dhe çdo rresht ka product_name, product_code, unit dhe quantity.

Fushat e detyrueshme#

  • internalId, identifikuesi i fletës në sistemin tuaj;
  • vehPlates, targa e automjetit;
  • valueOfGoods, vlera e mallit që udhëton;
  • invoice_lines, të paktën një rresht.

internalId#

Ky është ndryshimi i vetëm nga POST /api/v1/invoice/wtn, ku fusha është opsionale. Mbajeni unik brenda kompanisë për vitin: një kërkesë e dytë me të njëjtin internalId nuk lëshon fletë të dytë, kthen fletën e parë me 200. Kështu riprovimi pas një timeout-i është i sigurt, dhe fleta lexohet më vonë me GET /invoice/wtn/details/{internalId}.

Vlerat e lejuara#

Fusha Vlerat Parazgjedhja
type WTN, SALE WTN
transaction TRANSFER, EXAMINATION, SALES, DOOR TRANSFER
vehOwnership OWNER, THIRDPARTY OWNER
startPoint, destinPoint ANOTHER, CUSTOMS, EXHIBITION, OTHER, SALE, STORE, WAREHOUSE WAREHOUSE, STORE
carrier_id_type NUIS, ID NUIS

Adresat e nisjes dhe të mbërritjes (startCity, startAddr, destinCity, destinAddr) dhe transportuesi (carrier_name, carrier_id_num, carrier_town, carrier_address) merren nga njësia dhe kompania juaj kur nuk dërgohen. startDateTime dhe destinDateTime marrin kohën e lëshimit kur mungojnë.

Pas lëshimit#

Përgjigja mban id, internalId, number, iic, fic, fiscalStatus, verifyURL dhe print. Kur CIS-i nuk arrihet, fleta ruhet e pafiskalizuar, me fic: null dhe fiscalStatus: UNFISCALIZED; fiskalizimi kryhet më vonë nga paneli i fature.al, dhe gjendjen e lexoni te fiscal.status me GET /invoice/wtn/details/{internalId}. Kur CIS-i e refuzon fletën, ajo nuk ruhet dhe përgjigja është 500 me arsyen te message.

Një kërkesë e dytë nga i njëjti token, ndërsa e para nuk ka mbaruar, refuzohet menjëherë me 429. Vendi lirohet sapo kthehet përgjigja, ose pas 30 sekondash nëse kërkesa u ndërpre.

URL-ja e plotë: https://fature.al/api/v2/invoice/wtn

Ndryshuar që nga v1:

What changed v1 v2
body internalId — string, maxLength 255, required
200 data.invoice.internalId — string

Body parameters

Name Tipi E detyrueshme Përshkrimi
vehPlates string yes Targa e automjetit. E detyrueshme.
valueOfGoods number yes Vlera e mallit që udhëton, në ALL. E detyrueshme.
invoice_lines array yes Rreshtat e mallit, të paktën një.
invoice_lines[].product_name string, maxLength 255 yes Emri ose përshkrimi i mallit.
invoice_lines[].product_code string, maxLength 50 yes Kodi i mallit.
invoice_lines[].unit string, maxLength 50 yes Njësia matëse.
invoice_lines[].quantity number yes Sasia, gjithmonë më e madhe se 0.
internalId string, maxLength 255 yes Identifikuesi i fletës në sistemin tuaj, unik brenda kompanisë për vitin; shërben edhe si çelës idempotence. I detyrueshëm.
type string, one of WTN, SALE, nullable no Lloji i fletës: `WTN` për mall që lëviz pa shitje, `SALE` për mall që shoqëron një shitje. Pa të merret `WTN`.
transaction string, one of TRANSFER, EXAMINATION, SALES, DOOR, nullable no Lloji i transaksionit: `TRANSFER` zhvendosje malli, `EXAMINATION` dërgim për ekzaminim ose provë, `SALES` shitje, `DOOR` shitje derë më derë. Pa të merret `TRANSFER`.
vehOwnership string, one of OWNER, THIRDPARTY, nullable no Pronësia e automjetit: `OWNER` automjet i kompanisë, `THIRDPARTY` automjet i një pale të tretë. Pa të merret `OWNER`.
startPoint string, one of ANOTHER, CUSTOMS, EXHIBITION, OTHER, SALE, STORE, WAREHOUSE, nullable no Pika e nisjes, si lloj vendi: `WAREHOUSE` magazinë, `STORE` dyqan, `SALE` pikë shitjeje, `EXHIBITION` panair, `CUSTOMS` doganë, `ANOTHER` magazinë e një personi tjetër, `OTHER` tjetër. Pa të merret `WAREHOUSE`.
destinPoint string, one of ANOTHER, CUSTOMS, EXHIBITION, OTHER, SALE, STORE, WAREHOUSE, nullable no Pika e mbërritjes, si lloj vendi, me të njëjtat vlera si `startPoint`. Pa të merret `STORE`.
carrier_id_type string, one of NUIS, ID, nullable no Lloji i identifikuesit të transportuesit: `NUIS` për një biznes, `ID` për një person. Pa të merret `NUIS`.
startCity string, nullable no Qyteti i nisjes. Pa të merret qyteti i kompanisë.
startAddr string, nullable no Adresa e nisjes. Pa të merret adresa e njësisë së biznesit.
destinCity string, nullable no Qyteti i mbërritjes. Pa të merret qyteti i kompanisë.
destinAddr string, nullable no Adresa e mbërritjes. Pa të merret adresa e njësisë së biznesit.
carrier_id_num string, nullable no NIPT-i ose numri i dokumentit të transportuesit, sipas `carrier_id_type`. Pa të merret NIPT-i i kompanisë.
carrier_name string, nullable no Emri i transportuesit. Pa të merret emri i përdoruesit të token-it.
carrier_town string, nullable no Qyteti i transportuesit. Pa të merret qyteti i kompanisë.
carrier_address string, nullable no Adresa e transportuesit. Pa të merret adresa e njësisë së biznesit.
startDateTime string<date-time>, nullable no Data dhe ora e nisjes, `YYYY-MM-DD HH:MM`. Pa të merret çasti i lëshimit.
destinDateTime string<date-time>, nullable no Data dhe ora e mbërritjes, `YYYY-MM-DD HH:MM`. Pa të merret çasti i lëshimit.

Përgjigjet

200 Kur CIS-i nuk arrihet, fleta ruhet e pafiskalizuar: përgjigja mban `invoice` me `fic: null` dhe `fiscalStatus: UNFISCALIZED`, dhe fiskalizimi kryhet më vonë.

Field Tipi Përshkrimi
status boolean
data object
data.invoice object, nullable
data.invoice.id integer Id-ja e fletës në fature.al. Ruajeni: me të lexohen detajet dhe të dhënat për printim
data.invoice.internalId string Identifikuesi i fletës në sistemin tuaj, ai që dërguat te `internalId`
data.invoice.number string, nullable Numri i fletës, si `3/2026`: numri rendor i fletës brenda ditës për njësinë e biznesit, dhe viti
data.invoice.iic string, nullable Kodi identifikues i fletës (WTNIC, në rolin e IIC-së së faturave), 32 shifra hex. Llogaritet nga fature.al para dërgimit te CIS-i, ndaj vjen edhe kur fleta pret fiskalizimin
data.invoice.fic string, nullable Kodi që ktheu CIS-i kur e regjistroi fletën (FWTNIC, në rolin e FIC-ut); `null` sa kohë fleta pret fiskalizimin
data.invoice.tcrCode string, nullable Kodi TCR i pajisjes fiskale të përdoruesit të token-it në çastin e lëshimit
data.invoice.businessCode string, nullable Kodi i njësisë së biznesit nën të cilën u lëshua fleta
data.invoice.operatorCode string, nullable Kodi i operatorit që e lëshoi fletën
data.invoice.fiscalStatus string, nullable `FISCALIZED` kur CIS-i e regjistroi fletën, `UNFISCALIZED` kur ajo u ruajt pa u fiskalizuar
data.invoice.fiscalizedAt string, nullable Data dhe ora e fiskalizimit, `YYYY-MM-DD HH:MM:SS`, orë lokale. `null` sa kohë fleta pret fiskalizimin. Fletët e fiskalizuara para 28 shtatorit 2026 mbajnë `00:00:00`, sepse kolona ruante vetëm datën
data.invoice.verifyURL string, nullable URL-ja e verifikimit të fletës te administrata tatimore, ajo që hap kodi QR; `null` kur fleta nuk ka `iic`
data.invoice.print string URL-ja e `GET /invoice/wtn/print/{id}`, të dhënat e fletës për printim. Vjen nën të njëjtin version që e lëshoi fletën
data.message string

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`

422 Të dhënat nuk kaluan validimin, `internalId` që mungon përfshirë. Kjo përgjigje përdor fushën `success`, jo `status`, dhe `errors` është objekt sipas fushës.

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, ose CIS-i e refuzoi fletën; arsyeja është te `message`. Fleta nuk u ruajt.

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 
curl -X POST 'https://fature.al/api/v2/invoice/wtn' \
  -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 '{
    "vehPlates": "AA123BB",
    "valueOfGoods": 10000,
    "invoice_lines": [
        {
            "product_name": "Kafe",
            "product_code": "K1",
            "unit": "cope",
            "quantity": 5
        }
    ],
    "internalId": "WTN-2026-000412",
    "type": "WTN",
    "transaction": "TRANSFER",
    "vehOwnership": "OWNER",
    "startPoint": "WAREHOUSE",
    "destinPoint": "STORE",
    "carrier_id_type": "NUIS",
    "startCity": "Tirane",
    "startAddr": "Rruga X",
    "destinCity": "Durres",
    "destinAddr": "Rruga Y",
    "carrier_id_num": "L01234567A",
    "carrier_name": "Transport SHPK",
    "carrier_town": "Tirane",
    "carrier_address": "Rruga Z",
    "startDateTime": "2025-01-15 10:30",
    "destinDateTime": "2025-01-15 14:30"
}'
PHP (Laravel) 
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/wtn', [
    'vehPlates' => 'AA123BB',
    'valueOfGoods' => 10000,
    'invoice_lines' => [
        [
            'product_name' => 'Kafe',
            'product_code' => 'K1',
            'unit' => 'cope',
            'quantity' => 5,
        ],
    ],
    'internalId' => 'WTN-2026-000412',
    'type' => 'WTN',
    'transaction' => 'TRANSFER',
    'vehOwnership' => 'OWNER',
    'startPoint' => 'WAREHOUSE',
    'destinPoint' => 'STORE',
    'carrier_id_type' => 'NUIS',
    'startCity' => 'Tirane',
    'startAddr' => 'Rruga X',
    'destinCity' => 'Durres',
    'destinAddr' => 'Rruga Y',
    'carrier_id_num' => 'L01234567A',
    'carrier_name' => 'Transport SHPK',
    'carrier_town' => 'Tirane',
    'carrier_address' => 'Rruga Z',
    'startDateTime' => '2025-01-15 10:30',
    'destinDateTime' => '2025-01-15 14:30',
]);

$data = $response->json();
PHP (Guzzle) 
use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('POST', 'https://fature.al/api/v2/invoice/wtn', [
    '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' => [
        'vehPlates' => 'AA123BB',
        'valueOfGoods' => 10000,
        'invoice_lines' => [
            [
                'product_name' => 'Kafe',
                'product_code' => 'K1',
                'unit' => 'cope',
                'quantity' => 5,
            ],
        ],
        'internalId' => 'WTN-2026-000412',
        'type' => 'WTN',
        'transaction' => 'TRANSFER',
        'vehOwnership' => 'OWNER',
        'startPoint' => 'WAREHOUSE',
        'destinPoint' => 'STORE',
        'carrier_id_type' => 'NUIS',
        'startCity' => 'Tirane',
        'startAddr' => 'Rruga X',
        'destinCity' => 'Durres',
        'destinAddr' => 'Rruga Y',
        'carrier_id_num' => 'L01234567A',
        'carrier_name' => 'Transport SHPK',
        'carrier_town' => 'Tirane',
        'carrier_address' => 'Rruga Z',
        'startDateTime' => '2025-01-15 10:30',
        'destinDateTime' => '2025-01-15 14:30',
    ],
]);

$data = json_decode((string) $response->getBody(), true);
JavaScript 
const response = await fetch('https://fature.al/api/v2/invoice/wtn', {
  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({
      "vehPlates": "AA123BB",
      "valueOfGoods": 10000,
      "invoice_lines": [
          {
              "product_name": "Kafe",
              "product_code": "K1",
              "unit": "cope",
              "quantity": 5
          }
      ],
      "internalId": "WTN-2026-000412",
      "type": "WTN",
      "transaction": "TRANSFER",
      "vehOwnership": "OWNER",
      "startPoint": "WAREHOUSE",
      "destinPoint": "STORE",
      "carrier_id_type": "NUIS",
      "startCity": "Tirane",
      "startAddr": "Rruga X",
      "destinCity": "Durres",
      "destinAddr": "Rruga Y",
      "carrier_id_num": "L01234567A",
      "carrier_name": "Transport SHPK",
      "carrier_town": "Tirane",
      "carrier_address": "Rruga Z",
      "startDateTime": "2025-01-15 10:30",
      "destinDateTime": "2025-01-15 14:30"
  })
});

const data = await response.json();

Shembull përgjigjeje

200 
{
    "status": true,
    "data": {
        "invoice": {
            "id": 403,
            "internalId": "WTN-2026-000412",
            "number": "3/2026",
            "iic": "A1B2C3D4E5F60718293A4B5C6D7E8F90",
            "fic": "7f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
            "tcrCode": "cc123cc123",
            "businessCode": "bb123bb123",
            "operatorCode": "oo123oo123",
            "fiscalStatus": "FISCALIZED",
            "fiscalizedAt": "2026-09-13 10:30:00",
            "verifyURL": "https://efiskalizimi-app.tatime.gov.al/invoice-check/#/wtn?wtnic=A1B2C3D4E5F60718293A4B5C6D7E8F90&tin=L01234567A&crtd=2026-09-13T10:30:00+02:00&ord=3&bu=bb123bb123&sw=ss123ss123",
            "print": "https://fature.al/api/v1/invoice/wtn/print/403"
        },
        "message": "Hello there"
    }
}
401 
{
    "message": "Unauthenticated."
}
403 
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}
422 
{
    "success": false,
    "message": "Te dhena jo te sakta",
    "errors": []
}
429 
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}
500 
{
    "status": false,
    "message": "Te dhenat jo te sakta.",
    "errors": [
        "errors"
    ]
}

Regjistrimi është falas.

Regjistrohu në fature.al

This page as Markdown, or the whole API as OpenAPI.