{ "openapi": "3.1.0", "info": { "title": "fature.al API", "version": "1.0.0" }, "servers": [ { "url": "https://fature.al" }, { "url": "https://fature.al", "description": "Production" }, { "url": "https://demo.fature.al", "description": "Sandbox" } ], "tags": [ { "name": "Klienti (v2)", "description": "Versioni 2 i endpoint-eve te klientit. Perdor nje format te ri me objekte te ndara\n(`company`/`person`/`address`/`contact`) dhe nje fushe diskriminuese `type` (company|person).\nIdentifikuesi jepet si objekt `id` me `type` dhe `value`. Lloji (`type`) eshte i pandryshueshem ne editim." }, { "name": "Ping (v1)", "description": "Nje thirrje qe nuk prek asgje, per te provuar lidhjen dhe token-in." }, { "name": "Regjistrimi (v1)", "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 kompanine (`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, njesoj 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": "Faturat (v1)", "description": "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.\n\nTrupi 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." }, { "name": "Arka Fiskale (v1)", "description": "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.\n\nVeprimet regjistrohen ne pajisjen fiskale (TCR) te lidhur me perdoruesin qe ben kerkesen, prandaj pa nje TCR nuk kane ku te shkojne." }, { "name": "Klienti (v1)", "description": "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." }, { "name": "Produkte (v1)", "description": "Katalogu i produkteve dhe kategorite e tyre: lista, detajet, krijimi dhe perditesimi. Keta jane artikujt qe dalin si rreshta ne fature." }, { "name": "Llogaritë bankare (v1)", "description": "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." }, { "name": "Monedhat (v1)", "description": "Monedhat e konfiguruara per kompanine dhe kursi i kembimit i dites, i marre nga kursi.al." }, { "name": "Fletë shoqëruese (v1)", "description": "Fletet shoqeruese (WTN) per mallin qe leviz midis njesive ose drejt nje klienti pa qene shitje: krijimi, lista, detajet dhe te dhenat per printim." }, { "name": "Faturat e blerjes (v1)", "description": "Faturat qe kompania ka marre nga furnitoret, ashtu sic vijne nga sistemi i e-faturave. Vetem lexim: keto dokumente nuk leshohen ketu." }, { "name": "Llogaria (v1)", "description": "Kush eshte perdoruesi qe mban token-in: emri, kompania, NIPT-i, njesia e biznesit, kodi fiskal dhe te drejtat.\n\nEshte thirrja e pare e dobishme kur nis nje integrim, sepse tregon me cfare konteksti do te leshohen faturat." }, { "name": "Paneli (v1)", "description": "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.\n\nPergjigja ruhet ne cache per pak sekonda, prandaj eshte per ekran, jo per rakordim." }, { "name": "Raportet (v1)", "description": "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.\n\nLlogaritja behet ne bazen e te dhenave, prandaj nje raport i pergjigjet pyetjes me shpejt dhe me sakte se marrja e faturave nje nga nje." }, { "name": "Wolt Partner API", "description": "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.\n\nThe 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." } ], "paths": { "/api/partner/v1/wolt/events": { "get": { "operationId": "api.partner.wolt.events", "summary": "Event feed", "description": "The spine of the integration. Poll this endpoint with the last next_cursor\nyou received to get the venue's order lifecycle events in order. The feed is\nappend-only, so nothing is missed across your downtime; delivery is\nat-least-once, so treat (order_id, type) as idempotent. Each event carries a\ncompact snapshot of the order at that moment in `order`.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "since", "in": "query", "description": "The cursor to resume from; pass the previous next_cursor. Defaults to 0, the start of retention. Defaults to `0`.", "schema": { "type": "integer", "example": 10420 } }, { "name": "limit", "in": "query", "description": "Max events to return, 1-200. Defaults to `50`.", "schema": { "type": "integer", "example": 50 } }, { "name": "types", "in": "query", "description": "Comma-separated event types to include, e.g. order.received,order.ready.", "schema": { "type": "string", "example": "order.received,order.ready" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Monotonic cursor id; pass the highest one you have seen as ?since=" }, "type": { "type": "string", "description": "Event type, e.g. order.received, order.accepted, order.ready, order.delivered, order.fiscalized, order.fiscalization_failed" }, "order_id": { "type": "integer", "description": "Fatureal order id the event is about" }, "wolt_order_id": { "type": "string", "description": "Wolt's order id" }, "status": { "type": [ "string", "null" ], "description": "Order status at the moment of the event" }, "occurred_at": { "type": [ "string", "null" ], "description": "When the event occurred (ISO-8601)" }, "order": { "type": "object", "description": "Compact snapshot of the order at that moment", "properties": { "id": { "type": "integer", "description": "Fatureal order id; use this as {id} in the order and action routes" }, "wolt_order_id": { "type": "string", "description": "Wolt's own order id" }, "display_number": { "type": [ "string", "null" ], "description": "Human order number shown to the customer" }, "status": { "type": "string", "description": "Raw Wolt lifecycle status: received, acknowledged, production, ready, picked_up, courier_at_customer, delivered, rejected, refunded, ..." }, "fiscal_state": { "type": "string", "description": "Fiscal state derived from the invoice: pending, deferred, fiscalised or failed" }, "total_amount": { "type": "number", "description": "Charged total in major currency units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "received_at": { "type": [ "string", "null" ], "description": "When Wolt handed the order to us (ISO-8601)" }, "pickup_at": { "type": [ "string", "null" ], "description": "Committed handover time (ISO-8601), set when a pickup time was chosen on accept" }, "delivery_type": { "type": [ "string", "null" ], "description": "Wolt delivery type: takeaway, eatin, homedelivery, ..." }, "self_delivery": { "type": "boolean", "description": "Whether the venue fulfils delivery with its own courier" }, "branch": { "type": [ "string", "null" ], "description": "Branch name" }, "invoice": { "type": [ "object", "null" ], "description": "Linked fiscal invoice reference, or null before fiscalisation" } } } } } }, "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "events", "next_cursor", "has_more" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "events": [ { "id": 1, "type": "type", "order_id": 1, "wolt_order_id": "wolt order id", "status": "status", "occurred_at": "occurred at", "order": { "id": 1, "wolt_order_id": "wolt order id", "display_number": "display number", "status": "status", "fiscal_state": "fiscal state", "total_amount": 4200, "currency": "USD", "received_at": "received at", "pickup_at": "pickup at", "delivery_type": "delivery type", "self_delivery": true, "branch": "branch", "invoice": [] } } ], "next_cursor": "next cursor", "has_more": true } } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders": { "get": { "operationId": "api.partner.wolt.orders.list", "summary": "List orders", "description": "The venue's orders, newest first.\n\nPage backwards by passing the `next_cursor` from the previous response as `?cursor=`. Stop\nwhen `has_more` is `false`.\n\nThis is a snapshot for listing and backfill. For keeping in step with the venue in real time,\npoll the event feed instead: it is append-only and ordered, so nothing is missed.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "cursor", "in": "query", "description": "Return orders older than this id; pass the previous next_cursor.", "schema": { "type": "integer", "example": 10420 } }, { "name": "limit", "in": "query", "description": "Page size, 1-100. Defaults to `25`.", "schema": { "type": "integer", "example": 25 } }, { "name": "status", "in": "query", "description": "Filter by raw Wolt status (e.g. received, acknowledged, ready, delivered).", "schema": { "type": "string", "example": "received" } }, { "name": "from", "in": "query", "description": "Only orders received on/after this date (YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-08-01" } }, { "name": "to", "in": "query", "description": "Only orders received on/before this date (YYYY-MM-DD).", "schema": { "type": "string", "example": "2026-08-31" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "orders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Fatureal order id; use this as {id} in the order and action routes" }, "wolt_order_id": { "type": "string", "description": "Wolt's own order id" }, "display_number": { "type": [ "string", "null" ], "description": "Human order number shown to the customer" }, "status": { "type": "string", "description": "Raw Wolt lifecycle status: received, acknowledged, production, ready, picked_up, courier_at_customer, delivered, rejected, refunded, ..." }, "fiscal_state": { "type": "string", "description": "Fiscal state derived from the invoice: pending, deferred, fiscalised or failed" }, "total_amount": { "type": "number", "description": "Charged total in major currency units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "received_at": { "type": [ "string", "null" ], "description": "When Wolt handed the order to us (ISO-8601)" }, "pickup_at": { "type": [ "string", "null" ], "description": "Committed handover time (ISO-8601), set when a pickup time was chosen on accept" }, "delivery_type": { "type": [ "string", "null" ], "description": "Wolt delivery type: takeaway, eatin, homedelivery, ..." }, "self_delivery": { "type": "boolean", "description": "Whether the venue fulfils delivery with its own courier" }, "branch": { "type": [ "string", "null" ], "description": "Branch name" }, "invoice": { "type": [ "object", "null" ], "description": "Linked fiscal invoice reference, or null before fiscalisation", "properties": { "id": { "type": "integer", "description": "Fatureal invoice id" }, "number": { "description": "Fiscal invoice number, once assigned" }, "state": { "type": "string", "description": "Fiscal state: pending, deferred, fiscalised or failed" }, "fiscal_iic": { "description": "Fiscal IIC (NSLF), once fiscalised" }, "fiscal_fic": { "description": "Fiscal FIC (NIVF), once fiscalised" } } } } } }, "next_cursor": { "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "orders", "next_cursor", "has_more" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "orders": [ { "id": 1, "wolt_order_id": "wolt order id", "display_number": "display number", "status": "status", "fiscal_state": "fiscal state", "total_amount": 4200, "currency": "USD", "received_at": "received at", "pickup_at": "pickup at", "delivery_type": "delivery type", "self_delivery": true, "branch": "branch", "invoice": { "id": 1, "number": "number", "state": "state", "fiscal_iic": "fiscal iic", "fiscal_fic": "fiscal fic" } } ], "next_cursor": "next cursor", "has_more": true } } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}": { "get": { "operationId": "api.partner.wolt.orders.show", "summary": "Get an order", "description": "The authoritative snapshot of one order: header, parties, lines, totals and\nfiscal linkage.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/accept": { "post": { "operationId": "api.partner.wolt.orders.accept", "summary": "Accept an order", "description": "Relays acceptance to Wolt. No fiscal invoice is created here: that happens when the order is\nmarked ready.\n\n`pickup_minutes` means two different things depending on the order:\n\n| Order type | What `pickup_minutes` commits to |\n| --- | --- |\n| Marketplace | When the food will be ready, so Wolt dispatches a courier to match |\n| Self-delivery | The **total delivery time** promised to the customer |\n\nGetting this wrong on a marketplace order sends a courier to wait, or leaves food going cold.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pickup_minutes": { "type": "integer", "description": "Minutes from now until ready, 5-180.", "example": 20 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "pickup_minutes is outside 5-180, or the action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/confirm-preorder": { "post": { "operationId": "api.partner.wolt.orders.confirm-preorder", "summary": "Confirm a pre-order", "description": "Confirms a customer-scheduled pre-order. It is parked until Wolt releases it\ninto production near its due time, after which it can be marked ready.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/courier-at-customer": { "post": { "operationId": "api.partner.wolt.orders.courier-at-customer", "summary": "Self-delivery step 2: the courier reached the customer", "description": "Only for **self-delivery** orders, and only after `pickup-completed`. Wolt notifies the\ncustomer that the courier has arrived, so send it when that is actually true rather than in\nadvance.\n\nThe order moves to `courier_at_customer`. The drop-off itself is confirmed separately with\n`delivered`.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/delivered": { "post": { "operationId": "api.partner.wolt.orders.delivered", "summary": "Close the order", "description": "The final step, used in two situations:\n\n- **Takeaway**: the customer has collected the order after it was marked ready.\n- **Self-delivery**: your courier has handed it over, after `courier-at-customer`.\n\nMarketplace orders do not need this: a Wolt courier collects them and Wolt closes them.\n\nThe order moves to `delivered` and leaves the active board.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/invoice": { "get": { "operationId": "api.partner.wolt.orders.invoice", "summary": "Get the order's fiscal invoice", "description": "Returns the fiscal invoice issued for the order: `IIC`, `FIC` and `EIC` identifiers,\nverification through `pdf_url`, the client, the amounts and the lines.\n\nThe invoice object is identical to the one from `GET /api/v1/invoice/{id}/details`, so anything\nalready written against that endpoint works here unchanged.\n\n## While it is still null\n\n`invoice` is `null` until the order has been fiscalised. Track `fiscal_state` rather than\npolling blindly:\n\n| `fiscal_state` | Meaning |\n| --- | --- |\n| `pending` | No invoice yet. Mark the order ready to create one |\n| `deferred` | Issued, waiting on the tax service. It will complete on its own |\n| `fiscalised` | Done. `invoice` is populated |\n| `failed` | Needs a retry |\n\nBetter still, watch the `order.fiscalized` event on the feed instead of polling.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "fiscal_state": { "type": "string" }, "invoice": { "type": [ "object", "null" ], "properties": { "lines": { "type": "array", "items": { "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 with the line discount already taken off, 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": "Line discount percent, as sent in `lines[].discount` when the line was discounted" }, "discount": { "type": [ "number", "null" ], "description": "Line discount amount, net-denominated, major units" }, "amount_net": { "type": "number" }, "amount_vat": { "type": "number" }, "total": { "type": "number", "description": "Gross line total, major units" } } } } } } }, "required": [ "fiscal_state", "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "fiscal_state": "fiscal state", "invoice": { "lines": [ { "name": "Jane Doe", "product_code": "product code", "unit": "unit", "unit_code": "unit code", "quantity": 2, "unitPrice": 1999, "vat_rate": 19.99, "vat_exempt_type": "vat exempt type", "discount_rate": 3, "discount": 3, "amount_net": 4200, "amount_vat": 4200, "total": 4200 } ] } } } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/pickup-completed": { "post": { "operationId": "api.partner.wolt.orders.pickup-completed", "summary": "Self-delivery step 1: the venue's own courier collected the order", "description": "Only for **self-delivery** orders, where the venue delivers with its own courier rather than a\nWolt one. Marketplace and takeaway orders never call this.\n\nThis is **not** delivery. The order moves to `picked_up` and stays open through\n`courier-at-customer` and `delivered`, so it remains on the board until the drop-off is\nconfirmed.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/ready": { "post": { "operationId": "api.partner.wolt.orders.ready", "summary": "Mark an order ready for handover", "description": "**This is the step that creates the fiscal invoice.** If the order has no invoice yet, one is\nissued and fiscalised here, so marking ready is the point at which the sale becomes a legal\ndocument. Calling it again on an order that already has one does not issue a second.\n\nWhat happens next depends on the delivery type:\n\n| Delivery type | After ready |\n| --- | --- |\n| Marketplace | A Wolt courier collects the order |\n| Takeaway | The customer collects it, then call `delivered` |\n| Self-delivery | Call `pickup-completed`, then `courier-at-customer`, then `delivered` |\n\nThe order moves to status `ready`.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/reject": { "post": { "operationId": "api.partner.wolt.orders.reject", "summary": "Reject an order", "description": "Declines the order and relays the refusal to Wolt. This is terminal: a rejected order cannot\nbe accepted afterwards, and no fiscal invoice is created for it.\n\n| Field | Notes |\n| --- | --- |\n| `reason` | Free text, up to 255 characters. **Wolt may show it to the customer**, so keep it presentable |\n| `code` | `GENERIC`, `ITEMS_UNAVAILABLE` or `VENUE_CLOSING_SOON`. Defaults to `GENERIC` |\n\nBoth are optional, but sending a specific `code` helps Wolt route the customer to a sensible\nalternative instead of a generic apology.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": [ "string", "null" ], "description": "A short human-readable reason; Wolt may show it to the customer.", "example": "Kitchen is closing", "maxLength": 255 }, "code": { "type": [ "string", "null" ], "description": "Machine reason code. Defaults to GENERIC.", "example": "ITEMS_UNAVAILABLE" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The reject code is not one of GENERIC, ITEMS_UNAVAILABLE or VENUE_CLOSING_SOON, or the action failed on our side. A validation failure adds an errors object to the envelope.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/orders/{id}/retry-fiscalize": { "post": { "operationId": "api.partner.wolt.orders.retry-fiscalize", "summary": "Retry a deferred or failed fiscalisation for this order", "description": "Use it when `fiscal_state` is `deferred` or `failed`, which happens when the tax service was\nunreachable at the moment the invoice was issued. The retry does whichever of these applies:\n\n- the order already has an unfiscalised invoice, so that invoice is fiscalised;\n- the order has no invoice at all, so one is issued and fiscalised now.\n\n**A cancelled order cannot be fiscalised** and the call is refused. Retrying an order that is\nalready fiscalised is harmless and changes nothing.", "tags": [ "Wolt Partner API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The order's Fatureal id, from the feed or the order list.", "schema": { "type": "integer", "example": 8801 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Your own unique key for this action. A retry with the same key replays the first result instead of relaying a second action to Wolt, and the replay carries an Idempotent-Replayed: true header. Kept for 24 hours.", "schema": { "type": "string", "example": "a2f1c9e4-5b60-4d7a-9c31-8e0f2b6d4a17" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "order": { "type": "object", "properties": { "customer": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ], "description": "Shared by Wolt only for self-delivery orders" }, "note": { "type": [ "string", "null" ], "description": "Customer note left with the order" } } }, "company": { "type": [ "object", "null" ], "description": "B2B billing company, or null for a normal consumer order", "properties": { "tax_id": { "type": "string", "description": "Tax id (NUIS/NIPT) the customer asked to bill" }, "name": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] } } }, "preorder": { "type": [ "object", "null" ], "description": "Scheduled pre-order info, or null for an instant order", "properties": { "time": { "type": "string", "description": "Scheduled time (ISO-8601)" }, "status": { "type": [ "string", "null" ], "description": "Wolt pre-order status" } } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "quantity": { "type": "number" }, "unit_price": { "type": "number", "description": "Unit price in major units" }, "total": { "type": "number", "description": "Line total in major units, after discount" }, "discount": { "type": "number", "description": "Discount applied to the line, major units" }, "product": { "type": [ "object", "null" ], "description": "Linked internal product, or null when the Wolt item is unmapped" }, "options": { "type": "array", "description": "Chosen modifiers/options for the line" } } } }, "totals": { "type": "object", "properties": { "subtotal_before_discount": { "type": "number", "description": "Basket total before any discount, major units" }, "discount": { "type": "number", "description": "Total discount applied, major units" }, "total": { "type": "number", "description": "Charged total, major units" }, "currency": { "type": "string", "description": "ISO 4217 currency code" }, "campaigns": { "type": "array", "description": "Applied promotion labels" } } } } } }, "required": [ "order" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "order": { "customer": { "name": "Jane Doe", "phone": "+15551234567", "note": "note" }, "company": { "tax_id": "tax id", "name": "Jane Doe", "address": "1 Example Street" }, "preorder": { "time": "time", "status": "status" }, "lines": [ { "name": "Jane Doe", "quantity": 2, "unit_price": 1999, "total": 4200, "discount": 3, "product": [], "options": [ "options" ] } ], "totals": { "subtotal_before_discount": 4200, "discount": 3, "total": 4200, "currency": "USD", "campaigns": [ "campaigns" ] } } } } } } } } }, "400": { "description": "The Idempotency-Key header is missing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "404": { "description": "No such order for this venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "409": { "description": "The order's current status does not allow this action, or a call with the same Idempotency-Key is still in flight. Nothing was relayed to Wolt.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "422": { "description": "The action failed on our side and was not completed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 60 writes a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "502": { "description": "Wolt refused or did not answer. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/partner/v1/wolt/ping": { "get": { "operationId": "api.partner.wolt.ping", "summary": "Ping", "description": "Verify the token and return the single Wolt venue it is bound to. Call this\nfirst to confirm credentials and discover which company/branch/venue the\ntoken operates on.", "tags": [ "Wolt Partner API" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "company": { "type": "string" }, "branch": { "type": "string" }, "venue_id": { "type": "string" }, "connection_status": { "type": "string" }, "server_time": { "type": "string" } }, "required": [ "company", "branch", "venue_id", "connection_status", "server_time" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "company": "company", "branch": "branch", "venue_id": "venue id", "connection_status": "connection status", "server_time": "server time" } } } } } } }, "403": { "description": "The company has no Wolt add-on, the token has no Wolt right, or it resolves to no single active venue.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false" }, "message": { "type": "string", "description": "Localised explanation, safe to log but not to branch on" }, "code": { "type": "string", "description": "Stable machine readable reason: `unauthenticated`, `wolt_not_enabled`, `forbidden`, `no_venue`, `order_not_found`, `invalid_transition`, `invalid_data`, `action_failed`, `wolt_upstream_error`, `idempotency_key_required`, `idempotency_in_progress`" } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "code": "code" } } } } } }, "429": { "description": "Rate limit reached: 180 reads a minute per token. Retry after the number of seconds in the Retry-After header.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/account": { "get": { "operationId": "get-api-v1-account", "summary": "Te dhenat e llogarise", "description": "Kthen te dhenat e perdoruesit te autentifikuar: emri, email, kodi fiskal dhe kompania.", "tags": [ "Llogaria (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "fiscalCode": {}, "company": {}, "nipt": {}, "setupFinished": { "type": "boolean" }, "branch": { "type": "object", "properties": { "name": { "type": "string" }, "address": {}, "city": {} } }, "companyBranches": {}, "permissions": { "type": "object", "properties": { "createArticles": { "type": "boolean" }, "createClients": { "type": "boolean" } } }, "configs": { "type": "object", "properties": { "openDayAlways0": {} } }, "vatConfigs": { "type": "object", "properties": { "issuerInVat": {}, "vat_rates": {}, "vat_exempts": {} } }, "subscription": { "type": "object", "properties": { "cash": {}, "noncash": {}, "einvoice": {}, "wtn": {} } } } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "name": "Jane Doe", "email": "jane@example.com", "fiscalCode": "fiscalCode", "company": "company", "nipt": "nipt", "setupFinished": true, "branch": { "name": "Jane Doe", "address": "1 Example Street", "city": "Berlin" }, "companyBranches": "companyBranches", "permissions": { "createArticles": true, "createClients": true }, "configs": { "openDayAlways0": "openDayAlways0" }, "vatConfigs": { "issuerInVat": "issuerInVat", "vat_rates": "vat rates", "vat_exempts": "vat exempts" }, "subscription": { "cash": "cash", "noncash": "noncash", "einvoice": "einvoice", "wtn": "wtn" } } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/bank-accounts": { "get": { "operationId": "api.v1.bank-accounts.list", "summary": "Lista e llogarive bankare", "description": "Merr listen e llogarive bankare aktive te kompanise me faqosje dhe filtrim me tekst.", "tags": [ "Llogaritë bankare (v1)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i llogarive per faqe (max 100). Defaults to `20`.", "schema": { "type": "integer", "example": 20 } }, { "name": "offset", "in": "query", "description": "Nga cila llogari te fillohet. Defaults to `0`.", "schema": { "type": "integer", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "bank_name": { "type": [ "string", "null" ] }, "iban": { "type": [ "string", "null" ] }, "swift": { "type": [ "string", "null" ] }, "holder": { "type": [ "string", "null" ] }, "currency_code": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "valid_from": { "type": [ "string", "null" ] }, "valid_to": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "items": [ { "id": 1, "bank_name": "Jane Doe", "iban": "iban", "swift": "swift", "holder": "holder", "currency_code": "USD", "is_default": true, "notes": "notes", "valid_from": "valid from", "valid_to": "valid to", "created_at": "created at" } ], "pagination": { "records": 1, "total": 4200, "limit": 25, "offset": 0 } } } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/cash-register/actions": { "get": { "operationId": "api.v1.cash-register.list", "summary": "Lista e veprimeve me arken", "description": "Historiku i arkes: hyrjet, daljet dhe hapjet me mbylljet e dites, me filtrim dhe faqosje.\n\n| `type` | Veprimi |\n| --- | --- |\n| `MONEY_IN` | Hyrje parash |\n| `MONEY_OUT` | Dalje parash |\n| `OPEN_DAY` | Hapje e dites |\n| `CLOSE_DAY` | Mbyllje e dites |\n\nDisa tipe ndahen me presje, pra `type=MONEY_IN,MONEY_OUT` kthen vetem levizjet e parave.\nFaqezohet me `limit` dhe `offset`.", "tags": [ "Arka Fiskale (v1)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i veprimeve per faqe. Defaults to `20`.", "schema": { "type": "integer", "example": 20 } }, { "name": "offset", "in": "query", "description": "Nga cili veprim te fillohet. Defaults to `0`.", "schema": { "type": "integer", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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", "null" ] }, "fiscal_uuid": { "type": [ "string", "null" ] }, "fiscal_fic": { "type": [ "string", "null" ] }, "fiscal_tcr_code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "third_party": { "type": [ "string", "null" ] }, "id_client": { "type": [ "integer", "null" ] }, "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", "null" ] } }, "required": [ "records", "limit", "offset", "type" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "items": [ { "id": 1, "action_type": "action type", "amount": 4200, "currency": "USD", "transaction_date": "transaction date", "transaction_no": 1, "cash_action_no": "cash action no", "fiscal_status": "fiscal status", "fiscal_uuid": "9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c", "fiscal_fic": "fiscal fic", "fiscal_tcr_code": "fiscal tcr code", "description": "A short description.", "third_party": "third party", "id_client": 1, "created_at": "created at" } ], "pagination": { "records": 1, "limit": 25, "offset": 0, "type": "type" } } } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/cash-register/balance": { "get": { "operationId": "api.v1.cash-register.balance", "summary": "Balanca e arkes fiskale", "description": "Kthen gjendjen e arkes fiskale (TCR) te perdoruesit, ne ALL.\n\nPa `toDate` kthehet balanca e fundit. Me `toDate` llogaritet gjendja sic ka qene ne fund te asaj\ndite, cka e ben te dobishme per rakordim me nje dite te shkuar.", "tags": [ "Arka Fiskale (v1)" ], "parameters": [ { "name": "toDate", "in": "query", "description": "Data deri te cila llogaritet balanca. Pa te kthehet balanca e fundit.", "schema": { "type": [ "string", "null" ], "format": "date", "description": "Data deri te cila llogaritet balanca. Pa te kthehet balanca e fundit.", "example": "2026-04-21" } } ], "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/cash-register/close-balance": { "post": { "operationId": "api.v1.cash-register.close", "summary": "Mbyll balancen e arkes", "description": "Mbyll diten ne arken fiskale dhe regjistron veprimin `CLOSE_DAY`.\n\n**Nese arka nuk eshte e hapur, hapet vete me balance `0` dhe mbyllet menjehere.** Kjo do te\nthote se thirrja nuk deshton kurre sepse dita nuk u hap, prandaj mund ta thirrni ne fund te\nturnit pa kontrolluar me pare gjendjen.\n\nPer shifrat e turnit qe sapo u mbyll perdorni raportin e mbylljes se arkes.", "tags": [ "Arka Fiskale (v1)" ], "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale ose mbyllja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "balance": 19.99 } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/cash-register/deposit": { "post": { "operationId": "api.v1.cash-register.deposit", "summary": "Hyrje ne arke (Deposit)", "description": "Regjistron para qe hyjne ne arke pa qene shitje, si nje arketim nga klienti ose nje fond fillestar.\nVeprimi ruhet si `MONEY_IN`.\n\n- `amount` duhet te jete gjithmone me e madhe se `0`. Per para qe dalin perdorni endpoint-in e\n daljes, jo nje vlere negative ketu.\n- `description` dhe pala e trete jane opsionale por ndihmojne ne rakordim.\n- Kerkon nje pajisje fiskale (TCR) te lidhur.", "tags": [ "Arka Fiskale (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 tuaj, per ta lidhur veprimin me te. Kthehet me pas ne listen e veprimeve. Nje ID qe nuk i perket kompanise suaj refuzohet.", "example": 42 } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale ose arka nuk ka fonde te mjaftueshme, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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", "null" ] }, "fiscal_uuid": { "type": [ "string", "null" ] }, "fiscal_fic": { "type": [ "string", "null" ] }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "id": 1, "action_type": "action type", "amount": 4200, "currency": "USD", "transaction_date": "transaction date", "transaction_no": 1, "cash_action_no": "cash action no", "fiscal_status": "fiscal status", "fiscal_uuid": "9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c", "fiscal_fic": "fiscal fic", "description": "A short description." } } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/cash-register/open-balance": { "post": { "operationId": "api.v1.cash-register.open", "summary": "Hap balancen e arkes", "description": "Hap diten ne arken fiskale, hapi qe duhet para se te leshohet fatura e pare cash.\n\n- `balance` eshte gjendja me te cilen nis dita. Pa te merret `0`.\n- Perdoruesi duhet te kete nje pajisje fiskale (TCR) te lidhur, perndryshe veprimi nuk ka ku\n te regjistrohet.\n\nHapja regjistrohet si veprim `OPEN_DAY` dhe del ne listen e veprimeve.", "tags": [ "Arka Fiskale (v1)" ], "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`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "balance": { "type": "number" } }, "required": [ "balance" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "balance": 19.99 } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/cash-register/withdraw": { "post": { "operationId": "api.v1.cash-register.withdraw", "summary": "Dalje nga arka (Withdraw)", "description": "Regjistron para qe dalin nga arka, si nje pagese furnitori ose terheqje ne fund te dites.\nVeprimi ruhet si `MONEY_OUT`.\n\n- `amount` duhet te jete gjithmone me e madhe se `0`. Shenja vjen nga endpoint-i qe thirret,\n jo nga numri.\n- Kerkon nje pajisje fiskale (TCR) te lidhur.", "tags": [ "Arka Fiskale (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 tuaj, per ta lidhur veprimin me te. Kthehet me pas ne listen e veprimeve. Nje ID qe nuk i perket kompanise suaj refuzohet.", "example": 42 } }, "required": [ "amount" ] } } } }, "responses": { "200": { "description": "Kur perdoruesi nuk ka pajisje fiskale ose arka nuk ka fonde te mjaftueshme, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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", "null" ] }, "fiscal_uuid": { "type": [ "string", "null" ] }, "fiscal_fic": { "type": [ "string", "null" ] }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "id": 1, "action_type": "action type", "amount": 4200, "currency": "USD", "transaction_date": "transaction date", "transaction_no": 1, "cash_action_no": "cash action no", "fiscal_status": "fiscal status", "fiscal_uuid": "9f8c7b6a-5d4e-3f2a-1b0c-9d8e7f6a5b4c", "fiscal_fic": "fiscal fic", "description": "A short description." } } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/client/search": { "get": { "operationId": "api.v1.client.search", "summary": "Kerko klient sipas NIPT", "description": "Kerkon nje kompani ne **regjistrin fiskal** me NIPT/NUIS dhe kthen te dhenat e saj.\n\nPerdoreni per te mbushur vete formularin e nje klienti te ri: kerkoni nje fushe te vetme nga\nperdoruesi dhe merrni emrin, adresen dhe qytetin nga regjistri. Nje NIPT i gabuar kapet ketu,\npara se te dale ne nje fature.\n\nFusha `verified` thote nese kompania u gjet e konfirmuar ne regjister.\n\nDalloni dy pergjigjet qe duken te ngjashme:\n\n- `404`, NIPT-i nuk ekziston ne regjister;\n- `503`, regjistri nuk u arrit, pra NIPT-i mbeti i pakontrolluar. Provoni perseri.", "tags": [ "Klienti (v1)" ], "parameters": [ { "name": "nuis", "in": "query", "required": true, "description": "NIPT/NUIS i kompanise per te kerkuar, ne formatin X00000000X.", "schema": { "type": "string", "example": "L91806031A" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "nuis": "nuis", "name": "Jane Doe", "address": "1 Example Street", "city": "Berlin", "country": 1, "country_code": "US", "verified": true } } } } } } } }, "404": { "description": "NIPT-i nuk gjendet ne regjistrin fiskal.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "NIPT-i mungon ose nuk eshte ne formatin X00000000X. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "503": { "description": "Regjistri fiskal nuk u arrit, keshtu qe NIPT-i mbeti i pakontrolluar. Provoni perseri.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/clients": { "get": { "operationId": "api.v1.clients.list", "summary": "Lista e klienteve", "description": "Merr listen e klienteve te kompanise me faqosje dhe filtrim me tekst.\n\nFaqezohet me `limit` dhe `offset`. `limit` kufizohet ne **100** dhe `pagination` kthen edhe\n`total`, prandaj e dini qe ne faqen e pare sa faqe ju presin: vazhdoni me `offset += limit`\nderisa `offset` te kaloje `total`.", "tags": [ "Klienti (v1)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i klienteve per faqe (max 100). Defaults to `20`.", "schema": { "type": "integer", "example": 20 } }, { "name": "offset", "in": "query", "description": "Nga cili klient te fillohet. Defaults to `0`.", "schema": { "type": "integer", "example": 0 } }, { "name": "query", "in": "query", "description": "Kerkim ne emer, mbiemer, NIPT, dokument, email ose telefon.", "schema": { "type": "string", "example": "Agon" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "nipt": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "surname": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "nationality_code": { "type": [ "string", "null" ] }, "nationality_id": { "type": [ "integer", "null" ] }, "telephone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "customer_number": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "items": [ { "id": 1, "name": "Jane Doe", "client_type": "client type", "company_name": "Jane Doe", "company_type": "company type", "nipt": "nipt", "first_name": "Jane", "surname": "Jane Doe", "birthday": "birthday", "id_type": "id type", "id_num": "id num", "nationality_code": "nationality code", "nationality_id": 1, "telephone": "+15551234567", "email": "jane@example.com", "address": "1 Example Street", "city": "Berlin", "customer_number": "customer number", "created_at": "created at" } ], "pagination": { "records": 1, "total": 4200, "limit": 25, "offset": 0 } } } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] }, "post": { "operationId": "api.v1.clients.create", "summary": "Krijo klient", "description": "Trupi ndryshon sipas `client_type`, i cili pranon `COMPANY` ose `PERSON`.\n\n| `client_type` | Fushat e detyrueshme |\n| --- | --- |\n| `COMPANY` | `company_name`, `nipt`, `address`, `city` |\n| `PERSON` | vetem emri |\n\n`company_type` eshte opsional dhe pranon `BUSINESS`, `BANK` ose `EXCHANGE`.\n\nPer nje kompani shqiptare, thirrni me pare `GET /client/search` me NIPT-in: ju kthen emrin,\nadresen dhe qytetin gati per ketu.", "tags": [ "Klienti (v1)" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "nationality_code": { "type": [ "string", "null" ], "description": "Kodi ISO 3166-1 alpha-3 i kombesise. 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" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "nipt": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "surname": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "nationality_code": { "type": [ "string", "null" ] }, "nationality_id": { "type": [ "integer", "null" ] }, "telephone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "customer_number": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "id": 1, "name": "Jane Doe", "client_type": "client type", "company_name": "Jane Doe", "company_type": "company type", "nipt": "nipt", "first_name": "Jane", "surname": "Jane Doe", "birthday": "birthday", "id_type": "id type", "id_num": "id num", "nationality_code": "nationality code", "nationality_id": 1, "telephone": "+15551234567", "email": "jane@example.com", "address": "1 Example Street", "city": "Berlin", "customer_number": "customer number", "created_at": "created at" } } } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Ekziston tashme nje regjistrim me te njejtat te dhena.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/clients/{id}": { "put": { "operationId": "api.v1.clients.update", "summary": "Perditeso klient", "description": "Perditeson nje klient ekzistues. Trupi ka te njejtin format si `POST /clients`, prandaj vlejne\nte njejtat fusha te detyrueshme sipas `client_type`.", "tags": [ "Klienti (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "nationality_code": { "type": [ "string", "null" ], "description": "Kodi ISO 3166-1 alpha-3 i kombesise. 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" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "nipt": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "surname": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "nationality_code": { "type": [ "string", "null" ] }, "nationality_id": { "type": [ "integer", "null" ] }, "telephone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "customer_number": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "id": 1, "name": "Jane Doe", "client_type": "client type", "company_name": "Jane Doe", "company_type": "company type", "nipt": "nipt", "first_name": "Jane", "surname": "Jane Doe", "birthday": "birthday", "id_type": "id type", "id_num": "id num", "nationality_code": "nationality code", "nationality_id": 1, "telephone": "+15551234567", "email": "jane@example.com", "address": "1 Example Street", "city": "Berlin", "customer_number": "customer number", "created_at": "created at" } } } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Ekziston tashme nje klient me te njejtat te dhena.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/clients/{id}/details": { "get": { "operationId": "api.v1.clients.details", "summary": "Detajet e klientit sipas ID", "description": "Kthen nje klient te vetem me te gjitha fushat, si per kompani ashtu edhe per person. Fushat qe\nnuk i perkasin llojit te klientit kthehen `null`.", "tags": [ "Klienti (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "nipt": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "surname": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "nationality_code": { "type": [ "string", "null" ] }, "nationality_id": { "type": [ "integer", "null" ] }, "telephone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "customer_number": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "id": 1, "name": "Jane Doe", "client_type": "client type", "company_name": "Jane Doe", "company_type": "company type", "nipt": "nipt", "first_name": "Jane", "surname": "Jane Doe", "birthday": "birthday", "id_type": "id type", "id_num": "id num", "nationality_code": "nationality code", "nationality_id": 1, "telephone": "+15551234567", "email": "jane@example.com", "address": "1 Example Street", "city": "Berlin", "customer_number": "customer number", "created_at": "created at" } } } } } } } }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/currencies": { "get": { "operationId": "api.v1.currencies.list", "summary": "Lista e monedhave", "description": "Kthen monedhat e konfiguruara per kompanine, me ALL gjithmone ne fillim.", "tags": [ "Monedhat (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "currencies": [ { "id": 1, "code": "code", "name": "Jane Doe" } ] } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/dashboard/summary": { "get": { "operationId": "api.v1.dashboard.summary", "summary": "Permbledhja e dites", "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.", "tags": [ "Paneli (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": {} } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": "data" } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 kerkesa ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/exchange-rates": { "get": { "operationId": "api.v1.exchange-rates", "summary": "Kursi i kembimit", "description": "Kthen kursin e shitjes se dites per cdo monedhe, sipas burimit te zgjedhur. Te dhenat\nvijne nga `https://api.kursi.al/api/rates` dhe ruhen ne cache per nje ore ne server,\nprandaj klienti mund ta mbaje snapshot-in e fundit lokalisht dhe te punoje edhe pa internet.\n\nBurimet e mbeshtetura (vlera `source` ne kerkese):\n - `BOA` -> Banka e Shqiperise (kursi zyrtar)\n - `BKT` -> Banka Kombetare Tregtare\n - `Iliria98` -> Kembim Valutor \"Iliria '98\"\n - `ADON` -> Kembim Valutor \"Adon\"\n\nNje burim i papercaktuar kthehet automatikisht ne `BOA`. Fusha `source` ne pergjigje\neshte gjithmone vlera e normalizuar.", "tags": [ "Monedhat (v1)" ], "parameters": [ { "name": "source", "in": "query", "description": "Burimi i kursit: BOA, BKT, Iliria98 ose ADON. Defaults to `BOA`.", "schema": { "type": "string", "example": "BOA" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "rates": { "type": "object" }, "source": { "type": "string" }, "fetchedAt": { "type": "string" } }, "required": [ "rates", "source", "fetchedAt" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "rates": [], "source": "source", "fetchedAt": "fetchedAt" } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice": { "get": { "operationId": "get-api-v1-invoice", "summary": "Lista e faturave", "description": "Merrni listen e faturave me filtrim dhe faqosje.", "tags": [ "Faturat (v1)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i faturave per faqe. Defaults to `20`.", "schema": { "type": "integer", "example": 10 } }, { "name": "offset", "in": "query", "description": "Nga cila fature te fillohet. Defaults to `0`.", "schema": { "type": "integer", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "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": { "type": "object", "properties": { "name": { "type": "string", "description": "Full name (or company name)" }, "id": { "type": "object", "properties": { "type": { "description": "Identifier type, e.g. NUIS, ID, PASSPORT" }, "id": { "description": "The identifier value" } } }, "address": { "type": "object", "properties": { "street": {}, "city": {}, "country": { "description": "ISO 3166-1 alpha-3 country code, defaults to ALB" } } } } }, "amount": { "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", "description": "Gross total, already reduced by the invoice discount" }, "net": { "type": "number", "description": "Net total, already reduced by the invoice discount" }, "vat": { "type": "number" }, "discount": { "type": "number", "description": "The invoice-level discount, net-denominated: how much net came off the whole invoice. Line discounts are not in here; those are per line, on `lines[].discount`. Zero when the invoice carries no invoice discount" }, "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": "Invoice-level discount converted to the local currency (ALL)" }, "local_currency": { "type": [ "object", "null" ], "description": "Present only on a foreign-currency invoice" } } }, "payment_method": { "type": [ "string", "null" ] }, "payment": { "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" } } }, "bank_account": { "type": [ "object", "null" ], "description": "Bank account printed on the invoice, or null", "properties": { "id": { "type": "integer" }, "bank_name": {}, "iban": {}, "swift": {}, "currency": { "description": "ISO 4217 currency code" }, "notes": {} } }, "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" ], "description": "UBL document type: 380 invoice, 381 credit note, 383 debit note. Null on a plain fiscal invoice" }, "process": { "type": [ "string", "null" ], "description": "UBL ProfileID: P1 for a sale, P9 for a correction. Set on e-invoices" }, "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" } } } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "query": { "type": [ "string", "null" ] } }, "required": [ "records", "limit", "offset", "type", "query" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "items": [ { "id": 1, "number": "number", "type": "type", "issue_date": "issue date", "due_date": "due date", "delivery_date": "delivery date", "created_at": "created at", "supply_start_date": "supply start date", "supply_end_date": "supply end date", "client": { "name": "Jane Doe", "id": { "type": "type", "id": 1 }, "address": { "street": "street", "city": "Berlin", "country": "US" } }, "amount": { "currency": "USD", "exchange_rate": 19.99, "gross": 19.99, "net": 19.99, "vat": 19.99, "discount": 3, "net_all": 19.99, "gross_all": 19.99, "vat_all": 19.99, "discount_all": 3, "local_currency": [] }, "payment_method": "payment method", "payment": { "state": "state", "amount_paid": 4200, "amount_left": 4200 }, "bank_account": { "id": 1, "bank_name": "Jane Doe", "iban": "iban", "swift": "swift", "currency": "USD", "notes": "notes" }, "notes": "notes", "iic": "iic", "fic": "fic", "eic": "eic", "doc_type": "doc type", "process": "process", "self_issue_type": "self issue type", "reversed_at": "reversed at", "reversed_by": 1, "pdf_url": "https://example.com", "reverse_charge": true, "periodic_invoice": true } ], "pagination": { "records": 1, "limit": 25, "offset": 0, "type": "type", "query": "query" } } } } } } } }, "422": { "description": "Formati i datave nuk eshte YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/bulk-noncash": { "post": { "operationId": "post-api-v1-invoice-bulk-noncash", "summary": "Krijo fatura pa para ne dore ne bllok (Bulk NonCash)", "description": "Leshon shume fatura jo-cash me nje kerkese te vetme, e menduar per faturim periodik.\n\nPergjigja eshte nje objekt me nje hyrje per cdo `internalId`, dhe statusi mbetet `200` edhe kur\nndonje fature brenda bllokut deshton. Prandaj:\n\n- mos u mbeshtetni tek kodi HTTP per te ditur nese gjithcka shkoi mire;\n- kontrolloni `status` brenda cdo hyrjeje me vete;\n- riprovoni vetem `internalId` qe deshtuan, jo te gjithe bllokun.", "tags": [ "Faturat (v1)" ], "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 shume blloqeve te vogla." } }, "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." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "example": { "summary": "Example", "value": [] } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/cancel-by-internal-id/{internalId}": { "post": { "operationId": "post-api-v1-invoice-cancel-by-internal-id-internalid", "summary": "Anulo fature sipas Internal ID", "description": "Anulon faturen duke perdorur ID-ne tuaj interne qe keni derguar kur keni krijuar faturen.\n\nSillet njesoj si anulimi sipas ID, vetem se e gjen faturen me numrin tuaj:\n\n- pa trup anulohet e gjithe fatura;\n- me `lines` anulohet vetem nje pjese, e mundur **vetem per faturat Cash**;\n- rreshtat duhet te perputhen ne `product_code` dhe `product_name`, dhe sasia vetem ulet;\n- nje fature me zbritje mbi te gjithe faturen anulohet vetem e plote.\n\nPerdoreni kur nuk doni te mbani `id` e fature.al prane shitjes tuaj.", "tags": [ "Faturat (v1)" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "ID juaj interne, e derguar kur u krijua fatura.", "schema": { "type": "string", "example": "CASH-001" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "description": "Rreshtat qe anulohen. Pa te anulohet e gjithe fatura; me te anulohet vetem pjesa e derguar, e mundur vetem per faturat Cash. Cdo rresht duhet te ekzistoje ne faturen origjinale me te njejtin `product_code` dhe `product_name`, dhe sasia mund vetem te ulet. Nje fature qe u leshua me zbritje mbi te gjithe faturen nuk pranon anulim te pjesshem:\ndergojeni kerkesen pa `lines` qe te anulohet e plote.", "items": { "type": "object", "properties": { "product_name": { "type": "string" }, "product_code": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": [ "number", "null" ] } }, "required": [ "product_name", "product_code", "quantity" ] }, "minItems": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "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 EIC 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 treat it as absent rather than null on every other invoice" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "id": 1, "number": "number", "iic": "iic", "fic": "fic", "tcrCode": "tcrCode", "businessCode": "businessCode", "operatorCode": "operatorCode", "fiscalizedAt": "fiscalizedAt", "verifyURL": "https://example.com", "pdf": "pdf", "eic": "eic" } } } } } } } }, "404": { "description": "Fatura nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Fatura nuk mund te anulohet ne gjendjen e saj aktuale.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "429": { "description": "Kufiri i anulimeve u arrit. Pergjigja kthen vetem `message` bashke me header-in `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "500": { "description": "Gabim i papritur ne server. Perfshin rastin kur anulimi nuk u regjistrua ne fiskalizim.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/cancel/{id}": { "post": { "operationId": "post-api-v1-invoice-cancel-id", "summary": "Anulo fature sipas ID", "description": "Anulon faturen dhe krijon regjistrim fiskal anulimi ne sistemin e tatimeve.\n\n## I plote ose i pjesshem\n\n| Trupi | Cfare ndodh |\n| --- | --- |\n| bosh | Anulohet e gjithe fatura |\n| me `lines` | Anulohet vetem pjesa e derguar, **vetem per faturat Cash** |\n\n## Rregullat e anulimit te pjesshem\n\n- cdo rresht duhet te ekzistoje ne faturen origjinale me te njejtin `product_code` dhe\n `product_name`;\n- sasia mund vetem te ulet ose te mbetet e njejte;\n- produktet qe nuk i dergoni mbeten te shitura;\n- kur i njejti produkt eshte faturuar ne dy rreshta me cmime te ndryshme, shtoni `price` per te\n zgjedhur rreshtin;\n- nje fature me zbritje mbi te gjithe faturen (`invoice_discount_type`) nuk anulohet dot\n pjeserisht. Zbritja eshte shperndare mbi te gjitha normat e TVSH-se se dokumentit, keshtu qe\n nje pjese e rreshtave nuk e mban dot pjesen e vet pa e gabuar TVSH-ne. Dergoni kerkesen pa\n `lines` qe te anulohet e plote.\n\nFatura origjinale mbetet e hapur per anulime te metejshme derisa ato ta mbulojne te gjithen, dhe\nvetem atehere shenohet si e anuluar.", "tags": [ "Faturat (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures ne fature.al.", "schema": { "type": "integer", "example": 403 } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "type": "array", "description": "Rreshtat qe anulohen. Pa te anulohet e gjithe fatura; me te anulohet vetem pjesa e derguar, e mundur vetem per faturat Cash. Cdo rresht duhet te ekzistoje ne faturen origjinale me te njejtin `product_code` dhe `product_name`, dhe sasia mund vetem te ulet. Nje fature qe u leshua me zbritje mbi te gjithe faturen nuk pranon anulim te pjesshem:\ndergojeni kerkesen pa `lines` qe te anulohet e plote.", "items": { "type": "object", "properties": { "product_name": { "type": "string" }, "product_code": { "type": "string" }, "quantity": { "type": "number" }, "price": { "type": [ "number", "null" ] } }, "required": [ "product_name", "product_code", "quantity" ] }, "minItems": 1 } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "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 EIC 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 treat it as absent rather than null on every other invoice" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "id": 1, "number": "number", "iic": "iic", "fic": "fic", "tcrCode": "tcrCode", "businessCode": "businessCode", "operatorCode": "operatorCode", "fiscalizedAt": "fiscalizedAt", "verifyURL": "https://example.com", "pdf": "pdf", "eic": "eic" } } } } } } } }, "404": { "description": "Fatura nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Fatura nuk mund te anulohet ne gjendjen e saj aktuale.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "429": { "description": "Kufiri i anulimeve u arrit. Pergjigja kthen vetem `message` bashke me header-in `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } }, "500": { "description": "Gabim i papritur ne server. Perfshin rastin kur anulimi nuk u regjistrua ne fiskalizim.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/cash": { "post": { "operationId": "post-api-v1-invoice-cash", "summary": "Krijo fature me para ne dore (Cash)", "description": "## Bleresi eshte opsional\n\nPa `client` fatura leshohet per klientin e rastit, qe eshte rasti normal i nje arke.\n\nSapo dergoni qofte edhe nje te dhene te klientit, behen te nevojshme `client.name`,\n`client.address` dhe `client.city`, sepse adresa dhe qyteti shkojne ne sistemin fiskal.\nAdresen dhe qytetin mund t'i kete edhe klienti i ruajtur me pare ne fature.al, keshtu qe nuk\nka nevoje t'i dergoni ne cdo fature. Kur mungon njera, kerkesa refuzohet me `400` dhe fusha\n`errors` thote sakte cfare duhet plotesuar.\n\n## Fusha qe varen nga menyra e pageses\n\nDy fusha kerkohen vetem per nje menyre pagese, dhe ndalohen per cdo tjeter:\n\n| `payment_method` | Fusha e detyrueshme | Kufiri |\n| --- | --- | --- |\n| `COMPANY` | `company_card` | deri ne 50 karaktere |\n| `SVOUCHER` | `vouchers` | deri ne 20, ne formen numer-vit-NIPT, pa perseritje |\n\nDergimi i `company_card` me `BANKNOTE`, ose i `vouchers` me `CARD`, refuzohet. Nuk ka vend ku\nato te shkojne ne dokumentin fiskal, prandaj nuk pranohen ne heshtje.\n\n## Zbritja mbi faturen\n\n`invoice_discount_type` me `invoice_discount_value` dergohen gjithmone bashke, dhe zbresin\nte gjithe faturen. Nje rresht i vetem zbritet me `lines[].discount`, dhe te dyja mund te\njene ne te njejten fature.\n\n| `invoice_discount_type` | Si lexohet `invoice_discount_value` | Kufiri |\n| --- | --- | --- |\n| `percent` | perqindje mbi totalin me TVSH | 100 |\n| `amount` | vlere me TVSH, ne monedhen e fatures | totali i fatures |\n\nZbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total, dhe TVSH-ja\nrillogaritet mbi vleren e ulur, keshtu qe nje fature me disa norma TVSH-je mbetet e sakte.\n`lines[].discount` eshte perqindje mbi cmimin e njesise se atij rreshti. `price` mbetet\ncmimi i plote dhe `total` vjen tashme i ulur: `price` here `quantity`, me zbritjen e hequr.", "tags": [ "Faturat (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence.", "example": "CASH-001" }, "client": { "type": [ "object", "null" ], "description": "Pa te, ose me vlere bosh, fatura leshohet per klientin e rastit.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "ID e nje klienti te ruajtur ne fature.al. Kur e dergoni, klienti gjendet me te dhe fushat me poshte nuk lexohen." }, "name": { "type": [ "string", "null" ], "description": "I detyrueshem sapo dergoni cilendo fushe tjeter te klientit.", "example": "Klient i rastit" }, "id": { "type": [ "object", "null" ], "description": "Dokumenti i identifikimit te bleresit, si objekt me `type` dhe `id`.", "properties": { "id": { "type": [ "string", "null" ], "description": "Numri i dokumentit te identifikimit.", "example": "L62221018T" } } }, "address": { "type": [ "string", "null" ], "description": "Adresa e bleresit qe shkon ne fiskalizim. Nje klient i emeruar e kerkon, ose ne kete kerkese ose e ruajtur me pare ne fature.al." }, "city": { "type": [ "string", "null" ], "description": "Qyteti i bleresit qe shkon ne fiskalizim. Nje klient i emeruar e kerkon, ose ne kete kerkese ose e ruajtur me pare ne fature.al." }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-3 country code (e.g. RKS, ALB, USA). ALB when absent." } } }, "lines": { "type": "array", "description": "Rreshtat 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", "description": "Cmimi per njesi, me TVSH.", "example": 150 }, "total": { "type": "number", "description": "Totali i rreshtit, me TVSH.", "example": 300 }, "discount": { "type": [ "number", "null" ], "description": "Zbritja e ketij rreshti, ne perqindje mbi cmimin e njesise. Eshte opsionale: pa te, ose me vlere bosh, rreshti kalon pikerisht si me pare dhe mungesa e saj nuk kthen kurre gabim. `price` mbetet cmimi i plote i njesise, ndersa `total` vjen tashme i ulur: `price`\nhere `quantity`, me zbritjen e hequr. Nje `total` qe nuk perputhet me ate shifer e\nrefuzon kerkesen me `400`, dhe `errors` tregon cili eshte rreshti dhe cila vlere\npritej.", "example": 10, "minimum": 0, "maximum": 100 }, "vat": { "type": "integer", "description": "Norma e TVSH-se ne perqindje: `0`, `6`, `10` ose `20`. Kur biznesi juaj nuk eshte ne skemen e TVSH-se, rreshti regjistrohet me TVSH `0` dhe\nme perjashtim `TAX_FREE` sido qe ta dergoni kete fushe. Kerkesa nuk refuzohet.", "enum": [ "0", "6", "10", "20" ], "example": 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 }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "Si lexohet `invoice_discount_value`: `percent` si perqindje, `amount` si vlere fikse me TVSH. Zbritja zbatohet mbi te gjithe faturen, kurre mbi nje rresht te vetem: rreshtat ruhen ashtu si i dergoni dhe ulet vetem totali. Punon vetem ne cift me `invoice_discount_value`. Njera pa tjetren injorohet ne\nheshtje, dhe fatura del pa zbritje.", "enum": [ "percent", "amount" ], "example": "percent" }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Vlera e zbritjes, e lexuar sipas `invoice_discount_type`: perqindje kur tipi eshte `percent`, e kufizuar ne 100; vlere me TVSH ne monedhen e fatures kur tipi eshte `amount`, e kufizuar ne totalin e fatures. Zeroja e le faturen pa zbritje. Zbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total, dhe TVSH-ja\nrillogaritet mbi vleren e ulur. Detajet dhe shembujt: faqja Zbritjet ne fature.", "example": 10, "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, merret 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" ], "description": "Afati i pageses, ne formatin `YYYY-MM-DD`.", "example": "2026-10-04" }, "supply_start_date": { "type": [ "string", "null" ], "description": "Fillimi i periudhes se furnizimit, per fatura qe mbulojne nje interval.", "example": "2026-09-01" }, "supply_end_date": { "type": [ "string", "null" ], "description": "Fundi i periudhes se furnizimit.", "example": "2026-09-30" }, "reverse_charge": { "type": [ "boolean", "null" ], "description": "Ngarkesa e kundert: TVSH-ja deklarohet nga bleresi, jo nga shitesi.", "example": false }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shfaqen ne fature.", "example": "Faleminderit per blerjen" }, "periodic_invoice": { "type": [ "boolean", "null" ], "description": "Shenon nje fature qe i perket nje cikli te perseritur faturimi.", "example": false }, "self_issue_type": { "type": [ "string", "null" ], "description": "Vetefaturim. Kur e dergoni, `client` eshte shitesi dhe i duhet numri i identifikimit (NUIS ose dokument) bashke me shtetin. Kur nuk e dergoni, fatura eshte e zakonshme.", "enum": [ "DOMESTIC", "ABROAD", "OTHER" ], "example": "DOMESTIC" } }, "required": [ "internalId", "lines" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "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 EIC 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 treat it as absent rather than null on every other invoice" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "id": 1, "number": "number", "iic": "iic", "fic": "fic", "tcrCode": "tcrCode", "businessCode": "businessCode", "operatorCode": "operatorCode", "fiscalizedAt": "fiscalizedAt", "verifyURL": "https://example.com", "pdf": "pdf", "eic": "eic" } } } } } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "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": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/details/{internalId}": { "post": { "operationId": "post-api-v1-invoice-details-internalid", "summary": "Detajet e fatures sipas Internal ID", "description": "Merr detajet e nje fature duke perdorur ID-ne tuaj interne.", "tags": [ "Faturat (v1)" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "ID juaj interne, e derguar kur u krijua fatura.", "schema": { "type": "string", "example": "CASH-001" } } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "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 EIC 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 treat it as absent rather than null on every other invoice" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "id": 1, "number": "number", "iic": "iic", "fic": "fic", "tcrCode": "tcrCode", "businessCode": "businessCode", "operatorCode": "operatorCode", "fiscalizedAt": "fiscalizedAt", "verifyURL": "https://example.com", "pdf": "pdf", "eic": "eic" } } } } } } } }, "404": { "description": "Nuk u gjet asnje fature me kete `internalId`.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "`internalId` eshte bosh.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/e-invoice": { "post": { "operationId": "post-api-v1-invoice-e-invoice", "summary": "Krijo fature elektronike (E-Invoice)", "description": "Fatura dergohet automatikisht ne sistemin qendror te e-faturave. Klienti identifikohet me NIPT.\n\n**Bleresi shkon i plote** ne sistemin e e-faturave, prandaj `client.address` dhe `client.city`\nduhen ose ne kerkese, ose te ruajtura me pare tek klienti ne fature.al. Kur mungon nje e dhene\ne nevojshme, kerkesa refuzohet me `400` dhe fusha `errors` thote sakte cfare duhet plotesuar.\n\n## Lloji i dokumentit\n\n`process` shkon si ProfileID ne dokumentin UBL, `doc_type` si lloji i dokumentit. Te dyja jane\nte detyrueshme:\n\n| Dokumenti | `doc_type` | `process` | Kerkon `original_invoice_iic` |\n| --- | --- | --- | --- |\n| Fature shitjeje | `380` | `P1` | jo |\n| Note krediti | `381` | `P9` | **po** |\n| Note debiti | `383` | `P9` | **po** |\n\nNje note krediti dhe nje note debiti korrigjojne nje fature tjeter, prandaj kerkojne\n`original_invoice_iic`, IIC-ne qe ju ktheu ajo fature:\n\n- shkon si BillingReference ne dokumentin UBL;\n- shkon si reference korrigjimi ne regjistrimin e CIS;\n- pa te, kerkesa refuzohet me `422`.\n\nPer te kthyer nje fature te plote perdorni endpoint-in e anulimit, jo nje note krediti: ai e\nshenon origjinalin si te kthyer.\n\n## Zbritja mbi faturen\n\n`invoice_discount_type` me `invoice_discount_value` dergohen gjithmone bashke, dhe zbresin\nte gjithe faturen. Nje rresht i vetem zbritet me `lines[].discount`, dhe te dyja mund te\njene ne te njejten fature.\n\n| `invoice_discount_type` | Si lexohet `invoice_discount_value` | Kufiri |\n| --- | --- | --- |\n| `percent` | perqindje mbi totalin me TVSH | 100 |\n| `amount` | vlere me TVSH, ne monedhen e fatures | totali i fatures |\n\nZbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total, dhe TVSH-ja\nrillogaritet mbi vleren e ulur, keshtu qe nje fature me disa norma TVSH-je mbetet e sakte.\n`lines[].discount` eshte perqindje mbi cmimin e njesise se atij rreshti. `price` mbetet\ncmimi i plote dhe `total` vjen tashme i ulur: `price` here `quantity`, me zbritjen e hequr.\n\nNe dokumentin UBL zbritja del si AllowanceCharge, me nje ze per cdo norme TVSH-je.", "tags": [ "Faturat (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence: i njejti `internalId` brenda te njejtit vit kthen `409` ne vend qe te leshoje nje fature te dyte, prandaj nje riprovim pas nje lidhjeje qe u nderpre eshte i sigurt.", "example": "EINV-2026-000412" }, "client": { "type": "object", "description": "Bleresi. I detyrueshem per nje e-fature, sepse dokumenti shkon i plote ne sistemin qendror. Dergoni `client.internal_id` per nje klient te ruajtur, ose NIPT-in me emrin dhe shtetin per nje te ri.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "ID e nje klienti te ruajtur ne fature.al. Kur e dergoni, klienti gjendet me te dhe fushat e tjera nuk lexohen.", "example": 8812 }, "nuis": { "type": "string", "description": "NIPT-i i bleresit. I detyrueshem kur nuk dergoni `client.internal_id`.", "example": "L62221018T" }, "name": { "type": "string", "description": "Emri i bleresit. I detyrueshem kur nuk dergoni `client.internal_id`.", "example": "Ei3 Software Solution shpk" }, "address": { "type": [ "string", "null" ], "description": "Adresa e bleresit qe shkon ne sistemin e e-faturave. Duhet ose ne kete kerkese ose e ruajtur me pare ne fature.al." }, "city": { "type": [ "string", "null" ], "description": "Qyteti i bleresit qe shkon ne sistemin e e-faturave. Duhet ose ne kete kerkese ose i ruajtur me pare ne fature.al." }, "country": { "type": "string", "description": "Kodi i shtetit ISO 3166-1 alpha-3.", "example": "ALB" } } }, "lines": { "type": "array", "description": "Rreshtat e fatures, te pakten nje.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Emri i produktit ose i sherbimit.", "example": "Kafe" }, "product_code": { "type": "string", "description": "Kodi i produktit ne katalogun tuaj.", "example": "KAF-001" }, "unit": { "type": "string", "description": "Njesia matese si tekst, ajo qe lexon njeriu.", "example": "cope" }, "quantity": { "type": "number", "description": "Sasia.", "example": 2 }, "price": { "type": "number", "description": "Cmimi per njesi, me TVSH.", "example": 150 }, "total": { "type": "number", "description": "Totali i rreshtit, me TVSH.", "example": 300 }, "discount": { "type": [ "number", "null" ], "description": "Zbritja e ketij rreshti, ne perqindje mbi cmimin e njesise. Eshte opsionale: pa te, ose me vlere bosh, rreshti kalon pikerisht si me pare dhe mungesa e saj nuk kthen kurre gabim. `price` mbetet cmimi i plote i njesise, ndersa `total` vjen tashme i ulur: `price`\nhere `quantity`, me zbritjen e hequr. Nje `total` qe nuk perputhet me ate shifer e\nrefuzon kerkesen me `400`, dhe `errors` tregon cili eshte rreshti dhe cila vlere\npritej.", "example": 10, "minimum": 0, "maximum": 100 }, "vat": { "type": [ "integer", "null" ], "description": "Norma e TVSH-se ne perqindje: `0`, `6`, `10` ose `20`. Kur biznesi juaj nuk eshte ne skemen e TVSH-se, rreshti regjistrohet me TVSH `0` dhe\nme perjashtim `TAX_FREE` sido qe ta dergoni kete fushe. Kerkesa nuk refuzohet.", "enum": [ "0", "6", "10", "20" ], "example": 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" ], "example": "EXPORT_OF_GOODS" } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total" ] }, "minItems": 1 }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "Si lexohet `invoice_discount_value`: `percent` si perqindje, `amount` si vlere fikse me TVSH. Zbritja zbatohet mbi te gjithe faturen, kurre mbi nje rresht te vetem: rreshtat ruhen ashtu si i dergoni dhe ulet vetem totali. Punon vetem ne cift me `invoice_discount_value`. Njera pa tjetren injorohet ne\nheshtje, dhe fatura del pa zbritje.", "enum": [ "percent", "amount" ], "example": "percent" }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Vlera e zbritjes, e lexuar sipas `invoice_discount_type`: perqindje kur tipi eshte `percent`, e kufizuar ne 100; vlere me TVSH ne monedhen e fatures kur tipi eshte `amount`, e kufizuar ne totalin e fatures. Zeroja e le faturen pa zbritje. Ne dokumentin UBL del si AllowanceCharge me nje ze per cdo norme TVSH-je, sepse\nzbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total. Detajet\ndhe shembujt: faqja Zbritjet ne fature.", "example": 10, "minimum": 0 }, "bank_account": { "type": [ "integer", "null" ], "description": "ID e nje llogarie bankare te ruajtur ne fature.al.", "example": 42 }, "bank_account_iban": { "type": [ "string", "null" ], "description": "IBAN-i i llogarise. Alternative ndaj `bank_account`, kur mbani IBAN-in dhe jo ID-ne.", "example": "AL35202111090000000001234567" }, "bankAccount": { "type": [ "object", "null" ], "description": "Llogaria bankare e shkruar e plote, kur nuk e keni ende ne fature.al. Ruhet si llogari e kompanise suaj, dhe nje IBAN qe ekziston tashme riperdoret ne vend qe te dyfishohet.", "properties": { "name": { "type": [ "string", "null" ], "description": "Emri i bankes.", "example": "BKT" }, "iban": { "type": [ "string", "null" ], "description": "IBAN-i i llogarise.", "example": "AL35202111090000000001234567" }, "currency": { "type": [ "string", "null" ], "description": "Monedha e llogarise.", "example": "ALL" }, "swift": { "type": [ "string", "null" ], "description": "Kodi SWIFT/BIC i bankes.", "example": "NCBAALTX" }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shoqerojne llogarine ne fature." }, "holder": { "type": [ "string", "null" ], "description": "Mbajtesi i llogarise.", "example": "Ei3 Software Solution shpk" } } }, "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, merret 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" ], "description": "Afati i pageses, ne formatin `YYYY-MM-DD`.", "example": "2026-10-04" }, "supply_start_date": { "type": [ "string", "null" ], "description": "Fillimi i periudhes se furnizimit, per fatura qe mbulojne nje interval.", "example": "2026-09-01" }, "supply_end_date": { "type": [ "string", "null" ], "description": "Fundi i periudhes se furnizimit.", "example": "2026-09-30" }, "reverse_charge": { "type": [ "boolean", "null" ], "description": "Ngarkesa e kundert: TVSH-ja deklarohet nga bleresi, jo nga shitesi.", "example": false }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shfaqen ne fature.", "example": "Faleminderit per blerjen" }, "periodic_invoice": { "type": [ "boolean", "null" ], "description": "Shenon nje fature qe i perket nje cikli te perseritur faturimi.", "example": false }, "original_invoice_iic": { "type": [ "string", "null" ], "description": "IIC-ja e fatures qe ky dokument korrigjon, ajo qe ju ktheu fatura origjinale. E detyrueshme per nje note krediti (`doc_type=381`) dhe per nje note debiti (`doc_type=383`), sepse te dyja korrigjojne nje fature tjeter. Nuk pranohet per llojet e tjera te dokumentit. Required depending on doc_type.", "example": "8FE72E2ACD1C500A83F8C89B4E2E3E1D" } }, "required": [ "internalId", "client", "lines", "original_invoice_iic" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "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 EIC 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 treat it as absent rather than null on every other invoice" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "id": 1, "number": "number", "iic": "iic", "fic": "fic", "tcrCode": "tcrCode", "businessCode": "businessCode", "operatorCode": "operatorCode", "fiscalizedAt": "fiscalizedAt", "verifyURL": "https://example.com", "pdf": "pdf", "eic": "eic" } } } } } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "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": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/noncash": { "post": { "operationId": "post-api-v1-invoice-noncash", "summary": "Krijo fature pa para ne dore (NonCash)", "description": "Perdoret per transaksione me transferte bankare, cek dhe cdo pagese qe nuk kryhet ne arke.\n\n## Bleresi\n\nKlienti identifikohet me `client.name` dhe, kur e dergoni, me `client.id`. Adresa dhe qyteti\nshkojne ne sistemin fiskal, prandaj duhen njera nga dy rruget:\n\n- `client.address` dhe `client.city` ne vete kerkesen;\n- ose te ruajtura me pare tek klienti ne fature.al.\n\nKur mungon nje e dhene e nevojshme, kerkesa refuzohet me `400` dhe fusha `errors` thote sakte\ncfare duhet plotesuar.\n\n## Llogaria bankare\n\nShkruhet ne fature ne tri menyra, sipas asaj qe keni ne dore:\n\n| Fusha | Kuptimi |\n| --- | --- |\n| `bank_account` | ID e nje llogarie te ruajtur ne fature.al |\n| `bank_account_iban` | Gjendet me IBAN |\n| `bankAccount` | Shkruhet e plote dhe ruhet si llogari e kompanise; nje IBAN ekzistues riperdoret |\n\n## Zbritja mbi faturen\n\n`invoice_discount_type` me `invoice_discount_value` dergohen gjithmone bashke, dhe zbresin\nte gjithe faturen. Nje rresht i vetem zbritet me `lines[].discount`, dhe te dyja mund te\njene ne te njejten fature.\n\n| `invoice_discount_type` | Si lexohet `invoice_discount_value` | Kufiri |\n| --- | --- | --- |\n| `percent` | perqindje mbi totalin me TVSH | 100 |\n| `amount` | vlere me TVSH, ne monedhen e fatures | totali i fatures |\n\nZbritja shperndahet mbi grupet e TVSH-se sipas peshes se secilit ne total, dhe TVSH-ja\nrillogaritet mbi vleren e ulur, keshtu qe nje fature me disa norma TVSH-je mbetet e sakte.\n`lines[].discount` eshte perqindje mbi cmimin e njesise se atij rreshti. `price` mbetet\ncmimi i plote dhe `total` vjen tashme i ulur: `price` here `quantity`, me zbritjen e hequr.\n\nTarifa `fee` mbetet jashte bazes se zbritjes: zbritet shuma e rreshtave, dhe tarifa i\nshtohet totalit te ulur.\n\n## Note krediti dhe note debiti\n\nNje fature jo-cash korrigjohet nga nje fature tjeter jo-cash. Dergoni `doc_type` bashke me\n`original_invoice_iic`, IIC-ne qe ju ktheu fatura origjinale:\n\n| `doc_type` | Dokumenti | Efekti |\n| --- | --- | --- |\n| mungon ose `380` | Fature e zakonshme | asnje |\n| `381` | Note krediti | ul vleren qe bleresi ju detyrohet |\n| `383` | Note debiti | rrit vleren qe bleresi ju detyrohet |\n\nOrigjinali duhet te jete fature jo-cash e fiskalizuar, e paanuluar dhe ende e korrigjueshme.\nRreshtat qe dergoni jane rreshtat e korrigjimit, me vlerat pozitive: drejtimin e percakton\n`doc_type`, jo shenja e numrave. Kur korrigjimet e mbulojne te gjithe faturen, origjinali\nshenohet si i kthyer.\n\nPer te kthyer nje fature te plote perdorni endpoint-in e anulimit, jo nje note krediti.", "tags": [ "Faturat (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence: i njejti `internalId` brenda te njejtit vit kthen `409` ne vend qe te leshoje nje fature te dyte, prandaj nje riprovim pas nje lidhjeje qe u nderpre eshte i sigurt.", "example": "NONCASH-2026-000412" }, "client": { "type": [ "object", "null" ], "description": "Pa te, ose me vlere bosh, fatura leshohet per klientin e rastit.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "ID e nje klienti te ruajtur ne fature.al. Kur e dergoni, klienti gjendet me te dhe fushat me poshte nuk lexohen." }, "name": { "type": "string", "description": "Emri i bleresit.", "example": "Alpha SHPK" }, "id": { "type": [ "object", "null" ], "description": "Dokumenti i identifikimit te bleresit, si objekt me `type` dhe `id`.", "properties": { "id": { "type": [ "string", "null" ], "description": "Numri i dokumentit te identifikimit.", "example": "L62221018T" } } }, "address": { "type": [ "string", "null" ], "description": "Adresa e bleresit qe shkon ne fiskalizim. Nje klient i emeruar e kerkon, ose ne kete kerkese ose e ruajtur me pare ne fature.al." }, "city": { "type": [ "string", "null" ], "description": "Qyteti i bleresit qe shkon ne fiskalizim. Nje klient i emeruar e kerkon, ose ne kete kerkese ose e ruajtur me pare ne fature.al." }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code (e.g. RKS, ALB, USA). ALB when absent." } } }, "lines": { "type": "array", "description": "Rreshtat e fatures, te pakten nje.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Emri i produktit ose i sherbimit.", "example": "Kafe" }, "product_code": { "type": "string", "description": "Kodi i produktit ne katalogun tuaj.", "example": "KAF-001" }, "unit": { "type": "string", "description": "Njesia matese si tekst, ajo qe lexon njeriu.", "example": "cope" }, "quantity": { "type": "number", "description": "Sasia.", "example": 2 }, "price": { "type": "number", "description": "Cmimi per njesi, me TVSH.", "example": 150 }, "total": { "type": "number", "description": "Totali i rreshtit, me TVSH.", "example": 300 }, "discount": { "type": [ "number", "null" ], "description": "Zbritja e ketij rreshti, ne perqindje mbi cmimin e njesise. Eshte opsionale: pa te, ose me vlere bosh, rreshti kalon pikerisht si me pare dhe mungesa e saj nuk kthen kurre gabim. `price` mbetet cmimi i plote i njesise, ndersa `total` vjen tashme i ulur: `price`\nhere `quantity`, me zbritjen e hequr. Nje `total` qe nuk perputhet me ate shifer e\nrefuzon kerkesen me `400`, dhe `errors` tregon cili eshte rreshti dhe cila vlere\npritej.", "example": 10, "minimum": 0, "maximum": 100 }, "vat": { "type": [ "integer", "null" ], "description": "Norma e TVSH-se ne perqindje: `0`, `6`, `10` ose `20`. Kur biznesi juaj nuk eshte ne skemen e TVSH-se, rreshti regjistrohet me TVSH `0` dhe\nme perjashtim `TAX_FREE` sido qe ta dergoni kete fushe. Kerkesa nuk refuzohet.", "enum": [ "0", "6", "10", "20" ], "example": 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" ], "example": "EXPORT_OF_GOODS" } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total" ] }, "minItems": 1 }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "Si lexohet `invoice_discount_value`: `percent` si perqindje, `amount` si vlere fikse me TVSH. Zbritja zbatohet mbi te gjithe faturen, kurre mbi nje rresht te vetem: rreshtat ruhen ashtu si i dergoni dhe ulet vetem totali. Punon vetem ne cift me `invoice_discount_value`. Njera pa tjetren injorohet ne\nheshtje, dhe fatura del pa zbritje.", "enum": [ "percent", "amount" ], "example": "percent" }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Vlera e zbritjes, e lexuar sipas `invoice_discount_type`: perqindje kur tipi eshte `percent`, e kufizuar ne 100; vlere me TVSH ne monedhen e fatures kur tipi eshte `amount`, e kufizuar ne totalin e fatures. Zeroja e le faturen pa zbritje. Baza e zbritjes eshte shuma e rreshtave. Tarifa `fee` mbetet jashte saj dhe nuk\nzbritet. Detajet dhe shembujt: faqja Zbritjet ne fature.", "example": 10, "minimum": 0 }, "bank_account": { "type": [ "integer", "null" ], "description": "ID e nje llogarie bankare te ruajtur ne fature.al.", "example": 42 }, "bank_account_iban": { "type": [ "string", "null" ], "description": "IBAN-i i llogarise. Alternative ndaj `bank_account`, kur mbani IBAN-in dhe jo ID-ne.", "example": "AL35202111090000000001234567" }, "bankAccount": { "type": [ "object", "null" ], "description": "Llogaria bankare e shkruar e plote, kur nuk e keni ende ne fature.al. Ruhet si llogari e kompanise suaj, dhe nje IBAN qe ekziston tashme riperdoret ne vend qe te dyfishohet.", "properties": { "name": { "type": [ "string", "null" ], "description": "Emri i bankes.", "example": "BKT" }, "iban": { "type": [ "string", "null" ], "description": "IBAN-i i llogarise.", "example": "AL35202111090000000001234567" }, "currency": { "type": [ "string", "null" ], "description": "Monedha e llogarise.", "example": "ALL" }, "swift": { "type": [ "string", "null" ], "description": "Kodi SWIFT/BIC i bankes.", "example": "NCBAALTX" }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shoqerojne llogarine ne fature." }, "holder": { "type": [ "string", "null" ], "description": "Mbajtesi i llogarise.", "example": "Ei3 Software Solution shpk" } } }, "fee": { "type": [ "object", "null" ], "description": "Tarife shtese qe shkon vecmas nga rreshtat e fatures.", "properties": { "fee_type": { "type": [ "string", "null" ], "description": "Lloji i tarifes: OTHER, COMMISSION, PACK ose BOTTLE.", "example": "PACK" }, "fee_amount": { "type": [ "number", "null" ], "description": "Vlera e tarifes.", "example": 50 } } }, "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, merret 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" ], "description": "Afati i pageses, ne formatin `YYYY-MM-DD`.", "example": "2026-10-04" }, "supply_start_date": { "type": [ "string", "null" ], "description": "Fillimi i periudhes se furnizimit, per fatura qe mbulojne nje interval.", "example": "2026-09-01" }, "supply_end_date": { "type": [ "string", "null" ], "description": "Fundi i periudhes se furnizimit.", "example": "2026-09-30" }, "reverse_charge": { "type": [ "boolean", "null" ], "description": "Ngarkesa e kundert: TVSH-ja deklarohet nga bleresi, jo nga shitesi.", "example": false }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shfaqen ne fature.", "example": "Faleminderit per blerjen" }, "periodic_invoice": { "type": [ "boolean", "null" ], "description": "Shenon nje fature qe i perket nje cikli te perseritur faturimi.", "example": false }, "self_issue_type": { "type": [ "string", "null" ], "description": "Vetefaturim. Kur e dergoni, `client` eshte shitesi.", "enum": [ "DOMESTIC", "ABROAD", "OTHER" ], "example": "DOMESTIC" }, "doc_type": { "type": [ "string", "null" ], "description": "E ben faturen dokument korrigjues mbi nje fature tjeter jo-cash: `381` note krediti, `383` note debiti. Pa te, ose me `380`, fatura eshte e zakonshme. Nje note kerkon `original_invoice_iic`, dhe rreshtat qe dergoni jane rreshtat e\nkorrigjimit, jo ata te fatures origjinale. Vlerat shkojne pozitive: eshte `doc_type`\nqe percakton drejtimin, jo shenja e numrave.", "example": 381 }, "original_invoice_iic": { "type": [ "string", "null" ], "description": "IIC-ja e fatures jo-cash qe ky dokument korrigjon, ajo qe ju ktheu fatura origjinale. E detyrueshme kur `doc_type` eshte `381` ose `383`, dhe e papranueshme ne cdo rast tjeter. Origjinali duhet te jete fature jo-cash e fiskalizuar, e paanuluar dhe ende e\nkorrigjueshme. Per te kthyer nje fature te plote perdorni endpoint-in e anulimit,\njo nje note krediti.", "example": "8FE72E2ACD1C500A83F8C89B4E2E3E1D" } }, "required": [ "internalId", "lines" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "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 EIC 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 treat it as absent rather than null on every other invoice" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "id": 1, "number": "number", "iic": "iic", "fic": "fic", "tcrCode": "tcrCode", "businessCode": "businessCode", "operatorCode": "operatorCode", "fiscalizedAt": "fiscalizedAt", "verifyURL": "https://example.com", "pdf": "pdf", "eic": "eic" } } } } } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "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": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/order": { "post": { "operationId": "post-api-v1-invoice-order", "summary": "Krijo fature porosi (Order)", "description": "Regjistron konsumin qe ka nisur pa e mbyllur pagesen. Perdoret ne cift me faturen permbledhese:\nporosia hap tavolinen, permbledhesja e paguan.\n\n- **Mos dergoni `payment_method`**: ai vendoset vete ne `ORDER`.\n- Ruani `iic` qe ju kthehet. Ai eshte celesi me te cilin porosia mbyllet me vone.\n- Nje tavoline mund te kete disa porosi te hapura njeheresh.\n\n**Zbritja mbi te gjithe faturen i perket permbledheses, jo porosise.** Porosia nuk pranon\n`invoice_discount_type` dhe `invoice_discount_value`, sepse permbledhesja i kopjon rreshtat\nnga porosite dhe nje zbritje mbi te gjithe porosine nuk kalon dot tek ajo.\n\nZbritja per rresht kalon: `lines[].discount` ruhet mbi rreshtin e porosise dhe permbledhesja\ne merr bashke me te, keshtu qe tavolina paguan pikerisht sa tregoi porosia.", "tags": [ "Faturat (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence.", "example": "ORD-001" }, "client": { "type": [ "object", "null" ], "description": "Bleresi. Opsional si tek fatura cash: pa te porosia i leshohet klientit te rastit. Me `client.internal_id` merret nje klient i ruajtur, ndryshe `client.name` behet i detyrueshem sapo dergoni cdo fushe tjeter te tij.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "ID e nje klienti te ruajtur ne fature.al. Kur e dergoni, fushat e tjera nuk lexohen." }, "name": { "type": [ "string", "null" ], "description": "Emri i bleresit.", "example": "Klient i rastit" }, "id": { "type": [ "object", "null" ], "description": "Dokumenti i identifikimit te bleresit, si objekt me `type` dhe `id`.", "properties": { "type": { "type": [ "string", "null" ], "description": "NUIS, VAT ose TAX per kompani; ID, PASS ose SOC per person." }, "id": { "type": [ "string", "null" ], "description": "Numri i dokumentit te identifikimit.", "example": "L62221018T" } } }, "address": { "type": [ "string", "null" ], "description": "Adresa e bleresit, kur klienti eshte i emeruar." }, "city": { "type": [ "string", "null" ], "description": "Qyteti i bleresit, kur klienti eshte i emeruar." }, "country": { "type": [ "string", "null" ], "description": "Kodi i shtetit ISO 3166-1 alpha-3. ALB kur mungon." } } }, "lines": { "type": "array", "description": "Rreshtat 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." }, "discount": { "type": [ "number", "null" ], "description": "Zbritja e ketij rreshti, ne perqindje mbi cmimin e njesise. Eshte opsionale: pa te, ose me vlere bosh, rreshti kalon pikerisht si me pare dhe mungesa e saj nuk kthen kurre gabim. `price` mbetet cmimi i plote i njesise, ndersa `total` vjen tashme i ulur: `price`\nhere `quantity`, me zbritjen e hequr. Nje `total` qe nuk perputhet me ate shifer e\nrefuzon kerkesen me `400`, dhe `errors` tregon cili eshte rreshti dhe cila vlere\npritej.", "example": 10, "minimum": 0, "maximum": 100 }, "vat": { "type": "integer", "description": "Shkalla e TVSH. Kur biznesi juaj nuk eshte ne skemen e TVSH-se, rreshti regjistrohet me TVSH `0` dhe\nme perjashtim `TAX_FREE` sido qe ta dergoni kete fushe. Kerkesa nuk refuzohet.", "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 }, "currency": { "type": [ "string", "null" ], "description": "Monedha e porosise. Pa te merret ALL.", "example": "ALL" }, "exchange_rate": { "type": [ "number", "null" ], "description": "Sa leke vlen nje njesi e monedhes se porosise. Pa te merret 1.", "example": 100.5 }, "supply_start_date": { "type": [ "string", "null" ], "description": "Fillimi i periudhes se furnizimit.", "example": "2026-09-01" }, "supply_end_date": { "type": [ "string", "null" ], "description": "Fundi i periudhes se furnizimit.", "example": "2026-09-30" }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shfaqen ne porosi.", "example": "Tavolina 4" } }, "required": [ "internalId", "lines" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "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 once it has been settled, so a freshly issued Order does not carry it" } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "isOrderInvoice": true, "summaryInvoiceId": 1 } } } } } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "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": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/print-eic/{eic}": { "get": { "operationId": "api.v1.einvoice.pdf", "summary": "Shkarko PDF te fatures sipas EIC", "description": "Kthen skedarin PDF te fatures duke perdorur kodin EIC (UUID).", "tags": [ "Faturat (v1)" ], "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": "Skedari PDF i fatures. Kontrolloni Content-Type para se ta ruani si PDF: nje EIC qe nuk gjendet kthehet po me statusin 200, por si text/html.", "content": { "application/json": { "schema": { "type": "string" }, "examples": { "example": { "summary": "Example", "value": "example" } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/print/{id}": { "get": { "operationId": "api.v1.invoice.pdf", "summary": "Shkarko PDF te fatures sipas ID", "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.", "tags": [ "Faturat (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures ne fature.al.", "schema": { "type": "integer", "example": 403 } }, { "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" } }, { "name": "copy_only", "in": "query", "description": "Vetem per faturat Cash: kthen kopjen e kuponit ne vend te origjinalit.", "schema": { "type": "integer", "example": 1 } } ], "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/json": { "schema": { "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ë Tatimore\"" }, "company": { "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" } } }, "client": { "type": "object", "properties": { "name": { "type": "string" }, "id": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "Identifier type, e.g. NUIS, ID, PASSPORT" }, "id": { "type": [ "string", "null" ], "description": "The identifier value" } } }, "addres": { "type": [ "string", "null" ], "description": "Buyer street address" }, "city": { "type": [ "string", "null" ] }, "country": { "type": "string", "description": "ISO 3166-1 alpha-3 country code. ALB when the buyer has none" } } }, "transporter": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "plate": { "type": [ "string", "null" ], "description": "Vehicle plate" }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } } }, "invoice": { "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": { "type": [ "object", "null" ], "description": "Bank account to print as payment instructions, or null", "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" ] } } }, "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 and shortened to \"Ana H.\", 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": { "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" } } } }, "amounts": { "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" } } }, "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" } } } } } }, "examples": { "example": { "summary": "Example", "value": { "logo": "logo", "title": "Quarterly report", "company": { "name": "Jane Doe", "nuis": "nuis", "address": "1 Example Street" }, "client": { "name": "Jane Doe", "id": { "type": "type", "id": "id" }, "addres": "addres", "city": "Berlin", "country": "US" }, "transporter": { "name": "Jane Doe", "plate": "plate", "address": "1 Example Street", "city": "Berlin" }, "invoice": { "type": "type", "payment_method": "payment method", "payment_method_label": "payment method label", "bank_account": { "id": 1, "bank_name": "Jane Doe", "iban": "iban", "swift": "swift", "currency": "USD", "notes": "notes" }, "issueDate": "issueDate", "businessCode": "businessCode", "operatorCode": "operatorCode", "operatorName": "Jane Doe", "deviceCode": "deviceCode", "currency": "USD", "exchangeRate": 19.99, "number": "number", "lines": [ { "name": "Jane Doe", "unit": "unit", "quantity": 2, "unitPrice": 1999, "total": 4200 } ], "amounts": { "net": 19.99, "gross": 19.99, "vat": 19.99, "discount": 3, "net_all": 19.99, "gross_all": 19.99, "vat_all": 19.99, "discount_all": 3 }, "iic": "iic", "fic": "fic", "eic": "eic", "process": "process", "doc_type": "doc type", "notes": "notes", "verifyUrl": "https://example.com", "footer": [ "footer" ] } } } } } } }, "404": { "description": "Fatura nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] }, "examples": { "example": { "summary": "Example", "value": { "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/summary": { "post": { "operationId": "post-api-v1-invoice-summary", "summary": "Krijo fature permbledhese (Summary)", "description": "Mbyll pagesen e nje ose me shume faturave porosi me nje dokument te vetem.\n\n- `order_invoices` mban IIC-te e porosive qe po mbyllen, te pakten nje.\n- **Rreshtat nuk dergohen**: merren nga vete porosite.\n- `payment_method` pranon vetem `BANKNOTE` ose `CARD`.\n- Zbritja e tavolines vendoset ketu, me `invoice_discount_type` dhe `invoice_discount_value`.\n\nPergjigja i liston porosite e mbyllura ne `settledOrderInvoices`.", "tags": [ "Faturat (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "internalId": { "type": "string", "description": "ID unike e fatures ne sistemin tuaj. Sherben edhe si celes idempotence: i njejti `internalId` brenda te njejtit vit kthen `409` ne vend qe te leshoje nje fature te dyte, prandaj nje riprovim pas nje lidhjeje qe u nderpre eshte i sigurt.", "example": "SUMMARY-2026-000021" }, "order_invoices": { "type": "array", "description": "IIC-te e faturave porosi qe po mbyllen, te pakten nje. Rreshtat e permbledhëses merren nga keto porosi, prandaj nuk dergohen ne kerkese.", "items": { "type": "string", "description": "IIC-ja e nje fature porosi qe po mbyllet.", "example": "8FE72E2ACD1C500A83F8C89B4E2E3E1D" }, "minItems": 1 }, "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 merret 1.", "example": 100.5 }, "supply_start_date": { "type": [ "string", "null" ], "description": "Fillimi i periudhes se furnizimit, per fatura qe mbulojne nje interval.", "example": "2026-09-01" }, "supply_end_date": { "type": [ "string", "null" ], "description": "Fundi i periudhes se furnizimit.", "example": "2026-09-30" }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "Si lexohet `invoice_discount_value`: `percent` si perqindje, `amount` si vlere fikse me TVSH. Zbritja mbi te gjithe faturen i perket permbledhëses, jo porosive, sepse porosia nuk e pranon fare. Zbritjet per rresht vijne bashke me rreshtat qe kopjohen nga porosite. Punon vetem ne cift me `invoice_discount_value`.", "enum": [ "percent", "amount" ], "example": "percent" }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Vlera e zbritjes, e lexuar sipas `invoice_discount_type`: perqindje kur tipi eshte `percent`, e kufizuar ne 100; vlere me TVSH ne monedhen e fatures kur tipi eshte `amount`, e kufizuar ne totalin e permbledhëses.", "example": 10, "minimum": 0 } }, "required": [ "internalId", "order_invoices" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "isSummaryInvoice": { "type": "boolean", "description": "Always true. The key marks the invoice as a Summary" }, "settledOrderInvoices": { "type": "array", "items": { "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": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "isSummaryInvoice": true, "settledOrderInvoices": [ { "id": 1, "number": "number", "date": "date", "amountGross": 4200, "currency": "USD" } ] } } } } } } } }, "400": { "description": "Te dhena te paplota ose te pavlefshme. `errors` thote sakte cfare duhet plotesuar.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Nje fature me kete `internalId` po procesohet ose ekziston tashme per kete vit.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "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": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem. Fatura ruhet dhe fiskalizohet automatikisht me vone.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/wtn": { "get": { "operationId": "api.v1.invoice.wtn.list", "summary": "Lista e faturave shoqeruese (WTN)", "description": "Merr listen e faturave shoqeruese me faqosje dhe filtrim sipas datave.\n\nFaqezohet me `limit` dhe `offset`. `pagination` kthen vetem numeruesit e faqes, pa nje total,\nprandaj ndaloni kur nje faqe vjen me e shkurter se `limit`.", "tags": [ "Fletë shoqëruese (v1)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i faturave per faqe. Defaults to `20`.", "schema": { "type": "integer", "example": 20 } }, { "name": "offset", "in": "query", "description": "Nga cila fature te fillohet. Defaults to `0`.", "schema": { "type": "integer", "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": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "message": {} } }, "examples": { "example": { "summary": "Example", "value": { "status": false, "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] }, "post": { "operationId": "api.v1.invoice.wtn.create", "summary": "Krijo fature shoqeruese (WTN)", "description": "Fleta shoqeruese nuk eshte shitje: shoqeron mall qe leviz nga nje pike ne tjetren, dhe kerkohet\nnga ligji edhe kur asgje nuk shitet.\n\nRreshtat quhen `invoice_lines`, jo `lines` si tek faturat.\n\n## Fushat e detyrueshme\n\n- `vehPlates`, targa e automjetit;\n- `valueOfGoods`, vlera e mallit qe udheton;\n- `invoice_lines`, te pakten nje rresht.\n\n## Vlerat e lejuara\n\n| Fusha | Vlerat |\n| --- | --- |\n| `type` | `WTN`, `SALE` |\n| `transaction` | `TRANSFER`, `EXAMINATION`, `SALES`, `DOOR` |\n| `vehOwnership` | `OWNER`, `THIRDPARTY` |\n| `startPoint`, `destinPoint` | `ANOTHER`, `CUSTOMS`, `EXHIBITION`, `OTHER`, `SALE`, `STORE`, `WAREHOUSE` |\n| `carrier_id_type` | `NUIS`, `ID` |", "tags": [ "Fletë shoqëruese (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vehPlates": { "type": "string", "description": "Targa e automjetit.", "example": "AA123BB" }, "valueOfGoods": { "type": "number", "description": "Vlera e mallrave, ne ALL.", "example": 10000 }, "invoice_lines": { "type": "array", "description": "Rreshtat 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 }, "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" } }, "required": [ "vehPlates", "valueOfGoods", "invoice_lines" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "message": {} } }, "examples": { "example": { "summary": "Example", "value": { "status": false, "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/wtn/print/{id}": { "get": { "operationId": "api.v1.invoice.wtn.print", "summary": "Te dhenat e fatures shoqeruese ne format printimi (JSON)", "description": "Kthen te dhenat e fletes si JSON, jo nje PDF, qe ta formatoni vete dokumentin.\n\nPerdoreni kur printoni me nje sistem tuajin. Per dokumentin e gatshem perdorni PDF-ne e fletes.", "tags": [ "Fletë shoqëruese (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures shoqeruese ne fature.al.", "schema": { "type": "integer", "example": 403 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": {} } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": "data" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/wtn/{id}/details": { "get": { "operationId": "api.v1.invoice.wtn.details", "summary": "Detajet e fatures shoqeruese sipas ID", "description": "Kthen fleten e plote: automjetin, piket e nisjes dhe te mberritjes, transportuesin dhe rreshtat\ne mallit.", "tags": [ "Fletë shoqëruese (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures shoqeruese ne fature.al.", "schema": { "type": "integer", "example": 403 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": false }, "message": {} } }, "examples": { "example": { "summary": "Example", "value": { "status": false, "message": "Hello there" } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/invoice/{id}/details": { "get": { "operationId": "get-api-v1-invoice-id-details", "summary": "Detajet e fatures sipas ID", "description": "Merrni detajet e plota te nje fature sipas ID-se ne sistem.", "tags": [ "Faturat (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e fatures ne fature.al.", "schema": { "type": "integer", "example": 403 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "type": [ "object", "null" ], "properties": { "lines": { "type": "array", "items": { "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 with the line discount already taken off, 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": "Line discount percent, as sent in `lines[].discount` when the line was discounted" }, "discount": { "type": [ "number", "null" ], "description": "Line discount amount, net-denominated, major units" }, "amount_net": { "type": "number" }, "amount_vat": { "type": "number" }, "total": { "type": "number", "description": "Gross line total, major units" } } } } } } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "invoice": { "lines": [ { "name": "Jane Doe", "product_code": "product code", "unit": "unit", "unit_code": "unit code", "quantity": 2, "unitPrice": 1999, "vat_rate": 19.99, "vat_exempt_type": "vat exempt type", "discount_rate": 3, "discount": 3, "amount_net": 4200, "amount_vat": 4200, "total": 4200 } ] } } } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/bank-account": { "post": { "operationId": "api.v1.on-boarding.bank-account", "summary": "Krijo llogari bankare", "description": "Krijoni nje llogari bankare per kompanine. Llogaria bankare shfaqet ne faturat elektronike dhe jo-cash si informacion pagese per klientin.", "tags": [ "Regjistrimi (v1)" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Emri i bankes, ai qe shfaqet ne fature krahas IBAN-it.", "example": "BKT" }, "holder": { "type": [ "string", "null" ], "description": "Mbajtesi i llogarise, zakonisht emri i kompanise.", "example": "Ei3 Software Solution shpk" }, "iban": { "type": [ "string", "null" ], "description": "IBAN-i i llogarise, ai qe shfaqet ne fature qe klienti te paguaje.", "example": "AL35202111090000000001234567" }, "swift": { "type": [ "string", "null" ], "description": "Kodi SWIFT/BIC i bankes, i nevojshem per pagesa nga jashte.", "example": "NCBAALTX" }, "currency": { "type": [ "string", "null" ], "description": "Monedha e llogarise. Nje llogari mban nje monedhe te vetme.", "example": "ALL" }, "notes": { "type": [ "string", "null" ], "description": "Shenime qe shoqerojne llogarine ne fature." } } } } } }, "responses": { "200": { "description": "Kur ruajtja e llogarise deshton, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "bankAccount": { "type": "object", "properties": { "id": { "type": "integer" }, "iban": { "type": "string" } }, "required": [ "id", "iban" ] } }, "required": [ "bankAccount" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "bankAccount": { "id": 1, "iban": "iban" } } } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/branch": { "post": { "operationId": "api.v1.on-boarding.branch-create", "summary": "Krijo njesi biznesi (Branch)", "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.", "tags": [ "Regjistrimi (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Emri i njesise se biznesit, ai qe del ne fature.", "example": "Dega Tirane", "maxLength": 255 }, "type": { "type": "string", "description": "Lloji i njesise: `main` per seline qendrore, `secondary` per nje seli dytesore.", "example": "main" }, "administrator": { "type": "string", "description": "Emri i personit pergjegjes per njesine.", "example": "Festim Peposhi", "maxLength": 255 }, "address": { "type": "string", "description": "Adresa e njesise, e cila shkon ne sistemin fiskal.", "example": "Rruga e Kavajes 12, Tirane", "maxLength": 255 }, "businessUnitCode": { "type": [ "string", "null" ], "description": "Kodi i njesise se biznesit nga tatimet. Pa te, njesia merr nje kod te ri.", "example": "bb123bb123", "maxLength": 50 } }, "required": [ "name", "type", "administrator", "address" ] } } } }, "responses": { "200": { "description": "Kur krijimi deshton per nje arsye tjeter, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "branch": { "id": 1, "name": "Jane Doe", "type": "type", "administrator": "administrator", "address": "1 Example Street", "businessUnitCode": "businessUnitCode" } } } } } } } }, "403": { "description": "Abonimi nuk lejon me njesi biznesi.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Kompania ka tashme nje seli qendrore.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/branch/{id}": { "post": { "operationId": "api.v1.on-boarding.branch", "summary": "Perditeso njesine e biznesit (Branch)", "description": "Perditesoni emrin, adresen, administratorin dhe kodin e biznesit per nje njesi biznesi ekzistuese. Kodi i biznesit (businessUnitCode) eshte i domosdoshem per leshimin e faturave.", "tags": [ "Regjistrimi (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e njesise se biznesit.", "schema": { "type": "integer", "example": 12 } } ], "responses": { "200": { "description": "Kur njesia nuk gjendet ose ruajtja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "branch": { "id": 1, "name": "Jane Doe", "businessUnitCode": "businessUnitCode" } } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/certificate": { "post": { "operationId": "api.v1.on-boarding.certificate", "summary": "Ngarko certifikaten elektronike", "description": "Ngarkoni certifikaten elektronike (.p12 ose .pfx) per kompanine. 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.", "tags": [ "Regjistrimi (v1)" ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "certificate_file": { "type": [ "string", "null" ], "format": "binary", "description": "Certifikata elektronike si skedar, ne formatin PFX. Me te nenshkruhen faturat qe dergohen ne fiskalizim, prandaj pa nje certifikate te vlefshme nuk leshohet dot fature." }, "password": { "type": [ "string", "null" ], "description": "Fjalekalimi i skedarit PFX. Pa te certifikata nuk hapet dot dhe nenshkrimi deshton." } } } } } }, "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`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "cert": { "type": "object", "properties": { "expiresAt": { "type": "string" } }, "required": [ "expiresAt" ] } }, "required": [ "cert" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "cert": { "expiresAt": "expiresAt" } } } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/fiscal-device": { "post": { "operationId": "api.v1.on-boarding.fiscal-device", "summary": "Krijo pajisje fiskale (TCR)", "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.", "tags": [ "Regjistrimi (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "branchId": { "type": "integer", "description": "ID e njesise se biznesit ku ndodhet pajisja, ashtu sic ju ktheu `POST /on-boarding/branch`. Cdo TCR i perket nje njesie te vetme.", "example": 12 }, "name": { "type": "string", "description": "Emri i pajisjes fiskale, ai qe e dallon nga te tjerat ne te njejten njesi.", "example": "Arka 1", "maxLength": 255 }, "fromDate": { "type": "string", "description": "Data nga e cila pajisja fillon te leshoje fatura, ne formatin `YYYY-MM-DD`.", "example": "2026-01-01" }, "toDate": { "type": [ "string", "null" ], "description": "Data deri kur pajisja eshte aktive. Pa te, pajisja mbetet aktive pa afat.", "example": "2026-12-31" } }, "required": [ "branchId", "name", "fromDate" ] } } } }, "responses": { "200": { "description": "Kur regjistrimi i pajisjes ne fiskalizim deshton, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "device": { "type": "object", "properties": { "fiscalTcrCode": { "type": "string" } }, "required": [ "fiscalTcrCode" ] } }, "required": [ "device" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "device": { "fiscalTcrCode": "fiscalTcrCode" } } } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/user": { "post": { "operationId": "api.v1.on-boarding.user", "summary": "Krijo perdorues te ri", "description": "Krijoni nje perdorues te ri per kompanine me kodin e operatorit dhe pajisjen fiskale. Kthen token API per kete perdorues.", "tags": [ "Regjistrimi (v1)" ], "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`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "user": { "id": 1, "name": "Jane Doe", "operatorCode": "operatorCode", "token": "a1b2c3d4e5f6" } } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/on-boarding/user/{id}": { "post": { "operationId": "api.v1.on-boarding.user-update", "summary": "Perditeso perdoruesin", "description": "Perditesoni emrin, kodin e operatorit, pajisjen fiskale dhe njesine e biznesit per nje perdorues ekzistues. Kodi i operatorit eshte i domosdoshem per leshimin e faturave.", "tags": [ "Regjistrimi (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e perdoruesit.", "schema": { "type": "integer", "example": 7 } } ], "responses": { "200": { "description": "Kur perdoruesi nuk gjendet ose ruajtja deshton, pergjigja kthehet me HTTP 200 dhe `status: false`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "user": { "id": 1, "name": "Jane Doe", "operatorCode": "operatorCode" } } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/ping": { "get": { "operationId": "get-api-v1-ping", "summary": "Ping", "description": "Kontrollo nese API eshte aktiv. Kthen timestamp dhe IP.", "tags": [ "Ping (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "pong": { "type": "integer" }, "ip": { "type": "array", "items": { "type": "string" } } }, "required": [ "pong", "ip" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "pong": 1, "ip": [ "ip" ] } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/product/categories": { "get": { "operationId": "get-api-v1-product-categories", "summary": "Lista e kategorive", "description": "Merrni listen e kategorive te produkteve per kompanine tuaj. Kthehen te gjitha ne nje pergjigje\nte vetme, pa faqosje.\n\nKur limiti i kerkesave arrihet ose ndodh nje gabim i papritur, pergjigja kthehet me HTTP 200 dhe\n`status: false`, prandaj lexoni `status` dhe jo vetem kodin HTTP.", "tags": [ "Produkte (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ], "description": "Hex colour used by the POS grid" } } } } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": [ { "id": 1, "name": "Jane Doe", "color": "color" } ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/products": { "get": { "operationId": "get-api-v1-products", "summary": "Lista e produkteve", "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```\n\nKur limiti i kerkesave arrihet ose ndodh nje gabim i papritur, pergjigja kthehet me HTTP 200 dhe\n`status: false`, prandaj lexoni `status` dhe jo vetem kodin HTTP.", "tags": [ "Produkte (v1)" ], "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": "service", "in": "query", "description": "true kthen vetem sherbimet, false vetem artikujt e inventarit. Pa te kthehen te dyja.", "schema": { "type": "boolean", "example": false } }, { "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`. Defaults to `0`.", "schema": { "type": "integer", "example": 0 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "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" ] } } } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": [ { "id": 1, "code": "code", "name": "Jane Doe", "description": "A short description.", "unit": "unit", "unit_code": "unit code", "last_price": 1999, "cost_price": 1999, "vat_rate": 19.99, "vat_exempt_type": "vat exempt type", "vat_exempt_description": "A short description.", "currency": "USD", "id_category": 1 } ], "pagination": { "records": 1, "total": 4200, "limit": 25, "offset": 0 } } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] }, "post": { "operationId": "api.v1.products.create", "summary": "Krijo produkt", "description": "Krijon nje produkt te ri per kompanine tuaj.\n\n- **`code` gjenerohet vete** nese nuk e dergoni, prandaj mund ta lini bosh dhe ta ruani ate qe\n ju kthehet.\n- **`unit` nuk dergohet**: njesia matese derivohet nga `unit_code`, i cili eshte kodi qe mban\n dokumenti fiskal.\n- `vat_rate` pranon `0`, `6`, `10` ose `20`. Per nje produkt te perjashtuar shtoni\n `vat_exempt_type`.\n\nProdukti i krijuar ketu del menjehere ne `GET /products` dhe mund te perdoret ne rreshtat e\nnje fature.", "tags": [ "Produkte (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 }, "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 }, "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", "last_price", "vat_rate" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "product": { "type": "object", "properties": { "service": { "type": "boolean", "description": "True for a service, false for an article that is tracked in stock" }, "category": { "type": [ "object", "null" ], "description": "The category resolved, or null when the product has none", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ], "description": "Hex colour used by the POS grid" } } }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601" } } } }, "required": [ "product" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "product": { "service": true, "category": { "id": 1, "name": "Jane Doe", "color": "color" }, "created_at": "created at" } } } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Ekziston tashme nje regjistrim me te njejtat te dhena.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/products/{id}": { "put": { "operationId": "api.v1.products.update", "summary": "Perditeso produkt", "description": "Perditeson nje produkt ekzistues. Trupi ka te njejtin format si `POST /products`, prandaj\n`unit_code` dhe `vat_rate` vlejne me te njejtat rregulla.\n\nNdryshimi i cmimit nuk prek faturat e leshuara: ato mbajne cmimin me te cilin u shiten.", "tags": [ "Produkte (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e produktit.", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "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 }, "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 }, "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", "last_price", "vat_rate" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "product": { "type": "object", "properties": { "service": { "type": "boolean", "description": "True for a service, false for an article that is tracked in stock" }, "category": { "type": [ "object", "null" ], "description": "The category resolved, or null when the product has none", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ], "description": "Hex colour used by the POS grid" } } }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601" } } } }, "required": [ "product" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "product": { "service": true, "category": { "id": 1, "name": "Jane Doe", "color": "color" }, "created_at": "created at" } } } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "404": { "description": "Produkti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Ekziston tashme nje produkt me kete kod.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/products/{id}/details": { "get": { "operationId": "api.v1.products.details", "summary": "Detajet e produktit sipas ID", "description": "Merrni detajet e nje produkti sipas id-se per kompanine tuaj.\n\nKthen me shume se lista: pervec emrit dhe cmimit, edhe kodin fiskal te njesise, normen e TVSH-se\ndhe kategorine.", "tags": [ "Produkte (v1)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e produktit.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "product": { "type": "object", "properties": { "service": { "type": "boolean", "description": "True for a service, false for an article that is tracked in stock" }, "category": { "type": [ "object", "null" ], "description": "The category resolved, or null when the product has none", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ], "description": "Hex colour used by the POS grid" } } }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601" } } } }, "required": [ "product" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "product": { "service": true, "category": { "id": 1, "name": "Jane Doe", "color": "color" }, "created_at": "created at" } } } } } } } }, "404": { "description": "Produkti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/purchase-invoices": { "get": { "operationId": "api.v1.purchase-invoices.list", "summary": "Lista e faturave te blerjes", "description": "Merrni faturat qe furnitoret ju kane leshuar juve, ashtu sic i ka regjistruar sistemi fiskal.\nFurnitori nuk ju dergon gje: dokumentet vijne nga tatimet.\n\nPer cdo fature terhiqen te dhenat e plota: artikujt, shitesi, bleresi, TVSH-ja dhe menyrat e\npageses. Kjo e ben rakordimin e blerjeve dhe te TVSH-se te mundur pa asnje hap manual.\n\n## Faqezimi\n\nKy endpoint lexon nga fiskalizimi, jo nga baza jone, prandaj faqezohet me `page` qe fillon nga\n`1` dhe jo me `limit` me `offset`. Perseritni me `page + 1` derisa `items` te kthehet bosh.\n\nPa `fromDate` dhe `toDate` merret dita e sotme, jo e gjithe historia.", "tags": [ "Faturat e blerjes (v1)" ], "parameters": [ { "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" } }, { "name": "page", "in": "query", "description": "Faqja e listes nga fiskalizimi. Perserit me page+1 derisa items te kthehet bosh. Defaults to `1`.", "schema": { "type": "integer", "example": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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", "null" ] }, "invoiceType": { "type": "string" }, "issuerTaxNumber": { "type": "string" }, "seller": { "type": "object", "properties": { "idType": { "type": "string" }, "idNum": { "type": "string" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "town": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "idType", "idNum", "name", "address", "town", "country" ] }, "buyer": { "type": "object", "properties": { "idType": { "type": "string" }, "idNum": { "type": "string" }, "name": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "town": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "idType", "idNum", "name", "address", "town", "country" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "unitPriceAfterVat": { "type": "number" }, "priceAfterVat": { "type": "number" }, "vatAmount": { "type": "number" }, "vatRate": { "type": [ "number", "null" ] }, "exemptFromVat": { "type": [ "string", "null" ] } }, "required": [ "name", "code", "unit", "quantity", "unitPriceAfterVat", "priceAfterVat", "vatAmount", "vatRate", "exemptFromVat" ] } }, "paymentMethod": { "type": "array", "items": { "type": "object", "properties": { "typeCode": { "type": "string" }, "compCard": { "type": [ "string", "null" ] } }, "required": [ "typeCode", "compCard" ] } }, "currency": { "type": [ "object", "null" ], "properties": { "code": { "type": "string" }, "exchangeRate": { "type": "number" } }, "required": [ "code", "exchangeRate" ] }, "totalPrice": { "type": "number" }, "totalPriceWithoutVAT": { "type": "number" }, "reverseCharge": { "type": "boolean" }, "businessUnit": { "type": [ "string", "null" ] }, "operatorCode": { "type": [ "string", "null" ] }, "tcrCode": { "type": [ "string", "null" ] }, "softwareCode": { "type": [ "string", "null" ] }, "iicSignature": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "items": [ { "iic": "iic", "fic": "fic", "invoiceNumber": "invoiceNumber", "invoiceOrderNumber": 1, "dateTimeCreated": "dateTimeCreated", "payDeadline": "payDeadline", "invoiceType": "invoiceType", "issuerTaxNumber": "issuerTaxNumber", "seller": { "idType": "idType", "idNum": "idNum", "name": "Jane Doe", "address": "1 Example Street", "town": "town", "country": "US" }, "buyer": { "idType": "idType", "idNum": "idNum", "name": "Jane Doe", "address": "1 Example Street", "town": "town", "country": "US" }, "items": [ { "name": "Jane Doe", "code": "code", "unit": "unit", "quantity": 2, "unitPriceAfterVat": 1999, "priceAfterVat": 1999, "vatAmount": 4200, "vatRate": 19.99, "exemptFromVat": "exemptFromVat" } ], "paymentMethod": [ { "typeCode": "typeCode", "compCard": "compCard" } ], "currency": { "code": "code", "exchangeRate": 19.99 }, "totalPrice": 4200, "totalPriceWithoutVAT": 4200, "reverseCharge": true, "businessUnit": "businessUnit", "operatorCode": "operatorCode", "tcrCode": "tcrCode", "softwareCode": "softwareCode", "iicSignature": "iicSignature" } ], "pagination": { "records": 1, "page": 1 } } } } } } } }, "422": { "description": "Formati i datave nuk eshte YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "502": { "description": "Fiskalizimi u pergjigj me nje gabim.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "503": { "description": "Sherbimi i fiskalizimit eshte i paarritshem.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/register": { "get": { "operationId": "api.v1.pong", "summary": "Ping (Register)", "description": "Kontrollo nese API eshte aktiv per regjistrimin e kompanive.", "tags": [ "Regjistrimi (v1)" ], "responses": { "200": { "description": "Kur llogaria juaj nuk eshte e autorizuar per onboarding, pergjigja kthehet me HTTP 200 dhe `status: false`.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] }, "post": { "operationId": "api.v1.register", "summary": "Regjistro kompani te re", "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.", "tags": [ "Regjistrimi (v1)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Emri tregtar i kompanise qe po regjistrohet.", "example": "Ei3 Software Solution shpk", "maxLength": 255 }, "address": { "type": "string", "description": "Adresa e selise se kompanise, ashtu sic eshte regjistruar.", "example": "Rruga e Kavajes 12, Tirane", "maxLength": 255 }, "administrator": { "type": "string", "description": "Emri i administratorit te kompanise.", "example": "Festim Peposhi", "maxLength": 255 }, "phone": { "type": "string", "description": "Telefoni i kontaktit i kompanise.", "example": "+355 69 000 0000", "maxLength": 50 }, "email": { "type": "string", "format": "email", "description": "Email-i i perdoruesit te pare, ai qe do te administroje llogarine.", "example": "admin@example.com", "maxLength": 255 }, "issuerInVat": { "type": [ "boolean", "null" ], "description": "A eshte kompania e regjistruar per TVSH. Percakton nese faturat dalin me TVSH.", "example": true }, "lastNonCashEInvoiceNumber": { "type": [ "string", "null" ], "description": "Numri i fundit i perdorur ne sistemin e meparshem, qe numerimi te vazhdoje nga aty dhe te mos rifilloje nga 1.", "example": 412, "maxLength": 50 } }, "required": [ "name", "address", "administrator", "phone", "email" ] } } } }, "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`." }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "user": { "token": "a1b2c3d4e5f6", "id": 1 }, "branch": { "id": 1, "name": "Jane Doe" } } } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/by-operator": { "get": { "operationId": "api.v1.reports.by-operator", "summary": "Shitjet sipas operatorit", "description": "Sa fatura leshoi dhe sa vlere beri secili operator ne periudhe.\n\nPerdoret per krahasim mes turneve dhe per shperblime sipas shitjes. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e fillimit, e perfshire.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e perfundimit, e perfshire.", "example": "2026-01-31" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "id_user": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "operator_code": { "type": [ "string", "null" ] }, "invoices": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "id_user", "name", "operator_code", "invoices", "gross" ] } } }, "required": [ "period", "items" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "items": [ { "id_user": 1, "name": "Jane Doe", "operator_code": "operator code", "invoices": 1, "gross": 19.99 } ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/by-tcr": { "get": { "operationId": "api.v1.reports.by-tcr", "summary": "Shitjet sipas pajisjes fiskale", "description": "Sa fatura leshoi dhe sa vlere beri secila pajisje fiskale (TCR) ne periudhe.\n\nNje biznes me disa njesi e perdor kete per te ndare shitjet sipas pikes se shitjes, sepse cdo\nTCR i perket nje njesie te vetme. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e fillimit, e perfshire.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e perfundimit, e perfshire.", "example": "2026-01-31" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "tcr_code": { "type": [ "string", "null" ] }, "invoices": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "tcr_code", "invoices", "gross" ] } } }, "required": [ "period", "items" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "items": [ { "tcr_code": "tcr code", "invoices": 1, "gross": 19.99 } ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/cash-register": { "get": { "operationId": "api.v1.reports.cash-register", "summary": "Gjendja e arkes per nje dite", "description": "Gjendja e arkes fiskale per nje dite te vetme: hapja, mbyllja dhe **mbyllja e pritur**, bashke\nme shitjet sipas menyres se pageses dhe levizjet e parave.\n\nMbyllja e pritur eshte ajo qe duhet te kete arka po te jete regjistruar gjithcka. Diferenca me\nmbylljen reale eshte pikerisht ajo qe kerkohet ne rakordim.\n\nPa `date` merret dita e sotme. Formati eshte `YYYY-MM-DD`.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "date", "in": "query", "description": "Dita e raportit. Pa te merret sot.", "schema": { "type": [ "string", "null" ], "format": "date", "description": "Dita e raportit. Pa te merret sot.", "example": "2026-04-21" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "date": { "type": "string" }, "currency": { "type": "string" }, "opening": { "type": "number" }, "closing": { "type": "number" }, "expected_closing": { "type": "number" }, "tcr": { "type": [ "string", "null" ] }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "date": "date", "currency": "USD", "opening": 19.99, "closing": 19.99, "expected_closing": 19.99, "tcr": "tcr", "operator": "operator", "sales_by_method": [ { "method": "method", "label": "label", "count": 3, "gross": 19.99, "net": 19.99, "vat": 19.99 } ], "movements": { "deposits_count": 3, "deposits_total": 4200, "withdrawals_count": 3, "withdrawals_total": 4200 } } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/cash-register/closing": { "get": { "operationId": "api.v1.reports.cash-register.closing", "summary": "Raporti i mbylljes se arkes", "description": "Raporti i fundit i dites, ai qe printohet kur mbyllet turni: totalet e shitjeve, produktet e\nshitura dhe levizjet e parave.\n\nNdryshimi nga gjendja e arkes eshte fokusi: ky raport i perket **turnit qe u mbyll**, jo dites\nsi periudhe.\n\nPa `date` merret dita e sotme. Formati eshte `YYYY-MM-DD`.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "date", "in": "query", "description": "Dita e raportit. Pa te merret sot.", "schema": { "type": [ "string", "null" ], "format": "date", "description": "Dita e raportit. Pa te merret sot.", "example": "2026-04-21" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "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", "null" ] }, "closed_at": { "type": [ "string", "null" ] }, "tcr": { "type": [ "string", "null" ] }, "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", "null" ] }, "quantity": { "type": "number" }, "unit": { "type": [ "string", "null" ] }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "date": "date", "currency": "USD", "opening": 19.99, "closing": 19.99, "closing_total": 4200, "expected_closing": 19.99, "opened_at": "opened at", "closed_at": "closed at", "tcr": "tcr", "operator": "operator", "sales": { "invoice_count": 3, "gross_total": 4200, "net_total": 4200, "vat_total": 4200 }, "sales_by_method": [ { "method": "method", "label": "label", "count": 3, "gross": 19.99, "net": 19.99, "vat": 19.99 } ], "products_sold": [ { "product_name": "Jane Doe", "product_code": "product code", "quantity": 2, "unit": "unit", "unit_price": 1999, "gross": 19.99 } ], "movements": { "deposits_count": 3, "deposits_total": 4200, "withdrawals_count": 3, "withdrawals_total": 4200 } } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/daily-trend": { "get": { "operationId": "api.v1.reports.daily-trend", "summary": "Ecuria ditore", "description": "Nje pike per cdo dite te periudhes, gati per nje grafik.\n\n| `metric` | Cfare mat pika |\n| --- | --- |\n| `gross` | Vlera bruto e shitjeve |\n| `count` | Numri i faturave |\n\nDitet pa shitje kthehen me vlere `0` dhe nuk hiqen nga seria, keshtu qe grafiku nuk\nshtrembrohet.\n\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "metric": "metric", "series": [ { "date": "date", "count": 3, "gross": 19.99 } ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/reversals": { "get": { "operationId": "api.v1.reports.reversals", "summary": "Faturat e anulluara", "description": "Faturat e anulluara ne periudhe, secila e lidhur me faturen origjinale qe korrigjon.\n\n`limit` pranon nga `1` deri ne `500`. Perdoreni per te kontrolluar sa dhe pse anulohet, sepse\nnje numer i larte anulimesh eshte zakonisht shenje e nje problemi ne procesin e shitjes. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "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", "null" ] }, "original_invoice_id": { "type": [ "integer", "null" ] }, "gross": { "type": "number" }, "operator": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "type", "reversed_at", "original_invoice_id", "gross", "operator" ] } } }, "required": [ "period", "totals", "items" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "totals": { "count": 3, "gross": 19.99 }, "items": [ { "id": 1, "number": "number", "type": "type", "reversed_at": "reversed at", "original_invoice_id": 1, "gross": 19.99, "operator": "operator" } ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/sales-summary": { "get": { "operationId": "api.v1.reports.sales-summary", "summary": "Permbledhje e shitjeve", "description": "Totalet e shitjeve per nje periudhe, te llogaritura ne baze te te dhenave. Vlerat jane ne ALL.\n\nNdarjet qe kthehen njeheresh:\n\n- sipas menyres se pageses;\n- sipas tipit te fatures;\n- sipas shkalles se TVSH;\n- sipas dites.\n\nPerfshin edhe sa fatura u anulluan, keshtu qe nuk ju duhet nje thirrje e dyte per t'i zbritur. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e fillimit, e perfshire.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e perfundimit, e perfshire.", "example": "2026-01-31" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "totals": { "invoices": 1, "gross": 19.99, "net": 19.99, "vat": 19.99, "avg_invoice": 19.99, "currency": "USD" }, "by_payment_method": [ { "method": "method", "count": 3, "gross": 19.99, "net": 19.99, "vat": 19.99 } ], "by_type": [ { "type": "type", "count": 3, "gross": 19.99 } ], "by_vat_rate": [ { "rate": 19.99, "net": 19.99, "vat": 19.99, "gross": 19.99 } ], "by_day": [ { "date": "date", "count": 3, "gross": 19.99 } ], "cancelled": { "count": 3, "gross": 19.99 } } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/top-clients": { "get": { "operationId": "api.v1.reports.top-clients", "summary": "Klientet kryesore", "description": "Klientet e renditur sipas vleres se faturuar ne periudhe.\n\n`limit` pranon nga `1` deri ne `500`. Klientet e rastit, pra faturat pa klient te emeruar, nuk\nhyjne ne renditje. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id_client": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "nipt": { "type": [ "string", "null" ] }, "invoices": { "type": "integer" }, "gross": { "type": "number" } }, "required": [ "id_client", "name", "nipt", "invoices", "gross" ] } } }, "required": [ "period", "limit", "items" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "limit": 25, "items": [ { "id_client": 1, "name": "Jane Doe", "nipt": "nipt", "invoices": 1, "gross": 19.99 } ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/top-products": { "get": { "operationId": "api.v1.reports.top-products", "summary": "Produktet me te shitura", "description": "Produktet e renditura sipas te ardhurave ose sipas sasise se shitur.\n\n| Parametri | Vlerat | Parazgjedhja |\n| --- | --- | --- |\n| `sort` | `revenue`, `quantity` | `revenue` |\n| `limit` | `1` deri ne `200` | `20` | *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "sort": { "type": "string" }, "limit": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id_product": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "revenue": { "type": "number" } }, "required": [ "id_product", "name", "code", "unit", "quantity", "revenue" ] } } }, "required": [ "period", "sort", "limit", "items" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "sort": "sort", "limit": 25, "items": [ { "id_product": 1, "name": "Jane Doe", "code": "code", "unit": "unit", "quantity": 2, "revenue": 19.99 } ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/vat": { "get": { "operationId": "api.v1.reports.vat", "summary": "Raporti i TVSH", "description": "TVSH e mbledhur nga shitjet perballe asaj te paguar ne blerje, me diferencen qe rezulton.\n\nRreshtat ndahen ne dy grupe:\n\n- **te tatueshem**, sipas shkalles: `0`, `6`, `10`, `20`;\n- **te perjashtuar**, sipas llojit te perjashtimit.\n\nBlerjet vijne nga faturat qe ka regjistruar sistemi fiskal, prandaj raporti mbulon te dyja anet\npa ju kerkuar te importoni gje. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e fillimit, e perfshire.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e perfundimit, e perfshire.", "example": "2026-01-31" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "totals": { "net": 19.99, "vat": 19.99, "gross": 19.99, "currency": "USD" }, "taxable": [ { "rate": 19.99, "net": 19.99, "vat": 19.99, "gross": 19.99 } ], "exempt": [ { "exempt_type": "exempt type", "rate": 19.99, "net": 19.99, "vat": 19.99, "gross": 19.99 } ], "purchases": { "taxable": [ { "rate": 19.99, "net": 19.99, "vat": 19.99, "gross": 19.99 } ], "exempt": [ { "exempt_type": "exempt type", "rate": 19.99, "net": 19.99, "vat": 19.99, "gross": 19.99 } ], "totals": { "net": 19.99, "vat": 19.99, "gross": 19.99, "currency": "USD" } }, "summary": { "output_vat": 19.99, "input_vat": 19.99, "vat_due": 19.99, "currency": "USD" } } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v1/reports/wtn": { "get": { "operationId": "api.v1.reports.wtn", "summary": "Raporti i faturave shoqeruese", "description": "Fletet shoqeruese te periudhes, te grupuara sipas gjendjes fiskale, bashke me destinacionet e\nperdorura dhe vleren e mallit qe ka levizur.\n\nNje flete e pafiskalizuar ketu eshte gje qe kerkon vemendje: malli ka levizur pa dokumentin qe\nligji kerkon. *\n`from` dhe `to` jane te detyrueshme, ne formatin `YYYY-MM-DD`, dhe periudha kthehet e\nkonfirmuar ne `period` te pergjigjes.", "tags": [ "Raportet (v1)" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Data e fillimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e fillimit, e perfshire.", "example": "2026-01-01" } }, { "name": "to", "in": "query", "required": true, "description": "Data e perfundimit, e perfshire.", "schema": { "type": "string", "format": "date", "description": "Data e perfundimit, e perfshire.", "example": "2026-01-31" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "description": "Start date (YYYY-MM-DD), inclusive" }, "to": { "type": "string", "description": "End date (YYYY-MM-DD), inclusive" } } }, "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", "null" ] }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "period": { "from": "from", "to": "to" }, "totals": { "count": 3, "value_of_goods": 19.99 }, "by_status": [ { "status": "status", "count": 3, "value_of_goods": 19.99 } ], "unique_destinations": 1, "destinations": [ "destinations" ] } } } } } } }, "422": { "description": "Datat mungojne ose nuk jane ne formatin YYYY-MM-DD.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "429": { "description": "Kufiri i kerkesave u arrit: 30 raporte ne minute.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v2/clients": { "get": { "operationId": "api.v2.clients.list", "summary": "Lista e klienteve", "description": "Merr listen e klienteve te kompanise me faqosje dhe filtrim me tekst.\n\nFaqezohet me `limit` dhe `offset`. `limit` kufizohet ne **100** dhe `pagination` kthen edhe\n`total`, prandaj e dini qe ne faqen e pare sa faqe ju presin: vazhdoni me `offset += limit`\nderisa `offset` te kaloje `total`.", "tags": [ "Klienti (v2)" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i klienteve per faqe (max 100). Defaults to `20`.", "schema": { "type": "integer", "example": 20 } }, { "name": "offset", "in": "query", "description": "Nga cili klient te fillohet. Defaults to `0`.", "schema": { "type": "integer", "example": 0 } }, { "name": "query", "in": "query", "description": "Kerkim ne emer, mbiemer, NIPT, dokument, email ose telefon.", "schema": { "type": "string", "example": "Agon" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "company_type": { "type": [ "string", "null" ] }, "nipt": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "surname": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ] }, "id_type": { "type": [ "string", "null" ] }, "id_num": { "type": [ "string", "null" ] }, "nationality_code": { "type": [ "string", "null" ] }, "nationality_id": { "type": [ "integer", "null" ] }, "telephone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "customer_number": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] } }, "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" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "items": [ { "id": 1, "name": "Jane Doe", "client_type": "client type", "company_name": "Jane Doe", "company_type": "company type", "nipt": "nipt", "first_name": "Jane", "surname": "Jane Doe", "birthday": "birthday", "id_type": "id type", "id_num": "id num", "nationality_code": "nationality code", "nationality_id": 1, "telephone": "+15551234567", "email": "jane@example.com", "address": "1 Example Street", "city": "Berlin", "customer_number": "customer number", "created_at": "created at" } ], "pagination": { "records": 1, "total": 4200, "limit": 25, "offset": 0 } } } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] }, "post": { "operationId": "api.v2.clients.create", "summary": "Krijo klient (v2)", "description": "Trupi eshte nje bashkim i diskriminuar nga fusha `type`, e cila pranon `company` ose `person`.\nPlotesohet vetem objekti qe i perket llojit.\n\n| `type` | Objekti | Fushat e detyrueshme |\n| --- | --- | --- |\n| `company` | `company` | `name`, `id` |\n| `person` | `person` | `first_name`, `last_name`, `id` |\n\n## Identifikuesi\n\nJepet gjithmone si objekt `id` me `type` dhe `value`, dhe vlerat e lejuara varen nga lloji:\n\n- kompani: `nuis`, `vat`, `tax`;\n- person: `id`, `passport`, `social`.\n\n## Objektet e perbashketa\n\n`address` (`line`, `city`, `country` me tre shkronja) dhe `contact` (`phone`, `email`) jane\nopsionale dhe vlejne per te dy llojet. `company.category` pranon `business`, `bank` ose\n`exchange`.", "tags": [ "Klienti (v2)" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Lloji i klientit, i cili vendos se cili objekt plotesohet: `company` ose `person`. Ne editim eshte i pandryshueshem, prandaj nje `type` i ndryshem nga ai ekzistues refuzohet me `422`.", "example": "company" }, "company": { "type": "object", "description": "Required depending on type.", "properties": { "name": { "type": [ "string", "null" ], "description": "Required depending on type.", "maxLength": 255 }, "category": { "type": [ "string", "null" ] }, "id": { "type": "object", "description": "Required depending on type.", "properties": { "type": { "type": "string", "description": "Required when company.id is present." }, "value": { "type": "string", "description": "Required when company.id is present.", "maxLength": 20 } }, "required": [ "type", "value" ] } }, "required": [ "name", "id" ] }, "person": { "type": "object", "description": "Required depending on type.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "Required depending on type.", "maxLength": 255 }, "last_name": { "type": [ "string", "null" ], "description": "Required depending on type.", "maxLength": 255 }, "birthday": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "object", "description": "Required depending on type.", "properties": { "type": { "type": "string", "description": "Required when person.id is present." }, "value": { "type": "string", "description": "Required when person.id is present.", "maxLength": 255 } }, "required": [ "type", "value" ] } }, "required": [ "first_name", "last_name", "id" ] }, "address": { "type": [ "object", "null" ], "description": "Adresa e klientit. Opsionale, dhe e njejta per te dy llojet.", "properties": { "line": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 50 }, "country": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } }, "contact": { "type": [ "object", "null" ], "description": "Kontaktet e klientit: telefoni dhe email-i. Opsionale.", "properties": { "phone": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 } } }, "customer_number": { "type": [ "string", "null" ], "description": "Numri juaj i klientit, nese e mbani nje te tille ne sistemin tuaj.", "example": "CL-00412", "maxLength": 30 } }, "required": [ "type", "company", "person" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "`company` or `person`" }, "company": { "type": [ "object", "null" ], "description": "Filled when `type` is `company`, null otherwise", "properties": { "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "description": "`business`, `bank` or `exchange`, or null when unclassified" }, "id": { "type": "object", "properties": { "type": { "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person" }, "value": { "description": "The identifier itself, null when the client has none recorded" } } } } }, "person": { "type": [ "object", "null" ], "description": "Filled when `type` is `person`, null otherwise", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ], "description": "Date of birth (YYYY-MM-DD)" }, "id": { "type": "object", "properties": { "type": { "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person" }, "value": { "description": "The identifier itself, null when the client has none recorded" } } } } }, "address": { "type": "object", "properties": { "line": { "type": [ "string", "null" ], "description": "Street address" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-3 country code" } } }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "customer_number": { "type": [ "string", "null" ], "description": "Your own reference for this client, when one was given" }, "verified": { "type": "boolean", "description": "Whether the identifier was confirmed against the fiscal register" }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601" }, "updated_at": { "type": [ "string", "null" ], "description": "Last update timestamp, ISO 8601" } } } }, "required": [ "client" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "id": 1, "type": "type", "company": { "name": "Jane Doe", "category": "category", "id": { "type": "type", "value": "value" } }, "person": { "first_name": "Jane", "last_name": "Doe", "birthday": "birthday", "id": { "type": "type", "value": "value" } }, "address": { "line": "line", "city": "Berlin", "country": "US" }, "contact": { "phone": "+15551234567", "email": "jane@example.com" }, "customer_number": "customer number", "verified": true, "created_at": "created at", "updated_at": "updated at" } } } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Ekziston tashme nje regjistrim me te njejtat te dhena.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } }, "/api/v2/clients/{id}": { "get": { "operationId": "api.v2.clients.show", "summary": "Detajet e klientit (v2)", "description": "Kthen klientin ne formatin e ri, me objekte te ndara: `company` ose `person` sipas `type`, plus\n`address` dhe `contact`.\n\nEshte i njejti klient qe kthen edhe `v1`, vetem i strukturuar ndryshe. Nje klient i krijuar me\n`v1` lexohet ketu pa asnje hap tjeter.", "tags": [ "Klienti (v2)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer", "example": 42 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "`company` or `person`" }, "company": { "type": [ "object", "null" ], "description": "Filled when `type` is `company`, null otherwise", "properties": { "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "description": "`business`, `bank` or `exchange`, or null when unclassified" }, "id": { "type": "object", "properties": { "type": { "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person" }, "value": { "description": "The identifier itself, null when the client has none recorded" } } } } }, "person": { "type": [ "object", "null" ], "description": "Filled when `type` is `person`, null otherwise", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ], "description": "Date of birth (YYYY-MM-DD)" }, "id": { "type": "object", "properties": { "type": { "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person" }, "value": { "description": "The identifier itself, null when the client has none recorded" } } } } }, "address": { "type": "object", "properties": { "line": { "type": [ "string", "null" ], "description": "Street address" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-3 country code" } } }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "customer_number": { "type": [ "string", "null" ], "description": "Your own reference for this client, when one was given" }, "verified": { "type": "boolean", "description": "Whether the identifier was confirmed against the fiscal register" }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601" }, "updated_at": { "type": [ "string", "null" ], "description": "Last update timestamp, ISO 8601" } } } }, "required": [ "client" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "id": 1, "type": "type", "company": { "name": "Jane Doe", "category": "category", "id": { "type": "type", "value": "value" } }, "person": { "first_name": "Jane", "last_name": "Doe", "birthday": "birthday", "id": { "type": "type", "value": "value" } }, "address": { "line": "line", "city": "Berlin", "country": "US" }, "contact": { "phone": "+15551234567", "email": "jane@example.com" }, "customer_number": "customer number", "verified": true, "created_at": "created at", "updated_at": "updated at" } } } } } } } }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] }, "patch": { "operationId": "api.v2.clients.update", "summary": "Perditeso klient (v2)", "description": "I njejti trup si `POST`, me nje kufizim:\n\n- **`type` eshte i pandryshueshem.** Nje kompani nuk behet person dhe as e kunderta. Nese\n dergoni nje `type` te ndryshem nga ai ekzistues, kerkesa refuzohet me `422`.", "tags": [ "Klienti (v2)" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer", "example": 42 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "Lloji i klientit, i cili vendos se cili objekt plotesohet: `company` ose `person`. Ne editim eshte i pandryshueshem, prandaj nje `type` i ndryshem nga ai ekzistues refuzohet me `422`.", "example": "company" }, "company": { "type": "object", "description": "Required depending on type.", "properties": { "name": { "type": [ "string", "null" ], "description": "Required depending on type.", "maxLength": 255 }, "category": { "type": [ "string", "null" ] }, "id": { "type": "object", "description": "Required depending on type.", "properties": { "type": { "type": "string", "description": "Required when company.id is present." }, "value": { "type": "string", "description": "Required when company.id is present.", "maxLength": 20 } }, "required": [ "type", "value" ] } }, "required": [ "name", "id" ] }, "person": { "type": "object", "description": "Required depending on type.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "Required depending on type.", "maxLength": 255 }, "last_name": { "type": [ "string", "null" ], "description": "Required depending on type.", "maxLength": 255 }, "birthday": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "object", "description": "Required depending on type.", "properties": { "type": { "type": "string", "description": "Required when person.id is present." }, "value": { "type": "string", "description": "Required when person.id is present.", "maxLength": 255 } }, "required": [ "type", "value" ] } }, "required": [ "first_name", "last_name", "id" ] }, "address": { "type": [ "object", "null" ], "description": "Adresa e klientit. Opsionale, dhe e njejta per te dy llojet.", "properties": { "line": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 50 }, "country": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } }, "contact": { "type": [ "object", "null" ], "description": "Kontaktet e klientit: telefoni dhe email-i. Opsionale.", "properties": { "phone": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 } } }, "customer_number": { "type": [ "string", "null" ], "description": "Numri juaj i klientit, nese e mbani nje te tille ne sistemin tuaj.", "example": "CL-00412", "maxLength": 30 } }, "required": [ "type", "company", "person" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "`company` or `person`" }, "company": { "type": [ "object", "null" ], "description": "Filled when `type` is `company`, null otherwise", "properties": { "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "description": "`business`, `bank` or `exchange`, or null when unclassified" }, "id": { "type": "object", "properties": { "type": { "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person" }, "value": { "description": "The identifier itself, null when the client has none recorded" } } } } }, "person": { "type": [ "object", "null" ], "description": "Filled when `type` is `person`, null otherwise", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ], "description": "Date of birth (YYYY-MM-DD)" }, "id": { "type": "object", "properties": { "type": { "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a person" }, "value": { "description": "The identifier itself, null when the client has none recorded" } } } } }, "address": { "type": "object", "properties": { "line": { "type": [ "string", "null" ], "description": "Street address" }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ], "description": "ISO 3166-1 alpha-3 country code" } } }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "customer_number": { "type": [ "string", "null" ], "description": "Your own reference for this client, when one was given" }, "verified": { "type": "boolean", "description": "Whether the identifier was confirmed against the fiscal register" }, "created_at": { "type": [ "string", "null" ], "description": "Creation timestamp, ISO 8601" }, "updated_at": { "type": [ "string", "null" ], "description": "Last update timestamp, ISO 8601" } } } }, "required": [ "client" ] } }, "required": [ "status", "data" ] }, "examples": { "example": { "summary": "Example", "value": { "status": true, "data": { "client": { "id": 1, "type": "type", "company": { "name": "Jane Doe", "category": "category", "id": { "type": "type", "value": "value" } }, "person": { "first_name": "Jane", "last_name": "Doe", "birthday": "birthday", "id": { "type": "type", "value": "value" } }, "address": { "line": "line", "city": "Berlin", "country": "US" }, "contact": { "phone": "+15551234567", "email": "jane@example.com" }, "customer_number": "customer number", "verified": true, "created_at": "created at", "updated_at": "updated at" } } } } } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "409": { "description": "Ekziston tashme nje klient me te njejtat te dhena.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`. Perfshin edhe rastin kur `type` ndryshon nga ai ekzistues.", "content": { "application/json": { "schema": { "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 nested objects and array items, e.g. `lines.0.quantity`" } } }, "examples": { "example": { "summary": "Example", "value": { "success": true, "message": "Hello there", "errors": [] } } } } } }, "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`.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application/json": { "schema": { "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 nothing to add beyond `message`", "items": { "type": "string" } } } }, "examples": { "example": { "summary": "Example", "value": { "status": true, "message": "Hello there", "errors": [ "errors" ] } } } } } } }, "security": [ { "bearerAuth": [], "xClientId": [], "xClientSecret": [] } ] } } }, "components": { "securitySchemes": { "xClientId": { "type": "apiKey", "in": "header", "name": "X-Client-Id" }, "xClientSecret": { "type": "apiKey", "in": "header", "name": "X-Client-Secret" }, "bearerAuth": { "type": "http", "scheme": "bearer" } } } }