Krijo fature me para ne dore (Cash) (v1)

POST /api/v1/invoice/cash Requires authentication Rate limited by the `api-global` limiter v1

Send a bearer token in the Authorization header.

Bleresi eshte opsional#

Pa client fatura leshohet per klientin e rastit, qe eshte rasti normal i nje arke.

Sapo dergoni qofte edhe nje te dhene te klientit, behen te nevojshme client.name, client.address dhe client.city, sepse adresa dhe qyteti shkojne ne sistemin fiskal. Adresen dhe qytetin mund t'i kete edhe klienti i ruajtur me pare ne fature.al, keshtu qe nuk ka nevoje t'i dergoni ne cdo fature. Kur mungon njera, kerkesa refuzohet me 400 dhe fusha errors thote sakte cfare duhet plotesuar.

Fusha qe varen nga menyra e pageses#

Dy fusha kerkohen vetem per nje menyre pagese, dhe ndalohen per cdo tjeter:

`payment_method`	Fusha e detyrueshme	Kufiri
`COMPANY`	`company_card`	deri ne 50 karaktere
`SVOUCHER`	`vouchers`	deri ne 20, ne formen numer-vit-NIPT, pa perseritje

Dergimi i company_card me BANKNOTE, ose i vouchers me CARD, refuzohet. Nuk ka vend ku ato te shkojne ne dokumentin fiskal, prandaj nuk pranohen ne heshtje.

Zbritja mbi faturen#

invoice_discount_type me invoice_discount_value dergohen gjithmone bashke, dhe zbresin te gjithe faturen. Nje rresht i vetem zbritet me lines[].discount, dhe te dyja mund te jene ne te njejten fature.

`invoice_discount_type`	Si lexohet `invoice_discount_value`	Kufiri
`percent`	perqindje mbi totalin me TVSH	100
`amount`	vlere me TVSH, ne monedhen e fatures	totali i fatures

Zbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total, dhe TVSH-ja rillogaritet mbi vleren e ulur, keshtu qe nje fature me disa norma TVSH-je mbetet e sakte. lines[].discount eshte perqindje mbi cmimin e njesise se atij rreshti. price mbetet cmimi i plote dhe total vjen tashme i ulur: price here quantity, me zbritjen e hequr.

Full URL: https://fature.al/api/v1/invoice/cash

Body parameters

Name	Type	Required	Description
internalId	string	yes	ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence.
client	object, nullable	no	Pa te, ose me vlere bosh, fatura leshohet per klientin e rastit.
client.internal_id	integer, nullable	no	ID e nje klienti te ruajtur ne fature.al. Kur e dergoni, klienti gjendet me te dhe fushat me poshte nuk lexohen.
client.name	string, nullable	no	I detyrueshem sapo dergoni cilendo fushe tjeter te klientit.
client.id	object, nullable	no	Dokumenti i identifikimit te bleresit, si objekt me `type` dhe `id`.
client.id.id	string, nullable	no	Numri i dokumentit te identifikimit.
client.address	string, nullable	no	Adresa e bleresit qe shkon ne fiskalizim. Nje klient i emeruar e kerkon, ose ne kete kerkese ose e ruajtur me pare ne fature.al.
client.city	string, nullable	no	Qyteti i bleresit qe shkon ne fiskalizim. Nje klient i emeruar e kerkon, ose ne kete kerkese ose e ruajtur me pare ne fature.al.
client.country	string, nullable	no	ISO 3166-1 alpha-3 country code (e.g. RKS, ALB, USA). ALB when absent.
lines	array	yes	Rreshtat e fatures.
lines[].product_name	string	yes	Emri i produktit.
lines[].product_code	string	yes	Kodi i produktit.
lines[].unit	string	yes	Njesia matese.
lines[].quantity	number	yes	Sasia.
lines[].price	number	yes	Cmimi per njesi, me TVSH.
lines[].total	number	yes	Totali i rreshtit, me TVSH.
lines[].discount	number, min 0, max 100, nullable	no	Zbritja e ketij rreshti, ne perqindje mbi cmimin e njesise. Eshte opsionale: pa te, ose me vlere bosh, rreshti kalon pikerisht si me pare dhe mungesa e saj nuk kthen kurre gabim. `price` mbetet cmimi i plote i njesise, ndersa `total` vjen tashme i ulur: `price` here `quantity`, me zbritjen e hequr. Nje `total` qe nuk perputhet me ate shifer e refuzon kerkesen me `400`, dhe `errors` tregon cili eshte rreshti dhe cila vlere pritej.
lines[].vat	integer, one of 0, 6, 10, 20	yes	Norma e TVSH-se ne perqindje: `0`, `6`, `10` ose `20`. Kur biznesi juaj nuk eshte ne skemen e TVSH-se, rreshti regjistrohet me TVSH `0` dhe me perjashtim `TAX_FREE` sido qe ta dergoni kete fushe. Kerkesa nuk refuzohet.
lines[].vat_exempt_type	string, one of TYPE_1, TYPE_2, EXPORT_OF_GOODS, TAX_FREE, nullable	no	Arsyeja e perjashtimit nga TVSH, kur rreshti eshte i perjashtuar.
invoice_discount_type	string, one of percent, amount, nullable	no	Si lexohet `invoice_discount_value`: `percent` si perqindje, `amount` si vlere fikse me TVSH. Zbritja zbatohet mbi te gjithe faturen, kurre mbi nje rresht te vetem: rreshtat ruhen ashtu si i dergoni dhe ulet vetem totali. Punon vetem ne cift me `invoice_discount_value`. Njera pa tjetren injorohet ne heshtje, dhe fatura del pa zbritje.
invoice_discount_value	number, min 0, nullable	no	Vlera e zbritjes, e lexuar sipas `invoice_discount_type`: perqindje kur tipi eshte `percent`, e kufizuar ne 100; vlere me TVSH ne monedhen e fatures kur tipi eshte `amount`, e kufizuar ne totalin e fatures. Zeroja e le faturen pa zbritje. Zbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total, dhe TVSH-ja rillogaritet mbi vleren e ulur. Detajet dhe shembujt: faqja Zbritjet ne fature.
currency	string, nullable	no	Monedha e fatures. Pa te merret ALL.
exchange_rate	number, nullable	no	Sa leke vlen nje njesi e monedhes se fatures. Pa te, ose me nje vlere jo pozitive, merret 1. Per monedha qe vlejne me pak se nje lek, si JPY ose HUF, dergoni vlere nen 1.
due_date	string, nullable	no	Afati i pageses, ne formatin `YYYY-MM-DD`.
supply_start_date	string, nullable	no	Fillimi i periudhes se furnizimit, per fatura qe mbulojne nje interval.
supply_end_date	string, nullable	no	Fundi i periudhes se furnizimit.
reverse_charge	boolean, nullable	no	Ngarkesa e kundert: TVSH-ja deklarohet nga bleresi, jo nga shitesi.
notes	string, nullable	no	Shenime qe shfaqen ne fature.
periodic_invoice	boolean, nullable	no	Shenon nje fature qe i perket nje cikli te perseritur faturimi.
self_issue_type	string, one of DOMESTIC, ABROAD, OTHER, nullable	no	Vetefaturim. Kur e dergoni, `client` eshte shitesi dhe i duhet numri i identifikimit (NUIS ose dokument) bashke me shtetin. Kur nuk e dergoni, fatura eshte e zakonshme.

Responses

201 Created

Field	Type	Description
status	boolean
data	object
data.invoice	object
data.invoice.id	integer	Fatureal invoice id. Store it next to your own internalId
data.invoice.number	string, nullable	Fiscal invoice number
data.invoice.iic	string, nullable	IIC / NSLF
data.invoice.fic	string, nullable	FIC / NIVF. Null while the invoice waits for a deferred fiscalisation
data.invoice.tcrCode	string, nullable	TCR code of the fiscal device that issued it
data.invoice.businessCode	string, nullable	Business unit code the invoice was issued under
data.invoice.operatorCode	string, nullable	Operator code the invoice was issued under
data.invoice.fiscalizedAt	string	Creation timestamp (YYYY-MM-DD HH:MM:SS)
data.invoice.verifyURL	string, nullable	Government verification URL, the one behind the QR code
data.invoice.pdf	string	Direct download URL for the document. On an e-invoice that already has an EIC this points at the official e-invoice PDF instead of ours
data.invoice.eic	string, nullable	EIC. The key is present only on an e-invoice that already has one, so treat it as absent rather than null on every other invoice

400 Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

403 Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

409 Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

422 Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.

Field	Type	Description
success	boolean	Always false
message	string	A single summary line, the same for every validation failure
errors	object	The failing fields, each with the messages for it. Dotted keys point into nested objects and array items, e.g. `lines.0.quantity`

429 Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

500 Gabim i papritur ne server.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

503 Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.

Field	Type	Description
status	boolean	Always false. A successful response carries `status: true` and a `data` object instead
message	string	The exception message. Empty when the failure carries no exception of its own
errors	array	Messages to show the operator or to log. Absent when the failure has nothing to add beyond `message`

Example request

cURL

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",
    "client": {
        "internal_id": 1,
        "name": "Klient i rastit",
        "id": {
            "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"
}'

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/v1/invoice/cash', [
    'internalId' => 'CASH-001',
    'client' => [
        'internal_id' => 1,
        'name' => 'Klient i rastit',
        'id' => [
            '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();

PHP (Guzzle)

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',
        'client' => [
            'internal_id' => 1,
            'name' => 'Klient i rastit',
            'id' => [
                '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);

JavaScript

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",
      "client": {
          "internal_id": 1,
          "name": "Klient i rastit",
          "id": {
              "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();

Example response

201

{
    "status": true,
    "data": {
        "invoice": {
            "id": 1,
            "number": "number",
            "iic": "iic",
            "fic": "fic",
            "tcrCode": "tcrCode",
            "businessCode": "businessCode",
            "operatorCode": "operatorCode",
            "fiscalizedAt": "fiscalizedAt",
            "verifyURL": "https://example.com",
            "pdf": "pdf",
            "eic": "eic"
        }
    }
}

400

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

403

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

409

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

422

{
    "success": true,
    "message": "Hello there",
    "errors": []
}

429

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

500

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}

503

{
    "status": true,
    "message": "Hello there",
    "errors": [
        "errors"
    ]
}