# fature.al API

> HTTP API reference for fature.al API, version 1.0.0.

All endpoints are relative to `https://fature.al`.

## API versions

| Version | Status | Endpoints |
| --- | --- | --- |
| `v2` | previous | 4 |
| `v1` | current | 60 |

Write new integrations against `v1`. Every endpoint below states the version it belongs to, and any endpoint with a newer edition links to it.

## Si te fillosh

- [Hyrje](/api-reference/pages/introduction.md): API-ja e fature.al ju jep fiskalizimin shqiptar si sherbim: dergoni nje fature si JSON dhe merrni nje dokument te fiskalizuar, me IIC, NIVF, URL verifikimi dhe PDF.
- [Fillimi i shpejte](/api-reference/pages/quickstart.md): Nga token-i deri te fatura e pare e leshuar me API-n e fature.al, ne tri thirrje.
- [Cfare mund te ndertoni](/api-reference/pages/use-cases.md): Kjo API ju jep fiskalizimin shqiptar si sherbim, bashke me te dhena qe nuk i keni ju: regjistrin e NIPT-eve, faturat e blerjes nga tatimet dhe kursin e dites.
- [Identifikimi](/api-reference/pages/authentication.md): Cdo endpoint kerkon token-in e perdoruesit. Integrimet e ofruesve dergojne edhe nje cift kredencialesh qe tregon cili program po therret.
- [Versionet e API-t](/api-reference/pages/versioning.md): v1 eshte API-ja e plote dhe ajo mbi te cilen ndertohet. v2 eshte formati i ri i klientit dhe mbulon vetem klientet. Asnje nga te dyja nuk eshte ne dalje.
- [Gabimet](/api-reference/pages/errors.md): Kodet HTTP qe kthen kjo API, forma e trupit te gabimit, dhe perjashtimi i vetem qe duhet ditur: validimi ne v1 perdor success ne vend te status.
- [Kufiri i kerkesave](/api-reference/pages/rate-limiting.md): Cfare e kufizon nje integrim me fature.al: kufiri i pergjithshem per token, intervali minimal mes dy thirrjeve, endpoint-et qe kryhen nje nga nje, dhe buxheti per grup endpoint-esh.
- [Faqezimi](/api-reference/pages/pagination.md): Listat nuk faqezohen te gjitha njesoj. Cili endpoint pranon limit me offset, cili pranon page, dhe ku qendron numri i pergjithshem.

## Shembuj

- [Llojet e faturave](/api-reference/pages/invoice-types.md): Cash, jo-cash, e-fature, porosi me permbledhese, bllok dhe flete shoqeruese. Cili endpoint leshon cilin dokument, dhe cilat fusha ndryshojne mes tyre.
- [Fatura elektronike](/api-reference/pages/e-invoice.md): Cfare e ndan nje fature elektronike nga nje fature e zakonshme jo-cash, dhe si zgjidhet doc_type me process per secilin dokument.
- [Zbritjet ne fature](/api-reference/pages/discounts.md): Si zbritet nje fature nga API, si zbritet nje rresht i vetem, si lexohen perqindja dhe vlera fikse dhe cfare kthehet ne pergjigje.

## Klienti (v2)

Versioni 2 i endpoint-eve te klientit. Perdor nje format te ri me objekte te ndara
(`company`/`person`/`address`/`contact`) dhe nje fushe diskriminuese `type` (company|person).
Identifikuesi jepet si objekt `id` me `type` dhe `value`. Lloji (`type`) eshte i pandryshueshem ne editim.

- [GET /api/v2/clients](/api-reference/endpoints/api-v2-clients-list.md): Lista e klienteve
- [POST /api/v2/clients](/api-reference/endpoints/api-v2-clients-create.md): Krijo klient (v2)
- [GET /api/v2/clients/{id}](/api-reference/endpoints/api-v2-clients-show.md): Detajet e klientit (v2)
- [PATCH /api/v2/clients/{id}](/api-reference/endpoints/api-v2-clients-update.md): Perditeso klient (v2)

## Ping (v1)

Nje thirrje qe nuk prek asgje, per te provuar lidhjen dhe token-in.

- [GET /api/v1/ping](/api-reference/endpoints/get-api-v1-ping.md): Ping

## Regjistrimi (v1)

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.

**Workflow:**
1. Regjistroni kompanine (`POST /register`).
2. Perditesoni njesine e biznesit (branch) me `businessUnitCode`, i cili merret nga self-care dhe ruhet te njesia e biznesit.
3. Perditesoni perdoruesin me `operatorCode`, i cili merret nga self-care.
4. Ngarkoni certifikaten elektronike se bashku me fjalekalimin perkates, te cilin e merrni nga e-Albania.
5. Ruani llogarite bankare qe kompania do te perdore per faturat pa para ne dore ose per faturat elektronike (eInvoice).

**Nese kompania do te leshoje fatura me para ne dore:**
6. Ruani pajisjen fiskale (fiscal device) dhe kodi i kthyer `fiscalTcrCode` duhet te ruhet te perdoruesi qe do te leshoje keto lloj faturash, njesoj si te pika 3.

**Shtimi i perdoruesve te rinj:**
Mund te shtoni me shume perdorues nese eshte e nevojshme, por per secilin duhet te plotesohen:
- Nje email unik, p.sh. `dicka-unike@domaini-juaj.com`
- Pajisja fiskale, sipas pikes 6
- Kodi i operatorit, sipas pikes 3

> **Shenim:** Cdo perdorues do te operoje me `api_token`-in e vet, te cilin e merr pasi te regjistrohet.

**Sandbox (vetem ne instancen DEMO):**
Per 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:

- Nuk krijohet kompani e re; perdoruesi dhe njesia e biznesit krijohen nen kompanine ekzistuese sandbox `L62221018T`.
- 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.
- `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.
- Hapat e tjere (`branch`, `user`, `bank-account`, `fiscal-device`) ekzekutohen normalisht ne kompanine sandbox.

Ne `PRODUCTION` keto sjellje sandbox jane jo-aktive. NIPT `L62221018T` trajtohet si cdo NIPT tjeter.

- [GET /api/v1/register](/api-reference/endpoints/api-v1-pong.md): Ping (Register)
- [POST /api/v1/register](/api-reference/endpoints/api-v1-register.md): Regjistro kompani te re
- [POST /api/v1/on-boarding/branch/{id}](/api-reference/endpoints/api-v1-on-boarding-branch.md): Perditeso njesine e biznesit (Branch)
- [POST /api/v1/on-boarding/user/{id}](/api-reference/endpoints/api-v1-on-boarding-user-update.md): Perditeso perdoruesin
- [POST /api/v1/on-boarding/certificate](/api-reference/endpoints/api-v1-on-boarding-certificate.md): Ngarko certifikaten elektronike
- [POST /api/v1/on-boarding/bank-account](/api-reference/endpoints/api-v1-on-boarding-bank-account.md): Krijo llogari bankare
- [POST /api/v1/on-boarding/fiscal-device](/api-reference/endpoints/api-v1-on-boarding-fiscal-device.md): Krijo pajisje fiskale (TCR)
- [POST /api/v1/on-boarding/branch](/api-reference/endpoints/api-v1-on-boarding-branch-create.md): Krijo njesi biznesi (Branch)
- [POST /api/v1/on-boarding/user](/api-reference/endpoints/api-v1-on-boarding-user.md): Krijo perdorues te ri

## Faturat (v1)

Leshimi i faturave dhe gjithcka qe vjen pas tij: cash, jo-cash, e-fature, porosi, permbledhese dhe bllok jo-cash, si dhe anulimi, detajet dhe PDF-ja.

Trupi i kerkeses ndryshon nga njeri lloj tek tjetri me shume nga sa duket, prandaj e njejta fature e derguar tek dy endpoint-e refuzohet nga njeri prej tyre. Cili endpoint leshon cilin dokument shpjegohet ne faqen Llojet e faturave.

- [GET /api/v1/invoice](/api-reference/endpoints/get-api-v1-invoice.md): Lista e faturave
- [POST /api/v1/invoice/bulk-noncash](/api-reference/endpoints/post-api-v1-invoice-bulk-noncash.md): Krijo fatura pa para ne dore ne bllok (Bulk NonCash)
- [POST /api/v1/invoice/cancel-by-internal-id/{internalId}](/api-reference/endpoints/post-api-v1-invoice-cancel-by-internal-id-internalid.md): Anulo fature sipas Internal ID
- [POST /api/v1/invoice/cancel/{id}](/api-reference/endpoints/post-api-v1-invoice-cancel-id.md): Anulo fature sipas ID
- [POST /api/v1/invoice/cash](/api-reference/endpoints/post-api-v1-invoice-cash.md): Krijo fature me para ne dore (Cash)
- [POST /api/v1/invoice/details/{internalId}](/api-reference/endpoints/post-api-v1-invoice-details-internalid.md): Detajet e fatures sipas Internal ID
- [POST /api/v1/invoice/e-invoice](/api-reference/endpoints/post-api-v1-invoice-e-invoice.md): Krijo fature elektronike (E-Invoice)
- [POST /api/v1/invoice/noncash](/api-reference/endpoints/post-api-v1-invoice-noncash.md): Krijo fature pa para ne dore (NonCash)
- [POST /api/v1/invoice/order](/api-reference/endpoints/post-api-v1-invoice-order.md): Krijo fature porosi (Order)
- [GET /api/v1/invoice/print-eic/{eic}](/api-reference/endpoints/api-v1-einvoice-pdf.md): Shkarko PDF te fatures sipas EIC
- [GET /api/v1/invoice/print/{id}](/api-reference/endpoints/api-v1-invoice-pdf.md): Shkarko PDF te fatures sipas ID
- [POST /api/v1/invoice/summary](/api-reference/endpoints/post-api-v1-invoice-summary.md): Krijo fature permbledhese (Summary)
- [GET /api/v1/invoice/{id}/details](/api-reference/endpoints/get-api-v1-invoice-id-details.md): Detajet e fatures sipas ID

## Arka Fiskale (v1)

Dita ne arken fiskale: hapja e balances para fatures se pare cash, hyrjet dhe daljet e parave, mbyllja ne fund dhe gjendja ne cdo moment.

Veprimet regjistrohen ne pajisjen fiskale (TCR) te lidhur me perdoruesin qe ben kerkesen, prandaj pa nje TCR nuk kane ku te shkojne.

- [GET /api/v1/cash-register/actions](/api-reference/endpoints/api-v1-cash-register-list.md): Lista e veprimeve me arken
- [GET /api/v1/cash-register/balance](/api-reference/endpoints/api-v1-cash-register-balance.md): Balanca e arkes fiskale
- [POST /api/v1/cash-register/close-balance](/api-reference/endpoints/api-v1-cash-register-close.md): Mbyll balancen e arkes
- [POST /api/v1/cash-register/deposit](/api-reference/endpoints/api-v1-cash-register-deposit.md): Hyrje ne arke (Deposit)
- [POST /api/v1/cash-register/open-balance](/api-reference/endpoints/api-v1-cash-register-open.md): Hap balancen e arkes
- [POST /api/v1/cash-register/withdraw](/api-reference/endpoints/api-v1-cash-register-withdraw.md): Dalje nga arka (Withdraw)

## Klienti (v1)

Klientet e kompanise: lista, detajet, krijimi dhe perditesimi, si dhe nje kerkim sipas NIPT-it qe e gjen subjektin qe te mos e krijoni dy here.

- [GET /api/v1/client/search](/api-reference/endpoints/api-v1-client-search.md): Kerko klient sipas NIPT
- [GET /api/v1/clients](/api-reference/endpoints/api-v1-clients-list.md): Lista e klienteve
- [POST /api/v1/clients](/api-reference/endpoints/api-v1-clients-create.md): Krijo klient
- [PUT /api/v1/clients/{id}](/api-reference/endpoints/api-v1-clients-update.md): Perditeso klient
- [GET /api/v1/clients/{id}/details](/api-reference/endpoints/api-v1-clients-details.md): Detajet e klientit sipas ID

## Produkte (v1)

Katalogu i produkteve dhe kategorite e tyre: lista, detajet, krijimi dhe perditesimi. Keta jane artikujt qe dalin si rreshta ne fature.

- [GET /api/v1/product/categories](/api-reference/endpoints/get-api-v1-product-categories.md): Lista e kategorive
- [GET /api/v1/products](/api-reference/endpoints/get-api-v1-products.md): Lista e produkteve
- [POST /api/v1/products](/api-reference/endpoints/api-v1-products-create.md): Krijo produkt
- [PUT /api/v1/products/{id}](/api-reference/endpoints/api-v1-products-update.md): Perditeso produkt
- [GET /api/v1/products/{id}/details](/api-reference/endpoints/api-v1-products-details.md): Detajet e produktit sipas ID

## Llogaritë bankare (v1)

Llogarite bankare te kompanise, ashtu sic dalin si informacion pagese ne faturat jo-cash dhe elektronike. Vetem lexim: nje llogari e re shtohet gjate regjistrimit ose nga paneli.

- [GET /api/v1/bank-accounts](/api-reference/endpoints/api-v1-bank-accounts-list.md): Lista e llogarive bankare

## Monedhat (v1)

Monedhat e konfiguruara per kompanine dhe kursi i kembimit i dites, i marre nga kursi.al.

- [GET /api/v1/currencies](/api-reference/endpoints/api-v1-currencies-list.md): Lista e monedhave
- [GET /api/v1/exchange-rates](/api-reference/endpoints/api-v1-exchange-rates.md): Kursi i kembimit

## Fletë shoqëruese (v1)

Fletet shoqeruese (WTN) per mallin qe leviz midis njesive ose drejt nje klienti pa qene shitje: krijimi, lista, detajet dhe te dhenat per printim.

- [GET /api/v1/invoice/wtn](/api-reference/endpoints/api-v1-invoice-wtn-list.md): Lista e faturave shoqeruese (WTN)
- [POST /api/v1/invoice/wtn](/api-reference/endpoints/api-v1-invoice-wtn-create.md): Krijo fature shoqeruese (WTN)
- [GET /api/v1/invoice/wtn/print/{id}](/api-reference/endpoints/api-v1-invoice-wtn-print.md): Te dhenat e fatures shoqeruese ne format printimi (JSON)
- [GET /api/v1/invoice/wtn/{id}/details](/api-reference/endpoints/api-v1-invoice-wtn-details.md): Detajet e fatures shoqeruese sipas ID

## Faturat e blerjes (v1)

Faturat qe kompania ka marre nga furnitoret, ashtu sic vijne nga sistemi i e-faturave. Vetem lexim: keto dokumente nuk leshohen ketu.

- [GET /api/v1/purchase-invoices](/api-reference/endpoints/api-v1-purchase-invoices-list.md): Lista e faturave te blerjes

## Llogaria (v1)

Kush eshte perdoruesi qe mban token-in: emri, kompania, NIPT-i, njesia e biznesit, kodi fiskal dhe te drejtat.

Eshte thirrja e pare e dobishme kur nis nje integrim, sepse tregon me cfare konteksti do te leshohen faturat.

- [GET /api/v1/account](/api-reference/endpoints/get-api-v1-account.md): Te dhenat e llogarise

## Paneli (v1)

Permbledhja e dites ne nje thirrje te vetme: turni i hapur, shitjet e sotme perballe atyre te djeshme, gjendja e arkes dhe faturat e fundit.

Pergjigja ruhet ne cache per pak sekonda, prandaj eshte per ekran, jo per rakordim.

- [GET /api/v1/dashboard/summary](/api-reference/endpoints/api-v1-dashboard-summary.md): Permbledhja e dites

## Raportet (v1)

Shifra te grumbulluara mbi nje periudhe: shitjet, TVSH-ja, ecuria ditore, klientet dhe produktet kryesore, shitjet sipas operatorit dhe sipas pajisjes, arka dhe fletet shoqeruese.

Llogaritja behet ne bazen e te dhenave, prandaj nje raport i pergjigjet pyetjes me shpejt dhe me sakte se marrja e faturave nje nga nje.

- [GET /api/v1/reports/by-operator](/api-reference/endpoints/api-v1-reports-by-operator.md): Shitjet sipas operatorit
- [GET /api/v1/reports/by-tcr](/api-reference/endpoints/api-v1-reports-by-tcr.md): Shitjet sipas pajisjes fiskale
- [GET /api/v1/reports/cash-register](/api-reference/endpoints/api-v1-reports-cash-register.md): Gjendja e arkes per nje dite
- [GET /api/v1/reports/cash-register/closing](/api-reference/endpoints/api-v1-reports-cash-register-closing.md): Raporti i mbylljes se arkes
- [GET /api/v1/reports/daily-trend](/api-reference/endpoints/api-v1-reports-daily-trend.md): Ecuria ditore
- [GET /api/v1/reports/reversals](/api-reference/endpoints/api-v1-reports-reversals.md): Faturat e anulluara
- [GET /api/v1/reports/sales-summary](/api-reference/endpoints/api-v1-reports-sales-summary.md): Permbledhje e shitjeve
- [GET /api/v1/reports/top-clients](/api-reference/endpoints/api-v1-reports-top-clients.md): Klientet kryesore
- [GET /api/v1/reports/top-products](/api-reference/endpoints/api-v1-reports-top-products.md): Produktet me te shitura
- [GET /api/v1/reports/vat](/api-reference/endpoints/api-v1-reports-vat.md): Raporti i TVSH
- [GET /api/v1/reports/wtn](/api-reference/endpoints/api-v1-reports-wtn.md): Raporti i faturave shoqeruese

## Wolt Partner API

The venue side of a Wolt integration: read the order feed, accept or reject what arrives, move an order through pickup and delivery, and fetch the fiscal invoice it produced.

The feed is append-only and ordered, so it is what a venue's own system should follow to stay in step. The listing endpoints are for backfill and for showing a snapshot.

- [GET /api/partner/v1/wolt/events](/api-reference/endpoints/api-partner-wolt-events.md): Event feed
- [GET /api/partner/v1/wolt/orders](/api-reference/endpoints/api-partner-wolt-orders-list.md): List orders
- [GET /api/partner/v1/wolt/orders/{id}](/api-reference/endpoints/api-partner-wolt-orders-show.md): Get an order
- [POST /api/partner/v1/wolt/orders/{id}/accept](/api-reference/endpoints/api-partner-wolt-orders-accept.md): Accept an order
- [POST /api/partner/v1/wolt/orders/{id}/confirm-preorder](/api-reference/endpoints/api-partner-wolt-orders-confirm-preorder.md): Confirm a pre-order
- [POST /api/partner/v1/wolt/orders/{id}/courier-at-customer](/api-reference/endpoints/api-partner-wolt-orders-courier-at-customer.md): Self-delivery step 2: the courier reached the customer
- [POST /api/partner/v1/wolt/orders/{id}/delivered](/api-reference/endpoints/api-partner-wolt-orders-delivered.md): Close the order
- [GET /api/partner/v1/wolt/orders/{id}/invoice](/api-reference/endpoints/api-partner-wolt-orders-invoice.md): Get the order's fiscal invoice
- [POST /api/partner/v1/wolt/orders/{id}/pickup-completed](/api-reference/endpoints/api-partner-wolt-orders-pickup-completed.md): Self-delivery step 1: the venue's own courier collected the order
- [POST /api/partner/v1/wolt/orders/{id}/ready](/api-reference/endpoints/api-partner-wolt-orders-ready.md): Mark an order ready for handover
- [POST /api/partner/v1/wolt/orders/{id}/reject](/api-reference/endpoints/api-partner-wolt-orders-reject.md): Reject an order
- [POST /api/partner/v1/wolt/orders/{id}/retry-fiscalize](/api-reference/endpoints/api-partner-wolt-orders-retry-fiscalize.md): Retry a deferred or failed fiscalisation for this order
- [GET /api/partner/v1/wolt/ping](/api-reference/endpoints/api-partner-wolt-ping.md): Ping

## Machine-readable

- [OpenAPI 3.1](/api-reference/openapi.json): complete machine-readable specification.
- [Full text](/api-reference/llms-full.txt): every endpoint in one file.
- [Discovery](/api-reference/.well-known/api-docs): index of every documentation surface.