Lësho fletë shoqëruese (v2): fature.al API

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 e fiskalizimit, `YYYY-MM-DD HH:MM:SS`, orë lokale. Ora është gjithmonë `00:00:00`, sepse për fletët ruhet vetëm data. `null` sa kohë fleta pret fiskalizimin
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.

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.

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.

500 Gabim i papritur në server, ose CIS-i e refuzoi fletën; arsyeja është te `message`. Fleta nuk u ruajt.

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 00:00: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

example

422

example

429

example

500

example