{ "openapi": "3.1.0", "info": { "title": "fature.al API", "version": "1.0", "description": "# fature.al API\n\nAPI per integrimin me fature.al - sistemi i fiskalizimit dhe faturimit per bizneset ne Shqiperi.\n\n## Identifikimi\n\nCdo kerkese ka dy nivele identifikimi: **kush** e ben (perdoruesi, me Bearer token) dhe **cili software** e ben (aplikacioni juaj, me client id dhe client secret).\n\n```\nAuthorization: Bearer {api_token}\nX-Client-Id: ft_id_...\nX-Client-Secret: ft_sk_...\n```\n\nToken-in e gjeneroni nga **Konfigurime > API Tokens** ne panelin e fature.al, ose e merrni nga pergjigja e endpoint-it Register Company. Ai i perket klientit tuaj dhe ndryshon nga njeri klient te tjetri.\n\nClient id dhe client secret i perkasin **aplikacionit tuaj**, jo klientit: jane te njejtat per te gjithe bizneset qe perdorin software-in tuaj. Shihni \"Identifikoni aplikacionin tuaj\" me poshte per menyren se si i merrni dhe si i rigjeneroni.\n\n## Serverat\n\nCdo rruge ne kete dokument eshte relative ndaj adresave me poshte, prandaj `\/invoice\/cash` do te\nthote `https:\/\/fature.al\/api\/v1\/invoice\/cash`.\n\n| Mjedisi | URL |\n|---------|-----|\n| **Live** | `https:\/\/fature.al\/api\/v1` |\n| **Sandbox\/Demo** | `https:\/\/demo.fature.al\/api\/v1` |\n\n## Dokumentet e tjera\n\nAPI-ja botohet ne tre dokumente, sepse secili ka adrese baze te vetin.\n\n| Dokumenti | Cfare mbulon | Adresa |\n|-----------|--------------|--------|\n| **v1** (ky dokument) | e gjithe API-ja e faturimit dhe e onboarding-ut | [`\/docs\/api`](\/docs\/api) |\n| **v2** | klientet ne formatin e ri me objekte te ndara | [`\/docs\/api\/v2`](\/docs\/api\/v2) |\n| **Partner** | porosite e Wolt per nje njesi te vetme | [`\/docs\/api\/partner`](\/docs\/api\/partner) |\n\nSecili dokument botohet edhe si OpenAPI JSON (`\/docs\/api.json`) dhe si Markdown per asistentet AI\n(`\/docs\/api.md`).\n\n## Postman dhe mjete te tjera\n\nNuk shperndajme koleksion Postman, sepse do te vjeteronte sa here ndryshon API. Ne vend te tij\nimportoni direkt dokumentin OpenAPI, i cili gjenerohet ne cdo kerkese dhe eshte gjithmone i\nperditesuar:\n\n**Postman** > *Import* > *Link* > `https:\/\/fature.al\/docs\/api.json`\n\nI njejti adresim vlen per Insomnia, Bruno, Swagger UI ose cdo gjenerues klientesh. Per v2 dhe per\npartner API-n perdorni `\/docs\/api\/v2.json` dhe `\/docs\/api\/partner.json`.\n\nPas importimit vendosni `Authorization: Bearer ` bashke me `X-Client-Id` dhe\n`X-Client-Secret` si variabla te koleksionit, dhe zgjidhni serverin Sandbox derisa integrimi te jete\ngati.\n\n## Seksionet kryesore\n\n- **On Boarding** - regjistrimi i kompanise, certifikata elektronike, njesite e biznesit, perdoruesit, pajisjet fiskale (TCR), llogarite bankare\n- **Invoice** - krijimi i faturave Cash, NonCash, E-Invoice, Order, Summary. Listimi, detajet, anullimi, printimi PDF\n- **Arka Fiskale** - hapja dhe mbyllja e arkes per shitje me para ne dore, hyrjet dhe daljet e parave, balanca\n- **Klienti** - kerkimi i kompanive ne regjistrin fiskal sipas NIPT, si dhe lista dhe menaxhimi i klienteve tuaj\n- **Produkte** - katalogu i produkteve dhe kategorite e tyre\n- **Llogarite bankare** - llogarite qe shfaqen ne faturat pa para ne dore dhe elektronike\n- **Monedhat** - monedhat e kompanise dhe kursi i kembimit i dites\n- **Fatura shoqeruese (WTN)** - leshimi dhe listimi i fletave shoqeruese te mallit\n- **Faturat e blerjes** - terheqja e faturave te blerjes nga fiskalizimi\n- **Reports** - permbledhja e shitjeve, TVSH, ecuria ditore, produktet dhe klientet kryesore, anullimet, arka\n- **Dashboard** - permbledhja e dites per ekranin kryesor\n\n## Rrjedha e integrimit (ne rastet kur behet onboarding e klienteve me api)\n\n1. **Regjistro kompanin\u00eb** (`POST \/register`) - merr token + branch ID\n2. **Ngarko certifikaten** (`POST \/on-boarding\/certificate`)\n3. **Konfiguro njesine e biznesit** (`POST \/on-boarding\/branch\/{id}`) - vendos businessUnitCode\n4. **Krijo pajisje fiskale** (`POST \/on-boarding\/fiscal-device`) - merr kodin TCR\n5. **Konfiguro perdoruesin** (`POST \/on-boarding\/user\/{id}`) - vendos operatorCode + fiscalTcrCode\n6. **Fillo leshimin e faturave** - perdor endpoint-et e Invoice\n\n## Formati i pergjigjes\n\nNje pergjigje e suksesshme ka gjithmone kete forme:\n```json\n{\"status\": true, \"data\": { ... }}\n```\n\nNje gabim ka kete:\n```json\n{\"status\": false, \"message\": \"Pershkrimi i gabimit\", \"errors\": [\"Mesazhi per perdoruesin\"]}\n```\n\nFusha eshte `status`, jo `success`. Fusha `errors` mungon kur gabimi nuk ka asgje per te shtuar\npertej `message`.\n\n### Perjashtimi: gabimet e validimit\n\nKur kerkesa nuk kalon validimin, pergjigja kthehet me statusin **422** dhe perdor `success` ne vend\nte `status`, sepse gjenerohet nga nje shtrese tjeter:\n```json\n{\"success\": false, \"message\": \"Te dhena te pavlefshme\", \"errors\": {\"lines.0.quantity\": [\"...\"]}}\n```\n\nKetu `errors` eshte objekt, jo varg: celesi eshte fusha qe deshtoi, me shenimin e plote drejt\nfushave te brendshme, p.sh. `lines.0.quantity` ose `client.id.type`.\n\n### Disa gabime kthehen me statusin HTTP 200\n\nNje pjese e endpoint-eve i kthejne refuzimet e tyre me statusin **200** dhe me `status: false` ne\ntrup. Ndodh te `POST \/register` (llogaria pa te drejte onboarding-u, NIPT i regjistruar tashme),\nte te gjitha endpoint-et e arkes fiskale (perdorues pa pajisje fiskale, fonde te pamjaftueshme),\nte `POST \/on-boarding\/*` dhe te listat e produkteve. Prandaj mos e lexoni `data` vetem sepse\nstatusi eshte 200: kontrolloni gjithmone `status` me pare. Ne specifikim keto endpoint-e e\ntregojne kete duke pranuar te dyja format ne pergjigjen 200.\n\n`GET \/client\/search` nuk eshte me nje prej tyre: kthen **404** kur NIPT-i nuk gjendet ne\nregjistrin fiskal dhe **503** kur regjistri nuk arrihet, qe te dallohet nje biznes qe nuk\nekziston nga nje kontroll qe nuk u krye dot.\n\n### Statusi 401 ka dy kuptime\n\nNje token i pavlefshem ose i skaduar kthen `{\"message\": \"Unauthenticated.\"}`.\n\nEndpoint-et qe varen nga nje modul (faturat, arka, fatura shoqeruese, faturat e blerjes) kthejne\ngjithashtu **401** kur moduli nuk perfshihet ne abonimin tuaj, por me zarfin standard te gabimit\ndhe me nje shpjegim ne `errors`. Dalloni midis tyre nga trupi: nje kerkese me token te sakte qe\nmerr 401 do te thote abonim, jo autentifikim, dhe rigjenerimi i token-it nuk e zgjidh.\n\n## Limitet (Rate limiting)\n\nAPI ka limit kerkesash per te mbrojtur sherbimin dhe per te garantuar performance per te gjithe perdoruesit. Kur arrihet limiti, server-i kthen statusin **HTTP 429 Too Many Requests** se bashku me header-in `Retry-After` (sekonda) qe tregon kohen e nevojshme per te ritestuar.\n\nLimitet e tabeles me poshte jane vlerat e konfiguruara. Disa prej tyre mund te jene ende ne faze\nvezhgimi, ku kalimi i tyre regjistrohet por kerkesa nuk refuzohet. Mos u mbeshtetni ne kete: ndertoni\nintegrimin qe t'i respektoje limitet dhe te trajtoje statusin 429 qe tani.\n\nLimitet jane **per perdorues** (te lidhura me API token-in tuaj), me perjashtim te limitit te pergjithshem qe eshte per IP.\n\n| Kategoria | Endpoint-et | Limit |\n|-----------|-------------|-------|\n| **I pergjithshem (per IP)** | te gjitha kerkesat e nivelit te API-t | 120\/minute |\n| **Default (per perdorues)** | te gjitha endpoint-et e mbrojtura me identifikim | 240\/minute |\n| **Fatura fiskale** | `POST \/invoice\/cash`, `\/invoice\/noncash`, `\/invoice\/e-invoice`, `\/invoice\/order`, `\/invoice\/summary`, `\/invoice\/cancel\/*`, `\/invoice\/wtn` | 30\/minute, 600\/ore |\n| **Bulk** | `POST \/invoice\/bulk-noncash` | 3\/minute, 30\/ore |\n| **Printim PDF** | `GET \/invoice\/print\/{id}`, `\/invoice\/print-eic\/{eic}`, `\/invoice\/wtn\/print\/{id}` | 30\/minute |\n| **Kerkim klientesh** | `GET \/client\/search` | 90\/minute |\n| **Onboarding** | `POST \/register`, `POST \/on-boarding\/*` | 30\/minute, 600\/ore (per perdorues) |\n| **Raporte** | `GET \/reports\/*`, `GET \/dashboard\/summary` | 30\/minute |\n| **Veprime te ndjeshme** | `POST \/account\/delete` | 5\/ore per perdorues, 20\/ore per IP |\n| **Wolt Partner API, lexim** | `GET \/api\/partner\/v1\/wolt\/*` | 180\/minute |\n| **Wolt Partner API, shkrim** | `POST \/api\/partner\/v1\/wolt\/orders\/*` | 60\/minute |\n\nKur perdorimi juaj eshte i larte ne menyre te qendrueshme dhe limitet bllokojne integrimin, na kontaktoni.\n\n### Nje kerkese ne te njejten kohe per endpoint\n\nKrahas limiteve me siper, shumica e endpoint-eve lejojne vetem **nje kerkese ne proces njekohesisht\nper perdorues**. Nje kerkese e dyte drejt te njejtit endpoint, ndersa e para nuk ka mbaruar ende,\nrefuzohet. Ky eshte kufiri qe hasin me shpesh integrimet qe punojne me shume fije njekohesisht:\nzgjidhja nuk eshte te riprovoni menjehere, por t'i radhisni kerkesat per perdorues.\n\nKy refuzim vjen me zarfin standard te gabimit. Ne varesi te endpoint-it statusi eshte **429** ose\n**200 me `status: false`**, prandaj kontrolloni gjithmone `status`.\n\n### Pergjigja kur arrihet limiti\n\n```json\n{\n \"message\": \"Too Many Attempts.\"\n}\n```\n\nHeader-at e kthyer:\n- `Retry-After: 30` - numri i sekondave para se te ritestoni\n- `X-RateLimit-Limit` - limiti maksimal per dritaren aktuale\n- `X-RateLimit-Remaining` - kerkesat e mbetura ne kete dritare\n\n## Udhezime per implementimin\n\nDisa praktika qe e bejne integrimin me te qendrueshem dhe shmangin gabimet me te shpeshta:\n\n### Identifikoni aplikacionin tuaj\n\nAplikacioni juaj identifikohet me nje cift kredencialesh qe i dergoni ne cdo kerkese, krahas token-it te perdoruesit:\n\n```\nX-Client-Id: ft_id_a1b2c3d4e5f6g7h8i9j0k1l2\nX-Client-Secret: ft_sk_...\n```\n\n- **Client id** fillon me `ft_id_` dhe eshte publik. **Client secret** fillon me `ft_sk_` dhe eshte i fshehte: trajtojeni si fjalekalim.\n- Te dyja i perkasin aplikacionit tuaj, jo klientit. Nuk gjenerohen per cdo biznes dhe nuk duhet te perfundojne ne kod qe shperndahet dhe mund te lexohet nga te tjeret.\n- Kredencialet e para i merrni nga fature.al kur regjistrohet integrimi juaj. Me pas i shihni dhe i rigjeneroni vete nga **Konfigurime > Zhvillues** ne llogarine tuaj ne fature.al, ku shihni edhe sa perdorues dhe sa biznese kane punuar permes aplikacionit tuaj ne 24 oret e fundit.\n\nSecret-i shfaqet **vetem nje here**, ne momentin qe gjenerohet, dhe nuk mund te lexohet me pas. Ruajeni menjehere.\n\nNese e humbisni ose dyshoni se eshte kompromentuar, rigjenerojeni nga i njejti ekran. **Rigjenerimi\neshte i menjehershem dhe pa periudhe mbivendosjeje:** secret-i i vjeter nderpritet ne kerkesen e\npare qe vjen pas tij. Kjo eshte e qellimshme, sepse nje secret rigjenerohet pikerisht kur ka rrjedhur,\ndhe mbajtja e tij gjalle do te mbante gjalle edhe ate qe e mori.\n\nPrandaj rendi i veprimeve ka rendesi: pergatisni instalimet tuaja qe te marrin secret-in e ri, dhe\nrigjenerojeni vetem kur jeni gati ta shperndani menjehere. Client id nuk ndryshon, keshtu qe ju\nmbetet te zevendesoni nje vlere te vetme.\n\n#### Vazhdoni te dergoni edhe header-in User-Agent\n\nKrahas kredencialeve, ne cdo kerkese dergoni header-in `User-Agent` ne formatin `\/`:\n\n```\nUser-Agent: EmriIAplikacionit\/2.4.1\n```\n\n- **Emri i aplikacionit** duhet te jete gjithmone i njejti: ne cdo kerkese, per cdo klient tuajin dhe ne cdo version te aplikacionit. Ky emer eshte identifikuesi i integrimit tuaj, prandaj mos e ndryshoni dhe mos e varioni sipas kompanise, pajisjes apo mjedisit (Live\/Sandbox). Perdorni shkronja, numra ose shenjat `_ . + -`, filloni me nje shkronje dhe mos vendosni hapesira.\n- **Versioni i build-it** ndryshon me cdo publikim te aplikacionit tuaj, p.sh. `2.4.1` ose `2026.07.13`. Pa hapesira dhe pa `\/`.\n\nKredencialet tregojne cili aplikacion po flet, ndersa User-Agent-i tregon cili version i tij eshte ne perdorim. Kjo e fundit nuk nxirret dot nga kredencialet dhe na ndihmon te reagojme me shpejt kur raportoni nje problem. Nese kredencialet mungojne, User-Agent-i mbetet e vetmja menyre per te identifikuar integrimin tuaj.\n\n#### Kalimi ne detyrim\n\nNese header-at **nuk dergohen fare**, kerkesa vazhdon normalisht dhe integrimi identifikohet vetem nga User-Agent-i. Kjo eshte periudha e kalimit. Cdo ofrues software-i njoftohet paraprakisht per daten nga e cila kredencialet behen te detyrueshme per aplikacionin e tij, dhe vetem pas asaj date kerkesat pa kredenciale refuzohen me statusin **401 Unauthorized**.\n\nNese header-at **dergohen por nuk verifikohen**, kerkesa refuzohet menjehere me **401 Unauthorized**, pa pritur asnje date. Nje client id qe nuk njihet ose nje secret i gabuar do te thote qe aplikacioni juaj nuk eshte i identifikuar, prandaj preferojme te ju njoftojme ne cast se sa ta pranojme heshtazi. Nese ende nuk i keni kredencialet, mos i dergoni header-at bosh ose me vlera provizore.\n\nPergjigja e refuzimit ndjek te njejtin format si gabimet e tjera:\n\n```json\n{\n \"status\": false,\n \"message\": \"Kjo kerkese duhet te dergoje header-at X-Client-Id dhe X-Client-Secret.\"\n}\n```\n\n| Shkaku | Refuzohet | Mesazhi |\n|--------|-----------|---------|\n| Header-at mungojne | vetem pas dates se detyrimit | Kjo kerkese duhet te dergoje header-at X-Client-Id dhe X-Client-Secret. |\n| Client id nuk njihet | gjithmone | Client ID nuk njihet. |\n| Client secret i gabuar ose mungon | gjithmone | Client secret nuk eshte i sakte. |\n| Aplikacioni eshte pezulluar | gjithmone | Ky aplikacion integrimi eshte pezulluar. |\n\nFilloni ta dergoni ciftin qe tani. Kerkesat me kredenciale te sakta punojne njesoj si me pare, prandaj nuk ka pse te pritet data e detyrimit.\n\n### Testoni ne Sandbox para Live\n\nFilloni implementimin gjithmone kundrejt `https:\/\/demo.fature.al`. Faturat e leshuara atje nuk kane vlere fiskale dhe mund te perdoren lirisht per testim. Kaloni ne `https:\/\/fature.al` vetem pasi rrjedha juaj te jete e plote dhe e provuar.\n\n### Kontrolloni gjithmone fushen `status`\n\nMos u mbeshtetni vetem ne kodin HTTP: disa refuzime kthehen me statusin 200 (shih \"Formati i\npergjigjes\"). Para se te lexoni `data`, verifikoni qe `status` eshte `true`. Ne rast gabimi,\nmesazhet vijne ne vargun `errors` dhe duhet te shfaqen ose te logohen. Vetem pergjigjet 422 te\nvalidimit e quajne kete fushe `success`, ndaj nje klient i qendrueshem i lexon te dyja.\n\n### Riprovimi dhe respektimi i limiteve\n\nKur merrni statusin **429**, prisni aq sa tregon header-i `Retry-After` para se te riprovoni dhe mos riprovoni ne menyre te vazhdueshme brenda nje cikli. Per gabimet e perkohshme te rrjetit (timeout, 5xx), perdorni riprovim me vonese progresive, p.sh. 1s, 2s, 4s.\n\n### Fusha internalId\n\n`internalId` eshte identifikuesi i fatures ne sistemin tuaj, te cilin ia kaloni fature.al-it ne cdo kerkese leshimi. Eshte fushe **e detyrueshme** (string) per te gjitha endpoint-et qe leshojne fatura: `POST \/invoice\/cash`, `\/invoice\/noncash`, `\/invoice\/e-invoice`, `\/invoice\/order`, `\/invoice\/summary` dhe `\/invoice\/bulk-noncash`.\n\n- **Vlera:** cdo identifikues unik nga sistemi juaj, p.sh. numri juaj i fatures ose nje UUID. Shembull: `CASH-001`.\n- **Uniciteti:** duhet te jete unik brenda kompanise suaj. Mbrojtja kundrejt dublikatave vepron per vitin kalendarik aktual.\n- **Roli:** sherben si celes idempotence (shih me poshte) dhe ju lejon ta gjeni me vone faturen permes `POST \/invoice\/details\/{internalId}`.\n\nNese mungon, kerkesa refuzohet me statusin **422**. fature.al nuk e kthen `internalId` ne pergjigjen e leshimit, prandaj ruani vete lidhjen mes `internalId` tuaj dhe vlerave qe kthehen (`id`, `number`, `iic`).\n\n### Te dhenat e klientit\n\nObjekti `client` percakton bleresin e fatures dhe ka tre rrjedha te ndryshme:\n\n| Rasti | Cfare dergoni | Rezultati |\n|-------|---------------|-----------|\n| **Klient i rastit** | `client` mungon, ose `client: null` | Fatura leshohet per klientin e rastit te kompanise. Vlen per `POST \/invoice\/cash` dhe `\/invoice\/noncash` |\n| **Klient i ruajtur ne fature.al** | vetem `client.internal_id` | Klienti merret nga fature.al ashtu si eshte. Fushat e tjera nuk lexohen |\n| **Klient nga sistemi juaj** | `client.name` dhe te dhenat e tjera | Klienti kerkohet me emer dhe identifikues. Nese nuk ekziston, krijohet |\n\nNe rrjedhen e trete:\n\n- **`client.name` behet i detyrueshem** sapo dergoni ndonje te dhene tjeter te klientit. Nje adrese ose nje NIPT pa emer refuzohet, sepse fatura fiskale do te mbetej pa bleresin qe pretendoni.\n- **`client.address` dhe `client.city` duhen** per cdo klient te emeruar: adresa dhe qyteti i bleresit shkojne ne kerkesen drejt sistemit fiskal, i cili nuk pranon fatura ku ato mungojne. Nuk duhet te dergohen ne cdo fature: nese klienti ekziston tashme ne fature.al me adrese e qytet, kerkesa mund te mos i permende dhe vlerat e ruajtura ruhen. Nese dergoni vetem `client.address`, qyteti i ruajtur nuk fshihet.\n- **`client.country`** eshte opsional. Pa te merret `ALB`. Per klientet jashte Shqiperise dergoni kodin ISO 3166-1 alpha-3, p.sh. `RKS` ose `ITA`.\n- **`client.id`** identifikon bleresin: `{\"type\": \"NUIS\", \"id\": \"L62221018T\"}` per bizneset shqiptare, `VAT` ose `TAX` per bizneset e huaja, `ID`, `PASS` ose `SOC` per personat. NIPT-i nuk verifikohet ne regjistrin fiskal, keshtu qe edhe njeri i panjohur per fature.al pranohet dhe ruhet si klient i re.\n\nNese mungon nje e dhene e nevojshme, kerkesa refuzohet me statusin **400** dhe fusha `errors` thote sakte cfare duhet plotesuar, p.sh. `Klientit \"Kompani Prove SHPK\" i mungon qyteti.`. Fatura dhe klienti nuk ruhen ne kete rast, prandaj mund te riprovoni me te njejtin `internalId` pasi plotesoni te dhenat.\n\n### Shmangni dyfishimin e faturave (idempotenca)\n\n`internalId` (shih fushen me siper) eshte njekohesisht celesi i idempotences. E perdorim per te mos krijuar fatura dublikate.\n\nNje timeout ose nderprerje e rrjetit gjate leshimit nuk do te thote domosdoshmerisht qe fatura deshtoi. Ajo mund te jete ruajtur ose fiskalizuar tashme ne server. Prandaj, kur riprovoni, dergoni **te njejtin `internalId`** dhe asnjehere mos gjeneroni nje te ri per riprovim. Gjenerimi i nje `internalId` te ri eshte pikerisht ajo qe krijon dublikate.\n\nKur merr nje `internalId` qe ekziston tashme per kete vit, server-i nuk krijon fature te dyte. Kthen faturen ekzistuese dhe, nese ajo ishte ruajtur por jo e fiskalizuar, perpiqet ta perfundoje fiskalizimin para se ta ktheje.\n\nNese riprovoni shume shpejt, ndersa kerkesa e pare eshte ende duke u procesuar (brenda rreth 5 minutash), mund te merrni statusin **409**. Ne kete rast prisni pak dhe riprovoni, ose verifikoni gjendjen e fatures permes `POST \/invoice\/details\/{internalId}`.\n\n### Trajtoni fiskalizimin offline\n\nKur sherbimi i Administrates Tatimore eshte i paarritshem, fatura ruhet dhe fiskalizohet automatikisht me vone. Ne kete rast fatura ekziston dhe eshte e vlefshme, por mund te mos kete ende numrin fiskal (NIVF). Mos e trajtoni si gabim dhe mos e leshoni perseri.\n\n### Ruajeni token-in te sigurt\n\nToken-i jep akses te plote ne llogarine tuaj. Ruajeni ne server, jo ne kodin e shfletuesit apo ne aplikacione publike. Mos e vendosni ne kontrollin e versioneve dhe rigjenerojeni menjehere nese dyshoni se eshte kompromentuar.\n\n### Ndiqni formatet e fushave nga specifikimi\n\nPer formatet e sakta te datave, numrave dhe fushave te detyrueshme per cdo endpoint, mbeshtetuni ne skemat e OpenAPI te `\/docs\/api.json`. Dergoni vetem fushat e dokumentuara dhe ruani tipat e tyre." }, "servers": [ { "url": "https:\/\/fature.al\/api\/v1", "description": "Live" }, { "url": "https:\/\/demo.fature.al\/api\/v1", "description": "Sandbox" } ], "tags": [ { "name": "On Boarding", "description": "Ne kete koleksion perfshihen endpoint-et qe ju lejojne te regjistroni nje kompani ne fature.al dhe te plotesoni te dhenat e nevojshme per ta bere gati per leshimin e faturave.\n\n**Workflow:**\n1. Regjistroni kompanin\u00eb (`POST \/register`).\n2. Perditesoni njesine e biznesit (branch) me `businessUnitCode`, i cili merret nga self-care dhe ruhet te njesia e biznesit.\n3. Perditesoni perdoruesin me `operatorCode`, i cili merret nga self-care.\n4. Ngarkoni certifikaten elektronike se bashku me fjalekalimin perkates, te cilin e merrni nga e-Albania.\n5. Ruani llogarite bankare qe kompania do te perdore per faturat pa para ne dore ose per faturat elektronike (eInvoice).\n\n**Nese kompania do te leshoje fatura me para ne dore:**\n6. Ruani pajisjen fiskale (fiscal device) dhe kodi i kthyer `fiscalTcrCode` duhet te ruhet te perdoruesi qe do te leshoje keto lloj faturash, nj\u00ebsoj si te pika 3.\n\n**Shtimi i perdoruesve te rinj:**\nMund te shtoni me shume perdorues nese eshte e nevojshme, por per secilin duhet te plotesohen:\n- Nje email unik, p.sh. `dicka-unike@domaini-juaj.com`\n- Pajisja fiskale, sipas pikes 6\n- Kodi i operatorit, sipas pikes 3\n\n> **Shenim:** Cdo perdorues do te operoje me `api_token`-in e vet, te cilin e merr pasi te regjistrohet.\n\n**Sandbox (vetem ne instancen DEMO):**\nPer te testuar te gjithe flow-in e onboarding-ut pa krijuar nje kompani te re, perdorni NIPT-in sandbox `L62221018T` ne thirrjen `POST \/register`. Sjellja:\n\n- Nuk krijohet kompani e re; perdoruesi dhe njesia e biznesit krijohen nen kompanine ekzistuese sandbox `L62221018T`.\n- Email-i qe dergoni shtohet me nje sufiks unik (`+sandbox-XXXXXXXX`) ne DB, keshtu qe mund ta riperseritni `POST \/register` me te njejtin email pa goditur unique-key.\n- `POST \/on-boarding\/certificate` ne DEMO kthen `success` per cdo certifikate (`.p12` ose `.pfx`) dhe cdo fjalekalim, pa e validuar fjalekalimin apo NIPT-in brenda certifikates. Data `expiresAt` qe kthehet eshte +1 vit nga sot.\n- Hapat e tjere (`branch`, `user`, `bank-account`, `fiscal-device`) ekzekutohen normalisht ne kompanine sandbox.\n\nNe `PRODUCTION` keto sjellje sandbox jane jo-aktive. NIPT `L62221018T` trajtohet si cdo NIPT tjeter." }, { "name": "Invoice" }, { "name": "Arka Fiskale" }, { "name": "Klienti" }, { "name": "Produkte" }, { "name": "Llogarit\u00eb bankare" }, { "name": "Monedhat", "description": "Mbulon list\u00ebn e monedhave t\u00eb kompanis\u00eb dhe kursin e k\u00ebmbimit ditor nga kursi.al." }, { "name": "Warehouse transfer Note (Fatura Shoqeruese)" }, { "name": "Purchase Invoice" }, { "name": "Llogaria" }, { "name": "Dashboard" }, { "name": "Reports" } ], "security": [ { "bearerAuth": [], "clientId": [], "clientSecret": [] }, { "bearerAuth": [] } ], "paths": { "\/register": { "get": { "operationId": "v1.pong", "description": "Kontrollo nese API eshte aktiv per regjistrimin e kompanive.", "summary": "Ping (Register)", "tags": [ "On Boarding" ], "responses": { "200": { "description": "Kur llogaria juaj nuk eshte e autorizuar per onboarding, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.register", "description": "Regjistron nje kompani te re ne fature.al. Kerkon token special te autorizuar nga fature.al. Kthen token API per perdoruesin e krijuar dhe ID e njesise se biznesit.\n\n**Sandbox (DEMO):** ne instancen DEMO, dergimi i NIPT-it `L62221018T` aktivizon rrjedhen sandbox: nuk krijohet kompani e re, por krijohet nje perdorues + njesi biznesi nen kompanine ekzistuese sandbox dhe ju kthehet nje `api_token` real qe e perdorni per hapat e tjere te onboarding-ut. Email-i shtohet me sufiks `+sandbox-XXXXXXXX` qe te lejojme thirrje te perseritura me te njejtin email. Ne `PRODUCTION` ky NIPT trajtohet normalisht.", "summary": "Regjistro kompani te re", "tags": [ "On Boarding" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RegisterCompanyRequest" } } } }, "responses": { "200": { "description": "Kur llogaria nuk eshte e autorizuar per onboarding, kur NIPT-i eshte i regjistruar tashme, ose kur nuk gjendet ne regjistrin fiskal, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "token": { "type": "string" }, "id": { "type": "integer" } }, "required": [ "token", "id" ] }, "branch": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "required": [ "id", "name" ] } }, "required": [ "user", "branch" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/on-boarding\/certificate": { "post": { "operationId": "v1.on-boarding.certificate", "description": "Ngarkoni certifikaten elektronike (.p12 ose .pfx) per kompanin\u00eb. Fjalekalimi duhet te jete i sakte dhe NIPT-i ne certifikate duhet te perputhet me NIPT-in e kompanise.\n\n**Sandbox (DEMO):** ne instancen DEMO ky endpoint kthen `success` per cdo certifikate dhe cdo fjalekalim. `expiresAt` qe kthehet eshte +1 vit nga sot.", "summary": "Ngarko certifikaten elektronike", "tags": [ "On Boarding" ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CertificateRequest" } } } }, "responses": { "200": { "description": "Kur fjalekalimi eshte i gabuar ose NIPT-i i certifikates nuk perputhet me kompanine, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "cert": { "type": "object", "properties": { "expiresAt": { "type": "string" } }, "required": [ "expiresAt" ] } }, "required": [ "cert" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/on-boarding\/branch": { "post": { "operationId": "v1.on-boarding.branch-create", "description": "Krijoni nje njesi biznesi te re per kompanine tuaj. Lloji jepet ne fushen `type` si enum:\n`main` per seline qendrore dhe `secondary` per nje njesi dytesore. Kompania mund te kete\nvetem nje seli qendrore, prandaj `main` refuzohet nese ajo ekziston (kodi 409).\n\nNumri i njesive varet nga abonimi. Kur limiti eshte arritur kerkesa refuzohet me kodin 403.\n\nKodi i biznesit (`businessUnitCode`) mund te dergohet me vone me `POST \/on-boarding\/branch\/{id}`,\npor eshte i domosdoshem per leshimin e faturave nga kjo njesi.", "summary": "Krijo njesi biznesi (Branch)", "tags": [ "On Boarding" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateBranchRequest" } } } }, "responses": { "200": { "description": "Kur krijimi deshton per nje arsye tjeter, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "branch": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "administrator": { "type": "string" }, "address": { "type": "string" }, "businessUnitCode": { "type": "string" } }, "required": [ "id", "name", "type", "administrator", "address", "businessUnitCode" ] } }, "required": [ "branch" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "Abonimi nuk lejon me njesi biznesi.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Kompania ka tashme nje seli qendrore.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/on-boarding\/branch\/{id}": { "post": { "operationId": "v1.on-boarding.branch", "description": "Perditesoni emrin, adresen, administratorin dhe kodin e biznesit per nje njesi biznesi ekzistuese. Kodi i biznesit (businessUnitCode) eshte i domosdshem per leshimin e faturave.", "summary": "Perditeso njesine e biznesit (Branch)", "tags": [ "On Boarding" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e njesise se biznesit.", "schema": { "type": "integer" }, "example": 12 } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "businessUnitCode": { "type": "string" }, "administrator": { "type": "string" }, "address": { "type": "string" } } } } } }, "responses": { "200": { "description": "Kur njesia nuk gjendet ose ruajtja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "branch": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "businessUnitCode": { "type": "string" } }, "required": [ "id", "name", "businessUnitCode" ] } }, "required": [ "branch" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/on-boarding\/user": { "post": { "operationId": "v1.on-boarding.user", "description": "Krijoni nje perdorues te ri per kompanin\u00eb me kodin e operatorit dhe pajisjen fiskale. Kthen token API per kete perdorues.", "summary": "Krijo perdorues te ri", "tags": [ "On Boarding" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "branchId": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string", "default": "0000" }, "fiscalTcrCode": { "type": "string" }, "operatorCode": { "type": "string" } } } } } }, "responses": { "200": { "description": "Kur email-i eshte ne perdorim, kur njesia nuk gjendet, ose kur ruajtja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "operatorCode": { "type": "string" }, "token": { "type": "string" } }, "required": [ "id", "name", "operatorCode", "token" ] } }, "required": [ "user" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/on-boarding\/user\/{id}": { "post": { "operationId": "v1.on-boarding.user-update", "description": "Perditesoni emrin, kodin e operatorit, pajisjen fiskale dhe njesine e biznesit per nje perdorues ekzistues. Kodi i operatorit eshte i domosdshem per leshimin e faturave.", "summary": "Perditeso perdoruesin", "tags": [ "On Boarding" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e perdoruesit.", "schema": { "type": "integer" }, "example": 7 } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "fiscalTcrCode": { "type": "string" }, "name": { "type": "string" }, "branchId": { "type": "string" }, "operatorCode": { "type": "string" } } } } } }, "responses": { "200": { "description": "Kur perdoruesi nuk gjendet ose ruajtja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "operatorCode": { "type": "string" } }, "required": [ "id", "name", "operatorCode" ] } }, "required": [ "user" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/on-boarding\/fiscal-device": { "post": { "operationId": "v1.on-boarding.fiscal-device", "description": "Regjistron nje pajisje fiskale te re ne sistemin e tatimeve dhe kthen kodin TCR. Ky kod perdoret per faturat me para ne dore dhe duhet te lidhet me perdoruesin perkates.", "summary": "Krijo pajisje fiskale (TCR)", "tags": [ "On Boarding" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FiscalDeviceRequest" } } } }, "responses": { "200": { "description": "Kur regjistrimi i pajisjes ne fiskalizim deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "device": { "type": "object", "properties": { "fiscalTcrCode": { "type": "string" } }, "required": [ "fiscalTcrCode" ] } }, "required": [ "device" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/on-boarding\/bank-account": { "post": { "operationId": "v1.on-boarding.bank-account", "description": "Krijoni nje llogari bankare per kompanin\u00eb. Llogaria bankare shfaqet ne faturat elektronike dhe jo-cash si informacion pagese per klientin.", "summary": "Krijo llogari bankare", "tags": [ "On Boarding" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BankAccountRequest" } } } }, "responses": { "200": { "description": "Kur ruajtja e llogarise deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "bankAccount": { "type": "object", "properties": { "id": { "type": "integer" }, "iban": { "type": "string" } }, "required": [ "id", "iban" ] } }, "required": [ "bankAccount" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/invoice": { "get": { "operationId": "invoice.invoicesList", "description": "Merrni listen e faturave me filtrim dhe faqosje.", "summary": "Lista e faturave", "tags": [ "Invoice" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i faturave per faqe.", "schema": { "type": "integer", "default": 20 }, "example": 10 }, { "name": "offset", "in": "query", "description": "Nga cila fature te fillohet.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "type", "in": "query", "description": "Filtro sipas tipit: `CASH`, `NONCASH` ose `EINVOICE`. Disa tipe ndahen me presje. Cdo vlere jashte ketyre te treve injorohet pa gabim, dhe nese asnje nuk mbetet e vlefshme, filtri nuk zbatohet fare.", "schema": { "type": "string" }, "example": "CASH,NONCASH" }, { "name": "fromDate", "in": "query", "description": "Data e fillimit (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2025-01-01" }, { "name": "toDate", "in": "query", "description": "Data e perfundimit (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2025-12-31" }, { "name": "query", "in": "query", "description": "Kerko sipas numrit te fatures, emrit te bleresit ose NIPT-it.", "schema": { "type": "string" }, "example": "K12345AB" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InvoiceListItem" } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "type": { "type": "string" }, "query": { "type": "string" } }, "required": [ "records", "limit", "offset", "type", "query" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Formati i datave nuk eshte YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/{id}\/details": { "get": { "operationId": "invoice.invoicesDetails", "description": "Merrni detajet e plota te nje fature sipas ID-se ne sistem.", "summary": "Detajet e fatures sipas ID", "tags": [ "Invoice" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures ne fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceDetail" }, { "type": "null" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/details\/{internalId}": { "post": { "operationId": "invoice.details", "description": "Merr detajet e nje fature duke perdorur ID-ne tuaj interne.", "summary": "Detajet e fatures sipas Internal ID", "tags": [ "Invoice" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "ID juaj interne, e derguar kur u krijua fatura.", "schema": { "type": "string" }, "example": "CASH-001" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "Nuk u gjet asnje fature me kete `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "422": { "description": "`internalId` eshte bosh.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/e-invoice": { "post": { "operationId": "invoice.createEInvoice", "description": "Fatura dergohet automatikisht ne sistemin qendror te e-faturave. Klienti identifikohet me NIPT.\n\nBleresi shkon i plote ne sistemin e e-faturave, prandaj adresa dhe qyteti duhen ose ne kerkese\n(`client.address`, `client.city`) ose te ruajtura me pare tek klienti ne fature.al. Kur mungon\nnje e dhene e nevojshme, kerkesa refuzohet me statusin 400 dhe fusha `errors` thote sakte cfare\nduhet plotesuar.\n\n`process` dhe `doc_type` jane te detyrueshme: i pari shkon si ProfileID ne dokumentin UBL,\ni dyti si lloji i dokumentit. Per nje fature te zakonshme shitjeje dergoni `process=P1` dhe\n`doc_type=380`; nje note krediti kerkon `process=P9` dhe `doc_type=381`.", "summary": "Krijo fature elektronike (E-Invoice)", "tags": [ "Invoice" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EInvoiceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/noncash": { "post": { "operationId": "invoice.createNonCash", "description": "Perdoret per transaksione me transferte bankare, cek, etj.\n\nKlienti identifikohet me `client.name` dhe, kur e dergoni, me `client.id`. Adresa dhe qyteti i\nbleresit shkojne ne sistemin fiskal, prandaj duhen ose ne kerkese (`client.address`,\n`client.city`) ose te ruajtura me pare tek klienti ne fature.al. Kur mungon nje e dhene e\nnevojshme, kerkesa refuzohet me statusin 400 dhe fusha `errors` thote sakte cfare duhet plotesuar.", "summary": "Krijo fature pa para ne dore (NonCash)", "tags": [ "Invoice" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/NonCashInvoiceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/cash": { "post": { "operationId": "invoice.createCash", "description": "Objekti `client` nuk eshte i detyrueshem: pa te fatura leshohet per klientin e rastit. Sapo dergoni\nndonje te dhene te klientit, behen te nevojshme `client.name`, `client.address` dhe `client.city`,\nsepse adresa dhe qyteti i bleresit shkojne ne sistemin fiskal. Adresen dhe qytetin mund t'i kete\nedhe klienti i ruajtur me pare ne fature.al, keshtu qe nuk ka nevoje t'i dergoni ne cdo fature.\nKur mungon nje e dhene e nevojshme, kerkesa refuzohet me statusin 400 dhe fusha `errors` thote\nsakte cfare duhet plotesuar.", "summary": "Krijo fature me para ne dore (Cash)", "tags": [ "Invoice" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashInvoice" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/order": { "post": { "operationId": "invoice.createOrder", "description": "Fatura regjistrohet por pagesa nuk perfundon - perdoret me summary invoice.\npayment_method vendoset automatikisht ne ORDER.", "summary": "Krijo fature porosi (Order)", "tags": [ "Invoice" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/OrderInvoice" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/summary": { "post": { "operationId": "invoice.createSummary", "description": "Perfundon pagesen e nje ose me shume faturave Order. Duhet te specifikoni IIC-te e faturave order ne fushen order_invoices.\n\nRrjeshtat merren nga faturat Order dhe nuk dergohen ne kerkese. Pergjigja i liston ato fatura\nne `settledOrderInvoices`.", "summary": "Krijo fature permbledhese (Summary)", "tags": [ "Invoice" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SummaryInvoice" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. `internalId` qe mungon kthehet me zarfin standard te gabimit.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/cancel\/{invoiceId}": { "post": { "operationId": "invoice.cancelInvoice", "description": "Anulon faturen dhe krijon regjistrim fiskal anulimi ne sistemin e tatimeve.\n\nPa body anulohet e gjithe fatura, si me pare.\n\nMe `lines` anulohet vetem nje pjese e fatures, e mundur vetem per faturat Cash. Cdo rresht i derguar\nduhet te ekzistoje ne faturen origjinale me te njejtin `product_code` dhe `product_name`, dhe sasia mund\nvetem te ulet ose te mbetet e njejte. Produktet qe nuk i dergoni mbeten te shitura. Kur i njejti produkt\neshte faturuar ne dy rreshta me cmime te ndryshme, shtoni `price` per te zgjedhur rreshtin.\n\nFatura origjinale mbetet e hapur per anulime te metejshme derisa anulimet e pjesshme ta mbulojne te\ngjithen, dhe vetem atehere shenohet si e anuluar.", "summary": "Anulo fature sipas ID", "tags": [ "Invoice" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "description": "ID e fatures ne fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CancelInvoiceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Fatura nuk mund te anulohet ne gjendjen e saj aktuale.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "Fatura nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server. Perfshin rastin kur anulimi nuk u regjistrua ne fiskalizim.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/cancel-by-internal-id\/{internalId}": { "post": { "operationId": "invoice.cancelInvoiceByInternalId", "description": "Anulon faturen duke perdorur ID-ne tuaj interne qe keni derguar kur keni krijuar faturen.\n\nPa body anulohet e gjithe fatura. Me `lines` anulohet vetem nje pjese e saj, me te njejtat rregulla\nsi tek anulimi sipas ID: vetem fatura Cash, produkt me te njejtin `product_code` dhe `product_name`,\ndhe sasi qe vetem ulet ose mbetet e njejte.", "summary": "Anulo fature sipas Internal ID", "tags": [ "Invoice" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "ID juaj interne, e derguar kur u krijua fatura.", "schema": { "type": "string" }, "example": "CASH-001" } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CancelInvoiceRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Fatura nuk mund te anulohet ne gjendjen e saj aktuale.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "Fatura nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server. Perfshin rastin kur anulimi nuk u regjistrua ne fiskalizim.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/bulk-noncash": { "post": { "operationId": "invoice.createNonCashBulk", "summary": "Krijo fatura pa para ne dore ne bllok (Bulk NonCash)", "tags": [ "Invoice" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "description": "Faturat qe do te leshohen, secila me te njejtat fusha si trupi i `POST \/invoice\/noncash`, `internalId` perfshire. Nuk ka kufi ne numrin e tyre, por endpoint-i lejon vetem 3 kerkesa ne minute, prandaj dergoni blloqe te medha ne vend te shum\u00eb te vogla.", "items": {} } }, "required": [ "invoices" ] } } } }, "responses": { "200": { "description": "Kthen nje objekt me nje hyrje per cdo `internalId`. Nje fature qe deshton mban zarfin e gabimit brenda hyrjes se vet, dhe statusi i pergjigjes mbetet 200.", "content": { "application\/json": { "schema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice\/print\/{invoiceId}": { "get": { "operationId": "v1.invoice.pdf", "description": "Kthen dokumentin e fatures. Pa parametra kthehet formati i paracaktuar per tipin e fatures: kupon termik\nper faturat Cash (sipas gjeresise 58\/80mm te konfiguruar te perdoruesi), dokument A4 per faturat NonCash\ndhe Estimate, dhe PDF-ja zyrtare e marre nga sistemi qeveritar per faturat elektronike.\n\nMe parametrin `format` merrni te njejtat versione printimi qe ofron edhe paneli i fature.al:\n\n| `format` | Tipi i fatures | Rezultati | Content-Type |\n|----------|----------------|-----------|--------------|\n| `a4` | Cash | Dokument A4 i fatures | application\/pdf |\n| `thermal` | NonCash | Kupon termik | application\/pdf |\n| `v2` | NonCash, Estimate | Dokument A4, versioni i gjere | application\/pdf |\n| `receipt` | Estimate | Kupon termik | application\/pdf |\n| `local` | EInvoice | Dokument A4 i gjeneruar nga fature.al, pa e kerkuar PDF-ne zyrtare | application\/pdf |\n| `local-thermal` | EInvoice | Kupon termik i gjeneruar nga fature.al | application\/pdf |\n| `html` | Cash | Kuponi termik si HTML, per ta derguar vete ne printer | text\/html |\n| `json` | te gjitha | Te dhenat e dokumentit ne JSON, per ta formatuar vete faturen | application\/json |\n\nParametri `lang` (`en`, `it`, `de`) e perkthen dokumentin A4 te faturave NonCash, Estimate dhe EInvoice,\ndhe kombinohet me `format`. Pa te, dokumenti kthehet shqip. Kuponat termike dhe faturat Cash mbeten\ngjithmone shqip, sepse jane dokumente fiskale.\n\nPer faturat Cash, parametri `copy_only=1` kthen kopjen e kuponit ne HTML ne vend te origjinalit.\n\nNje `format` qe nuk vlen per tipin e fatures nuk kthen gabim: kthehet formati i paracaktuar i atij tipi.", "summary": "Shkarko PDF te fatures sipas ID", "tags": [ "Invoice" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "description": "ID e fatures ne fature.al.", "schema": { "type": "integer" }, "example": 403 }, { "name": "copy_only", "in": "query", "description": "Vetem per faturat Cash: kthen kopjen e kuponit ne vend te origjinalit.", "schema": { "type": "integer" }, "example": 1 }, { "name": "format", "in": "query", "description": "Versioni i dokumentit sipas tabeles me siper: a4, thermal, v2, receipt, local, local-thermal, html, json.", "schema": { "type": "string" }, "example": "a4" }, { "name": "lang", "in": "query", "description": "Gjuha e dokumentit A4: en, it, de. Pa te dokumenti kthehet shqip.", "schema": { "type": "string" }, "example": "en" } ], "responses": { "200": { "description": "Tipi i permbajtjes varet nga `format`: PDF si parazgjedhje, `text\/html` me `format=html`, dhe dokumenti i fatures ne JSON me `format=json`, gati per ta formatuar vete.", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } }, "application\/json": { "schema": { "$ref": "#\/components\/schemas\/InvoicePrintDocument" } }, "text\/html": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "Fatura nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/invoice\/print-eic\/{eic}": { "get": { "operationId": "v1.einvoice.pdf", "description": "Kthen skedarin PDF te fatures duke perdorur kodin EIC (UUID).", "summary": "Shkarko PDF te fatures sipas EIC", "tags": [ "Invoice" ], "parameters": [ { "name": "eic", "in": "path", "required": true, "description": "Kodi EIC i fatures elektronike.", "schema": { "type": "string" }, "example": "2e9b6f31-d712-4c45-8cc0-9faf24c805a3" } ], "responses": { "200": { "description": "Kur EIC nuk gjendet, kthehet teksti `Document not found.` me statusin 200 dhe Content-Type text\/html, jo PDF. Kontrolloni Content-Type para se ta ruani si PDF.", "content": { "application\/pdf": { "schema": { "type": "string" } }, "application\/json": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/open-balance": { "post": { "operationId": "v1.cash-register.open", "description": "Hapni balancen e arkes fiskale per te filluar shitjet me para ne dore. Perdoruesi duhet te kete pajisje fiskale (TCR) te lidhur.", "summary": "Hap balancen e arkes", "tags": [ "Arka Fiskale" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "balance": { "type": "string", "default": 0 } } } } } }, "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale, kur balanca eshte negative, ose kur ruajtja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/close-balance": { "post": { "operationId": "v1.cash-register.close", "description": "Mbyllni balancen e arkes fiskale ne fund te dites. Nese arka nuk eshte e hapur, hapet automatikisht me balance 0.", "summary": "Mbyll balancen e arkes", "tags": [ "Arka Fiskale" ], "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale ose mbyllja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/deposit": { "post": { "operationId": "v1.cash-register.deposit", "description": "Bej nje hyrje parash ne arken fiskale (MONEY_IN). Kerkon qe perdoruesi te kete pajisje fiskale (TCR) te lidhur.", "summary": "Hyrje ne arke (Deposit)", "tags": [ "Arka Fiskale" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashActionRequest" } } } }, "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale ose arka nuk ka fonde te mjaftueshme, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "action_type": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "transaction_date": { "type": "string" }, "transaction_no": { "type": "integer" }, "cash_action_no": { "type": "string" }, "fiscal_status": { "type": "string" }, "fiscal_uuid": { "type": "string" }, "fiscal_fic": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "action_type", "amount", "currency", "transaction_date", "transaction_no", "cash_action_no", "fiscal_status", "fiscal_uuid", "fiscal_fic", "description" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/cash-register\/withdraw": { "post": { "operationId": "v1.cash-register.withdraw", "description": "Bej nje dalje parash nga arka fiskale (MONEY_OUT). Kerkon qe perdoruesi te kete pajisje fiskale (TCR) te lidhur.", "summary": "Dalje nga arka (Withdraw)", "tags": [ "Arka Fiskale" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashActionRequest" } } } }, "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale ose arka nuk ka fonde te mjaftueshme, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "action_type": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "transaction_date": { "type": "string" }, "transaction_no": { "type": "integer" }, "cash_action_no": { "type": "string" }, "fiscal_status": { "type": "string" }, "fiscal_uuid": { "type": "string" }, "fiscal_fic": { "type": "string" }, "description": { "type": "string" } }, "required": [ "id", "action_type", "amount", "currency", "transaction_date", "transaction_no", "cash_action_no", "fiscal_status", "fiscal_uuid", "fiscal_fic", "description" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/cash-register\/actions": { "get": { "operationId": "v1.cash-register.list", "description": "Merrni listen e veprimeve me arken fiskale (hyrje, dalje, hapje\/mbyllje dite) me filtrim dhe faqosje.", "summary": "Lista e veprimeve me arken", "tags": [ "Arka Fiskale" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i veprimeve per faqe.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Nga cili veprim te fillohet.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "type", "in": "query", "description": "Filtro sipas tipit: MONEY_IN, MONEY_OUT, OPEN_DAY, CLOSE_DAY. Disa tipe ndahen me presje.", "schema": { "type": "string" }, "example": "MONEY_IN" }, { "name": "fromDate", "in": "query", "description": "Data e fillimit (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "toDate", "in": "query", "description": "Data e perfundimit (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2026-12-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "action_type": { "type": "string" }, "amount": { "type": "number" }, "currency": { "type": "string" }, "transaction_date": { "type": "string" }, "transaction_no": { "type": "integer" }, "cash_action_no": { "type": "string" }, "fiscal_status": { "type": "string" }, "fiscal_uuid": { "type": "string" }, "fiscal_fic": { "type": "string" }, "fiscal_tcr_code": { "type": "string" }, "description": { "type": "string" }, "third_party": { "type": "string" }, "id_client": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "action_type", "amount", "currency", "transaction_date", "transaction_no", "cash_action_no", "fiscal_status", "fiscal_uuid", "fiscal_fic", "fiscal_tcr_code", "description", "third_party", "id_client", "created_at" ] } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "type": { "type": "string" } }, "required": [ "records", "limit", "offset", "type" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/balance": { "get": { "operationId": "v1.cash-register.balance", "description": "Merrni balancen aktuale ne ALL te arkes fiskale (TCR) te perdoruesit. Nese [toDate] nuk jepet, kthehet balanca e fundit.", "summary": "Balanca e arkes fiskale", "tags": [ "Arka Fiskale" ], "parameters": [ { "name": "toDate", "in": "query", "description": "Data deri te cila llogaritet balanca. Pa te kthehet balanca e fundit.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "fiscal_tcr_code": { "type": "string" }, "currency": { "type": "string" }, "to_date": { "type": "string" }, "balance": { "type": "number" } }, "required": [ "fiscal_tcr_code", "currency", "to_date", "balance" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/clients": { "get": { "operationId": "v1.clients.list", "description": "Merr listen e klienteve te kompanise me faqosje dhe filtrim me tekst.", "summary": "Lista e klienteve", "tags": [ "Klienti" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i klienteve per faqe (max 100).", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Nga cili klient te fillohet.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "query", "in": "query", "description": "Kerkim ne emer, mbiemer, NIPT, dokument, email ose telefon.", "schema": { "type": "string" }, "example": "Agon" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": "string" }, "company_name": { "type": "string" }, "company_type": { "type": "string" }, "nipt": { "type": "string" }, "first_name": { "type": "string" }, "surname": { "type": "string" }, "birthday": { "type": "string" }, "id_type": { "type": "string" }, "id_num": { "type": "string" }, "nationality_code": { "type": "string" }, "nationality_id": { "type": "string" }, "telephone": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "customer_number": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "client_type", "company_name", "company_type", "nipt", "first_name", "surname", "birthday", "id_type", "id_num", "nationality_code", "nationality_id", "telephone", "email", "address", "city", "customer_number", "created_at" ] } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "records", "total", "limit", "offset" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } }, "post": { "operationId": "v1.clients.create", "summary": "Krijo klient", "tags": [ "Klienti" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": "string" }, "company_name": { "type": "string" }, "company_type": { "type": "string" }, "nipt": { "type": "string" }, "first_name": { "type": "string" }, "surname": { "type": "string" }, "birthday": { "type": "string" }, "id_type": { "type": "string" }, "id_num": { "type": "string" }, "nationality_code": { "type": "string" }, "nationality_id": { "type": "string" }, "telephone": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "customer_number": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "client_type", "company_name", "company_type", "nipt", "first_name", "surname", "birthday", "id_type", "id_num", "nationality_code", "nationality_id", "telephone", "email", "address", "city", "customer_number", "created_at" ] } }, "required": [ "client" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Ekziston tashme nje regjistrim me te njejtat te dhena.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/clients\/{id}\/details": { "get": { "operationId": "v1.clients.details", "summary": "Detajet e klientit sipas ID", "tags": [ "Klienti" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": "string" }, "company_name": { "type": "string" }, "company_type": { "type": "string" }, "nipt": { "type": "string" }, "first_name": { "type": "string" }, "surname": { "type": "string" }, "birthday": { "type": "string" }, "id_type": { "type": "string" }, "id_num": { "type": "string" }, "nationality_code": { "type": "string" }, "nationality_id": { "type": "string" }, "telephone": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "customer_number": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "client_type", "company_name", "company_type", "nipt", "first_name", "surname", "birthday", "id_type", "id_num", "nationality_code", "nationality_id", "telephone", "email", "address", "city", "customer_number", "created_at" ] } }, "required": [ "client" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/clients\/{id}": { "put": { "operationId": "v1.clients.update", "description": "Perditeson nje klient ekzistues. Trupi i kerkeses ka te njejtin format si POST \/clients.", "summary": "Perditeso klient", "tags": [ "Klienti" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": "string" }, "company_name": { "type": "string" }, "company_type": { "type": "string" }, "nipt": { "type": "string" }, "first_name": { "type": "string" }, "surname": { "type": "string" }, "birthday": { "type": "string" }, "id_type": { "type": "string" }, "id_num": { "type": "string" }, "nationality_code": { "type": "string" }, "nationality_id": { "type": "string" }, "telephone": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "customer_number": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "client_type", "company_name", "company_type", "nipt", "first_name", "surname", "birthday", "id_type", "id_num", "nationality_code", "nationality_id", "telephone", "email", "address", "city", "customer_number", "created_at" ] } }, "required": [ "client" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Ekziston tashme nje klient me te njejtat te dhena.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/client\/search": { "get": { "operationId": "v1.client.search", "description": "Kerkoni nje kompani ne regjistrin fiskal duke perdorur NIPT\/NUIS. Kthen te dhenat e kompanise nese gjendet.", "summary": "Kerko klient sipas NIPT", "tags": [ "Klienti" ], "parameters": [ { "name": "nuis", "in": "query", "required": true, "description": "NIPT\/NUIS i kompanise per te kerkuar.", "schema": { "type": "string" }, "example": "L91806031A" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "nuis": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "integer" }, "country_code": { "type": "string" }, "verified": { "type": "boolean" } }, "required": [ "nuis", "name", "address", "city", "country", "country_code", "verified" ] } }, "required": [ "client" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "NIPT-i nuk gjendet ne regjistrin fiskal.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Regjistri fiskal nuk u arrit, keshtu qe NIPT-i mbeti i pakontrolluar. Provoni perseri.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/product\/categories": { "get": { "operationId": "products.categories", "description": "Merrni listen e kategorive te produkteve per kompanin\u00eb tuaj. Kthehen te gjitha ne nje pergjigje\nte vetme, pa faqosje.", "summary": "Lista e kategorive", "tags": [ "Produkte" ], "responses": { "200": { "description": "Kur limiti i kerkesave arrihet ose ndodh nje gabim i papritur, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" } }, "required": [ "id", "name", "color" ] } } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/products": { "get": { "operationId": "products.products", "description": "Katalogu i produkteve te kompanise. Perjashtohen produktet e fshira dhe ato qe nuk jane per\nshitje, prandaj kjo eshte lista qe mund ta perdorni per te ndertuar nje arke ose nje katalog.\n\n## Filtrat\n\nTe gjithe parametrat jane opsionale dhe kombinohen me njeri-tjetrin. Nje kerkese pa asnje\nparameter kthen te gjithe katalogun, njesoj si me pare.\n\n| Parametri | Cfare ben |\n|-----------|-----------|\n| `query` | Kerkim ne emer, kod ose pershkrim. Perputhja eshte e pjesshme dhe nuk dallon shkronjat e medha |\n| `id_category` | Vetem produktet e nje kategorie, sipas `id` nga `GET \/product\/categories` |\n| `service` | `true` kthen vetem sherbimet, `false` vetem artikujt e inventarit |\n| `limit` dhe `offset` | Faqosja. Pa `limit` kthehet i gjithe rezultati dhe `offset` nuk zbatohet |\n\n## Faqosja\n\n`data` mbetet lista e produkteve, ashtu si ka qene gjithmone. Numeruesit vijne ne `pagination`\nkrahas saj dhe jo brenda saj, qe nje program i shkruar para filtrave te vazhdoje te lexoje\n`data` si me pare, pa asnje ndryshim.\n\n`pagination.total` eshte numri i produkteve qe i pergjigjen filtrave, ndersa\n`pagination.records` eshte sa u kthyen ne kete faqe. Kur nuk dergoni `limit`, te dyja jane te\nnjejta, `pagination.limit` kthehet `null` dhe `offset` nuk merret parasysh: faqosja ka kuptim\nvetem kur i dergoni te dy bashke.\n\nPer te marre faqen e dyte me nga 50 produkte: `?limit=50&offset=50`. Vazhdoni derisa\n`offset + records` te arrije `total`.\n\n```\nGET \/products?query=kafe&id_category=3&limit=50\n```", "summary": "Lista e produkteve", "tags": [ "Produkte" ], "parameters": [ { "name": "query", "in": "query", "description": "Kerkim ne emer, kod ose pershkrim te produktit.", "schema": { "type": "string" }, "example": "kafe" }, { "name": "id_category", "in": "query", "description": "Vetem produktet e kesaj kategorie, nga GET \/product\/categories.", "schema": { "type": "integer" }, "example": 3 }, { "name": "limit", "in": "query", "description": "Sa produkte te kthehen, deri ne 500. Pa te kthehet i gjithe katalogu.", "schema": { "type": "integer" }, "example": 50 }, { "name": "offset", "in": "query", "description": "Nga cili produkt te fillohet. Zbatohet vetem bashke me `limit`.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "service", "in": "query", "description": "true kthen vetem sherbimet, false vetem artikujt e inventarit. Pa te kthehen te dyja.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "Kur limiti i kerkesave arrihet ose ndodh nje gabim i papritur, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ProductListItem" } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": [ "integer", "null" ] }, "offset": { "type": "integer" } }, "required": [ "records", "total", "limit", "offset" ] } }, "required": [ "status", "data", "pagination" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.products.create", "description": "Krijon nje produkt te ri per kompanin\u00eb tuaj. Kodi gjenerohet automatikisht nese nuk jepet. Njesia matese derivohet nga unit_code.", "summary": "Krijo produkt", "tags": [ "Produkte" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ProductRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "product": { "$ref": "#\/components\/schemas\/ProductDetail" } }, "required": [ "product" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Ekziston tashme nje regjistrim me te njejtat te dhena.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/products\/{id}\/details": { "get": { "operationId": "v1.products.details", "description": "Merrni detajet e nje produkti sipas id-se per kompanin\u00eb tuaj.", "summary": "Detajet e produktit sipas ID", "tags": [ "Produkte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e produktit.", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "product": { "$ref": "#\/components\/schemas\/ProductDetail" } }, "required": [ "product" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "Produkti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/products\/{id}": { "put": { "operationId": "v1.products.update", "description": "Perditeson nje produkt ekzistues. Trupi i kerkeses ka te njejtin format si POST \/products.", "summary": "Perditeso produkt", "tags": [ "Produkte" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e produktit.", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ProductRequest" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "product": { "$ref": "#\/components\/schemas\/ProductDetail" } }, "required": [ "product" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "Produkti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Ekziston tashme nje produkt me kete kod.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/bank-accounts": { "get": { "operationId": "v1.bank-accounts.list", "description": "Merr listen e llogarive bankare aktive te kompanise me faqosje dhe filtrim me tekst.", "summary": "Lista e llogarive bankare", "tags": [ "Llogarit\u00eb bankare" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i llogarive per faqe (max 100).", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Nga cila llogari te fillohet.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "query", "in": "query", "description": "Kerkim ne emer te bankes, IBAN, SWIFT, mbajtes ose shenime.", "schema": { "type": "string" }, "example": "Raiffeisen" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "bank_name": { "type": "string" }, "iban": { "type": "string" }, "swift": { "type": "string" }, "holder": { "type": "string" }, "currency_code": { "type": "string" }, "is_default": { "type": "boolean" }, "notes": { "type": "string" }, "valid_from": { "type": "string" }, "valid_to": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "bank_name", "iban", "swift", "holder", "currency_code", "is_default", "notes", "valid_from", "valid_to", "created_at" ] } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "records", "total", "limit", "offset" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "description": "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`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/currencies": { "get": { "operationId": "v1.currencies.list", "description": "Kthen monedhat e konfiguruara p\u00ebr kompanin\u00eb,\nme ALL gjithmon\u00eb n\u00eb fillim.", "summary": "Lista e monedhave", "tags": [ "Monedhat" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "code", "name" ] } } }, "required": [ "currencies" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/exchange-rates": { "get": { "operationId": "v1.exchange-rates", "description": "Kthen kursin e shitjes s\u00eb dit\u00ebs p\u00ebr \u00e7do monedh\u00eb, sipas burimit t\u00eb\nzgjedhur. T\u00eb dh\u00ebnat vijn\u00eb nga `https:\/\/api.kursi.al\/api\/rates` dhe\nruhen ne cache per 1h n\u00eb server; klienti mund t\u00eb mbaj\u00eb snapshot-in e fundit\nlokalisht p\u00ebr p\u00ebrdorim offline.\n\nBurimet e mb\u00ebshtetura (vlera `source` n\u00eb k\u00ebrkes\u00eb):\n - `BOA` \u2192 Banka e Shqip\u00ebris\u00eb (kursi zyrtar)\n - `BKT` \u2192 Banka Komb\u00ebtare Tregtare\n - `Iliria98` \u2192 K\u00ebmbim Valutor \"Iliria '98\"\n - `ADON` \u2192 K\u00ebmbim Valutor \"Adon\"\n\nBurim i pa percaktuar kthehet automatikisht n\u00eb `BOA`. Fusha `source` n\u00eb\np\u00ebrgjigje \u00ebsht\u00eb gjithmon\u00eb vlera e normalizuar.", "summary": "Kursi i k\u00ebmbimit", "tags": [ "Monedhat" ], "parameters": [ { "name": "source", "in": "query", "description": "Burimi i kursit: BOA, BKT, Iliria98 ose ADON.", "schema": { "type": "string", "default": "BOA" }, "example": "BOA" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "rates": { "type": "object", "additionalProperties": { "type": "number" } }, "source": { "type": "string" }, "fetchedAt": { "type": "string" } }, "required": [ "rates", "source", "fetchedAt" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice\/wtn": { "get": { "operationId": "v1.invoice.wtn.list", "description": "Merr listen e faturave shoqeruese me faqosje dhe filtrim sipas datave.", "summary": "Lista e faturave shoqeruese (WTN)", "tags": [ "Warehouse transfer Note (Fatura Shoqeruese)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i faturave per faqe.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Nga cila fature te fillohet.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "fromDate", "in": "query", "description": "Data e fillimit (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2025-01-01" }, { "name": "toDate", "in": "query", "description": "Data e perfundimit (YYYY-MM-DD).", "schema": { "type": "string" }, "example": "2025-12-31" } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "Ndodhi nje gabim, po e kontrollojme." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "422": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "Datat nuk jane ne formatin e duhur: Y-m-d." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "transaction": { "type": [ "string", "null" ] }, "issue_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "destination_date": { "type": [ "string", "null" ] }, "origin": { "type": "object", "properties": { "point": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "point", "city", "address" ] }, "destination": { "type": "object", "properties": { "point": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "point", "city", "address" ] }, "carrier": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "town": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "vehicle_ownership": { "type": [ "string", "null" ] }, "vehicle_plates": { "type": [ "string", "null" ] } }, "required": [ "name", "id_type", "id_num", "town", "address", "vehicle_ownership", "vehicle_plates" ] }, "value_of_goods": { "type": "number" }, "items_num": { "type": "integer" }, "fiscal": { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "iic": { "type": [ "string", "null" ] }, "fic": { "type": [ "string", "null" ] }, "tcr_code": { "type": [ "string", "null" ] }, "business_code": { "type": [ "string", "null" ] }, "operator_code": { "type": [ "string", "null" ] }, "fiscalized_at": { "type": [ "string", "null" ] }, "verify_url": { "type": [ "string", "null" ] } }, "required": [ "status", "iic", "fic", "tcr_code", "business_code", "operator_code", "fiscalized_at", "verify_url" ] }, "lines": { "type": "array", "items": {} }, "print": { "type": "string" } }, "required": [ "id", "number", "type", "transaction", "issue_date", "start_date", "destination_date", "origin", "destination", "carrier", "value_of_goods", "items_num", "fiscal", "lines", "print" ] } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "limit": { "type": [ "object", "null" ] }, "offset": { "type": [ "object", "null" ] } }, "required": [ "records", "limit", "offset" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "Eshte arritur numri maksimal i kerkesave te lejuara ne API." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.invoice.wtn.create", "summary": "Krijo fature shoqeruese (WTN)", "tags": [ "Warehouse transfer Note (Fatura Shoqeruese)" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WtnInvoiceRequest" } } } }, "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "503": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "iic": { "type": [ "string", "null" ] }, "fic": { "type": [ "string", "null" ] }, "tcrCode": { "type": [ "string", "null" ] }, "businessCode": { "type": [ "string", "null" ] }, "operatorCode": { "type": [ "string", "null" ] }, "fiscalStatus": { "type": [ "string", "null" ] }, "fiscalizedAt": { "type": [ "string", "null" ] }, "verifyURL": { "type": [ "string", "null" ] }, "print": { "type": "string" } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalStatus", "fiscalizedAt", "verifyURL", "print" ] }, "message": { "type": "string" } }, "required": [ "invoice", "message" ] } }, "required": [ "status", "data" ] }, { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "iic": { "type": [ "string", "null" ] }, "fic": { "type": [ "string", "null" ] }, "tcrCode": { "type": [ "string", "null" ] }, "businessCode": { "type": [ "string", "null" ] }, "operatorCode": { "type": [ "string", "null" ] }, "fiscalStatus": { "type": [ "string", "null" ] }, "fiscalizedAt": { "type": [ "string", "null" ] }, "verifyURL": { "type": [ "string", "null" ] }, "print": { "type": "string" } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalStatus", "fiscalizedAt", "verifyURL", "print" ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } ] } } } }, "403": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "Kontrolloni ne Konfigurime > Abonimi i softit per te porositur nje abonim te ri." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "429": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "Eshte arritur numri maksimal i kerkesave te lejuara ne API." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" } } } }, "\/invoice\/wtn\/{id}\/details": { "get": { "operationId": "v1.invoice.wtn.details", "summary": "Detajet e fatures shoqeruese sipas ID", "tags": [ "Warehouse transfer Note (Fatura Shoqeruese)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures shoqeruese ne fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string", "const": "Ndodhi nje gabim, po e kontrollojme." } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "transaction": { "type": [ "string", "null" ] }, "issue_date": { "type": [ "string", "null" ] }, "start_date": { "type": [ "string", "null" ] }, "destination_date": { "type": [ "string", "null" ] }, "origin": { "type": "object", "properties": { "point": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "point", "city", "address" ] }, "destination": { "type": "object", "properties": { "point": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } }, "required": [ "point", "city", "address" ] }, "carrier": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "town": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "vehicle_ownership": { "type": [ "string", "null" ] }, "vehicle_plates": { "type": [ "string", "null" ] } }, "required": [ "name", "id_type", "id_num", "town", "address", "vehicle_ownership", "vehicle_plates" ] }, "value_of_goods": { "type": "number" }, "items_num": { "type": "integer" }, "fiscal": { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "iic": { "type": [ "string", "null" ] }, "fic": { "type": [ "string", "null" ] }, "tcr_code": { "type": [ "string", "null" ] }, "business_code": { "type": [ "string", "null" ] }, "operator_code": { "type": [ "string", "null" ] }, "fiscalized_at": { "type": [ "string", "null" ] }, "verify_url": { "type": [ "string", "null" ] } }, "required": [ "status", "iic", "fic", "tcr_code", "business_code", "operator_code", "fiscalized_at", "verify_url" ] }, "lines": { "type": "array", "items": {} }, "print": { "type": "string" } }, "required": [ "id", "number", "type", "transaction", "issue_date", "start_date", "destination_date", "origin", "destination", "carrier", "value_of_goods", "items_num", "fiscal", "lines", "print" ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice\/wtn\/print\/{invoiceId}": { "get": { "operationId": "v1.invoice.wtn.print", "description": "Kthen nje strukture JSON me te gjitha te dhenat per nje \"print view\".", "summary": "Te dhenat e fatures shoqeruese ne format printimi (JSON)", "tags": [ "Warehouse transfer Note (Fatura Shoqeruese)" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "description": "ID e fatures shoqeruese ne fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "logo": { "type": [ "string", "null" ] }, "title": { "type": "string", "const": "Fatur\u00eb Shoq\u00ebruese" }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "nuis": { "type": "string" }, "address": { "type": "string" } }, "required": [ "name", "nuis", "address" ] }, "carrier": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "idType": { "type": [ "string", "null" ] }, "idNum": { "type": [ "string", "null" ] }, "town": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "vehicleOwnership": { "type": [ "string", "null" ] }, "vehiclePlates": { "type": [ "string", "null" ] } }, "required": [ "name", "idType", "idNum", "town", "address", "vehicleOwnership", "vehiclePlates" ] }, "origin": { "type": "object", "properties": { "point": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "dateTime": { "type": [ "string", "null" ] } }, "required": [ "point", "city", "address", "dateTime" ] }, "destination": { "type": "object", "properties": { "point": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "dateTime": { "type": [ "string", "null" ] } }, "required": [ "point", "city", "address", "dateTime" ] }, "invoice": { "type": "object", "properties": { "issueDate": { "type": [ "string", "null" ] }, "businessCode": { "type": [ "string", "null" ] }, "operatorCode": { "type": [ "string", "null" ] }, "deviceCode": { "type": [ "string", "null" ] }, "number": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "transaction": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ] } }, "required": [ "name", "code", "unit", "quantity" ] } }, "amounts": { "type": "object", "properties": { "valueOfGoods": { "type": "number" }, "currency": { "type": "string", "const": "ALL" }, "itemsNum": { "type": "integer" } }, "required": [ "valueOfGoods", "currency", "itemsNum" ] }, "iic": { "type": [ "string", "null" ] }, "fic": { "type": [ "string", "null" ] }, "fiscalStatus": { "type": [ "string", "null" ] }, "verifyUrl": { "type": [ "string", "null" ] }, "footer": { "type": "array", "items": { "type": "string" } } }, "required": [ "issueDate", "businessCode", "operatorCode", "deviceCode", "number", "type", "transaction", "lines", "amounts", "iic", "fic", "fiscalStatus", "verifyUrl", "footer" ] } }, "required": [ "logo", "title", "company", "carrier", "origin", "destination", "invoice" ] } }, "required": [ "status", "data" ] } } } }, "404": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "" ] } ] }, "errors": { "type": "array", "prefixItems": [ { "type": "string" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "status", "message", "errors" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/purchase-invoices": { "get": { "operationId": "v1.purchase-invoices.list", "description": "Merrni faturat e blerjes nga fiskalizimi. Per cdo fature terhiqen te dhenat\ne plota (artikujt, shitesi, bleresi, menyrat e pageses).", "summary": "Lista e faturave te blerjes", "tags": [ "Purchase Invoice" ], "parameters": [ { "name": "page", "in": "query", "description": "Faqja e listes nga fiskalizimi. Perserit me page+1 derisa items te kthehet bosh.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "fromDate", "in": "query", "description": "Data e fillimit (YYYY-MM-DD). Pa te merret sot.", "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "toDate", "in": "query", "description": "Data e perfundimit (YYYY-MM-DD). Pa te merret sot.", "schema": { "type": "string" }, "example": "2026-07-15" }, { "name": "fic", "in": "query", "description": "Filtro sipas FIC per nje fature te vetme.", "schema": { "type": "string" }, "example": "8a941d47-7d47-4b7e-8f3a-1c2d3e4f5a6b" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "iic": { "type": "string" }, "fic": { "type": "string" }, "invoiceNumber": { "type": "string" }, "invoiceOrderNumber": { "type": "integer" }, "dateTimeCreated": { "type": "string" }, "payDeadline": { "type": "string" }, "invoiceType": { "type": "string" }, "issuerTaxNumber": { "type": "string" }, "seller": { "type": "object", "properties": { "idType": { "type": "string" }, "idNum": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "town": { "type": "string" }, "country": { "type": "string" } }, "required": [ "idType", "idNum", "name", "address", "town", "country" ] }, "buyer": { "type": "object", "properties": { "idType": { "type": "string" }, "idNum": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "string" }, "town": { "type": "string" }, "country": { "type": "string" } }, "required": [ "idType", "idNum", "name", "address", "town", "country" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" }, "unitPriceAfterVat": { "type": "number" }, "priceAfterVat": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": "string" }, "exemptFromVat": { "type": "string" } }, "required": [ "name", "code", "unit", "quantity", "unitPriceAfterVat", "priceAfterVat", "vatAmount", "vatRate", "exemptFromVat" ] } }, "paymentMethod": { "type": "array", "items": { "type": "object", "properties": { "typeCode": { "type": "string" }, "compCard": { "type": "string" } }, "required": [ "typeCode", "compCard" ] } }, "currency": { "type": "string" }, "totalPrice": { "type": "number" }, "totalPriceWithoutVAT": { "type": "number" }, "reverseCharge": { "type": "boolean" }, "businessUnit": { "type": "string" }, "operatorCode": { "type": "string" }, "tcrCode": { "type": "string" }, "softwareCode": { "type": "string" }, "iicSignature": { "type": "string" } }, "required": [ "iic", "fic", "invoiceNumber", "invoiceOrderNumber", "dateTimeCreated", "payDeadline", "invoiceType", "issuerTaxNumber", "seller", "buyer", "items", "paymentMethod", "currency", "totalPrice", "totalPriceWithoutVAT", "reverseCharge", "businessUnit", "operatorCode", "tcrCode", "softwareCode", "iicSignature" ] } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "page": { "type": "integer" } }, "required": [ "records", "page" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Formati i datave nuk eshte YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "502": { "description": "Fiskalizimi u pergjigj me nje gabim.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/account": { "get": { "operationId": "account.index", "description": "Kthen te dhenat e perdoruesit te autentifikuar: emri, email, kodi fiskal dhe kompania.", "summary": "Te dhenat e llogarise", "tags": [ "Llogaria" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "fiscalCode": { "type": "string" }, "company": { "type": "string" }, "nipt": { "type": "string" }, "setupFinished": { "type": "boolean" }, "branch": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" } }, "required": [ "name", "address", "city" ] }, "companyBranches": { "type": "string" }, "permissions": { "type": "object", "properties": { "createArticles": { "type": "boolean" }, "createClients": { "type": "boolean" } }, "required": [ "createArticles", "createClients" ] }, "configs": { "type": "object", "properties": { "openDayAlways0": { "type": "string" } }, "required": [ "openDayAlways0" ] }, "vatConfigs": { "type": "object", "properties": { "issuerInVat": { "type": "string" }, "vat_rates": { "anyOf": [ { "type": "array", "prefixItems": [ { "type": "integer", "const": 20 }, { "type": "integer", "const": 10 }, { "type": "integer", "const": 6 }, { "type": "integer" } ], "minItems": 4, "maxItems": 4, "additionalItems": false }, { "type": "array", "prefixItems": [ { "type": "integer" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } ] }, "vat_exempts": { "type": "array", "items": {} } }, "required": [ "issuerInVat", "vat_rates", "vat_exempts" ] }, "subscription": { "type": "object", "properties": { "cash": { "type": "string" }, "noncash": { "type": "string" }, "einvoice": { "type": "string" }, "wtn": { "type": "string" } }, "required": [ "cash", "noncash", "einvoice", "wtn" ] } }, "required": [ "name", "email", "fiscalCode", "company", "nipt", "setupFinished", "branch", "companyBranches", "permissions", "configs", "vatConfigs", "subscription" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/dashboard\/summary": { "get": { "operationId": "v1.dashboard.summary", "description": "Nje pamje e shpejte e dites se sotme per ekranin kryesor: turni i hapur nese ka nje te tille,\nshitjet e sotme dhe ato te dje per krahasim, gjendja e arkes dhe faturat e fundit. Pergjigja\nruhet ne cache per pak sekonda, prandaj nuk eshte burim per rakordim.", "summary": "Permbledhja e dites", "tags": [ "Dashboard" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "shift": { "anyOf": [ { "type": "object", "properties": { "is_open": { "type": "string" }, "opened_at": { "type": "string" }, "cash_in_drawer": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "is_open", "opened_at", "cash_in_drawer", "currency" ] }, { "type": "object", "properties": { "is_open": { "type": "boolean" }, "opened_at": { "type": "null" }, "cash_in_drawer": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "is_open", "opened_at", "cash_in_drawer", "currency" ] } ] }, "today": { "type": "object", "properties": { "invoice_count": { "type": "integer" }, "gross_total": { "type": "number" }, "hourly_series": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "hour", "gross" ] } } }, "required": [ "invoice_count", "gross_total", "hourly_series" ] }, "week": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "gross": { "type": "number" } }, "required": [ "date", "gross" ] } }, "wow_delta_percent": { "type": "number" } }, "required": [ "series", "wow_delta_percent" ] } }, "required": [ "shift", "today", "week" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "description": "Kufiri i kerkesave u arrit: 30 kerkesa ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/sales-summary": { "get": { "operationId": "v1.reports.sales-summary", "description": "Totalet e shitjeve per nje periudhe, te ndara sipas menyres se pageses, tipit te fatures, \nshkalles se TVSH dhe dites. Perfshin edhe sa fatura u anulluan. Vlerat jane ne ALL.", "summary": "Permbledhje e shitjeve", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "type": "object", "properties": { "invoices": { "type": "integer" }, "gross": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "avg_invoice": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "invoices", "gross", "net", "vat", "avg_invoice", "currency" ] }, "by_payment_method": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "count": { "type": "integer" }, "gross": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" } }, "required": [ "method", "count", "gross", "net", "vat" ] } }, "by_type": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "type", "count", "gross" ] } }, "by_vat_rate": { "type": "array", "items": { "type": "object", "properties": { "rate": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } }, "required": [ "rate", "net", "vat", "gross" ] } }, "by_day": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "count": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "date", "count", "gross" ] } }, "cancelled": { "type": "object", "properties": { "count": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "count", "gross" ] } }, "required": [ "period", "totals", "by_payment_method", "by_type", "by_vat_rate", "by_day", "cancelled" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/top-products": { "get": { "operationId": "v1.reports.top-products", "description": "Produktet e renditura sipas te ardhurave ose sipas sasise se shitur.", "summary": "Produktet me te shitura", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "limit", "in": "query", "description": "Sa produkte te kthehen, deri ne 200.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "example": 20 }, { "name": "sort", "in": "query", "description": "Renditja: sipas te ardhurave ose sipas sasise. Pa te merret `revenue`.", "schema": { "type": [ "string", "null" ], "enum": [ "quantity", "revenue" ] }, "example": "revenue" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "sort": { "type": "string" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id_product": { "type": "string" }, "name": { "type": "string" }, "code": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" }, "revenue": { "type": "number" } }, "required": [ "id_product", "name", "code", "unit", "quantity", "revenue" ] } } }, "required": [ "period", "sort", "limit", "items" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/top-clients": { "get": { "operationId": "v1.reports.top-clients", "description": "Klientet e renditura sipas vleres se faturuar ne periudhe.", "summary": "Klientet kryesore", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "limit", "in": "query", "description": "Sa rreshta te kthehen, deri ne 500.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "example": 20 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id_client": { "type": "string" }, "name": { "type": "string" }, "nipt": { "type": "string" }, "invoices": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "id_client", "name", "nipt", "invoices", "gross" ] } } }, "required": [ "period", "limit", "items" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/vat": { "get": { "operationId": "v1.reports.vat", "description": "TVSH e mbledhur nga shitjet dhe ajo e paguar ne blerje, me diferencen qe rezulton. Rreshtat \nndahen ne te tatueshem sipas shkalles dhe te perjashtuar sipas llojit te perjashtimit.", "summary": "Raporti i TVSH", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "type": "object", "properties": { "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "net", "vat", "gross", "currency" ] }, "taxable": { "type": "array", "items": { "type": "object", "properties": { "rate": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } }, "required": [ "rate", "net", "vat", "gross" ] } }, "exempt": { "type": "array", "items": { "type": "object", "properties": { "exempt_type": { "type": "string" }, "rate": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } }, "required": [ "exempt_type", "rate", "net", "vat", "gross" ] } }, "purchases": { "type": "object", "properties": { "taxable": { "type": "array", "items": { "type": "object", "properties": { "rate": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } }, "required": [ "rate", "net", "vat", "gross" ] } }, "exempt": { "type": "array", "items": { "type": "object", "properties": { "exempt_type": { "type": "string" }, "rate": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" } }, "required": [ "exempt_type", "rate", "net", "vat", "gross" ] } }, "totals": { "type": "object", "properties": { "net": { "type": "number" }, "vat": { "type": "number" }, "gross": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "net", "vat", "gross", "currency" ] } }, "required": [ "taxable", "exempt", "totals" ] }, "summary": { "type": "object", "properties": { "output_vat": { "type": "number" }, "input_vat": { "type": "number" }, "vat_due": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "output_vat", "input_vat", "vat_due", "currency" ] } }, "required": [ "period", "totals", "taxable", "exempt", "purchases", "summary" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/daily-trend": { "get": { "operationId": "v1.reports.daily-trend", "description": "Nje pike per cdo dite te periudhes, qofte si vlere bruto qofte si numer faturash, sipas \n`metric`.", "summary": "Ecuria ditore", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "metric", "in": "query", "description": "Cfare mat seria: vlera bruto apo numri i faturave. Pa te merret `gross`.", "schema": { "type": [ "string", "null" ], "enum": [ "gross", "count" ] }, "example": "gross" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "metric": { "type": "string" }, "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "count": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "date", "count", "gross" ] } } }, "required": [ "period", "metric", "series" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/by-operator": { "get": { "operationId": "v1.reports.by-operator", "description": "Sa fatura leshoi dhe sa vlere beri secili operator ne periudhe.", "summary": "Shitjet sipas operatorit", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id_user": { "type": "string" }, "name": { "type": "string" }, "operator_code": { "type": "string" }, "invoices": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "id_user", "name", "operator_code", "invoices", "gross" ] } } }, "required": [ "period", "items" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/by-tcr": { "get": { "operationId": "v1.reports.by-tcr", "description": "Sa fatura leshoi dhe sa vlere beri secila pajisje fiskale (TCR) ne periudhe.", "summary": "Shitjet sipas pajisjes fiskale", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "items": { "type": "array", "items": { "type": "object", "properties": { "tcr_code": { "type": "string" }, "invoices": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "tcr_code", "invoices", "gross" ] } } }, "required": [ "period", "items" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/reversals": { "get": { "operationId": "v1.reports.reversals", "description": "Faturat e anulluara ne periudhe, me faturen origjinale qe secila korrigjon.", "summary": "Faturat e anulluara", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "limit", "in": "query", "description": "Sa rreshta te kthehen, deri ne 500.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "example": 20 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "type": "object", "properties": { "count": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "count", "gross" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "type": { "type": "string" }, "reversed_at": { "type": "string" }, "original_invoice_id": { "type": "string" }, "gross": { "type": "number" }, "operator": { "type": "string" } }, "required": [ "id", "number", "type", "reversed_at", "original_invoice_id", "gross", "operator" ] } } }, "required": [ "period", "totals", "items" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/wtn": { "get": { "operationId": "v1.reports.wtn", "description": "Fletet shoqeruese te periudhes, te grupuara sipas gjendjes fiskale, me destinacionet e \nperdorura.", "summary": "Raporti i faturave shoqeruese", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "period": { "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "type": "object", "properties": { "count": { "type": "integer" }, "value_of_goods": { "type": "number" } }, "required": [ "count", "value_of_goods" ] }, "by_status": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "count": { "type": "integer" }, "value_of_goods": { "type": "number" } }, "required": [ "status", "count", "value_of_goods" ] } }, "unique_destinations": { "type": "integer" }, "destinations": { "type": "array", "items": { "type": "string" } } }, "required": [ "period", "totals", "by_status", "unique_destinations", "destinations" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } } } } }, "\/reports\/cash-register": { "get": { "operationId": "v1.reports.cash-register", "description": "Hapja, mbyllja dhe mbyllja e pritur e arkes fiskale per nje dite, me shitjet sipas menyres se \npageses dhe levizjet e parave. Pa `date` merret dita e sotme.", "summary": "Gjendja e arkes per nje dite", "tags": [ "Reports" ], "parameters": [ { "name": "date", "in": "query", "description": "Dita e raportit. Pa te merret sot.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "date": { "type": "string" }, "currency": { "type": "string" }, "opening": { "type": "number" }, "closing": { "type": "number" }, "expected_closing": { "type": "number" }, "tcr": { "type": "string" }, "operator": { "type": "string" }, "sales_by_method": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "gross": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" } }, "required": [ "method", "label", "count", "gross", "net", "vat" ] } }, "movements": { "type": "object", "properties": { "deposits_count": { "type": "integer" }, "deposits_total": { "type": "number" }, "withdrawals_count": { "type": "integer" }, "withdrawals_total": { "type": "number" } }, "required": [ "deposits_count", "deposits_total", "withdrawals_count", "withdrawals_total" ] } }, "required": [ "date", "currency", "opening", "closing", "expected_closing", "tcr", "operator", "sales_by_method", "movements" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/reports\/cash-register\/closing": { "get": { "operationId": "v1.reports.cash-register.closing", "description": "Raporti i fundit i dites: totalet e shitjeve, produktet e shitura dhe levizjet e parave per \nturnin qe u mbyll. Pa `date` merret dita e sotme.", "summary": "Raporti i mbylljes se arkes", "tags": [ "Reports" ], "parameters": [ { "name": "date", "in": "query", "description": "Dita e raportit. Pa te merret sot.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "date": { "type": "string" }, "currency": { "type": "string" }, "opening": { "type": "number" }, "closing": { "type": "number" }, "closing_total": { "type": "number" }, "expected_closing": { "type": "number" }, "opened_at": { "type": "string" }, "closed_at": { "type": "string" }, "tcr": { "type": "string" }, "operator": { "type": "string" }, "sales": { "type": "object", "properties": { "invoice_count": { "type": "integer" }, "gross_total": { "type": "number" }, "net_total": { "type": "number" }, "vat_total": { "type": "number" } }, "required": [ "invoice_count", "gross_total", "net_total", "vat_total" ] }, "sales_by_method": { "type": "array", "items": { "type": "object", "properties": { "method": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "integer" }, "gross": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" } }, "required": [ "method", "label", "count", "gross", "net", "vat" ] } }, "products_sold": { "type": "array", "items": { "type": "object", "properties": { "product_name": { "type": "string" }, "product_code": { "type": "string" }, "quantity": { "type": "number" }, "unit": { "type": "string" }, "unit_price": { "type": "number" }, "gross": { "type": "number" } }, "required": [ "product_name", "product_code", "quantity", "unit", "unit_price", "gross" ] } }, "movements": { "type": "object", "properties": { "deposits_count": { "type": "integer" }, "deposits_total": { "type": "number" }, "withdrawals_count": { "type": "integer" }, "withdrawals_total": { "type": "number" } }, "required": [ "deposits_count", "deposits_total", "withdrawals_count", "withdrawals_total" ] } }, "required": [ "date", "currency", "opening", "closing", "closing_total", "expected_closing", "opened_at", "closed_at", "tcr", "operator", "sales", "sales_by_method", "products_sold", "movements" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/ping": { "get": { "operationId": "ping.pong", "description": "Kontrollo nese API eshte aktiv. Kthen timestamp dhe IP.", "summary": "Ping", "tags": [ "Ping" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "pong": { "type": "integer" }, "ip": { "type": "array", "items": { "type": "string" } } }, "required": [ "pong", "ip" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Token-i i perdoruesit, nga Konfigurime > API Tokens.", "scheme": "bearer" }, "clientId": { "type": "apiKey", "description": "Client id i aplikacionit tuaj, fillon me ft_id_", "in": "header", "name": "X-Client-Id" }, "clientSecret": { "type": "apiKey", "description": "Client secret i aplikacionit tuaj, fillon me ft_sk_", "in": "header", "name": "X-Client-Secret" } }, "schemas": { "ApiError": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false. A successful response carries `status: true` and a `data` object instead." }, "message": { "type": "string", "description": "The exception message. Empty when the failure carries no exception of its own." }, "errors": { "type": "array", "description": "Messages to show the operator or to log. Absent when the failure has\nnothing to add beyond `message`.", "items": { "type": "string" } } }, "required": [ "status", "message", "errors" ], "title": "ApiError" }, "ApiValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always false." }, "message": { "type": "string", "description": "A single summary line, the same for every validation failure." }, "errors": { "type": "object", "description": "The failing fields, each with the messages for it. Dotted keys point into\nnested objects and array items, e.g. `lines.0.quantity`.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "success", "message", "errors" ], "title": "ApiValidationError" }, "BankAccount": { "type": "object", "properties": { "id": { "type": "integer" }, "bank_name": { "type": [ "string", "null" ] }, "id_bank": { "type": [ "integer", "null" ] }, "iban": { "type": [ "string", "null" ] }, "swift": { "type": [ "string", "null" ] }, "id_currency": { "type": [ "integer", "null" ] }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "status": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "id_company": { "type": [ "integer", "null" ] }, "default": { "type": "integer" }, "maintenance_monthly_costs": { "type": "number" }, "holder": { "type": [ "string", "null" ] } }, "required": [ "id", "bank_name", "id_bank", "iban", "swift", "id_currency", "valid_from", "valid_to", "notes", "status", "created_at", "updated_at", "id_company", "default", "maintenance_monthly_costs", "holder" ], "title": "BankAccount" }, "BankAccountRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "holder": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "swift": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "title": "BankAccountRequest" }, "CancelInvoiceRequest": { "type": "object", "properties": { "lines": { "type": "array", "description": "Leave `lines` out to cancel the whole invoice. Send it to give back only part of it.", "items": { "type": "object", "properties": { "product_name": { "type": "string" }, "product_code": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": [ "number", "null" ], "description": "Only needed when the same product was invoiced on two lines at different prices." } }, "required": [ "product_name", "product_code", "quantity" ] }, "minItems": 1 } }, "title": "CancelInvoiceRequest" }, "CashActionRequest": { "type": "object", "properties": { "amount": { "type": "number", "description": "Vlera e veprimit, gjithmone me e madhe se 0.", "example": 1500 }, "description": { "type": [ "string", "null" ], "description": "Pershkrimi i veprimit.", "example": "Arketim nga klienti", "maxLength": 255 }, "third_party": { "type": [ "string", "null" ], "description": "Pala e trete per veprimin.", "example": "Klienti XYZ", "maxLength": 255 }, "id_client": { "type": [ "integer", "null" ], "description": "ID e nje klienti tuajin, per ta lidhur veprimin me te. Kthehet me pas ne listen e\nveprimeve. Nje ID qe nuk i perket kompanise suaj refuzohet.", "example": 42 } }, "required": [ "amount" ], "title": "CashActionRequest" }, "CashInvoice": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence.", "example": "CASH-001" }, "payment_method": { "type": "string", "description": "Menyra e pageses.", "enum": [ "BANKNOTE", "CARD", "CHECK", "SVOUCHER", "COMPANY", "ORDER" ], "example": "BANKNOTE" }, "company_card": { "type": [ "string", "null" ], "description": "Numri i kartes se kompanise. I detyrueshem vetem per COMPANY, sepse CIS-i e kthen faturen pa te,\ndhe i ndaluar per cdo menyre tjeter pagese, ku nuk do te kishte ku te shkonte.", "example": "4111-2233", "maxLength": 50 }, "invoice_discount_type": { "type": [ "string", "null" ], "enum": [ "percent", "amount" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": [ "string", "null" ], "description": "Monedha e fatures. Pa te merret ALL.", "example": "ALL" }, "exchange_rate": { "type": [ "number", "null" ], "description": "Sa leke vlen nje njesi e monedhes se fatures. Pa te, ose me nje vlere jo pozitive,\nmerret 1. Per monedha qe vlejne me pak se nje lek, si JPY ose HUF, dergoni vlere nen 1.", "example": 100.5 }, "due_date": { "type": [ "string", "null" ] }, "supply_start_date": { "type": [ "string", "null" ] }, "supply_end_date": { "type": [ "string", "null" ] }, "reverse_charge": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shfaqen ne fature.", "example": "Faleminderit per blerjen" }, "periodic_invoice": { "type": [ "boolean", "null" ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Vetefaturim. Kur e dergoni, `client` eshte shitesi dhe i duhet numri i identifikimit\n(NUIS ose dokument) bashke me shtetin. Kur nuk e dergoni, fatura eshte e zakonshme.", "enum": [ "DOMESTIC", "ABROAD", "OTHER" ], "example": "DOMESTIC" }, "vouchers": { "type": [ "array", "null" ], "description": "Numrat serial\u00eb te tollonave, ne formen numer-vit-NIPT (p.sh. 12-2026-K51501011M). I detyrueshem vetem per SVOUCHER.", "example": [ "12-2026-K51501011M" ], "items": { "type": "string", "description": "Nje tollon shpenzohet njehere, ndaj nuk perseritet brenda te njejtes fature.", "pattern": "^[1-9][0-9]{0,7}-[0-9]{4}-[a-zA-Z][0-9]{8}[a-zA-Z]$" }, "maxItems": 20 }, "client": { "type": "object", "description": "Omit it, or send it empty, and the invoice is issued to the walk-in client.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Existing Fatureal client id; when present the client is resolved by it and the fields below are ignored." }, "name": { "type": [ "string", "null" ], "description": "Required as soon as any other client field is sent.", "example": "Klient i rastit" }, "id": { "type": [ "object", "null" ], "properties": { "type": { "type": [ "string", "null" ], "description": "when client is Albanian Company (NUIS), when client is Non-AlbanCompany(VAT, TAX), when client is Person(ID, PASS, SOC)", "enum": [ "NUIS", "VAT", "TAX", "ID", "PASS", "SOC" ] }, "id": { "type": [ "string", "null" ] } } }, "address": { "type": [ "string", "null" ], "description": "Buyer address sent to the fiscal service. A named client needs it, either on this request or already stored in Fatureal." }, "city": { "type": [ "string", "null" ], "description": "Buyer town sent to the fiscal service. A named client needs it, either on this request or already stored in Fatureal." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-3 country code (e.g. RKS, ALB, USA). ALB when absent." } } }, "lines": { "type": "array", "description": "Rrjeshtat e fatures.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Emri i produktit.", "example": "Kafe" }, "product_code": { "type": "string", "description": "Kodi i produktit.", "example": "KAF-001" }, "unit": { "type": "string", "description": "Njesia matese.", "example": "cope" }, "quantity": { "type": "number", "description": "Sasia.", "example": 2 }, "price": { "type": "number" }, "total": { "type": "number", "description": "Totali i rreshtit, me TVSH.", "example": 300 }, "vat": { "type": "integer", "enum": [ "0", "6", "10", "20" ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Arsyeja e perjashtimit nga TVSH, kur rreshti eshte i perjashtuar.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE" ] } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total", "vat" ] }, "minItems": 1 } }, "required": [ "internalId", "payment_method", "lines" ], "title": "CashInvoice" }, "CertificateRequest": { "type": "object", "properties": { "certificate_file": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream" }, "password": { "type": [ "string", "null" ] } }, "title": "CertificateRequest" }, "ClientRequest": { "type": "object", "properties": { "client_type": { "type": "string", "description": "Percakton cilat fusha me poshte jane te detyrueshme.", "enum": [ "PERSON", "COMPANY" ], "example": "COMPANY" }, "company_name": { "type": [ "string", "null" ], "description": "Emri i kompanise.", "example": "Alpha SHPK", "maxLength": 255 }, "nipt": { "type": [ "string", "null" ], "description": "Identifikuesi i kompanise: NIPT, NUIS, VAT ose TAX.", "example": "L91806031A", "maxLength": 20 }, "address": { "type": [ "string", "null" ], "description": "Adresa e kompanise.", "example": "Rruga X", "maxLength": 255 }, "city": { "type": [ "string", "null" ], "description": "Qyteti i kompanise.", "example": "Tirane", "maxLength": 50 }, "company_type": { "type": [ "string", "null" ], "description": "Lloji i kompanise.", "enum": [ "BUSINESS", "BANK", "EXCHANGE" ], "example": "BUSINESS" }, "name": { "type": [ "string", "null" ], "description": "Emri i personit.", "example": "Agon", "maxLength": 255 }, "surname": { "type": [ "string", "null" ], "description": "Mbiemri i personit.", "example": "Hoxha", "maxLength": 255 }, "document_type": { "type": [ "string", "null" ], "description": "Lloji i dokumentit te identifikimit.", "enum": [ "NUIS", "ID", "PASS", "VAT", "TAX", "SOC" ], "example": "ID" }, "document_number": { "type": [ "string", "null" ], "description": "Numri i dokumentit te identifikimit.", "example": "I12345678A", "maxLength": 255 }, "nationality_code": { "type": [ "string", "null" ], "description": "Kodi ISO 3166-1 alpha-3 i nacionalitetit. Pa te merret ALB.", "example": "ALB", "minLength": 3, "maxLength": 3 }, "nationality_id": { "type": [ "integer", "null" ], "description": "ID e nacionalitetit ne fature.al. Plotesohet vete nga nationality_code." }, "telephone": { "type": [ "string", "null" ], "description": "Telefoni.", "example": "+355691234567", "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email.", "example": "klient@example.com", "maxLength": 255 }, "customer_number": { "type": [ "string", "null" ], "description": "Numri unik i klientit ne sistemin tuaj.", "example": "CLI-001", "maxLength": 30 }, "gender": { "type": [ "string", "null" ], "description": "Gjinia, vetem per PERSON.", "example": "M", "maxLength": 10 }, "birthday": { "type": [ "string", "null" ], "format": "date-time", "description": "Data e lindjes (YYYY-MM-DD).", "example": "1990-01-15" } }, "required": [ "client_type" ], "title": "ClientRequest" }, "CreateBranchRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "type": { "type": "string", "enum": [ "main", "secondary" ] }, "administrator": { "type": "string", "maxLength": 255 }, "address": { "type": "string", "maxLength": 255 }, "businessUnitCode": { "type": [ "string", "null" ], "maxLength": 50 } }, "required": [ "name", "type", "administrator", "address" ], "title": "CreateBranchRequest" }, "EInvoiceRequest": { "type": "object", "properties": { "internalId": { "type": "string" }, "payment_method": { "type": [ "string", "null" ], "enum": [ "ACCOUNT", "COMPENSATION", "FACTORING", "KIND", "OTHER", "TRANSFER", "WAIVER" ] }, "invoice_discount_type": { "type": [ "string", "null" ], "enum": [ "percent", "amount" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "minimum": 0 }, "bank_account": { "type": [ "integer", "null" ] }, "bank_account_iban": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "Sa leke vlen nje njesi e monedhes se fatures. Pa te, ose me nje vlere jo pozitive,\nmerret 1. Per monedha qe vlejne me pak se nje lek, si JPY ose HUF, dergoni vlere nen 1.", "example": 100.5 }, "due_date": { "type": [ "string", "null" ] }, "supply_start_date": { "type": [ "string", "null" ] }, "supply_end_date": { "type": [ "string", "null" ] }, "reverse_charge": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ] }, "periodic_invoice": { "type": [ "boolean", "null" ] }, "doc_type": { "type": "string", "enum": [ "80", "82", "84", "380", "381", "383", "384", "386", "388", "393", "394", "395", "575", "623", "780" ] }, "process": { "type": "string", "enum": [ "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9", "P10", "P11" ] }, "client": { "type": "object", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Existing Fatureal client id; when present the client is resolved by it and the fields below are ignored." }, "nuis": { "type": "string", "description": "Albanian company NUIS" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ], "description": "Buyer address sent to the e-invoice system. Needed either on this request or already stored in Fatureal." }, "city": { "type": [ "string", "null" ], "description": "Buyer town sent to the e-invoice system. Needed either on this request or already stored in Fatureal." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code (e.g. RKS, ALB, USA)." } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "product_name": { "type": "string" }, "product_code": { "type": "string" }, "unit": { "type": "string" }, "unit_code": { "type": "string", "description": "The code is what the fiscal document carries, so the caller states\nit. Defaulting an unknown one silently shipped e-invoices reading\n\"Cope\" for lines the operator had marked m2.", "enum": [ "C62", "XPP", "LTR", "MLT", "SEC", "MIN", "HUR", "DAY", "MON", "ANN", "MTK", "E4", "58", "DT", "DTN", "GRM", "M4", "E54", "KMT", "D68", "QB", "H93", "MTQ", "MSK", "LM", "KWH", "E49", "E55", "OT", "PR", "XBX", "XPK", "SET", "IE" ] }, "quantity": { "type": "number" }, "price": { "type": "number" }, "total": { "type": "number" }, "vat": { "type": [ "integer", "null" ], "enum": [ "0", "6", "10", "20" ] }, "vat_exempt_type": { "type": [ "string", "null" ], "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE" ] } }, "required": [ "product_name", "product_code", "unit", "unit_code", "quantity", "price", "total" ] }, "minItems": 1 } }, "required": [ "internalId", "doc_type", "process", "client", "lines" ], "title": "EInvoiceRequest" }, "FiscalDeviceRequest": { "type": "object", "properties": { "branchId": { "type": "integer" }, "name": { "type": "string", "maxLength": 255 }, "fromDate": { "type": "string" }, "toDate": { "type": [ "string", "null" ] } }, "required": [ "branchId", "name", "fromDate" ], "title": "FiscalDeviceRequest" }, "InvoiceAddress": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code, defaults to ALB." } }, "required": [ "street", "city", "country" ], "title": "InvoiceAddress" }, "InvoiceAmount": { "type": "object", "properties": { "currency": { "type": "string", "description": "ISO 4217 currency code." }, "exchange_rate": { "type": [ "number", "null" ], "description": "Rate to the local currency, null when the invoice is already in ALL." }, "gross": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "discount": { "type": "number" }, "net_all": { "type": "number", "description": "Net converted to the local currency (ALL)." }, "gross_all": { "type": "number", "description": "Gross converted to the local currency (ALL)." }, "vat_all": { "type": "number", "description": "VAT converted to the local currency (ALL)." }, "discount_all": { "type": "number", "description": "Discount converted to the local currency (ALL)." }, "local_currency": { "anyOf": [ { "description": "Present only on a foreign-currency invoice.", "$ref": "#\/components\/schemas\/InvoiceLocalAmount" }, { "type": "null" } ] } }, "required": [ "currency", "exchange_rate", "gross", "net", "vat", "discount", "net_all", "gross_all", "vat_all", "discount_all", "local_currency" ], "title": "InvoiceAmount" }, "InvoiceBankAccount": { "type": "object", "properties": { "id": { "type": "integer" }, "bank_name": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "swift": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ], "description": "ISO 4217 currency code." }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "bank_name", "iban", "swift", "currency", "notes" ], "title": "InvoiceBankAccount" }, "InvoiceDetail": { "type": "object", "properties": { "id": { "type": "integer", "description": "Fatureal invoice id." }, "number": { "type": [ "string", "null" ], "description": "Fiscal invoice number." }, "type": { "type": "string", "description": "Invoice type, e.g. NONCASH." }, "issue_date": { "type": "string", "description": "Issue date (YYYY-MM-DD)." }, "due_date": { "type": "string", "description": "Payment due date (YYYY-MM-DD)." }, "delivery_date": { "type": "string", "description": "Delivery\/supply-end date (YYYY-MM-DD)." }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp (YYYY-MM-DD HH:MM:SS)." }, "supply_start_date": { "type": [ "string", "null" ], "description": "Supply period start (YYYY-MM-DD)." }, "supply_end_date": { "type": [ "string", "null" ], "description": "Supply period end (YYYY-MM-DD)." }, "client": { "$ref": "#\/components\/schemas\/InvoiceParty" }, "amount": { "$ref": "#\/components\/schemas\/InvoiceAmount" }, "payment_method": { "type": [ "string", "null" ] }, "payment": { "$ref": "#\/components\/schemas\/InvoicePayment" }, "bank_account": { "anyOf": [ { "description": "Bank account printed on the invoice, or null.", "$ref": "#\/components\/schemas\/InvoiceBankAccount" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ] }, "iic": { "type": [ "string", "null" ], "description": "IIC \/ NSLF." }, "fic": { "type": [ "string", "null" ], "description": "FIC \/ NIVF." }, "eic": { "type": [ "string", "null" ], "description": "EIC, for e-invoices." }, "doc_type": { "type": [ "string", "null" ] }, "process": { "type": [ "string", "null" ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Self-issuance type, when the invoice is self-issued." }, "reversed_at": { "type": [ "string", "null" ], "description": "When the invoice was reversed (YYYY-MM-DD HH:MM:SS), or null." }, "reversed_by": { "type": [ "integer", "null" ], "description": "Id of the invoice this one reverses, or null." }, "pdf_url": { "type": "string", "description": "Direct download URL for the invoice PDF." }, "reverse_charge": { "type": "boolean" }, "periodic_invoice": { "type": "boolean" }, "lines": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InvoiceLine" } } }, "required": [ "id", "number", "type", "issue_date", "due_date", "delivery_date", "created_at", "supply_start_date", "supply_end_date", "client", "amount", "payment_method", "payment", "bank_account", "notes", "iic", "fic", "eic", "doc_type", "process", "self_issue_type", "reversed_at", "reversed_by", "pdf_url", "reverse_charge", "periodic_invoice", "lines" ], "title": "InvoiceDetail" }, "InvoiceIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "Fatureal invoice id. Store it next to your own internalId." }, "number": { "type": [ "string", "null" ], "description": "Fiscal invoice number." }, "iic": { "type": [ "string", "null" ], "description": "IIC \/ NSLF." }, "fic": { "type": [ "string", "null" ], "description": "FIC \/ NIVF. Null while the invoice waits for a deferred fiscalisation." }, "tcrCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device that issued it." }, "businessCode": { "type": [ "string", "null" ], "description": "Business unit code the invoice was issued under." }, "operatorCode": { "type": [ "string", "null" ], "description": "Operator code the invoice was issued under." }, "fiscalizedAt": { "type": "string", "description": "Creation timestamp (YYYY-MM-DD HH:MM:SS)." }, "verifyURL": { "type": [ "string", "null" ], "description": "Government verification URL, the one behind the QR code." }, "pdf": { "type": "string", "description": "Direct download URL for the document. On an e-invoice that already has an\nEIC this points at the official e-invoice PDF instead of ours." }, "eic": { "type": [ "string", "null" ], "description": "EIC. The key is present only on an e-invoice that already has one, so\ntreat it as absent rather than null on every other invoice." } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic" ], "title": "InvoiceIssueResult" }, "InvoiceLine": { "type": "object", "properties": { "name": { "type": "string" }, "product_code": { "type": [ "string", "null" ], "description": "Internal product code, when the line is a mapped product." }, "unit": { "type": [ "string", "null" ] }, "unit_code": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitPrice": { "type": "number", "description": "Unit price before discount, major units." }, "vat_rate": { "type": [ "number", "null" ], "description": "VAT rate percent." }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "VAT exemption type, when the line is exempt." }, "discount_rate": { "type": [ "number", "null" ], "description": "Discount rate percent." }, "discount": { "type": [ "number", "null" ], "description": "Discount amount, major units." }, "amount_net": { "type": "number" }, "amount_vat": { "type": "number" }, "total": { "type": "number", "description": "Gross line total, major units." } }, "required": [ "name", "product_code", "unit", "unit_code", "quantity", "unitPrice", "vat_rate", "vat_exempt_type", "discount_rate", "discount", "amount_net", "amount_vat", "total" ], "title": "InvoiceLine" }, "InvoiceListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "Fatureal invoice id." }, "number": { "type": [ "string", "null" ], "description": "Fiscal invoice number." }, "type": { "type": "string", "description": "Invoice type, e.g. NONCASH." }, "issue_date": { "type": "string", "description": "Issue date (YYYY-MM-DD)." }, "due_date": { "type": "string", "description": "Payment due date (YYYY-MM-DD)." }, "delivery_date": { "type": "string", "description": "Delivery\/supply-end date (YYYY-MM-DD)." }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp (YYYY-MM-DD HH:MM:SS)." }, "supply_start_date": { "type": [ "string", "null" ], "description": "Supply period start (YYYY-MM-DD)." }, "supply_end_date": { "type": [ "string", "null" ], "description": "Supply period end (YYYY-MM-DD)." }, "client": { "$ref": "#\/components\/schemas\/InvoiceParty" }, "amount": { "$ref": "#\/components\/schemas\/InvoiceAmount" }, "payment_method": { "type": [ "string", "null" ] }, "payment": { "$ref": "#\/components\/schemas\/InvoicePayment" }, "bank_account": { "anyOf": [ { "description": "Bank account printed on the invoice, or null.", "$ref": "#\/components\/schemas\/InvoiceBankAccount" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ] }, "iic": { "type": [ "string", "null" ], "description": "IIC \/ NSLF." }, "fic": { "type": [ "string", "null" ], "description": "FIC \/ NIVF." }, "eic": { "type": [ "string", "null" ], "description": "EIC, for e-invoices." }, "doc_type": { "type": [ "string", "null" ] }, "process": { "type": [ "string", "null" ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Self-issuance type, when the invoice is self-issued." }, "reversed_at": { "type": [ "string", "null" ], "description": "When the invoice was reversed (YYYY-MM-DD HH:MM:SS), or null." }, "reversed_by": { "type": [ "integer", "null" ], "description": "Id of the invoice this one reverses, or null." }, "pdf_url": { "type": "string", "description": "Direct download URL for the invoice PDF." }, "reverse_charge": { "type": "boolean" }, "periodic_invoice": { "type": "boolean" } }, "required": [ "id", "number", "type", "issue_date", "due_date", "delivery_date", "created_at", "supply_start_date", "supply_end_date", "client", "amount", "payment_method", "payment", "bank_account", "notes", "iic", "fic", "eic", "doc_type", "process", "self_issue_type", "reversed_at", "reversed_by", "pdf_url", "reverse_charge", "periodic_invoice" ], "title": "InvoiceListItem" }, "InvoiceLocalAmount": { "type": "object", "properties": { "exchange_rate": { "type": "number" }, "gross": { "type": "number" }, "net": { "type": "number" }, "vat": { "type": "number" }, "discount": { "type": "number" } }, "required": [ "exchange_rate", "gross", "net", "vat", "discount" ], "title": "InvoiceLocalAmount" }, "InvoiceParty": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name (or company name)." }, "id": { "$ref": "#\/components\/schemas\/InvoicePartyId" }, "address": { "$ref": "#\/components\/schemas\/InvoiceAddress" } }, "required": [ "name", "id", "address" ], "title": "InvoiceParty" }, "InvoicePartyId": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "Identifier type, e.g. NUIS, ID, PASSPORT." }, "id": { "type": [ "string", "null" ], "description": "The identifier value." } }, "required": [ "type", "id" ], "title": "InvoicePartyId" }, "InvoicePayment": { "type": "object", "properties": { "state": { "type": "string", "description": "PAID, PARTIALLY_PAID or UNPAID." }, "amount_paid": { "type": "number", "description": "Amount received so far, in the invoice currency." }, "amount_left": { "type": "number", "description": "Gross total minus what has been received, in the invoice currency." } }, "required": [ "state", "amount_paid", "amount_left" ], "title": "InvoicePayment" }, "InvoicePrintAmounts": { "type": "object", "properties": { "net": { "type": "number" }, "gross": { "type": "number" }, "vat": { "type": "number" }, "discount": { "type": "number" }, "net_all": { "type": "number" }, "gross_all": { "type": "number" }, "vat_all": { "type": "number" }, "discount_all": { "type": "number" } }, "required": [ "net", "gross", "vat", "discount", "net_all", "gross_all", "vat_all", "discount_all" ], "title": "InvoicePrintAmounts" }, "InvoicePrintClient": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "$ref": "#\/components\/schemas\/InvoicePartyId" }, "addres": { "type": [ "string", "null" ], "description": "Buyer street address. The key really is spelled `addres`. It is a typo we cannot correct\nwithout breaking every integration already reading it." }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code. ALB when the buyer has none." } }, "required": [ "name", "id", "addres", "city", "country" ], "title": "InvoicePrintClient" }, "InvoicePrintCompany": { "type": "object", "properties": { "name": { "type": "string" }, "nuis": { "type": [ "string", "null" ], "description": "Seller NUIS." }, "address": { "type": [ "string", "null" ], "description": "Address of the business unit that issued the invoice." } }, "required": [ "name", "nuis", "address" ], "title": "InvoicePrintCompany" }, "InvoicePrintDocument": { "type": "object", "properties": { "logo": { "type": [ "string", "null" ], "description": "The company logo as base64, or null when none is set." }, "title": { "type": "string", "description": "Document title in the account language, e.g. \"Fatur\u00eb Tatimore\"." }, "company": { "$ref": "#\/components\/schemas\/InvoicePrintCompany" }, "client": { "$ref": "#\/components\/schemas\/InvoicePrintClient" }, "transporter": { "$ref": "#\/components\/schemas\/InvoicePrintTransporter" }, "invoice": { "$ref": "#\/components\/schemas\/InvoicePrintInvoice" } }, "required": [ "logo", "title", "company", "client", "transporter", "invoice" ], "title": "InvoicePrintDocument" }, "InvoicePrintInvoice": { "type": "object", "properties": { "type": { "type": "string", "description": "Invoice type, e.g. CASH, NONCASH, EINVOICE." }, "payment_method": { "type": [ "string", "null" ] }, "payment_method_label": { "type": [ "string", "null" ], "description": "The payment method spelled out in the account language, ready to print." }, "bank_account": { "anyOf": [ { "description": "Bank account to print as payment instructions, or null.", "$ref": "#\/components\/schemas\/InvoiceBankAccount" }, { "type": "null" } ] }, "issueDate": { "type": [ "string", "null" ], "description": "Issue date (YYYY-MM-DD HH:MM:SS)." }, "businessCode": { "type": [ "string", "null" ] }, "operatorCode": { "type": [ "string", "null" ] }, "operatorName": { "type": [ "string", "null" ], "description": "The operator resolved to a name, when we know one." }, "deviceCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device." }, "currency": { "type": [ "string", "null" ], "description": "Invoice currency, null when it is ALL." }, "exchangeRate": { "type": [ "number", "null" ], "description": "Rate to ALL, null when the invoice is already in ALL." }, "number": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InvoicePrintLine" } }, "amounts": { "$ref": "#\/components\/schemas\/InvoicePrintAmounts" }, "iic": { "type": [ "string", "null" ], "description": "IIC \/ NSLF." }, "fic": { "type": [ "string", "null" ], "description": "FIC \/ NIVF." }, "eic": { "type": [ "string", "null" ], "description": "EIC, for e-invoices." }, "process": { "type": [ "string", "null" ] }, "doc_type": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "verifyUrl": { "type": [ "string", "null" ], "description": "Government verification URL, the one to render as a QR code." }, "footer": { "type": "array", "description": "Lines to print under the total, already ordered.", "items": { "type": "string" } } }, "required": [ "type", "payment_method", "payment_method_label", "bank_account", "issueDate", "businessCode", "operatorCode", "operatorName", "deviceCode", "currency", "exchangeRate", "number", "lines", "amounts", "iic", "fic", "eic", "process", "doc_type", "notes", "verifyUrl", "footer" ], "title": "InvoicePrintInvoice" }, "InvoicePrintLine": { "type": "object", "properties": { "name": { "type": "string" }, "unit": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitPrice": { "type": "number", "description": "Unit price before any line discount." }, "total": { "type": "number", "description": "Gross line total." } }, "required": [ "name", "unit", "quantity", "unitPrice", "total" ], "title": "InvoicePrintLine" }, "InvoicePrintTransporter": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "plate": { "type": [ "string", "null" ], "description": "Vehicle plate." }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } }, "required": [ "name", "plate", "address", "city" ], "title": "InvoicePrintTransporter" }, "NonCashInvoiceRequest": { "type": "object", "properties": { "internalId": { "type": "string" }, "payment_method": { "type": [ "string", "null" ], "enum": [ "ACCOUNT", "COMPENSATION", "FACTORING", "KIND", "OTHER", "TRANSFER", "WAIVER" ] }, "invoice_discount_type": { "type": [ "string", "null" ], "enum": [ "percent", "amount" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "minimum": 0 }, "bank_account": { "type": [ "integer", "null" ] }, "bank_account_iban": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "Sa leke vlen nje njesi e monedhes se fatures. Pa te, ose me nje vlere jo pozitive,\nmerret 1. Per monedha qe vlejne me pak se nje lek, si JPY ose HUF, dergoni vlere nen 1.", "example": 100.5 }, "due_date": { "type": [ "string", "null" ] }, "supply_start_date": { "type": [ "string", "null" ] }, "supply_end_date": { "type": [ "string", "null" ] }, "reverse_charge": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ] }, "periodic_invoice": { "type": [ "boolean", "null" ] }, "self_issue_type": { "type": [ "string", "null" ], "enum": [ "DOMESTIC", "ABROAD", "OTHER" ] }, "client": { "type": "object", "description": "Omit it, or send it empty, and the invoice is issued to the walk-in client.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Existing Fatureal client id; when present the client is resolved by it and the fields below are ignored." }, "name": { "type": "string", "description": "Emri i bleresit.", "example": "Alpha SHPK" }, "id": { "type": [ "object", "null" ], "properties": { "type": { "type": [ "string", "null" ], "description": "values when client is Albanian Company (NUIS), values when client is Non-AlbanCompany(VAT, TAX), values when client is Person(ID, PASS, SOC)", "enum": [ "NUIS", "VAT", "TAX", "ID", "PASS", "SOC" ] }, "id": { "type": [ "string", "null" ] } } }, "address": { "type": [ "string", "null" ], "description": "Buyer address sent to the fiscal service. A named client needs it, either on this request or already stored in Fatureal." }, "city": { "type": [ "string", "null" ], "description": "Buyer town sent to the fiscal service. A named client needs it, either on this request or already stored in Fatureal." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code (e.g. RKS, ALB, USA). ALB when absent." } } }, "bankAccount": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "currency": { "type": [ "string", "null" ] }, "swift": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "holder": { "type": [ "string", "null" ] } } }, "fee": { "type": "object", "properties": { "fee_type": { "type": [ "string", "null" ] }, "fee_amount": { "type": [ "number", "null" ] } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "product_name": { "type": "string" }, "product_code": { "type": "string" }, "unit": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": "number" }, "total": { "type": "number" }, "vat": { "type": [ "integer", "null" ], "enum": [ "0", "6", "10", "20" ] }, "vat_exempt_type": { "type": [ "string", "null" ], "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE" ] } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total" ] }, "minItems": 1 } }, "required": [ "internalId", "lines" ], "title": "NonCashInvoiceRequest" }, "OrderInvoice": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence.", "example": "ORD-001" }, "lines": { "type": "array", "description": "Rrjeshtat e fatures, me te njejtat fusha si tek Cash.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Emri i produktit.", "example": "Kafe" }, "product_code": { "type": "string", "description": "Kodi i produktit.", "example": "KAF-001" }, "unit": { "type": "string", "description": "Njesia matese.", "example": "cope" }, "quantity": { "type": "number" }, "price": { "type": "number" }, "total": { "type": "number", "description": "Totali i rreshtit, me TVSH." }, "vat": { "type": "integer", "description": "Shkalla e TVSH.", "example": 20 }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Arsyeja e perjashtimit nga TVSH, kur rreshti eshte i perjashtuar." } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total", "vat" ] }, "minItems": 1 } }, "required": [ "internalId", "lines" ], "title": "OrderInvoice" }, "OrderInvoiceIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "Fatureal invoice id. Store it next to your own internalId." }, "number": { "type": [ "string", "null" ], "description": "Fiscal invoice number." }, "iic": { "type": [ "string", "null" ], "description": "IIC \/ NSLF." }, "fic": { "type": [ "string", "null" ], "description": "FIC \/ NIVF. Null while the invoice waits for a deferred fiscalisation." }, "tcrCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device that issued it." }, "businessCode": { "type": [ "string", "null" ], "description": "Business unit code the invoice was issued under." }, "operatorCode": { "type": [ "string", "null" ], "description": "Operator code the invoice was issued under." }, "fiscalizedAt": { "type": "string", "description": "Creation timestamp (YYYY-MM-DD HH:MM:SS)." }, "verifyURL": { "type": [ "string", "null" ], "description": "Government verification URL, the one behind the QR code." }, "pdf": { "type": "string", "description": "Direct download URL for the document. On an e-invoice that already has an\nEIC this points at the official e-invoice PDF instead of ours." }, "eic": { "type": [ "string", "null" ], "description": "EIC. The key is present only on an e-invoice that already has one, so\ntreat it as absent rather than null on every other invoice." }, "isOrderInvoice": { "type": "boolean", "description": "Always true. The key marks the invoice as an Order." }, "summaryInvoiceId": { "type": [ "integer", "null" ], "description": "Id of the Summary invoice that settled this Order. The key appears only\nonce it has been settled, so a freshly issued Order does not carry it." } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic", "isOrderInvoice", "summaryInvoiceId" ], "title": "OrderInvoiceIssueResult" }, "ProductCategoryRef": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ], "description": "Hex colour used by the POS grid." } }, "required": [ "id", "name", "color" ], "title": "ProductCategoryRef" }, "ProductDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": [ "string", "null" ], "description": "Unique product code." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure, derived from unit_code." }, "unit_code": { "type": [ "string", "null" ], "description": "Unit of measure code, e.g. C62, XPP, LTR." }, "last_price": { "type": "number", "description": "Sale price." }, "cost_price": { "type": [ "number", "null" ], "description": "Purchase price, when one is recorded." }, "vat_rate": { "type": "number", "description": "VAT rate percent: 0, 6, 10 or 20." }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "VAT exemption type, when the product is exempt." }, "vat_exempt_description": { "type": [ "string", "null" ], "description": "The exemption type spelled out in the account language." }, "currency": { "type": [ "string", "null" ] }, "id_category": { "type": [ "integer", "null" ] }, "service": { "type": "boolean", "description": "True for a service, false for an article that is tracked in stock." }, "category": { "anyOf": [ { "description": "The category resolved, or null when the product has none.", "$ref": "#\/components\/schemas\/ProductCategoryRef" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601." } }, "required": [ "id", "code", "name", "description", "unit", "unit_code", "last_price", "cost_price", "vat_rate", "vat_exempt_type", "vat_exempt_description", "currency", "id_category", "service", "category", "created_at" ], "title": "ProductDetail" }, "ProductListItem": { "type": "object", "properties": { "id": { "type": "integer" }, "code": { "type": [ "string", "null" ], "description": "Unique product code." }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure, derived from unit_code." }, "unit_code": { "type": [ "string", "null" ], "description": "Unit of measure code, e.g. C62, XPP, LTR." }, "last_price": { "type": "number", "description": "Sale price." }, "cost_price": { "type": [ "number", "null" ], "description": "Purchase price, when one is recorded." }, "vat_rate": { "type": "number", "description": "VAT rate percent: 0, 6, 10 or 20." }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "VAT exemption type, when the product is exempt." }, "vat_exempt_description": { "type": [ "string", "null" ], "description": "The exemption type spelled out in the account language." }, "currency": { "type": [ "string", "null" ] }, "id_category": { "type": [ "integer", "null" ] } }, "required": [ "id", "code", "name", "description", "unit", "unit_code", "last_price", "cost_price", "vat_rate", "vat_exempt_type", "vat_exempt_description", "currency", "id_category" ], "title": "ProductListItem" }, "ProductRequest": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "Kodi unik i produktit. Gjenerohet vete nese mungon.", "example": "P001", "maxLength": 255 }, "name": { "type": "string", "description": "Emri i produktit.", "example": "Kafe Espresso", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "Pershkrimi. Pa te merret emri.", "example": "Kafe espresso e peshuar 18g", "maxLength": 255 }, "unit_code": { "type": "string", "description": "Kodi i njesise matese. Njesia derivohet prej tij.", "enum": [ "C62", "XPP", "LTR", "MLT", "SEC", "MIN", "HUR", "DAY", "MON", "ANN", "MTK", "E4", "58", "DT", "DTN", "GRM", "M4", "E54", "KMT", "D68", "QB", "H93", "MTQ", "MSK", "LM", "KWH", "E49", "E55", "OT", "PR", "XBX", "XPK", "SET", "IE" ], "example": "XPP" }, "last_price": { "type": "number", "description": "Cmimi i shitjes.", "example": 150, "minimum": 0 }, "cost_price": { "type": [ "number", "null" ], "description": "Cmimi i blerjes.", "example": 80, "minimum": 0 }, "vat_rate": { "type": "string", "description": "Shkalla e TVSH.", "enum": [ "0", "6", "10", "20" ], "example": "20" }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Lloji i perjashtimit nga TVSH.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE" ], "example": "TAX_FREE" }, "currency": { "type": [ "string", "null" ], "description": "Monedha. Pa te merret ALL.", "example": "ALL", "maxLength": 10 }, "service": { "type": "boolean", "description": "Sherbim (true) apo artikull inventarizues (false). Pa te merret true.", "example": true }, "id_category": { "type": [ "integer", "null" ], "description": "ID e kategorise, nga GET \/product\/categories.", "example": 3 } }, "required": [ "name", "unit_code", "last_price", "vat_rate" ], "title": "ProductRequest" }, "RegisterCompanyRequest": { "type": "object", "properties": { "nuis": { "type": "string", "pattern": "^[A-Z]\\d{8}[A-Z]$" }, "name": { "type": "string", "maxLength": 255 }, "address": { "type": "string", "maxLength": 255 }, "administrator": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "issuerInVat": { "type": [ "boolean", "null" ] }, "lastNonCashEInvoiceNumber": { "type": [ "string", "null" ], "maxLength": 50 } }, "required": [ "nuis", "name", "address", "administrator", "phone", "email" ], "title": "RegisterCompanyRequest" }, "ReportPeriod": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive." }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive." } }, "required": [ "from", "to" ], "title": "ReportPeriod" }, "SettledOrderInvoice": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": [ "string", "null" ] }, "date": { "type": "string", "description": "When the order was issued (YYYY-MM-DD HH:MM:SS)." }, "amountGross": { "type": "number" }, "currency": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "date", "amountGross", "currency" ], "title": "SettledOrderInvoice" }, "SummaryInvoice": { "type": "object", "properties": { "internalId": { "type": "string" }, "payment_method": { "type": "string", "enum": [ "BANKNOTE", "CARD" ] }, "currency": { "type": [ "string", "null" ] }, "exchange_rate": { "type": [ "number", "null" ] }, "supply_start_date": { "type": [ "string", "null" ] }, "supply_end_date": { "type": [ "string", "null" ] }, "order_invoices": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "internalId", "payment_method", "order_invoices" ], "title": "SummaryInvoice" }, "SummaryInvoiceIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "Fatureal invoice id. Store it next to your own internalId." }, "number": { "type": [ "string", "null" ], "description": "Fiscal invoice number." }, "iic": { "type": [ "string", "null" ], "description": "IIC \/ NSLF." }, "fic": { "type": [ "string", "null" ], "description": "FIC \/ NIVF. Null while the invoice waits for a deferred fiscalisation." }, "tcrCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device that issued it." }, "businessCode": { "type": [ "string", "null" ], "description": "Business unit code the invoice was issued under." }, "operatorCode": { "type": [ "string", "null" ], "description": "Operator code the invoice was issued under." }, "fiscalizedAt": { "type": "string", "description": "Creation timestamp (YYYY-MM-DD HH:MM:SS)." }, "verifyURL": { "type": [ "string", "null" ], "description": "Government verification URL, the one behind the QR code." }, "pdf": { "type": "string", "description": "Direct download URL for the document. On an e-invoice that already has an\nEIC this points at the official e-invoice PDF instead of ours." }, "eic": { "type": [ "string", "null" ], "description": "EIC. The key is present only on an e-invoice that already has one, so\ntreat it as absent rather than null on every other invoice." }, "isSummaryInvoice": { "type": "boolean", "description": "Always true. The key marks the invoice as a Summary." }, "settledOrderInvoices": { "type": "array", "items": { "$ref": "#\/components\/schemas\/SettledOrderInvoice" } } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic", "isSummaryInvoice", "settledOrderInvoices" ], "title": "SummaryInvoiceIssueResult" }, "WtnInvoiceRequest": { "type": "object", "properties": { "vehPlates": { "type": "string", "description": "Targa e automjetit.", "example": "AA123BB" }, "valueOfGoods": { "type": "number", "description": "Vlera e mallrave, ne ALL.", "example": 10000 }, "type": { "type": [ "string", "null" ], "description": "Lloji i dokumentit.", "enum": [ "WTN", "SALE" ], "example": "WTN" }, "transaction": { "type": [ "string", "null" ], "description": "Lloji i transaksionit.", "enum": [ "TRANSFER", "EXAMINATION", "SALES", "DOOR" ], "example": "TRANSFER" }, "vehOwnership": { "type": [ "string", "null" ], "description": "Pronesia e automjetit.", "enum": [ "OWNER", "THIRDPARTY" ], "example": "OWNER" }, "startPoint": { "type": [ "string", "null" ], "description": "Lloji i pikes se nisjes.", "enum": [ "ANOTHER", "CUSTOMS", "EXHIBITION", "OTHER", "SALE", "STORE", "WAREHOUSE" ], "example": "WAREHOUSE" }, "destinPoint": { "type": [ "string", "null" ], "description": "Lloji i pikes se destinacionit.", "enum": [ "ANOTHER", "CUSTOMS", "EXHIBITION", "OTHER", "SALE", "STORE", "WAREHOUSE" ], "example": "STORE" }, "carrier_id_type": { "type": [ "string", "null" ], "description": "Lloji i identifikuesit te transportuesit.", "enum": [ "NUIS", "ID" ], "example": "NUIS" }, "startCity": { "type": [ "string", "null" ], "description": "Qyteti i nisjes.", "example": "Tirane" }, "startAddr": { "type": [ "string", "null" ], "description": "Adresa e nisjes.", "example": "Rruga X" }, "destinCity": { "type": [ "string", "null" ], "description": "Qyteti i destinacionit.", "example": "Durres" }, "destinAddr": { "type": [ "string", "null" ], "description": "Adresa e destinacionit.", "example": "Rruga Y" }, "carrier_id_num": { "type": [ "string", "null" ], "description": "ID ose NIPT i transportuesit.", "example": "L01234567A" }, "carrier_name": { "type": [ "string", "null" ], "description": "Emri i transportuesit.", "example": "Transport SHPK" }, "carrier_town": { "type": [ "string", "null" ], "description": "Qyteti i transportuesit.", "example": "Tirane" }, "carrier_address": { "type": [ "string", "null" ], "description": "Adresa e transportuesit.", "example": "Rruga Z" }, "startDateTime": { "type": [ "string", "null" ], "description": "Data e nisjes, ne formatin Y-m-d H:i.", "example": "2025-01-15 10:30" }, "destinDateTime": { "type": [ "string", "null" ], "description": "Data e mberritjes, ne formatin Y-m-d H:i.", "example": "2025-01-15 14:30" }, "invoice_lines": { "type": "array", "description": "Rrjeshtat e mallit, minimumi nje rresht.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Emri ose pershkrimi i mallit.", "example": "Kafe", "maxLength": 255 }, "product_code": { "type": "string", "description": "Kodi i mallit.", "example": "K1", "maxLength": 50 }, "unit": { "type": "string", "description": "Njesia matese.", "example": "cope", "maxLength": 50 }, "quantity": { "type": "number", "description": "Sasia, gjithmone me e madhe se 0.", "example": 5 } }, "required": [ "product_name", "product_code", "unit", "quantity" ] }, "minItems": 1 } }, "required": [ "vehPlates", "valueOfGoods", "invoice_lines" ], "title": "WtnInvoiceRequest" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } } } } }