Listo produktet më të shitura (v1): fature.al API

GET /api/v1/reports/top-products 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.

Produktet e periudhës të renditura sipas të ardhurave ose sipas sasisë së shitur, me quantity dhe revenue për secilin.

Parametri	Vlerat	Parazgjedhja
`sort`	`revenue`, `quantity`	`revenue`
`limit`	`1` deri në `200`	`20`

sort dhe limit kthehen të konfirmuara bashkë me period.

Me categories, si listë id-sh ose 1,2, raporti mbledh vetëm rreshtat e produkteve të atyre kategorive; 0 merr produktet pa kategori.

URL-ja e plotë: https://fature.al/api/v1/reports/top-products

Query parameters

Name	Tipi	E detyrueshme	Përshkrimi
from	string<date>	yes	Data e fillimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme.
to	string<date>	yes	Data e mbarimit, `YYYY-MM-DD`, e përfshirë. E detyrueshme. Kur është para `from`, të dyja ndërrohen vend.
limit	integer, min 1, max 200, nullable	no	Sa produkte të kthehen, nga 1 deri në 200.
sort	string, one of quantity, revenue, nullable	no	Renditja: `revenue` sipas të ardhurave, `quantity` sipas sasisë. Pa të merret `revenue`.
categories	array, nullable	no	Kategoritë e produkteve që merr raporti, si listë id-sh ose `1,2`; `0` merr produktet pa kategori. Pa të merren të gjitha.

Përgjigjet

200 Produktet e periudhës te `items`, nga më i shituri sipas `sort`, deri në `limit`; `items` është bosh kur periudha nuk ka shitje.

Field	Tipi	Përshkrimi
status	boolean
data	object
data.period	object	Periudha e konfirmuar e raportit
data.period.from	string	Data e fillimit, `YYYY-MM-DD`, përfshirëse
data.period.to	string	Data e mbarimit, `YYYY-MM-DD`, përfshirëse
data.sort	string	Kriteri i renditjes, i konfirmuar: `revenue` sipas të ardhurave, `quantity` sipas sasisë
data.limit	integer	Numri më i madh i produkteve që kthehen, i konfirmuar
data.items	array	Produktet, nga më i shituri, sipas `sort`
data.items[].id_product	integer, nullable	Id-ja e produktit në katalog; `null` për rreshtat e shkruar lirisht në faturë, pa produkt katalogu, që grupohen të gjithë në një rresht të vetëm
data.items[].name	string	Emri i produktit siç është shkruar në faturë; kur emri ndryshon mes faturave, kthehet njëri prej tyre
data.items[].code	string, nullable	Kodi i produktit në faturë; `null` kur rreshtat nuk mbajnë kod
data.items[].unit	string, nullable	Njësia e matjes në faturë; `null` kur rreshtat nuk mbajnë njësi
data.items[].quantity	number	Sasia e shitur gjithsej, me deri në tre shifra pas presjes
data.items[].revenue	number	Të ardhurat bruto (me TVSH) nga produkti, në lekë

401 Unauthenticated

Field	Tipi	Përshkrimi
message	string

403 Përdoruesi nuk ka të drejtën e raporteve. Një operator merr në raport vetëm faturat e veta.

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 `from` ose `to` mungon ose nuk është në formatin `YYYY-MM-DD`, ose `limit` dhe `sort` janë jashtë vlerave të lejuara. 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`

Shembull kërkese

cURL

curl -X GET 'https://fature.al/api/v1/reports/top-products?from=2026-01-01&to=2026-01-31' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Client-Id: YOUR_CLIENT_ID' \
  -H 'X-Client-Secret: YOUR_CLIENT_SECRET' \
  -H 'Accept: application/json'

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',
])->get('https://fature.al/api/v1/reports/top-products?from=2026-01-01&to=2026-01-31');

$data = $response->json();

PHP (Guzzle)

use GuzzleHttp\Client;

$client = new Client();

$response = $client->request('GET', 'https://fature.al/api/v1/reports/top-products?from=2026-01-01&to=2026-01-31', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_TOKEN',
        'X-Client-Id' => 'YOUR_CLIENT_ID',
        'X-Client-Secret' => 'YOUR_CLIENT_SECRET',
        'Accept' => 'application/json',
    ],
]);

$data = json_decode((string) $response->getBody(), true);

JavaScript

const response = await fetch('https://fature.al/api/v1/reports/top-products?from=2026-01-01&to=2026-01-31', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'X-Client-Id': 'YOUR_CLIENT_ID',
    'X-Client-Secret': 'YOUR_CLIENT_SECRET',
    'Accept': 'application/json'
  }
});

const data = await response.json();

Shembull përgjigjeje

200

{
    "status": true,
    "data": {
        "period": {
            "from": "2026-09-01",
            "to": "2026-09-13"
        },
        "sort": "revenue",
        "limit": 20,
        "items": [
            {
                "id_product": 8123,
                "name": "Kafe espresso",
                "code": "KF-001",
                "unit": "copë",
                "quantity": 1260,
                "revenue": 189000
            }
        ]
    }
}

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"
    ]
}