{ "openapi": "3.1.0", "info": { "title": "fature.al API v2", "version": "2.0", "description": "# fature.al API v2\n\nVersioni 2 i API-t. Per momentin mbulon vetem klientet.\n\nGjithcka tjeter eshte e njejte me v1: i njejti token, te njejtat kredenciale te aplikacionit, i\nnjejti zarf pergjigjeje dhe te njejtat limite kerkesash. Per identifikimin, limitet dhe udhezimet e\nimplementimit shihni dokumentacionin e v1 te [`\/docs\/api`](\/docs\/api).\n\n## Serverat\n\n| Mjedisi | URL |\n|---------|-----|\n| **Live** | `https:\/\/fature.al\/api\/v2` |\n| **Sandbox\/Demo** | `https:\/\/demo.fature.al\/api\/v2` |\n\n## Cfare ndryshon nga v1\n\n- **Klienti ndahet ne objekte.** Ne vend te nje liste te sheshte fushash, te dhenat vijne ne\n `company`, `person`, `address` dhe `contact`, dhe fusha `type` (`company` ose `person`) thote cili\n prej dy te paret eshte i plotesuar.\n- **Identifikuesi eshte objekt.** `id` me `type` (`nuis`, `vat`, `tax` per kompani; `id`,\n `passport`, `social` per persona) dhe `value`, ne vend te `nipt` ose `document_number`.\n- **Vokabulari eshte me shkronja te vogla.** `company` ne vend te `COMPANY`, `nuis` ne vend te\n `NUIS`.\n- **Editimi behet me `PATCH`**, jo me `PUT`, dhe `type` nuk mund te ndryshohet: nje `type` i\n ndryshem nga ai ekzistues refuzohet me 422." }, "servers": [ { "url": "https:\/\/fature.al\/api\/v2", "description": "Live" }, { "url": "https:\/\/demo.fature.al\/api\/v2", "description": "Sandbox" } ], "tags": [ { "name": "Klienti" }, { "name": "Client 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." } ], "security": [ { "bearerAuth": [], "clientId": [], "clientSecret": [] }, { "bearerAuth": [] } ], "paths": { "\/clients": { "get": { "operationId": "v2.clients.list", "description": "Merr listen e klienteve te kompanise me faqosje dhe filtrim me tekst.", "summary": "Lista e klienteve", "tags": [ "Klienti" ], "parameters": [ { "name": "limit", "in": "query", "description": "Numri i klienteve per faqe (max 100).", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Nga cili klient te fillohet.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "query", "in": "query", "description": "Kerkim ne emer, mbiemer, NIPT, dokument, email ose telefon.", "schema": { "type": "string" }, "example": "Agon" } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "client_type": { "type": "string" }, "company_name": { "type": "string" }, "company_type": { "type": "string" }, "nipt": { "type": "string" }, "first_name": { "type": "string" }, "surname": { "type": "string" }, "birthday": { "type": "string" }, "id_type": { "type": "string" }, "id_num": { "type": "string" }, "nationality_code": { "type": "string" }, "nationality_id": { "type": "string" }, "telephone": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "customer_number": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "client_type", "company_name", "company_type", "nipt", "first_name", "surname", "birthday", "id_type", "id_num", "nationality_code", "nationality_id", "telephone", "email", "address", "city", "customer_number", "created_at" ] } }, "pagination": { "type": "object", "properties": { "records": { "type": "integer" }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "records", "total", "limit", "offset" ] } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "description": "Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } }, "post": { "operationId": "v2.clients.create", "description": "Trupi i kerkeses eshte nje bashkim i diskriminuar nga fusha `type` (company|person).\nObjekti `company` plotesohet kur `type=company`, ndersa `person` kur `type=person`.\nIdentifikuesi jepet si objekt `id` me `type` (nuis|vat|tax per kompani, id|passport|social per person) dhe `value`.", "summary": "Krijo klient (v2)", "tags": [ "Client v2" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientV2Request" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/ClientV2" } }, "required": [ "client" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "Te dhenat nuk kaluan validimin. Kjo pergjigje perdor fushen `success`, jo `status`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Ekziston tashme nje regjistrim me te njejtat te dhena.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/clients\/{id}": { "get": { "operationId": "v2.clients.show", "description": "Kthen klientin ne formatin e ri me objekte te ndara (company\/person\/address\/contact).", "summary": "Detajet e klientit (v2)", "tags": [ "Client v2" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/ClientV2" } }, "required": [ "client" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } }, "patch": { "operationId": "v2.clients.update", "description": "I njejti trup si POST. Lloji (`type`) eshte i pandryshueshem ne editim: nese dergohet nje\n`type` i ndryshem nga ai ekzistues, kerkesa refuzohet me 422.", "summary": "Perditeso klient (v2)", "tags": [ "Client v2" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID e klientit.", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientV2Request" } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/ClientV2" } }, "required": [ "client" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "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": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "403": { "description": "Abonimi ka mbaruar, ose veprimi nuk lejohet per kete llogari.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "Klienti nuk u gjet, ose nuk i perket kompanise suaj.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Ekziston tashme nje klient me te njejtat te dhena.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Kufiri i kerkesave u arrit. Kufiri per endpoint kthen zarfin standard te gabimit; kufiri i pergjithshem kthen vetem `message` bashke me header-in `Retry-After`.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } } }, "500": { "description": "Gabim i papritur ne server.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "Token-i i perdoruesit, nga Konfigurime > API Tokens.", "scheme": "bearer" }, "clientId": { "type": "apiKey", "description": "Client id i aplikacionit tuaj, fillon me ft_id_", "in": "header", "name": "X-Client-Id" }, "clientSecret": { "type": "apiKey", "description": "Client secret i aplikacionit tuaj, fillon me ft_sk_", "in": "header", "name": "X-Client-Secret" } }, "schemas": { "ApiError": { "type": "object", "properties": { "status": { "type": "boolean", "description": "Always false. A successful response carries `status: true` and a `data` object instead." }, "message": { "type": "string", "description": "The exception message. Empty when the failure carries no exception of its own." }, "errors": { "type": "array", "description": "Messages to show the operator or to log. Absent when the failure has\nnothing to add beyond `message`.", "items": { "type": "string" } } }, "required": [ "status", "message", "errors" ], "title": "ApiError" }, "ApiValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always false." }, "message": { "type": "string", "description": "A single summary line, the same for every validation failure." }, "errors": { "type": "object", "description": "The failing fields, each with the messages for it. Dotted keys point into\nnested objects and array items, e.g. `lines.0.quantity`.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "success", "message", "errors" ], "title": "ApiValidationError" }, "ClientV2": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string", "description": "`company` or `person`." }, "company": { "anyOf": [ { "description": "Filled when `type` is `company`, null otherwise.", "$ref": "#\/components\/schemas\/ClientV2Company" }, { "type": "null" } ] }, "person": { "anyOf": [ { "description": "Filled when `type` is `person`, null otherwise.", "$ref": "#\/components\/schemas\/ClientV2Person" }, { "type": "null" } ] }, "address": { "$ref": "#\/components\/schemas\/ClientV2Address" }, "contact": { "$ref": "#\/components\/schemas\/ClientV2Contact" }, "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": [ "id", "type", "company", "person", "address", "contact", "customer_number", "verified", "created_at", "updated_at" ], "title": "ClientV2" }, "ClientV2Address": { "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." } }, "required": [ "line", "city", "country" ], "title": "ClientV2Address" }, "ClientV2Company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ], "description": "`business`, `bank` or `exchange`, or null when unclassified." }, "id": { "$ref": "#\/components\/schemas\/ClientV2Id" } }, "required": [ "name", "category", "id" ], "title": "ClientV2Company" }, "ClientV2Contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } }, "required": [ "phone", "email" ], "title": "ClientV2Contact" }, "ClientV2Id": { "type": "object", "properties": { "type": { "type": "string", "description": "`nuis`, `vat` or `tax` on a company; `id`, `passport` or `social` on a\nperson." }, "value": { "type": [ "string", "null" ], "description": "The identifier itself, null when the client has none recorded." } }, "required": [ "type", "value" ], "title": "ClientV2Id" }, "ClientV2Person": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "birthday": { "type": [ "string", "null" ], "description": "Date of birth (YYYY-MM-DD)." }, "id": { "$ref": "#\/components\/schemas\/ClientV2Id" } }, "required": [ "first_name", "last_name", "birthday", "id" ], "title": "ClientV2Person" }, "ClientV2Request": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "company", "person" ] }, "customer_number": { "type": [ "string", "null" ], "maxLength": 30 }, "company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 255 }, "category": { "type": [ "string", "null" ], "enum": [ "business", "bank", "exchange" ] }, "id": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "nuis", "vat", "tax" ] }, "value": { "type": "string", "maxLength": 20 } } } } }, "person": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ], "maxLength": 255 }, "last_name": { "type": [ "string", "null" ], "maxLength": 255 }, "birthday": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "id", "passport", "social" ] }, "value": { "type": "string", "maxLength": 255 } } } } }, "address": { "type": "object", "properties": { "line": { "type": [ "string", "null" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "maxLength": 50 }, "country": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 } } }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 255 } } } }, "required": [ "type" ], "title": "ClientV2Request" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }