{ "openapi": "3.1.0", "info": { "title": "fature.al API v2", "version": "2.0", "description": "# fature.al API v2\n\nVersion 2 covers **invoices**, **clients**, **warehouse transfer notes** and the **cash register**.\nOnly these change shape from v1, so only these have a second address. Everything else (purchase\ninvoices, products, reports and registration) stays on `v1` and is called from there even by an\nintegration that sends its invoices with `v2`.\n\nBoth versions share the token, the application credentials, the response format and the rate\nlimits. Concepts, identification and the shared rules are in the v1 documentation, at\n[`\/docs\/api`](\/docs\/api). If you have not read it, start there.\n\n## Servers\n\n| Environment | URL |\n| --- | --- |\n| **Live** | `https:\/\/fature.al\/api\/v2` |\n| **Sandbox** | `https:\/\/demo.fature.al\/api\/v2` |\n\n## What changes from v1\n\n### Invoice payment is always a list\n\nThe invoice sends its payment as `payment_methods`, with one element per method. An invoice paid with\na single method sends a one-element list, so there is only one shape to learn.\n\n```json\n\"payment_methods\": [\n {\"type\": \"BANKNOTE\", \"amount\": 1200},\n {\"type\": \"CARD\", \"amount\": 800}\n]\n```\n\n| Rule | Limit |\n| --- | --- |\n| Methods per invoice | 10 |\n| Value of an `amount` | Any number the CIS accepts, including 0 and negative |\n| Same method twice | Not allowed |\n| Sum of `amount` | Equal to the invoice total, with the discount already applied |\n\nThe `payment_method`, `company_card` and `vouchers` fields on the invoice are not accepted: the company card\ngoes in `payment_methods[].company_card` and vouchers in `payment_methods[].vouchers`, inside the\nelement that requires them. Invoices returned by lists and details carry the same list, so\npayment reconciliation always reads a single shape.\n\nAn order invoice carries no payment at all: it opens the table, and the summary invoice pays for it.\n\n### The client is split into objects\n\n- **Objects instead of flat fields.** The data comes in `company`, `person`, `address` and\n `contact`, and the `type` field (`company` or `person`) says which of the first two is filled in.\n- **The identifier is an object.** `id` with `type` (`nuis`, `vat`, `tax` for companies; `id`,\n `passport`, `social` for persons) and `value`, instead of `nipt` or `document_number`.\n- **Values are lowercase.** `company` instead of `COMPANY`, `nuis` instead of `NUIS`.\n- **Updates use `PATCH`**, not `PUT`, and `type` does not change: a `type` different from\n the existing one is rejected with `422`.\n\n`GET \/clients` in v2 still returns the flat v1 format, because the mobile app was built on it.\nDetails, creation and updates use the new format, and a client created with `v1` can be read with\n`v2` with no extra step.\n\n### The warehouse transfer note requires internalId\n\n`POST \/invoice\/wtn` requires `internalId`, the note's identifier in your system, whereas in v1 it\nis optional. The rest of the note is exactly the same as in v1.\n\nKeep it unique within the company for the year. A second request with the same `internalId` does not issue\na second note; it returns the first note with `200`, so retrying after a timeout is safe.\nRead the note later with `GET \/invoice\/wtn\/details\/{internalId}`, without storing our `id`.\n\nThe note carries no fiscal device: the CIS registers it with the business unit, the operator code and\nthe software code, so it can be issued even by a user without a TCR.\n\n### Cash in and cash out require internalId\n\n`POST \/cash-register\/deposit` and `POST \/cash-register\/withdraw` require `internalId`, the action's identifier in your system. v1 does not know this field. The rest of the request is word for word the v1 one, as are opening, closing and the balance. `GET \/cash-register\/actions` returns `internalId` for every action, so the list can be matched to the actions in your system.\n\nKeep it unique within the company for the year. A second request with the same `internalId` does not put money in or take it out a second time, it returns the first action with `200`. A request that arrives while the first is still being processed, or an `internalId` used for the other direction, is refused with `409`." }, "servers": [ { "url": "https:\/\/fature.al\/api\/v2", "description": "Live" }, { "url": "https:\/\/demo.fature.al\/api\/v2", "description": "Sandbox" } ], "tags": [ { "name": "Invoices", "description": "Issuing invoices and everything that follows: cash, non-cash, e-invoice, order, summary and bulk non-cash, plus the list, details, cancellation and the printable document.\n\nThe request and response are those of v1, with a single change: the payment is always sent and returned as a `payment_methods` list, with one element per payment method. An invoice paid with a single method sends a one-element list. The `payment_method`, `company_card` and `vouchers` fields on the invoice are not accepted: the company card and vouchers go inside the element that requires them.\n\nOnly in v2, a line of a cash, non-cash or e-invoice can carry `vouchers_sold`: the vouchers that line sells, with their expiry date, nominal value and up to 1000 serial numbers. They go to CIS as the line's `VS` element.\n\nPurchase invoices carry no payment method and do not change in v2, so they are called on `v1`. Warehouse transfer notes carry no payment at all, but have their own group in v2, where `internalId` becomes required." }, { "name": "Clients", "description": "The company's clients, the buyers that appear on the invoice: list, details, create and update, plus looking up a business by NIPT in the fiscal registry.\n\nYou need it when you keep the client registry in fature.al, or when you want to verify a NIPT before putting it on an invoice. For a single invoice, the `client` object at issue time is enough; the client does not need to be created first." }, { "name": "Cash register", "description": "The working day on the fiscal device (TCR) of the token's user: opening the day, cash in and cash out, closing the day, the balance at any moment and the history of actions. Amounts are always in ALL.\n\nThe group is the `v1` one with a single change: on cash in and cash out, `internalId`, the action's identifier in your system, is required. With it, a retried request does not record a second action, and the money does not go in or out twice. The action list returns `internalId` for every action; opening, closing and the balance are word for word the `v1` ones." }, { "name": "Warehouse transfer notes", "description": "Warehouse transfer notes (WTN) for goods that move between units or to a client without being a sale: issuing, list, details and the print data.\n\nThe note is the same as in `v1`, with a single change: `internalId`, the note's identifier in your system, is required when issuing. With it, a retried request does not issue a second note, and the note is read with `GET \/invoice\/wtn\/details\/{internalId}` without storing our `id`.\n\nThe note is issued with the business unit code and the operator code of the token's user, and is fiscalized with the CIS like any other document. It carries no fiscal device: the CIS registers the note without a TCR. Lines are sent as `invoice_lines` and returned as `lines`." }, { "name": "Purchase invoices", "description": "The invoices suppliers have issued to the company, as the CIS recorded them. Read only: these documents are not issued here, and they do not come from the supplier but from the central fiscalisation system." } ], "security": [ { "bearerAuth": [], "clientId": [], "clientSecret": [] }, { "bearerAuth": [] } ], "paths": { "\/invoice\/e-invoice": { "post": { "operationId": "v2.invoice.e-invoice", "description": "The same e-invoice as in `v1`, with the payment as a `payment_methods` list. For the buyer, the document\ntype (`doc_type` and `process`) and correction notes, the rules of\n[`POST \/api\/v1\/invoice\/e-invoice`](\/docs\/api) apply.", "summary": "Issue an e-invoice", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/EInvoiceRequest" } } } }, "responses": { "200": { "description": "When the invoice is rejected after validation, by the CIS or while saving, the response comes back with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field. Only a missing `internalId` comes back in the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Incomplete or invalid data for fiscalization. `errors` says exactly what needs to be filled in. The invoice was not saved; retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nj\u00eb k\u00ebrkes\u00eb me k\u00ebt\u00eb `internalId` \u00ebsht\u00eb ende n\u00eb proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET \/invoice\/details\/{internalId}`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached and the invoice was not saved. Retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/noncash": { "post": { "operationId": "v2.invoice.noncash", "description": "The same invoice as in `v1`, with the payment as a `payment_methods` list. For the buyer, the bank\naccount, correction notes and discounts, the rules of\n[`POST \/api\/v1\/invoice\/noncash`](\/docs\/api) apply.\n\nThe allowed methods are `ACCOUNT`, `COMPENSATION`, `FACTORING`, `KIND`, `OTHER`, `TRANSFER`\nand `WAIVER`; none of them carries a company card or vouchers. When the method paying the largest\nshare is `ACCOUNT`, the invoice requires the bank account, as in `v1`.", "summary": "Issue a non-cash invoice", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/NonCashInvoiceRequest" } } } }, "responses": { "200": { "description": "When the invoice is rejected after validation, by the CIS or while saving, the response comes back with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field. Only a missing `internalId` comes back in the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Incomplete or invalid data for fiscalization. `errors` says exactly what needs to be filled in. The invoice was not saved; retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nj\u00eb k\u00ebrkes\u00eb me k\u00ebt\u00eb `internalId` \u00ebsht\u00eb ende n\u00eb proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET \/invoice\/details\/{internalId}`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached and the invoice was not saved. Retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/cash": { "post": { "operationId": "v2.invoice.cash", "description": "The same invoice as in `v1`, with the payment as a list. For the buyer, lines, discounts and\nself-invoicing, the rules of [`POST \/api\/v1\/invoice\/cash`](\/docs\/api) apply.\n\n## Payment\n\n`payment_methods` carries one element per method and is required even when the invoice\nis paid entirely with one method.\n\n```json\n{\n \"internalId\": \"CASH-2026-0101\",\n \"lines\": [\n {\n \"product_name\": \"Coffee\",\n \"product_code\": \"KAF-001\",\n \"unit\": \"piece\",\n \"quantity\": 10,\n \"price\": 200,\n \"total\": 2000,\n \"vat\": 20\n }\n ],\n \"payment_methods\": [\n {\"type\": \"BANKNOTE\", \"amount\": 1200},\n {\"type\": \"CARD\", \"amount\": 800}\n ]\n}\n```\n\n| Rule | Limit |\n| --- | --- |\n| Methods per invoice | 10 |\n| Same method twice | Not allowed |\n| Sum of `amount` | Equal to the invoice total, with the discount already applied |\n\nOnly the `COMPANY` element carries `company_card`, and only the `SVOUCHER` element carries `vouchers`.\nA list that does not add up to the total is rejected with `400`, because the sum is checked only after\nthe discount on the invoice has been applied.\n\nSelf-invoicing is paid from the cash register, as in `v1`: when the cash register does not cover the total, the invoice is not saved and\nthe response comes with HTTP 200 and `status: false`.\n\n## Selling vouchers\n\nWhen the goods sold are single-purpose vouchers themselves, the line carries `vouchers_sold`:\nwhich goods or services the voucher is for (`purpose`), the expiry date, the nominal value of one\nvoucher and the serial numbers, from 1 to 1000. They go to CIS as the line's `VS` element.\n\nThe name sent to CIS stays `product_name`, up to 50 characters. fature.al builds the full\ndescription required by Instruction 16\/2020 (article 8, point 4) from `purpose` and the numbers, and\nwrites it under the item name on the printed invoice and in the e-invoice. The description is legal text and stays in Albanian; for the example below it reads: Tollon me nj\u00eb q\u00ebllim p\u00ebr veshje dhe k\u00ebpuc\u00eb me numrat serial\u00eb 12-2026-K51501011M, 13-2026-K51501011M.\n\n```json\n{\n \"internalId\": \"CASH-2026-0102\",\n \"lines\": [\n {\n \"product_name\": \"Gift voucher 1000 L\",\n \"product_code\": \"TOL-1000\",\n \"unit\": \"piece\",\n \"quantity\": 2,\n \"price\": 1000,\n \"total\": 2000,\n \"vat\": 20,\n \"vouchers_sold\": {\n \"purpose\": \"clothing and shoes\",\n \"expires_at\": \"2027-12-31\",\n \"nominal_value\": 1000,\n \"numbers\": [\"12-2026-K51501011M\", \"13-2026-K51501011M\"]\n }\n }\n ],\n \"payment_methods\": [\n {\"type\": \"BANKNOTE\", \"amount\": 2000}\n ]\n}\n```\n\n| Rule | Limit |\n| --- | --- |\n| Serial numbers on one line | 1 to 1000 |\n| The same serial number | Once on the whole invoice |\n| `purpose` | Required, up to 255 characters |\n| Partial cancellation | A voucher line is returned only whole |\n\nCancellation returns the line with the same vouchers. The invoice details return this same object\nin `lines[].vouchers_sold`; the response example is on `GET \/invoice\/{id}\/details`.", "summary": "Issue a cash invoice", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashInvoice" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when the cash register does not cover a self-invoice, or when the invoice is rejected after validation by the CIS or while saving, the response comes back with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field. Only a missing `internalId` comes back in the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Incomplete or invalid data for fiscalization. `errors` says exactly what needs to be filled in. The invoice was not saved; retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nj\u00eb k\u00ebrkes\u00eb me k\u00ebt\u00eb `internalId` \u00ebsht\u00eb ende n\u00eb proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET \/invoice\/details\/{internalId}`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached and the invoice was not saved. Retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/order": { "post": { "operationId": "v2.invoice.order", "description": "The same order as in `v1`. The order opens the table and pays nothing, so it carries neither\n`payment_method` nor `payment_methods`: payment comes later, with the summary invoice that\ncloses the table. The rules are those of [`POST \/api\/v1\/invoice\/order`](\/docs\/api).", "summary": "Issue an order invoice", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/OrderInvoice" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, or when the invoice is rejected after validation by the CIS or while saving, the response comes back with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field. Only a missing `internalId` comes back in the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "Incomplete or invalid data for fiscalization. `errors` says exactly what needs to be filled in. The invoice was not saved; retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nj\u00eb k\u00ebrkes\u00eb me k\u00ebt\u00eb `internalId` \u00ebsht\u00eb ende n\u00eb proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET \/invoice\/details\/{internalId}`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached and the invoice was not saved. Retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/summary": { "post": { "operationId": "v2.invoice.summary", "description": "Settles the payment of one or more order invoices with a single document, as in `v1`, with the\npayment as a `payment_methods` list. A table paid half in cash and half by\ncard sends a two-element list; one paid entirely by card, a one-element list.\nOnly `BANKNOTE` and `CARD` are allowed. The rules for `order_invoices` and the discount are those of\n[`POST \/api\/v1\/invoice\/summary`](\/docs\/api).", "summary": "Issue a summary invoice", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/SummaryInvoice" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, or when the invoice is rejected after validation by the CIS or while saving, the response comes back with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field. Only a missing `internalId` comes back in the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "400": { "description": "An order was not found, is not an order invoice, or is already closed; or the data is incomplete for fiscalization. `errors` says exactly which. The invoice was not saved; retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Nj\u00eb k\u00ebrkes\u00eb me k\u00ebt\u00eb `internalId` \u00ebsht\u00eb ende n\u00eb proces. Prisni pak dhe riprovoni, ose lexoni gjendjen me `GET \/invoice\/details\/{internalId}`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached and the invoice was not saved. Retry with the same `internalId`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/cancel\/{id}": { "post": { "operationId": "v2.invoice.cancel", "description": "The same cancellation as in `v1`: without a body the whole invoice is canceled; with `lines`, only part of\nit, which is possible **only for cash invoices**. The full rules are in\n[`POST \/api\/v1\/invoice\/cancel\/{id}`](\/docs\/api).\n\nThe response is the corrective document, with its own `iic` and `fic` and with `payment_methods`\nalongside. When the CIS cannot be reached, the cancellation is saved with `fic: null` and is fiscalized automatically\nlater. Cancellations have their own rate limit: 30 per minute and 600 per hour per token.", "summary": "Cancel an invoice by id", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice's id in fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CancelInvoiceRequest" } } } }, "responses": { "200": { "description": "The corrective document, with its own `iic` and `fic`; `fic` is `null` when the CIS could not be reached and fiscalization will complete automatically.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The invoice cannot be canceled in its current state, or the lines sent do not match the original. `errors` says why.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "The invoice was not found, or does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Unexpected server error, including when the cancellation could not be registered with the CIS.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "The cancellation limit was reached, or another cancellation of the same type is still in progress. When the cancellation limit is hit, the response carries only `message` and the `Retry-After` header.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } } } } }, "\/invoice\/cancel-by-internal-id\/{internalId}": { "post": { "operationId": "v2.invoice.cancel-by-internal-id", "description": "The same cancellation as in `v1`, finding the invoice by the `internalId` you sent when you issued it:\nwithout a body the whole invoice is canceled; with `lines`, only part of it, which is possible **only for\ncash invoices**. The full rules are in\n[`POST \/api\/v1\/invoice\/cancel-by-internal-id\/{internalId}`](\/docs\/api).\n\nThe response is the corrective document, with its own `iic` and `fic` and with `payment_methods`\nalongside. When the CIS cannot be reached, the cancellation is saved with `fic: null` and is fiscalized automatically\nlater.", "summary": "Cancel an invoice by internalId", "tags": [ "Invoices" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "Your identifier for the invoice, sent when it was issued.", "schema": { "type": "string" }, "example": "CASH-001" } ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CancelInvoiceRequest" } } } }, "responses": { "200": { "description": "The corrective document, with its own `iic` and `fic`; `fic` is `null` when the CIS could not be reached and fiscalization will complete automatically.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The invoice cannot be canceled in its current state, or the lines sent do not match the original. `errors` says why.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "The invoice was not found, or does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Unexpected server error, including when the cancellation could not be registered with the CIS.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "The cancellation limit was reached, or another cancellation of the same type is still in progress. When the cancellation limit is hit, the response carries only `message` and the `Retry-After` header.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } } } } }, "\/invoice\/bulk-noncash": { "post": { "operationId": "v2.invoice.bulk-noncash", "description": "The same bulk as in `v1`, where each invoice in `invoices` carries its own payment as a\n`payment_methods` list. The response is an object with one entry per `internalId`, and the HTTP\nstatus stays `200` even when some invoice fails: check `status` inside each entry and\nretry only the ones that failed.", "summary": "Issue bulk non-cash invoices", "tags": [ "Invoices" ], "responses": { "200": { "description": "An object with one entry per `internalId`. An invoice that fails carries the error format inside its own entry, and the response status stays 200.", "content": { "application\/json": { "schema": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/InvoiceIssueResult" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/print\/{id}": { "get": { "operationId": "v2.invoice.pdf", "description": "Returns the invoice document to give to the buyer or to print. Without parameters, the default\nformat for the type is returned: a thermal receipt for cash invoices (58 or 80 mm, per the\nuser's configuration), an A4 document for non-cash invoices and estimates, and the official PDF\nfrom the e-invoicing platform for e-invoices.\n\nWith the `format` parameter you get the same versions the fature.al dashboard offers:\n\n| `format` | Invoice type | Result | Content-Type |\n| --- | --- | --- | --- |\n| `a4` | Cash | A4 invoice document | application\/pdf |\n| `thermal` | Non-cash | Thermal receipt | application\/pdf |\n| `v2` | Non-cash, estimate | A4 document, wide version | application\/pdf |\n| `receipt` | Estimate | Thermal receipt | application\/pdf |\n| `local` | E-invoice | A4 document generated by fature.al, without requesting the official PDF | application\/pdf |\n| `local-thermal` | E-invoice | Thermal receipt generated by fature.al | application\/pdf |\n| `html` | Cash | The thermal receipt as HTML, to send to the printer yourself | text\/html |\n| `json` | All | The document data as JSON, to format the invoice yourself | application\/json |\n\n`lang` (`en`, `it`, `de`) translates the A4 document of non-cash invoices, estimates and\ne-invoices, and combines with `format`. Without it, the document is returned in Albanian. Thermal receipts and\ncash invoices always stay in Albanian, because they are fiscal documents.\n\nFor cash invoices, `copy_only=1` returns the copy of the receipt instead of the original.\n\nA `format` that does not apply to the invoice type does not return an error: the default format of\nthat type is returned.\n\n## E-invoices when the platform is not responding\n\nThe official PDF comes from the e-invoicing platform. When it is not responding, no error is\nreturned: you get the copy kept from an earlier download or, when there is none, the document\ngenerated by fature.al. The `X-Document-Source` header says which one you got: `official`,\n`stored` or `local`.", "summary": "Download the invoice document", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice's id in fature.al.", "schema": { "type": "integer" }, "example": 403 }, { "name": "copy_only", "in": "query", "description": "Cash invoices only: returns the copy of the receipt instead of the original.", "schema": { "type": "integer" }, "example": 1 }, { "name": "format", "in": "query", "description": "The document version per the table above: `a4`, `thermal`, `v2`, `receipt`, `local`, `local-thermal`, `html`, `json`.", "schema": { "type": "string" }, "example": "a4" }, { "name": "lang", "in": "query", "description": "The language of the A4 document: `en`, `it` or `de`. Without it, the document is returned in Albanian.", "schema": { "type": "string" }, "example": "en" } ], "responses": { "500": { "description": "The document could not be generated. The problem is reported automatically.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "200": { "description": "The content type depends on `format`: PDF by default, `text\/html` with `format=html`, and the invoice document as JSON with `format=json`, ready for you to format yourself.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/InvoicePrintDocument" } }, "application\/pdf": { "schema": { "type": "string", "format": "binary" } }, "text\/html": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "X-Document-Source": { "schema": { "type": "string", "const": "stored" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "The invoice was not found or does not belong to your company, or the e-invoicing platform holds no document for this e-invoice.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "description": "The e-invoicing platform refused the request for the PDF; `message` says why.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/invoice\/print-eic\/{eic}": { "get": { "operationId": "v2.einvoice.pdf", "description": "Returns the official e-invoice PDF from the e-invoicing platform, by the EIC code that issuing\nreturned to you.\n\nEvery failure comes back with its own status and a JSON `message`, never as a PDF:\n\n| Status | When |\n| --- | --- |\n| `404` | The e-invoicing platform answered, but holds no document with this EIC. |\n| `422` | The e-invoicing platform refused the request; `message` says why. |\n| `503` | The e-invoicing platform is not responding. Try again after `Retry-After` seconds. |\n\nWhen the platform is not responding and the EIC belongs to one of your e-invoices in fature.al,\nyou get the fallback PDF instead of `503`, the same as when downloading by id. The\n`X-Document-Source` header says which one you got: `official` from the platform, `stored` the\ncopy kept from an earlier download, `local` the document generated by fature.al.", "summary": "Download the e-invoice PDF by EIC", "tags": [ "Invoices" ], "parameters": [ { "name": "eic", "in": "path", "required": true, "description": "The e-invoice EIC code, a UUID.", "schema": { "type": "string" }, "example": "2e9b6f31-d712-4c45-8cc0-9faf24c805a3" } ], "responses": { "500": { "description": "", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "string", "const": "Dokumenti nuk u krijua dot. Problemi u raportua dhe do t\u00eb kontrollohet." }, { "type": "object", "properties": { "message": { "type": "string", "const": "Dokumenti nuk u krijua dot. Problemi u raportua dhe do t\u00eb kontrollohet." } }, "required": [ "message" ] } ] } } } }, "200": { "description": "The e-invoice PDF. `X-Document-Source` says whether it is the official one (`official`), the stored copy (`stored`) or the fature.al document (`local`).", "content": { "application\/json": { "schema": { "type": "string" } }, "application\/pdf": { "schema": { "type": "string", "format": "binary" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } }, "X-Document-Source": { "schema": { "type": "string", "const": "official" } } } }, "503": { "description": "The e-invoicing platform is not responding. Try again after `Retry-After` seconds.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "The e-invoicing platform holds no document with this EIC.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "422": { "description": "The e-invoicing platform refused the request.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } } } } }, "\/invoice": { "get": { "operationId": "v2.invoice.list", "description": "The same list as in `v1`, where each invoice carries `payment_methods` instead of `payment_method`.\nFilters and pagination are those of [`GET \/api\/v1\/invoice`](\/docs\/api).", "summary": "List invoices", "tags": [ "Invoices" ], "responses": { "200": { "description": "The period's invoices in `items`, newest first, with `pagination`; `items` is empty when there are no invoices.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/InvoiceListItem" } }, "pagination": { "$ref": "#\/components\/schemas\/InvoiceListPagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice\/{id}\/details": { "get": { "operationId": "v2.invoice.details", "description": "The same details as in `v1`, where the payment comes as a `payment_methods` list. When the invoice is not found,\n`data.invoice` is `null` with status `200`.\n\nEvery line also carries `vouchers_sold`: the single-purpose vouchers it sells, or `null` for an\nordinary line. The line from the voucher sale example on `POST \/invoice\/cash` comes back like this\nin `data.invoice.lines`:\n\n```json\n{\n \"name\": \"Gift voucher 1000 L\",\n \"product_code\": \"TOL-1000\",\n \"unit\": \"piece\",\n \"unit_code\": null,\n \"quantity\": 2,\n \"unitPrice\": 1000,\n \"vat_rate\": 20,\n \"vat_exempt_type\": null,\n \"margin_cost\": null,\n \"discount_rate\": 0,\n \"discount\": 0,\n \"amount_net\": 1666.6666666667,\n \"amount_vat\": 333.3333333333,\n \"total\": 2000,\n \"vouchers_sold\": {\n \"purpose\": \"clothing and shoes\",\n \"expires_at\": \"2027-12-31\",\n \"nominal_value\": 1000,\n \"numbers\": [\"12-2026-K51501011M\", \"13-2026-K51501011M\"]\n }\n}\n```", "summary": "Get an invoice by id", "tags": [ "Invoices" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The invoice's id in fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "responses": { "200": { "description": "The full invoice in `data.invoice`, or `null` when it is not found.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceDetail" }, { "type": "null" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice\/details\/{internalId}": { "get": { "operationId": "v2.invoice.details-by-internal-id", "description": "The same issuing result as in `v1`, with `payment_methods` alongside. Use it to read\nthe state after a timeout or after a `409`.\n\nPranohet edhe `POST` n\u00eb t\u00eb nj\u00ebjt\u00ebn adres\u00eb, p\u00ebr integrimet q\u00eb e th\u00ebrrasin ashtu q\u00eb nga fillimi.", "summary": "Get an invoice by internalId", "tags": [ "Invoices" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "Your identifier for the invoice, sent when it was issued.", "schema": { "type": "string" }, "example": "CASH-001" } ], "responses": { "200": { "description": "The issuing result of the invoice with this `internalId`, the same one the issue call returned, with `payment_methods`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/InvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/OrderInvoiceIssueResult" }, { "$ref": "#\/components\/schemas\/SummaryInvoiceIssueResult" } ] } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/clients": { "get": { "operationId": "v2.clients.list", "description": "Returns the company's clients, newest first, with text search. Each client comes\nwith the same fields as in `GET \/clients\/{id}\/details`.\n\nUse it to find the `id` of a saved client, or to sync your\nrecords with those in fature.al.\n\n- Pagination me `limit` dhe `offset`. `limit` kufizohet n\u00eb `100`; nj\u00eb vler\u00eb m\u00eb e madhe ulet pa\n gabim. `pagination` kthen `total`, ndaj vazhdoni me `offset += limit` derisa `offset` t\u00eb\n arrij\u00eb `total`.\n- `query` k\u00ebrkon me p\u00ebrputhje t\u00eb pjesshme n\u00eb emrin e kompanis\u00eb, emrin, mbiemrin, at\u00ebsin\u00eb,\n NIPT-in, numrin e dokumentit, adres\u00ebn, email-in, telefonin dhe numrin e klientit, nj\u00ebsoj si\n k\u00ebrkimi i klient\u00ebve n\u00eb fature.al.\n- Nj\u00eb k\u00ebrkes\u00eb e dyt\u00eb nga i nj\u00ebjti token, nd\u00ebrsa e para nuk ka mbaruar, refuzohet menj\u00ebher\u00eb me\n `429`.\n\n`company_type` is returned `null` for a person, and `first_name` and `surname` for a company;\n`name` always holds the full name.", "summary": "List clients", "tags": [ "Clients" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many clients to return per page, up to 100.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Which client to start from, counting from 0.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "query", "in": "query", "description": "K\u00ebrkim n\u00eb emrin e kompanis\u00eb, emrin, mbiemrin, at\u00ebsin\u00eb, NIPT-in, numrin e dokumentit, adres\u00ebn, email-in, telefonin ose numrin e klientit.", "schema": { "type": "string" }, "example": "Agon" } ], "responses": { "200": { "description": "The page's clients in `items`, with `pagination`; `items` is empty when no client matches.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ClientV1" } }, "pagination": { "$ref": "#\/components\/schemas\/ClientListPagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } }, "post": { "operationId": "v2.clients.create", "description": "Creates a client in the v2 format. The body is split by the `type` field, which accepts `company` or\n`person`, and only the object matching the type is filled in.\n\n| `type` | Object | Required fields |\n| --- | --- | --- |\n| `company` | `company` | `name`, `id` |\n| `person` | `person` | `first_name`, `last_name`, `id` |\n\n## Identifier\n\nAlways sent as an `id` object with `type` and `value`, and the allowed values depend on the type:\n\n- company: `nuis`, `vat`, `tax`;\n- person: `id`, `passport`, `social`.\n\n## Shared objects\n\n`address` (`line`, `city`, three-letter `country`) and `contact` (`phone`, `email`) are\noptional and apply to both types. `company.category` accepts `business`, `bank` or\n`exchange`.\n\nStore the returned `id`: with it the client is found and updated again. A second request\nfrom the same token while the first has not finished is rejected immediately with `429`.", "summary": "Create a client", "tags": [ "Clients" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientV2Request" } } } }, "responses": { "200": { "description": "The created client in `data.client`, with its `id` in fature.al; store it for invoices and updates.", "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": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "A client with the same data already exists.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/clients\/{id}": { "get": { "operationId": "v2.clients.show", "description": "Returns the client in the v2 format: `company` or `person` depending on `type`, plus `address`,\n`contact`, `customer_number` and `verified`.\n\nIt is the same client that `v1` returns, only structured differently. A client created with\n`v1` can be read here with no extra step.", "summary": "Get a client by id", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client id.", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "The client in `data.client`, with `company` or `person` filled in according to its type.", "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": "The client was not found, or does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } }, "patch": { "operationId": "v2.clients.update", "description": "Updates a client with `PATCH` and the same body as creation, with one restriction: `type`\ndoes not change. A company does not become a person, nor the other way around; a `type` different from the\nexisting one is rejected with `422`.\n\nA second request from the same token while the first has not finished is rejected immediately with\n`429`.", "summary": "Update a client", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client id.", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientV2Request" } } } }, "responses": { "200": { "description": "The updated client in `data.client`, in full, not just the fields sent.", "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": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field. Only a `type` different from the existing one is returned in the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiValidationError" }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "404": { "description": "The client was not found, or does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "A client with the same data already exists.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/deposit": { "post": { "operationId": "v2.cash-register.deposit", "description": "Records money that enters the cash register without being a sale, such as a collection from a client or an opening\nfloat, as a `MONEY_IN` action on the fiscal device (TCR) of the token's user.\n\nFor a sale, issue a cash invoice, not a cash in. If the day has not been opened yet, it is opened automatically with\n`0`.\n\n- `internalId` is required.\n- `amount` is in ALL and must be greater than `0`.\n- `id_client`, when sent, must be the `id` of a client of your company.\n- The user must have a TCR.\n\n## internalId\n\nThis is the only change from [`POST \/api\/v1\/cash-register\/deposit`](\/docs\/api). Keep it unique within the company for the year: a second request with the same `internalId` does not record a second cash in, it returns the first action with `200`. That makes a retry after a timeout safe. An `internalId` already used for a cash out is refused with `409`.\n\nThe response carries the action's `id`, `internalId`, its numbers (`transaction_no`, `cash_action_no`) and its fiscal state (`fiscal_status`, `fiscal_uuid`, `fiscal_fic`). When the CIS cannot be reached, the action is saved and fiscalised automatically later: the response comes back complete, with `fiscal_status: UNFISCALIZED`.", "summary": "Record a cash in", "tags": [ "Cash register" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashActionRequest" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when `id_client` does not belong to your company, or when saving fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashActionIssueResult" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation, including a missing `internalId`. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "409": { "description": "A request with this `internalId` is still being processed, or the `internalId` was used for a cash out. The reason is in `message`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/withdraw": { "post": { "operationId": "v2.cash-register.withdraw", "description": "Records money that leaves the cash register, such as a supplier payment or a withdrawal during the day, as a\n`MONEY_OUT` action on the fiscal device (TCR) of the token's user.\n\nTo withdraw the whole balance at the end of the shift, use `POST \/cash-register\/close-balance`.\nIf the day has not been opened yet, it is opened automatically with `0`.\n\n- `internalId` is required.\n- `amount` is in ALL and must be greater than `0`; the sign comes from the endpoint, not from the number.\n- The register must hold at least `amount`; when it does not, the cash out is refused.\n- `id_client`, when sent, must be the `id` of a client of your company.\n- The user must have a TCR.\n\n## internalId\n\nThis is the only change from [`POST \/api\/v1\/cash-register\/withdraw`](\/docs\/api). Keep it unique within the company for the year: a second request with the same `internalId` does not take money out a second time, it returns the first action with `200`. An `internalId` already used for a cash in is refused with `409`.\n\nThe response has the same format as the cash in. When the CIS cannot be reached, the action is saved and fiscalised automatically later: the response comes back complete, with `fiscal_status: UNFISCALIZED`.", "summary": "Record a cash out", "tags": [ "Cash register" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashActionRequest" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when the cash register does not hold as much money as `amount`, when `id_client` does not belong to your company, or when saving fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashActionIssueResult" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation, including a missing `internalId`. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "409": { "description": "A request with this `internalId` is still being processed, or the `internalId` was used for a cash in. The reason is in `message`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/open-balance": { "post": { "operationId": "v2.cash-register.open", "description": "Opens the working day on the fiscal device (TCR) of the token's user with the opening\n`balance`, in ALL, and records it as an `OPEN_DAY` action.\n\nCall it at the start of the shift, before the first cash invoice. It is not required: the first\ncash invoice, a cash in, a cash out or closing the day open the day automatically with `0`. Use it when the day\nstarts with money in the cash register and you want the balance to be accurate.\n\n- `balance` is optional; without it, `0` is used. A negative value is rejected.\n- The user must have a TCR.\n\nThe response returns `balance` rounded to two decimals, as it was saved. When the CIS cannot be reached, the opening is saved and\nis fiscalized automatically later; the response is the same.", "summary": "Open the day on the cash register", "tags": [ "Cash register" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number", "description": "The balance the day starts with, in lek. Without it, `0` is used. A negative value is rejected.", "examples": [ 5000 ] } } } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when `balance` is negative, or when saving fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashRegisterOpenBalance" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/close-balance": { "post": { "operationId": "v2.cash-register.close", "description": "Closes the working day on the fiscal device (TCR) of the token's user: takes the whole\nbalance out of the cash register and returns the amount that went out.\n\nCall it at the end of the shift, without first checking whether the day is open: when it is not,\nit is opened automatically with `0` and closed immediately. The request has no body.\n\n- The user must have a TCR.\n\n`balance` is the amount in ALL that went out of the cash register, with two decimals; `0` when the cash register was empty. The cash out appears in\n`GET \/cash-register\/actions` as a `MONEY_OUT` action with the description \"Mbyllje turni\/xhiro ditore\" (shift\/daily close); when the cash register was empty, no cash out is recorded. When the CIS cannot be reached, the closing\nis saved and is fiscalized automatically later; the response is the same.", "summary": "Close the day on the cash register", "tags": [ "Cash register" ], "responses": { "200": { "description": "When the user has no fiscal device or when closing fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashRegisterCloseBalance" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/actions": { "get": { "operationId": "v2.cash-register.list", "description": "Returns the cash register history, newest first, filtered by type and date:\ncash ins, cash outs, and day openings and closings.\n\nUse it to reconcile the shift and to read the fiscal state of an action that was\nsaved while the CIS could not be reached.\n\n| `type` | Action |\n| --- | --- |\n| `MONEY_IN` | Cash in |\n| `MONEY_OUT` | Cash out |\n| `OPEN_DAY` | Opening the day |\n| `CLOSE_DAY` | Closing the day |\n\n- Several types are separated by commas: `type=MONEY_IN,MONEY_OUT` returns only money movements.\n- The closing from `POST \/cash-register\/close-balance` appears as `MONEY_OUT` with the description\n \"Mbyllje turni\/xhiro ditore\" (shift\/daily close), not as `CLOSE_DAY`.\n- `fromDate` and `toDate` limit by action date, both inclusive.\n- Pagination with `limit` and `offset`. `pagination` does not return `total`, so stop when a page\n comes back shorter than `limit`.\n\n`amount` is always positive, in ALL; `action_type` gives the direction. `fiscal_status` and\n`fiscal_fic` say whether the action has been fiscalized.\n\nThe only change from the v1 list is `internalId`: every action returns it as it was sent with the cash in or cash out, so you can match it to the action in your system. It is `null` for day openings and closings and for actions recorded without one.", "summary": "List cash register actions", "tags": [ "Cash register" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many actions to return per page.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Which action to start from, counting from 0.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "type", "in": "query", "description": "Filter by type: `MONEY_IN`, `MONEY_OUT`, `OPEN_DAY` or `CLOSE_DAY`, several types separated by commas.", "schema": { "type": "string" }, "example": "MONEY_IN" }, { "name": "fromDate", "in": "query", "description": "Start date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2026-12-31" } ], "responses": { "200": { "description": "The period's actions, newest first, with `pagination`; `items` is empty when there are no actions.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CashActionHistoryItem" } }, "pagination": { "$ref": "#\/components\/schemas\/CashActionPagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/balance": { "get": { "operationId": "v2.cash-register.balance", "description": "Returns the balance of the fiscal device (TCR) of the token's user, in ALL, together with its\n`fiscal_tcr_code`.\n\nWithout `toDate`, the current balance is returned. With `toDate`, the balance at the end of that day is returned, for\nreconciliation with a past day. The balance is cached for 5 seconds, so a just-recorded\naction may show up a moment later.\n\n- The user must have a TCR.", "summary": "Get the cash register balance", "tags": [ "Cash register" ], "parameters": [ { "name": "toDate", "in": "query", "description": "The date, `YYYY-MM-DD`, up to which the cash register balance is calculated. Without it, the latest balance\nis returned.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "When the user has no fiscal device, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashRegisterBalance" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/wtn": { "post": { "operationId": "v2.invoice.wtn.create", "description": "Issues a warehouse transfer note (WTN) and fiscalizes it with the CIS. The note is not a sale: it accompanies\ngoods moving from one point to another, and the law requires it even when nothing is sold.\n\nLines are sent as `invoice_lines`, not `lines` as on invoices, and each line has\n`product_name`, `product_code`, `unit` and `quantity`.\n\n## Required fields\n\n- `internalId`, the note's identifier in your system;\n- `vehPlates`, the vehicle's license plate;\n- `valueOfGoods`, the value of the goods in transit;\n- `invoice_lines`, at least one line.\n\n## internalId\n\nThis is the only change from [`POST \/api\/v1\/invoice\/wtn`](\/docs\/api), where the field is\noptional. Keep it unique within the company for the year: a second request with the same\n`internalId` does not issue a second note; it returns the first note with `200`. This makes retrying after a\ntimeout safe, and the note can be read later with\n`GET \/invoice\/wtn\/details\/{internalId}`.\n\n## Allowed values\n\n| Field | Values | Default |\n| --- | --- | --- |\n| `type` | `WTN`, `SALE` | `WTN` |\n| `transaction` | `TRANSFER`, `EXAMINATION`, `SALES`, `DOOR` | `TRANSFER` |\n| `vehOwnership` | `OWNER`, `THIRDPARTY` | `OWNER` |\n| `startPoint`, `destinPoint` | `ANOTHER`, `CUSTOMS`, `EXHIBITION`, `OTHER`, `SALE`, `STORE`, `WAREHOUSE` | `WAREHOUSE`, `STORE` |\n| `carrier_id_type` | `NUIS`, `ID` | `NUIS` |\n\nThe departure and arrival addresses (`startCity`, `startAddr`, `destinCity`, `destinAddr`) and\nthe carrier (`carrier_name`, `carrier_id_num`, `carrier_town`, `carrier_address`) are taken from\nyour business unit and company when not sent. `startDateTime` and `destinDateTime` take the issue\ntime when missing.\n\n## After issuing\n\nThe response carries `id`, `internalId`, `number`, `iic`, `fic`, `fiscalStatus`, `verifyURL` and\n`print`. When the CIS cannot be reached, the note is saved unfiscalized, with `fic: null` and\n`fiscalStatus: UNFISCALIZED`; fiscalization is done later from the fature.al dashboard, and you read the state\nin `fiscal.status` with `GET \/invoice\/wtn\/details\/{internalId}`. When the CIS rejects the\nnote, it is not saved and the response is `500` with the reason in `message`.\n\nA second request from the same token while the first is still running is rejected immediately with\n`429`. The slot frees up as soon as the response is returned, or after 30 seconds if the request was interrupted.", "summary": "Issue a warehouse transfer note", "tags": [ "Warehouse transfer notes" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/WtnInvoiceRequest" } } } }, "responses": { "200": { "description": "When the CIS cannot be reached, the note is saved unfiscalized: the response carries `invoice` with `fic: null` and `fiscalStatus: UNFISCALIZED`, and fiscalization happens later.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "anyOf": [ { "$ref": "#\/components\/schemas\/WtnIssueResult" }, { "type": "null" } ] }, "message": { "type": "string" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation, including a missing `internalId`. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error, or the CIS rejected the note; the reason is in `message`. The note was not saved.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } }, "get": { "operationId": "v2.invoice.wtn.list", "description": "The same list as [`GET \/api\/v1\/invoice\/wtn`](\/docs\/api): the company's notes, newest\nfirst, filtered by creation date. Each note comes in full, with `origin`,\n`destination`, `carrier`, `fiscal` and `lines`, so the lines need no second\ncall, and with `internalId` as it was sent.\n\n- Pagination with `limit` and `offset`. `pagination` does not return `total`, so stop when a page\n comes back shorter than `limit`.\n- A second request from the same token, while the first has not finished, is rejected immediately with\n `429`. The slot is released as soon as the response returns, or after 30 seconds if the request was interrupted.", "summary": "List warehouse transfer notes", "tags": [ "Warehouse transfer notes" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many notes to return per page.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Which note to start from, counting from 0.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "fromDate", "in": "query", "description": "The start date, `YYYY-MM-DD`, by creation date.", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2026-12-31" } ], "responses": { "200": { "description": "The period's notes, with `pagination`; `items` is empty when there are no notes.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/WtnInvoiceItem" } }, "pagination": { "$ref": "#\/components\/schemas\/WtnListPagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The dates are not in `YYYY-MM-DD` format.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/wtn\/print\/{id}": { "get": { "operationId": "v2.invoice.wtn.print", "description": "Returns the note's data as document-ready JSON, not as a PDF: the company with its logo,\nthe carrier, departure and arrival, and in `invoice` the number, fiscal codes, lines,\n`amounts` and `verifyUrl`.\n\nUse it when you format the document yourself, in your own printing system. The address of this\nendpoint comes in the `print` field of the list and of the details.", "summary": "Get the warehouse transfer note for printing", "tags": [ "Warehouse transfer notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the warehouse transfer note in fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "responses": { "200": { "description": "The note document as JSON, ready for you to format: the company with its logo, the carrier, departure, arrival and `invoice` with the lines and fiscal codes.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/WtnPrintDocument" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "The note was not found, or it does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/wtn\/{id}\/details": { "get": { "operationId": "v2.invoice.wtn.details", "description": "Returns the full note by its `id` in fature.al: the vehicle, the departure and\narrival points, the carrier, the fiscal codes and the goods lines. It is the same object the\nlist returns.", "summary": "Get a warehouse transfer note by id", "tags": [ "Warehouse transfer notes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the warehouse transfer note in fature.al.", "schema": { "type": "integer" }, "example": 403 } ], "responses": { "200": { "description": "The full note in `invoice`: departure and arrival points, the carrier, the fiscal codes and the goods lines.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/WtnInvoiceItem" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "The note was not found, or does not belong to your unit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/invoice\/wtn\/details\/{internalId}": { "get": { "operationId": "v2.invoice.wtn.details-by-internal-id", "description": "Returns the same object as `GET \/invoice\/wtn\/{id}\/details`, but by the identifier you\nsent in `internalId` when the note was issued, without storing our `id`. Since in v2 `internalId`\nis required, every note issued by this version can be read this way.\n\nWhen the same `internalId` has been used in more than one year, the most recent note is returned.", "summary": "Get a warehouse transfer note by internalId", "tags": [ "Warehouse transfer notes" ], "parameters": [ { "name": "internalId", "in": "path", "required": true, "description": "Your identifier for the note, sent when it was issued.", "schema": { "type": "string" }, "example": "WTN-2026-000412" } ], "responses": { "200": { "description": "The full note in `invoice`, the same one `GET \/invoice\/wtn\/{id}\/details` returns.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "invoice": { "$ref": "#\/components\/schemas\/WtnInvoiceItem" } }, "required": [ "invoice" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "No note with this `internalId` in your unit.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "422": { "description": "`internalId` is empty.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/purchase-invoices": { "get": { "operationId": "v2.purchase-invoices.list", "description": "Returns the invoices that suppliers have issued to your company, read from the CIS. The supplier\ndoes not send you anything: the documents are fetched from the central fiscalization system, each with the\nfull data, the seller, the buyer, the items, VAT and payment methods.\n\nUse it to reconcile purchases and deductible VAT without any manual step.\n\n- Pagination uses `page`, starting at `1`, not `limit` and `offset`, because the list comes from\n the CIS and not from fature.al. Repeat with `page + 1` as long as `pagination.hasMore` is `true`.\n- Do not stop at an empty `items`. A document whose details cannot be reached is dropped from\n `items` without an error, so a page can come back empty even when more pages follow it.\n- The period includes both days, from 00:00:00 on `fromDate` to 23:59:59 on `toDate`,\n in Albanian time.\n- A missing date defaults to today, so without either only today is read. For a past period\n send both: a past `toDate` on its own starts the period today, after it ends, and returns\n none of that period's invoices.\n- `fic` searches within the period, not the whole history. Send it together with a `fromDate` and\n `toDate` that include the invoice's date, otherwise only today's invoices are searched.\n- One page costs one CIS call for the list and one for each invoice on it. The details of each\n invoice are cached for one hour, and the endpoint has the fiscal rate limit.\n\nStore `iic` and `fic`: they let you find the invoice again, and `fic` also serves as a filter here.", "summary": "List purchase invoices", "tags": [ "Purchase invoices" ], "parameters": [ { "name": "page", "in": "query", "description": "The page of the list from the CIS, starting at 1. A value below 1 or not a number is read as 1. Repeat with `page + 1` as long as `pagination.hasMore` is `true`.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "fromDate", "in": "query", "description": "Start date, `YYYY-MM-DD`, inclusive. Defaults to today.", "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`, inclusive. Defaults to today.", "schema": { "type": "string" }, "example": "2026-07-15" }, { "name": "fic", "in": "query", "description": "Return only the invoice with this FIC, if it falls within the period.", "schema": { "type": "string" }, "example": "8a941d47-7d47-4b7e-8f3a-1c2d3e4f5a6b" } ], "responses": { "200": { "description": "The page's purchase invoices in `items`, each one complete, with `pagination`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PurchaseInvoiceItem" } }, "pagination": { "$ref": "#\/components\/schemas\/PurchaseInvoicePagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "description": "The token is missing or invalid, or the user does not have the purchase invoices right.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "422": { "description": "The dates are not in `YYYY-MM-DD` format.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "502": { "description": "The CIS responded with an error; the reason is in `message`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached. Try again later. `message` comes back empty; the reason is in `errors`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "description": "The user's token, from Settings > API tokens.", "scheme": "bearer" }, "clientId": { "type": "apiKey", "description": "The client id of your application, starts with ft_id_", "in": "header", "name": "X-Client-Id" }, "clientSecret": { "type": "apiKey", "description": "The client secret of your application, starts with 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 the `data` object.", "examples": [ false ] }, "message": { "type": "string", "description": "The error description. Empty when the failure carries no message of its own.", "examples": [ "Te dhenat jo te sakta." ] }, "errors": { "type": "array", "description": "Messages to show the user or to write to a log. Absent when there is nothing\nto add beyond `message`.", "items": { "type": "string" } } }, "required": [ "status", "message", "errors" ], "title": "ApiError" }, "ApiValidationError": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Always false.", "examples": [ false ] }, "message": { "type": "string", "description": "A summary line, the same for every validation failure.", "examples": [ "Te dhena jo te sakta" ] }, "errors": { "type": "object", "description": "The fields that failed validation, each with its own messages. Dotted keys point into\nobjects and array elements, e.g. `lines.0.quantity`.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "success", "message", "errors" ], "title": "ApiValidationError" }, "CancelInvoiceRequest": { "type": "object", "properties": { "lines": { "type": "array", "description": "The lines to cancel. Without it the whole invoice is canceled; with it only the\nlines sent are canceled, which is possible only for cash invoices. Each line must exist on the original\ninvoice with the same `product_code` and `product_name`, and the quantity can only decrease. An invoice issued with a discount on the whole invoice does not accept partial cancellation:\nsend the request without `lines` so it is canceled in full.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "The product name, as on the original invoice." }, "product_code": { "type": "string", "description": "The product code, as on the original invoice." }, "quantity": { "type": "number", "description": "The quantity being returned, greater than 0 and no greater than on the original invoice." }, "price": { "type": [ "number", "null" ], "description": "Unit price, including VAT. Needed only when the same product was invoiced on two\nlines at different prices, to tell which line is canceled." } }, "required": [ "product_name", "product_code", "quantity" ] }, "minItems": 1 } }, "title": "CancelInvoiceRequest" }, "CashActionHistoryItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "The action's id in fature.al.", "examples": [ 5120 ] }, "internalId": { "type": [ "string", "null" ], "description": "The action's identifier in your system, the one you sent in `internalId` to `POST \/cash-register\/deposit` or `POST \/cash-register\/withdraw`. `null` for day openings and closings and for actions recorded without `internalId`, through v1 or the dashboard.", "examples": [ "ARKA-2026-000318" ] }, "action_type": { "type": "string", "description": "Action type: `MONEY_IN` cash in, `MONEY_OUT` cash out, `OPEN_DAY` opening the\nday, `CLOSE_DAY` closing the day. Without the `type` filter the list returns every cash register action, including\ntypes recorded only from the dashboard, such as `INITIAL_OPEN_BALANCE` (the first opening of the cash register) and\n`MONEY_IN_TRANSFER` (money moved in from another cash register).", "examples": [ "MONEY_IN" ] }, "amount": { "type": "number", "description": "Action amount, always positive, in the `currency` currency; `action_type` gives the direction.", "examples": [ 1500 ] }, "currency": { "type": "string", "description": "ISO 4217 code of the action's currency; `ALL` on every action recorded through the API.", "examples": [ "ALL" ] }, "transaction_date": { "type": "string", "description": "Action date, `YYYY-MM-DD`: the day it was recorded.", "examples": [ "2026-09-14" ] }, "transaction_no": { "type": "integer", "description": "Sequence number of the action within the company: counts all of the company's cash register actions,\nof every type and every fiscal device (TCR).", "examples": [ 812 ] }, "cash_action_no": { "type": "string", "description": "Action number, `n\/year\/TCR code`: `n` starts at 1 every year, separately for each action type and\neach fiscal device (TCR).", "examples": [ "12\/2026\/pp556gh743" ] }, "fiscal_status": { "type": [ "string", "null" ], "description": "Fiscal status: `FISCALIZED` when the CIS has registered the action, `UNFISCALIZED` while it\nis waiting for fiscalization, which fature.al retries on its own.", "examples": [ "FISCALIZED" ] }, "fiscal_uuid": { "type": [ "string", "null" ], "description": "The UUID fature.al assigns to the action when sending it to the CIS, the same one sent as the UUID of the\n`RegisterCashDeposit` request. `null` when the action has not been sent to the CIS yet.", "examples": [ "3f2c9a4e-6b1d-4c8e-9a7f-2d5e8b1c4a60" ] }, "fiscal_fic": { "type": [ "string", "null" ], "description": "The FCDC code the CIS returns when it registers the action. `null` while the action is waiting for fiscalization;\nit also stays `null` when the CIS answered with one of the errors 56, 63 or 920, which fature.al\ncloses as `FISCALIZED` without a code.", "examples": [ "b6e1f2a3-9c4d-4e5f-8a7b-1c2d3e4f5a6b" ] }, "fiscal_tcr_code": { "type": [ "string", "null" ], "description": "Code of the fiscal device (TCR) where the action was recorded. For an administrator the list covers\nall of the company's cash registers, so this field tells which one the action belongs to. `null` on an action\nsaved without a fiscal device.", "examples": [ "pp556gh743" ] }, "description": { "type": [ "string", "null" ], "description": "Action description: the one sent in `description`, or the one fature.al sets itself on\nits own actions, such as \"Mbyllje turni\/xhiro ditore\" on closing the day and \"Hapje e gjendjes fillestare\" on opening with a balance. `null` when there is none.", "examples": [ "Arketim nga klienti" ] }, "third_party": { "type": [ "string", "null" ], "description": "The action's third party, as sent in `third_party`; when the action was linked to a\nclient (`id_client`), it is replaced by the client's name. `null` when there is none.", "examples": [ "Alba Market shpk" ] }, "id_client": { "type": [ "integer", "null" ], "description": "Id of the client linked to the action, as sent in `id_client`; `null` when the action has\nno client.", "examples": [ 42 ] }, "created_at": { "type": "string", "description": "Date and time of recording, `YYYY-MM-DD HH:MM:SS`, local time. The balance from\n`GET \/cash-register\/balance` with `toDate` is computed on this time, not on `transaction_date`.", "examples": [ "2026-09-14 10:15:00" ] } }, "required": [ "id", "internalId", "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" ], "title": "CashActionHistoryItem" }, "CashActionIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "The action's id in fature.al.", "examples": [ 5120 ] }, "internalId": { "type": "string", "description": "The action's identifier in your system, the one you sent in `internalId`.", "examples": [ "ARKA-2026-000318" ] }, "action_type": { "type": "string", "description": "Action type: `MONEY_IN` cash in, from `POST \/cash-register\/deposit`; `MONEY_OUT`\ncash out, from `POST \/cash-register\/withdraw`.", "examples": [ "MONEY_IN" ] }, "amount": { "type": "number", "description": "Action amount, always positive, in lek; `action_type` gives the direction.", "examples": [ 1500 ] }, "currency": { "type": "string", "description": "ISO 4217 code of the action's currency. Through the API, actions are recorded only in lek, so\nthis is always `ALL`.", "examples": [ "ALL" ] }, "transaction_date": { "type": "string", "description": "Action date, `YYYY-MM-DD`: the day it was recorded.", "examples": [ "2026-09-14" ] }, "transaction_no": { "type": "integer", "description": "Sequence number of the action within the company: counts all of the company's cash register actions,\nof every type and every fiscal device (TCR).", "examples": [ 812 ] }, "cash_action_no": { "type": "string", "description": "Action number, `n\/year\/TCR code`: `n` starts at 1 every year, separately for each action type and\neach fiscal device (TCR).", "examples": [ "12\/2026\/pp556gh743" ] }, "fiscal_status": { "type": [ "string", "null" ], "description": "Fiscal status: `FISCALIZED` when the CIS has registered the action, `UNFISCALIZED` while it\nis waiting for fiscalization, which fature.al retries on its own.", "examples": [ "FISCALIZED" ] }, "fiscal_uuid": { "type": [ "string", "null" ], "description": "The UUID fature.al assigns to the action when sending it to the CIS, the same one sent as the UUID of the\n`RegisterCashDeposit` request. `null` when the action has not been sent to the CIS yet.", "examples": [ "3f2c9a4e-6b1d-4c8e-9a7f-2d5e8b1c4a60" ] }, "fiscal_fic": { "type": [ "string", "null" ], "description": "The FCDC code the CIS returns when it registers the action. `null` while the action is waiting for fiscalization;\nit also stays `null` when the CIS answered with one of the errors 56, 63 or 920, which fature.al\ncloses as `FISCALIZED` without a code.", "examples": [ "b6e1f2a3-9c4d-4e5f-8a7b-1c2d3e4f5a6b" ] }, "description": { "type": [ "string", "null" ], "description": "The action's description, as sent in `description`; `null` when it was not sent.", "examples": [ "Arketim nga klienti" ] } }, "required": [ "id", "internalId", "action_type", "amount", "currency", "transaction_date", "transaction_no", "cash_action_no", "fiscal_status", "fiscal_uuid", "fiscal_fic", "description" ], "title": "CashActionIssueResult" }, "CashActionPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many actions `items` holds on this page.", "examples": [ 20 ] }, "limit": { "type": "integer", "description": "The request's `limit` parameter, after rounding up to at least 1.", "examples": [ 20 ] }, "offset": { "type": "integer", "description": "The request's `offset` parameter, after rounding up to at least 0.", "examples": [ 0 ] }, "type": { "type": [ "string", "null" ], "description": "The `type` filter as sent, `null` when not sent.", "examples": [ "MONEY_IN,MONEY_OUT" ] } }, "required": [ "records", "limit", "offset", "type" ], "title": "CashActionPagination" }, "CashActionRequest": { "type": "object", "description": "Cash in and cash out in the v2 shape.\n\nEvery other field is word for word the v1 one, and V2RequestRulesParityTest keeps it that way. Only `internalId` changes: here it is required, as on every other document recorded through v2, and a retried request does not record a second action.\n\nThe rules are written out in full and not taken from the v1 class, because the documentation generator reads `rules()` as text.", "properties": { "internalId": { "type": "string", "description": "The action's identifier in your system, unique within the company for the year; also serves as the idempotency key. Required.", "examples": [ "ARKA-2026-000318" ], "maxLength": 255 }, "amount": { "type": "number", "description": "The amount, always positive, in ALL. Whether it is cash in or cash out is decided by the endpoint you call,\nnot by the sign of the number.", "examples": [ 1500 ] }, "description": { "type": [ "string", "null" ], "description": "Action description.", "examples": [ "Arketim nga klienti" ], "maxLength": 255 }, "third_party": { "type": [ "string", "null" ], "description": "The action's third party: who brought or who took the money.", "examples": [ "Klienti XYZ" ], "maxLength": 255 }, "id_client": { "type": [ "integer", "null" ], "description": "Client: the id of one of your clients in fature.al, to link the action to it.\nReturned later in the list of actions. An id that does not belong to your company is rejected.", "examples": [ 42 ] } }, "required": [ "internalId", "amount" ], "title": "CashActionRequest" }, "CashInvoice": { "type": "object", "description": "Cash invoice, in the v2 shape.\n\nEvery other field is exactly the same as in v1, and a test keeps it that way.\nOnly the payment changes: here it is always sent as a `payment_methods` list,\neven when the invoice is settled with a single method, so a new integration\nlearns one shape instead of two.\n\nThe company card and vouchers go inside the element that requires them.\n\nv2 also adds `lines.*.vouchers_sold`, the vouchers a line sells.\n\nThe rules are written out in full and not inherited from the v1 class, because\nthe documentation generator reads `rules()` as text and cannot get any field\nfrom a `parent::rules()` call. See V2RequestRulesParityTest.", "properties": { "internalId": { "type": "string", "description": "The invoice identifier in your system, unique within the company for the year; also serves as the\nidempotency key. Required.", "examples": [ "CASH-001" ] }, "client": { "type": "object", "description": "The buyer. Optional: without it the invoice is issued to the walk-in customer. With `client.internal_id` a client saved in fature.al is used; otherwise `client.name` becomes required as soon as you send any other `client` field.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Id of a client saved in fature.al. When you send it, the buyer is taken from it and the other `client` fields are not read." }, "name": { "type": [ "string", "null" ], "description": "The buyer's name. Required as soon as you send any other `client` field.", "examples": [ "Klient i rastit" ] }, "id": { "type": [ "object", "null" ], "description": "The buyer's identification document, as an object with `type` and `id`.", "properties": { "type": { "type": [ "string", "null" ], "description": "Document type: `NUIS` for an Albanian business, `VAT` or `TAX` for a foreign business, `ID`, `PASS` or `SOC` for a person. Defaults to `NUIS`.", "enum": [ "NUIS", "VAT", "TAX", "ID", "PASS", "SOC", null ] }, "id": { "type": [ "string", "null" ], "description": "Identification document number, e.g. the NIPT when `type` is `NUIS`.", "examples": [ "L62221018T" ] } } }, "address": { "type": [ "string", "null" ], "description": "The buyer's address; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "city": { "type": [ "string", "null" ], "description": "The buyer's city; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "country": { "type": [ "string", "null" ], "description": "The buyer's country, ISO 3166-1 alpha-3 code, e.g. `ALB`, `RKS`, `ITA`. Defaults to `ALB`." } } }, "lines": { "type": "array", "description": "Invoice lines, at least one.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Name of the product or service.", "examples": [ "Kafe" ] }, "product_code": { "type": "string", "description": "Product code in your catalog.", "examples": [ "KAF-001" ] }, "unit": { "type": "string", "description": "Unit of measure, as human-readable text.", "examples": [ "cope" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 2 ] }, "price": { "type": "number", "description": "Unit price, including VAT.", "examples": [ 150 ] }, "total": { "type": "number", "description": "Line total, including VAT.", "examples": [ 300 ] }, "discount": { "type": [ "number", "null" ], "description": "Line discount, as a percentage of the unit price, from 0 to 100. Optional: without it,\nor with an empty value, the line goes through as you send it. `price` stays the full unit price, while `total` is sent already reduced: `price` times\n`quantity`, with the discount taken off. A `total` that does not match that figure rejects the\nrequest with `400`, and `errors` says which line and which value was expected.", "examples": [ 10 ], "minimum": 0, "maximum": 100 }, "vat": { "type": "integer", "description": "VAT rate as a percentage: `0`, `6`, `10` or `20`. Required. When your business is not in the VAT scheme, the line is recorded with VAT `0` and\nexemption `TAX_FREE`, however you send this field; the request is not rejected.", "enum": [ "0", "6", "10", "20" ], "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Type of VAT exemption, when the line is exempt: `TYPE_1`, `TYPE_2`,\n`EXPORT_OF_GOODS`, `TAX_FREE` or `MARGIN_SCHEME`. `MARGIN_SCHEME` is the margin scheme, for travel agencies: the line is sold at its full price with\nno VAT, and VAT is charged only on the margin. It is accepted only when the business has switched it\non in Settings and is VAT-registered; otherwise the request is refused. It requires `margin_cost`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", "MARGIN_SCHEME", null ], "examples": [ "EXPORT_OF_GOODS" ] }, "margin_cost": { "type": [ "number", "null" ], "description": "The purchase cost of the whole line (not per unit), in the invoice currency, for a line under the\nmargin scheme. Required when `vat_exempt_type` is `MARGIN_SCHEME`, not read on other lines. The\nmargin is `total` minus this cost and never goes below zero. The buyer never sees it: it is on\nneither the printed invoice nor the e-invoice.", "examples": [ 80 ], "minimum": 0 }, "vouchers_sold": { "type": [ "object", "null" ], "description": "The single-purpose vouchers this line sells, when the goods sold are the vouchers themselves: the\npurpose, the expiry date, the nominal value and the serial numbers. Sent to CIS as the line's `VS`\nelement. Optional: without it the line is an ordinary sale. It is not a voucher payment. An invoice paid with vouchers sends the numbers in\n`payment_methods[].vouchers`, inside the `SVOUCHER` entry.", "examples": [ { "purpose": "veshje dhe k\u00ebpuc\u00eb", "expires_at": "2027-12-31", "nominal_value": 1000, "numbers": [ "12-2026-K51501011M", "13-2026-K51501011M" ] } ], "properties": { "purpose": { "type": "string", "description": "Which goods or services the voucher is for. Required when the line carries `vouchers_sold`, up\nto 255 characters. Not sent to CIS: it builds the description required by Instruction 16\/2020\n(article 8, point 4), which appears under the item name on the printed invoice and in the\ne-invoice.", "examples": [ "veshje dhe k\u00ebpuc\u00eb" ], "maxLength": 255 }, "expires_at": { "type": "string", "format": "date", "description": "The vouchers' expiry date, `YYYY-MM-DD`. Required when the line carries `vouchers_sold`.", "examples": [ "2027-12-31" ] }, "nominal_value": { "type": "number", "description": "The nominal value of one voucher, in the invoice currency. Not negative. Required when the line\ncarries `vouchers_sold`.", "examples": [ 1000 ], "minimum": 0 }, "numbers": { "type": "array", "description": "The serial numbers of the vouchers sold, in the form number-year-NIPT, from 1 to 1000. A\nnumber is not repeated anywhere on the invoice.", "examples": [ [ "12-2026-K51501011M", "13-2026-K51501011M" ] ], "items": { "type": "string", "description": "One voucher sold, in the form number-year-NIPT.", "pattern": "^[1-9][0-9]{0,7}-[0-9]{4}-[a-zA-Z][0-9]{8}[a-zA-Z]$" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true } } } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total", "vat" ] }, "minItems": 1 }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "How `invoice_discount_value` is read: `percent` as a percentage, `amount` as a fixed value including\nVAT. The discount applies to the whole invoice: lines are saved as you send them and only the\ntotal is reduced. Works only paired with `invoice_discount_value`. One without the other is silently ignored and\nthe invoice comes out with no discount.", "enum": [ "percent", "amount", null ], "examples": [ "percent" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Discount value, read according to `invoice_discount_type`: a percentage up to 100 when the type\nis `percent`; a value including VAT in the invoice currency, up to the invoice total, when the type\nis `amount`. Zero leaves the invoice without a discount. The discount is spread over the VAT groups by each one's weight in the total, and the VAT\nis recomputed on the reduced value.", "examples": [ 10 ], "minimum": 0 }, "currency": { "type": [ "string", "null" ], "description": "Invoice currency, ISO 4217 code; defaults to `ALL`.", "examples": [ "ALL" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "How many lek one unit of the invoice currency is worth. Without it, or with a non-positive value, 1 is used. For\ncurrencies worth less than one lek, such as JPY or HUF, send a value below 1.", "examples": [ 100.5 ] }, "due_date": { "type": [ "string", "null" ], "description": "Payment due date, `YYYY-MM-DD`.", "examples": [ "2026-10-04" ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "Start of the supply period, `YYYY-MM-DD`, for invoices covering an interval.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-30" ] }, "reverse_charge": { "type": [ "boolean", "null" ], "description": "Reverse charge: VAT is declared by the buyer, not by the seller.", "examples": [ false ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the invoice.", "examples": [ "Faleminderit per blerjen" ] }, "periodic_invoice": { "type": [ "boolean", "null" ], "description": "Marks an invoice belonging to a recurring billing cycle.", "examples": [ false ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Self-invoicing: `DOMESTIC`, `ABROAD` or `OTHER`. When you send it, `client` is the seller and\nneeds its identification (`client.id`) together with the country. Without it the invoice is a regular one.", "enum": [ "DOMESTIC", "ABROAD", "OTHER", null ], "examples": [ "DOMESTIC" ] }, "payment_method": { "type": "string", "description": "Not accepted in v2: the payment method is sent as an element of `payment_methods`." }, "company_card": { "type": "string", "description": "Not accepted on the invoice in v2: it goes in `payment_methods[].company_card`, inside the `COMPANY` element." }, "vouchers": { "type": "string", "description": "Not accepted on the invoice in v2: they go in `payment_methods[].vouchers`, inside the `SVOUCHER` element." }, "payment_methods": { "type": "array", "description": "The payment methods, one element each. Required even when the invoice is paid with a single\nmethod; the list then has one element. Up to 10 elements, the same method is not\nrepeated, and the sum of `amount` must equal the invoice total, with the discount already\napplied; otherwise the request is rejected with `400`.", "examples": [ [ { "type": "BANKNOTE", "amount": 1200 }, { "type": "CARD", "amount": 800 } ] ], "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The payment method of this element: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` or\n`ORDER`. Required.", "enum": [ "BANKNOTE", "CARD", "CHECK", "SVOUCHER", "COMPANY", "ORDER" ], "examples": [ "BANKNOTE" ] }, "amount": { "type": "number", "description": "The amount paid with this method, including VAT, in the invoice currency. Required. Accepts any value\nthe CIS accepts: including 0, for an invoice worth 0, and negative.", "examples": [ 1200 ] }, "company_card": { "type": [ "string", "null" ], "description": "The company card. Required only in the `COMPANY` element and rejected in any other\nelement. Up to 50 characters.", "examples": [ "4111-2233" ], "maxLength": 50 }, "vouchers": { "type": [ "array", "null" ], "description": "The vouchers' serial numbers, in number-year-NIPT form, without repeats, up to 20.\nRequired only in the `SVOUCHER` element and rejected in any other element.", "examples": [ [ "12-2026-K51501011M" ] ], "items": { "type": "string", "description": "A voucher, in number-year-NIPT form. Not repeated within the element.", "pattern": "^[1-9][0-9]{0,7}-[0-9]{4}-[a-zA-Z][0-9]{8}[a-zA-Z]$" }, "maxItems": 20, "uniqueItems": true } }, "required": [ "type", "amount" ] }, "minItems": 1, "maxItems": 10, "uniqueItems": true } }, "required": [ "internalId", "lines", "payment_methods" ], "title": "CashInvoice" }, "CashRegisterBalance": { "type": "object", "properties": { "fiscal_tcr_code": { "type": "string", "description": "Code of the fiscal device (TCR) of the token's user, the one the balance was computed\nfor.", "examples": [ "pp556gh743" ] }, "currency": { "type": "string", "description": "ISO 4217 code of the balance currency; always `ALL`.", "examples": [ "ALL" ] }, "to_date": { "type": [ "string", "null" ], "description": "The request's `toDate` parameter as sent, `YYYY-MM-DD`: the balance is the one at the end\nof that day, with every action and invoice recorded up to 23:59:59. `null` when it was not\nsent and the balance is the current one.", "examples": [ "2026-09-14" ] }, "balance": { "type": "number", "description": "The balance, in lek, with two decimal places: cash in minus cash out recorded on this TCR\nplus the cash invoices issued from it, where self-invoices are subtracted and order invoices are not\nincluded.", "examples": [ 23450.5 ] } }, "required": [ "fiscal_tcr_code", "currency", "to_date", "balance" ], "title": "CashRegisterBalance" }, "CashRegisterCloseBalance": { "type": "object", "properties": { "balance": { "type": "number", "description": "The amount taken out of the cash register, in lek: the balance of the fiscal device (TCR) at the moment of closing,\nrecorded as a `MONEY_OUT` cash out. `0` when the cash register was empty; then no\ncash out is recorded.", "examples": [ 23450.5 ] } }, "required": [ "balance" ], "title": "CashRegisterCloseBalance" }, "CashRegisterOpenBalance": { "type": "object", "properties": { "balance": { "type": "number", "description": "The day's opening balance, in lek, as accepted from the request's `balance`; `0` when\n`balance` was not sent.", "examples": [ 5000 ] } }, "required": [ "balance" ], "title": "CashRegisterOpenBalance" }, "ClientListPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many clients `items` holds in this response.", "examples": [ 20 ] }, "total": { "type": "integer", "description": "How many clients match the search in total, across all pages.", "examples": [ 137 ] }, "limit": { "type": "integer", "description": "The limit that was applied: the one you sent, lowered to `100` when it was larger; `20` when you sent none.", "examples": [ 20 ] }, "offset": { "type": "integer", "description": "Which client this page started from, counting from 0.", "examples": [ 0 ] } }, "required": [ "records", "total", "limit", "offset" ], "title": "ClientListPagination" }, "ClientV1": { "type": "object", "properties": { "id": { "type": "integer", "description": "The client's id in fature.al.", "examples": [ 42 ] }, "name": { "type": "string", "description": "Full name: the company name for a company, first and last name for a person.", "examples": [ "Alpha SHPK" ] }, "client_type": { "type": [ "string", "null" ], "description": "`COMPANY` or `PERSON`.", "examples": [ "COMPANY" ] }, "company_name": { "type": [ "string", "null" ], "description": "Company name; empty or null for a person.", "examples": [ "Alpha SHPK" ] }, "company_type": { "type": [ "string", "null" ], "description": "Company category: `BUSINESS`, `BANK` or `EXCHANGE`. Always null for a person.", "examples": [ "BUSINESS" ] }, "nipt": { "type": [ "string", "null" ], "description": "The company's NIPT, or the VAT\/TAX number of a foreign business; null when there is none.", "examples": [ "L91806031A" ] }, "first_name": { "type": [ "string", "null" ], "description": "The person's first name; always null for a company.", "examples": [ "Agon" ] }, "surname": { "type": [ "string", "null" ], "description": "The person's last name; always null for a company.", "examples": [ "Hoxha" ] }, "birthday": { "type": [ "string", "null" ], "description": "Date of birth, `YYYY-MM-DD`; null when not provided.", "examples": [ "1990-01-15" ] }, "id_type": { "type": [ "string", "null" ], "description": "Identification document type: `NUIS`, `ID`, `PASS`, `VAT`, `TAX` or `SOC`; null when\nnot recorded.", "examples": [ "NUIS" ] }, "id_num": { "type": [ "string", "null" ], "description": "Document number: the NIPT for a company, the personal document number for a person.", "examples": [ "L91806031A" ] }, "nationality_code": { "type": [ "string", "null" ], "description": "The client's country, ISO 3166-1 alpha-3 code.", "examples": [ "ALB" ] }, "nationality_id": { "type": [ "integer", "null" ], "description": "Country id in fature.al, the counterpart of `nationality_code`.", "examples": [ 3 ] }, "telephone": { "type": [ "string", "null" ], "description": "Phone number.", "examples": [ "+355691234567" ] }, "email": { "type": [ "string", "null" ], "description": "Email.", "examples": [ "info@alpha.al" ] }, "address": { "type": [ "string", "null" ], "description": "Address.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "city": { "type": [ "string", "null" ], "description": "City.", "examples": [ "Tiran\u00eb" ] }, "customer_number": { "type": [ "string", "null" ], "description": "Client number in your system. When you have not provided one, fature.al sets the client's sequence\nnumber within the company.", "examples": [ "CLI-001" ] }, "created_at": { "type": [ "string", "null" ], "description": "Creation date and time, ISO 8601.", "examples": [ "2026-09-13T10:15:00+02:00" ] } }, "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" ], "title": "ClientV1" }, "ClientV2": { "type": "object", "properties": { "id": { "type": "integer", "description": "The client's id in fature.al.", "examples": [ 8123 ] }, "type": { "type": "string", "description": "`company` or `person`.", "examples": [ "company" ] }, "company": { "anyOf": [ { "description": "Filled in when `type` is `company`, otherwise null.", "$ref": "#\/components\/schemas\/ClientV2Company" }, { "type": "null" } ] }, "person": { "anyOf": [ { "description": "Filled in when `type` is `person`, otherwise null.", "$ref": "#\/components\/schemas\/ClientV2Person" }, { "type": "null" } ] }, "address": { "description": "The client's address.", "$ref": "#\/components\/schemas\/ClientV2Address" }, "contact": { "description": "The client's phone and email.", "$ref": "#\/components\/schemas\/ClientV2Contact" }, "customer_number": { "type": [ "string", "null" ], "description": "Your reference for this client, when you have provided one.", "examples": [ "CL-0042" ] }, "verified": { "type": "boolean", "description": "true when the client's identifier has been confirmed with the tax administration.", "examples": [ true ] }, "created_at": { "type": [ "string", "null" ], "description": "Creation date and time, ISO 8601.", "examples": [ "2026-03-02T09:30:00+01:00" ] }, "updated_at": { "type": [ "string", "null" ], "description": "Date and time of the last change, ISO 8601.", "examples": [ "2026-09-10T16:45:00+02:00" ] } }, "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 and number.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "city": { "type": [ "string", "null" ], "description": "City.", "examples": [ "Tiran\u00eb" ] }, "country": { "type": [ "string", "null" ], "description": "Country code, ISO 3166-1 alpha-3.", "examples": [ "ALB" ] } }, "required": [ "line", "city", "country" ], "title": "ClientV2Address" }, "ClientV2Company": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Company name.", "examples": [ "Alba Trade shpk" ] }, "category": { "type": [ "string", "null" ], "description": "`business`, `bank` or `exchange`; null when the company has not been classified.", "examples": [ "business" ] }, "id": { "description": "The company's fiscal identifier, usually the NIPT.", "$ref": "#\/components\/schemas\/ClientV2Id" } }, "required": [ "name", "category", "id" ], "title": "ClientV2Company" }, "ClientV2Contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ], "description": "The phone number.", "examples": [ "+355 69 234 5678" ] }, "email": { "type": [ "string", "null" ], "description": "Email address.", "examples": [ "info@albatrade.al" ] } }, "required": [ "phone", "email" ], "title": "ClientV2Contact" }, "ClientV2Id": { "type": "object", "properties": { "type": { "type": "string", "description": "`nuis`, `vat` or `tax` for a company; `id`, `passport` or `social` for a person.", "examples": [ "nuis" ] }, "value": { "type": [ "string", "null" ], "description": "The identifier itself; null when the client has none on record.", "examples": [ "K91807012A" ] } }, "required": [ "type", "value" ], "title": "ClientV2Id" }, "ClientV2Person": { "type": "object", "properties": { "first_name": { "type": [ "string", "null" ], "description": "First name.", "examples": [ "Arben" ] }, "last_name": { "type": [ "string", "null" ], "description": "Last name.", "examples": [ "Hoxha" ] }, "birthday": { "type": [ "string", "null" ], "description": "Date of birth, `YYYY-MM-DD`.", "examples": [ "1985-04-21" ] }, "id": { "description": "The person's identity document.", "$ref": "#\/components\/schemas\/ClientV2Id" } }, "required": [ "first_name", "last_name", "birthday", "id" ], "title": "ClientV2Person" }, "ClientV2Request": { "type": "object", "properties": { "type": { "type": "string", "description": "Client type: `company` or `person`. Required; decides which object is filled in. It cannot change on update: a `type` different from the existing one is rejected with `422`.", "enum": [ "company", "person" ], "examples": [ "company" ] }, "company": { "type": "object", "description": "Company details. Required when `type` is `company`.", "properties": { "name": { "type": [ "string", "null" ], "description": "Company name. Required for `company`.", "maxLength": 255 }, "category": { "type": [ "string", "null" ], "description": "Company category: `business`, `bank` or `exchange`.", "enum": [ "business", "bank", "exchange", null ] }, "id": { "type": "object", "description": "The company identifier, as an object with `type` and `value`. Required for `company`.", "properties": { "type": { "type": "string", "description": "Identifier type: `nuis` for an Albanian business, `vat` or `tax` for a foreign business.", "enum": [ "nuis", "vat", "tax" ] }, "value": { "type": "string", "description": "The identifier value, e.g. the NIPT when `type` is `nuis`. Up to 20 characters.", "maxLength": 20 } } } } }, "person": { "type": "object", "description": "Person details. Required when `type` is `person`.", "properties": { "first_name": { "type": [ "string", "null" ], "description": "First name. Required for `person`.", "maxLength": 255 }, "last_name": { "type": [ "string", "null" ], "description": "Last name. Required for `person`.", "maxLength": 255 }, "birthday": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of birth, `YYYY-MM-DD`." }, "id": { "type": "object", "description": "The identity document, as an object with `type` and `value`. Required for `person`.", "properties": { "type": { "type": "string", "description": "Document type: `id` identity card, `passport` passport, `social` social security number.", "enum": [ "id", "passport", "social" ] }, "value": { "type": "string", "description": "Document number.", "maxLength": 255 } } } } }, "address": { "type": "object", "description": "The client's address. Optional, the same for both types.", "properties": { "line": { "type": [ "string", "null" ], "description": "Street and number.", "maxLength": 255 }, "city": { "type": [ "string", "null" ], "description": "City.", "maxLength": 50 }, "country": { "type": [ "string", "null" ], "description": "Country, ISO 3166-1 alpha-3 code. Defaults to `ALB` when omitted.", "minLength": 3, "maxLength": 3 } } }, "contact": { "type": "object", "description": "The client's contacts. Optional.", "properties": { "phone": { "type": [ "string", "null" ], "description": "Phone number.", "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email.", "maxLength": 255 } } }, "customer_number": { "type": [ "string", "null" ], "description": "The client's number in your system, if you keep one.", "examples": [ "CL-00412" ], "maxLength": 30 } }, "required": [ "type" ], "title": "ClientV2Request" }, "EInvoiceRequest": { "type": "object", "description": "Electronic invoice, in the v2 shape.\n\nEvery other field is exactly the same as in v1, and a test keeps it that way.\nOnly the payment changes: here it is always sent as a `payment_methods` list,\neven when the invoice is settled with a single method, so a new integration\nlearns one shape instead of two.\n\nNone of this invoice's payment methods carries a card or vouchers, so a list element holds only `type` and `amount`.\n\nThe rules are written out in full and not inherited from the v1 class, because\nthe documentation generator reads `rules()` as text and cannot get any field\nfrom a `parent::rules()` call. See V2RequestRulesParityTest.", "properties": { "internalId": { "type": "string", "description": "The invoice identifier in your system, unique within the company for the year; also serves as the\nidempotency key. Required.", "examples": [ "EINV-2026-000412" ] }, "client": { "type": "object", "description": "The buyer. Required: an e-invoice cannot be issued to the walk-in customer. Send `client.internal_id` for a client saved in fature.al, or `client.nuis`, `client.name` and `client.country` for a client from your system.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Id of a client saved in fature.al. When you send it, the buyer is taken from it and\nthe other `client` fields are not read.", "examples": [ 8812 ] }, "nuis": { "type": "string", "description": "The buyer's NIPT. Required when you do not send `client.internal_id`.", "examples": [ "L62221018T" ] }, "name": { "type": "string", "description": "The buyer's name. Required when you do not send `client.internal_id`.", "examples": [ "Ei3 Software Solution shpk" ] }, "address": { "type": [ "string", "null" ], "description": "The buyer's address; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "city": { "type": [ "string", "null" ], "description": "The buyer's city; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "country": { "type": "string", "description": "The buyer's country, ISO 3166-1 alpha-3 code, e.g. `ALB`, `RKS`, `ITA`. Required when you do not\nsend `client.internal_id`.", "examples": [ "ALB" ] } } }, "lines": { "type": "array", "description": "Invoice lines, at least one.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Name of the product or service.", "examples": [ "Kafe" ] }, "product_code": { "type": "string", "description": "Product code in your catalog.", "examples": [ "KAF-001" ] }, "unit": { "type": "string", "description": "Unit of measure, as human-readable text.", "examples": [ "cope" ] }, "unit_code": { "type": "string", "description": "Fiscal code of the unit of measure, the one the UBL document carries, e.g. `C62` unit, `XPP` piece,\n`KGM` kg, `LTR` liter, `HUR` hour, `MTK` m\u00b2. Required; not derived from `unit`. The meaning\nof all 49 codes is in the introduction, \"Unit of measure codes\".", "enum": [ "C62", "XPP", "LTR", "MLT", "SEC", "MIN", "HUR", "DAY", "MON", "ANN", "MTK", "E4", "58", "KGM", "DT", "DTN", "TNE", "GRM", "M4", "E54", "KMT", "D68", "QB", "H93", "MTQ", "MSK", "MTR", "CMT", "MMT", "LM", "KWH", "E49", "E55", "OT", "PR", "DZN", "XBX", "XPK", "XPX", "XRO", "XBG", "XBO", "XCT", "XCR", "XSA", "XCA", "XBA", "SET", "IE" ], "examples": [ "C62" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 2 ] }, "price": { "type": "number", "description": "Unit price, including VAT.", "examples": [ 150 ] }, "total": { "type": "number", "description": "Line total, including VAT.", "examples": [ 300 ] }, "discount": { "type": [ "number", "null" ], "description": "Line discount, as a percentage of the unit price, from 0 to 100. Optional: without it,\nor with an empty value, the line goes through as you send it. `price` stays the full unit price, while `total` is sent already reduced: `price` times\n`quantity`, with the discount taken off. A `total` that does not match that figure rejects the\nrequest with `400`, and `errors` says which line and which value was expected.", "examples": [ 10 ], "minimum": 0, "maximum": 100 }, "vat": { "type": [ "integer", "null" ], "description": "VAT rate as a percentage: `0`, `6`, `10` or `20`. Validation allows it to be missing, but\nsend it on every line: without it the line has no VAT rate. When your business is not in the VAT scheme, the line is recorded with VAT `0` and\nexemption `TAX_FREE`, however you send this field; the request is not rejected.", "enum": [ "0", "6", "10", "20", null ], "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Type of VAT exemption, when the line is exempt: `TYPE_1`, `TYPE_2`,\n`EXPORT_OF_GOODS`, `TAX_FREE` or `MARGIN_SCHEME`. `MARGIN_SCHEME` is the margin scheme, for travel agencies: the line is sold at its full price with\nno VAT, and VAT is charged only on the margin. It is accepted only when the business has switched it\non in Settings and is VAT-registered; otherwise the request is refused. It requires `margin_cost`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", "MARGIN_SCHEME", null ], "examples": [ "EXPORT_OF_GOODS" ] }, "margin_cost": { "type": [ "number", "null" ], "description": "The purchase cost of the whole line (not per unit), in the invoice currency, for a line under the\nmargin scheme. Required when `vat_exempt_type` is `MARGIN_SCHEME`, not read on other lines. The\nmargin is `total` minus this cost and never goes below zero. The buyer never sees it: it is on\nneither the printed invoice nor the e-invoice.", "examples": [ 80 ], "minimum": 0 }, "vouchers_sold": { "type": [ "object", "null" ], "description": "The single-purpose vouchers this line sells, when the goods sold are the vouchers themselves: the\npurpose, the expiry date, the nominal value and the serial numbers. Sent to CIS as the line's `VS`\nelement. Optional: without it the line is an ordinary sale. It is not a voucher payment. An invoice paid with vouchers sends the numbers in\n`payment_methods[].vouchers`, inside the `SVOUCHER` entry.", "examples": [ { "purpose": "veshje dhe k\u00ebpuc\u00eb", "expires_at": "2027-12-31", "nominal_value": 1000, "numbers": [ "12-2026-K51501011M", "13-2026-K51501011M" ] } ], "properties": { "purpose": { "type": "string", "description": "Which goods or services the voucher is for. Required when the line carries `vouchers_sold`, up\nto 255 characters. Not sent to CIS: it builds the description required by Instruction 16\/2020\n(article 8, point 4), which appears under the item name on the printed invoice and in the\ne-invoice.", "examples": [ "veshje dhe k\u00ebpuc\u00eb" ], "maxLength": 255 }, "expires_at": { "type": "string", "format": "date", "description": "The vouchers' expiry date, `YYYY-MM-DD`. Required when the line carries `vouchers_sold`.", "examples": [ "2027-12-31" ] }, "nominal_value": { "type": "number", "description": "The nominal value of one voucher, in the invoice currency. Not negative. Required when the line\ncarries `vouchers_sold`.", "examples": [ 1000 ], "minimum": 0 }, "numbers": { "type": "array", "description": "The serial numbers of the vouchers sold, in the form number-year-NIPT, from 1 to 1000. A\nnumber is not repeated anywhere on the invoice.", "examples": [ [ "12-2026-K51501011M", "13-2026-K51501011M" ] ], "items": { "type": "string", "description": "One voucher sold, in the form number-year-NIPT.", "pattern": "^[1-9][0-9]{0,7}-[0-9]{4}-[a-zA-Z][0-9]{8}[a-zA-Z]$" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true } } } }, "required": [ "product_name", "product_code", "unit", "unit_code", "quantity", "price", "total" ] }, "minItems": 1 }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "How `invoice_discount_value` is read: `percent` as a percentage, `amount` as a fixed value including\nVAT. The discount applies to the whole invoice: lines are saved as you send them and only the\ntotal is reduced. Works only paired with `invoice_discount_value`. One without the other is silently ignored and\nthe invoice comes out with no discount.", "enum": [ "percent", "amount", null ], "examples": [ "percent" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Discount value, read according to `invoice_discount_type`: a percentage up to 100 when the type\nis `percent`; a value including VAT in the invoice currency, up to the invoice total, when the type\nis `amount`. Zero leaves the invoice without a discount. The discount is spread over the VAT groups by each one's weight in the total, and the VAT\nis recomputed on the reduced value. In the UBL document it appears as AllowanceCharge, with one entry per\nVAT rate.", "examples": [ 10 ], "minimum": 0 }, "bank_account": { "type": [ "integer", "null" ], "description": "Id of a bank account saved in fature.al.", "examples": [ 42 ] }, "bank_account_iban": { "type": [ "string", "null" ], "description": "IBAN of an account saved in fature.al; the account is looked up by IBAN, instead of\n`bank_account`.", "examples": [ "AL35202111090000000001234567" ] }, "bankAccount": { "type": "object", "description": "The full bank account, when you do not have it in fature.al yet: `name`, `iban`, `currency`, `swift`, `holder`. Saved as an account of your company; an IBAN that already exists is reused.", "properties": { "name": { "type": [ "string", "null" ], "description": "Bank name.", "examples": [ "BKT" ] }, "iban": { "type": [ "string", "null" ], "description": "Account IBAN.", "examples": [ "AL35202111090000000001234567" ] }, "currency": { "type": [ "string", "null" ], "description": "Account currency, ISO 4217 code.", "examples": [ "ALL" ] }, "swift": { "type": [ "string", "null" ], "description": "The bank's SWIFT\/BIC code.", "examples": [ "NCBAALTX" ] }, "notes": { "type": [ "string", "null" ], "description": "Notes that accompany the account on the invoice." }, "holder": { "type": [ "string", "null" ], "description": "Account holder.", "examples": [ "Ei3 Software Solution shpk" ] } } }, "currency": { "type": [ "string", "null" ], "description": "Invoice currency, ISO 4217 code; defaults to `ALL`.", "examples": [ "ALL" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "How many lek one unit of the invoice currency is worth. Without it, or with a non-positive value, 1 is used. For\ncurrencies worth less than one lek, such as JPY or HUF, send a value below 1.", "examples": [ 100.5 ] }, "due_date": { "type": [ "string", "null" ], "description": "Payment due date, `YYYY-MM-DD`.", "examples": [ "2026-10-04" ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "Start of the supply period, `YYYY-MM-DD`, for invoices covering an interval.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-30" ] }, "reverse_charge": { "type": [ "boolean", "null" ], "description": "Reverse charge: VAT is declared by the buyer, not by the seller.", "examples": [ false ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the invoice.", "examples": [ "Faleminderit per blerjen" ] }, "order_reference": { "type": [ "string", "null" ], "description": "The buyer's purchase order number (BT-13). The e-invoice sends it as `cac:OrderReference\/cbc:ID`.", "examples": [ "PO-2026-0187" ], "maxLength": 100 }, "project_reference": { "type": [ "string", "null" ], "description": "The project reference (BT-11), as `cac:ProjectReference\/cbc:ID` on the e-invoice.", "examples": [ "PRJ-TIR-042" ], "maxLength": 100 }, "periodic_invoice": { "type": [ "boolean", "null" ], "description": "Marks an invoice belonging to a recurring billing cycle.", "examples": [ false ] }, "doc_type": { "type": "string", "description": "UBL document type: `380` sales invoice, `381` credit note, `383` debit note.\nRequired. A note requires `original_invoice_iic`; the lines you send are the\ncorrection lines, with positive values, and `doc_type` sets the direction. Validation also accepts\nthe other UBL standard codes, `80`, `82`, `84`, `384`, `386`, `388`, `393`, `394`,\n`395`, `575`, `623` and `780`, with the meaning the standard gives them.", "enum": [ "80", "82", "84", "380", "381", "383", "384", "386", "388", "393", "394", "395", "575", "623", "780" ], "examples": [ "380" ] }, "process": { "type": "string", "description": "UBL profile of the document (ProfileID): `P1` for a sale, `P9` for a correction.\nRequired. Validation accepts `P1` through `P11`, per the UBL standard.", "enum": [ "P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9", "P10", "P11" ], "examples": [ "P1" ] }, "original_invoice_iic": { "type": [ "string", "null" ], "description": "The `iic` of the invoice this document corrects, the one the original invoice returned to you.\nRequired when `doc_type` is `381` or `383` and rejected with any other document\ntype. The original must be of the same type, fiscalized, not canceled and still\ncorrectable; to reverse a whole invoice use cancellation, not a credit note.", "examples": [ "8FE72E2ACD1C500A83F8C89B4E2E3E1D" ] }, "payment_method": { "type": "string", "description": "Not accepted in v2: the payment method is sent as an element of `payment_methods`." }, "payment_methods": { "type": "array", "description": "Payment methods, one element for each. Required even when the invoice is paid with a single method; the list then has one element. Up to 10 elements, the same method is not repeated, and the `amount` values must add up to the invoice total, with the discount already applied; otherwise the request is rejected with `400`. None of these methods carries a card or vouchers, so an element has only `type` and `amount`.", "examples": [ [ { "type": "TRANSFER", "amount": 1500 }, { "type": "COMPENSATION", "amount": 500 } ] ], "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The payment method of this element: `ACCOUNT`, `COMPENSATION`, `FACTORING`, `KIND`, `OTHER`, `TRANSFER` or `WAIVER`. Required.", "enum": [ "ACCOUNT", "COMPENSATION", "FACTORING", "KIND", "OTHER", "TRANSFER", "WAIVER" ], "examples": [ "TRANSFER" ] }, "amount": { "type": "number", "description": "The amount paid with this method, including VAT, in the invoice currency. Required. Accepts any value\nthe CIS accepts: including 0, for an invoice worth 0, and negative.", "examples": [ 1500 ] } }, "required": [ "type", "amount" ] }, "minItems": 1, "maxItems": 10, "uniqueItems": true } }, "required": [ "internalId", "client", "lines", "doc_type", "process", "payment_methods" ], "title": "EInvoiceRequest" }, "InvoiceAddress": { "type": "object", "properties": { "street": { "type": [ "string", "null" ], "description": "Street and number.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "city": { "type": [ "string", "null" ], "description": "City.", "examples": [ "Tiran\u00eb" ] }, "country": { "type": "string", "description": "Country code, ISO 3166-1 alpha-3; `ALB` when the buyer has none recorded.", "examples": [ "ALB" ] } }, "required": [ "street", "city", "country" ], "title": "InvoiceAddress" }, "InvoiceAmount": { "type": "object", "properties": { "currency": { "type": "string", "description": "Invoice currency, ISO 4217.", "examples": [ "EUR" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "Exchange rate against the lek; null when the invoice is already in lek.", "examples": [ 98.5 ] }, "gross": { "type": "number", "description": "Total including VAT, after the invoice discount is taken off.", "examples": [ 540 ] }, "net": { "type": "number", "description": "Total excluding VAT, after the invoice discount is taken off.", "examples": [ 450 ] }, "vat": { "type": "number", "description": "Total VAT.", "examples": [ 90 ] }, "discount": { "type": "number", "description": "Discount on the whole invoice, as an amount excluding VAT: how much was taken off the invoice's value excluding VAT.\nLine discounts are not here; they are in `lines[].discount`. Zero when the invoice has no\ninvoice discount.", "examples": [ 0 ] }, "net_all": { "type": "number", "description": "Total excluding VAT in lek.", "examples": [ 44325 ] }, "gross_all": { "type": "number", "description": "Total including VAT in lek.", "examples": [ 53190 ] }, "vat_all": { "type": "number", "description": "VAT in lek.", "examples": [ 8865 ] }, "discount_all": { "type": "number", "description": "Invoice discount in lek.", "examples": [ 0 ] }, "local_currency": { "anyOf": [ { "description": "Present only on an invoice in a foreign currency.", "$ref": "#\/components\/schemas\/InvoiceLocalAmount" }, { "type": "null" } ] } }, "required": [ "currency", "exchange_rate", "gross", "net", "vat", "discount", "net_all", "gross_all", "vat_all", "discount_all", "local_currency" ], "title": "InvoiceAmount" }, "InvoiceBankAccount": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id of the bank account in fature.al.", "examples": [ 27 ] }, "bank_name": { "type": [ "string", "null" ], "description": "Bank name.", "examples": [ "Banka Komb\u00ebtare Tregtare" ] }, "iban": { "type": [ "string", "null" ], "description": "Account IBAN.", "examples": [ "AL47212110090000000235698741" ] }, "swift": { "type": [ "string", "null" ], "description": "The bank's SWIFT code.", "examples": [ "NCBAALTX" ] }, "currency": { "type": [ "string", "null" ], "description": "Account currency, ISO 4217.", "examples": [ "EUR" ] }, "notes": { "type": [ "string", "null" ], "description": "Free-form notes on the account.", "examples": [ "Llogaria n\u00eb euro" ] } }, "required": [ "id", "bank_name", "iban", "swift", "currency", "notes" ], "title": "InvoiceBankAccount" }, "InvoiceDetail": { "type": "object", "properties": { "id": { "type": "integer", "description": "The invoice's id in fature.al.", "examples": [ 40323 ] }, "number": { "type": [ "string", "null" ], "description": "Invoice number, such as `12\/2026`.", "examples": [ "12\/2026" ] }, "type": { "type": "string", "description": "Invoice type: `CASH`, `NONCASH` or `EINVOICE`.", "examples": [ "EINVOICE" ] }, "issue_date": { "type": "string", "description": "Issue date, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "due_date": { "type": "string", "description": "Payment due date, `YYYY-MM-DD`.", "examples": [ "2026-09-27" ] }, "delivery_date": { "type": "string", "description": "Delivery date, or the end of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "created_at": { "type": [ "string", "null" ], "description": "Creation date and time, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:15:00" ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "Start of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "client": { "description": "The invoice's buyer.", "$ref": "#\/components\/schemas\/InvoiceParty" }, "amount": { "description": "Invoice amounts, in its currency and in lek.", "$ref": "#\/components\/schemas\/InvoiceAmount" }, "payment": { "description": "How much of the invoice has been paid.", "$ref": "#\/components\/schemas\/InvoicePayment" }, "bank_account": { "anyOf": [ { "description": "The bank account printed on the invoice, or `null`.", "$ref": "#\/components\/schemas\/InvoiceBankAccount" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the invoice.", "examples": [ "Pagesa brenda 14 dit\u00ebve." ] }, "iic": { "type": [ "string", "null" ], "description": "Invoice identification code (IIC, NSLF in the law).", "examples": [ "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returned when it registered the invoice (FIC, NIVF in the law). `null` while the invoice is waiting for fiscalization.", "examples": [ "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91" ] }, "eic": { "type": [ "string", "null" ], "description": "Invoice code on the e-invoicing platform. Only on e-invoices.", "examples": [ "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65" ] }, "doc_type": { "type": [ "string", "null" ], "description": "Document type in UBL: `380` invoice, `381` credit note, `383` debit note. `null` on a regular fiscal invoice.", "examples": [ "380" ] }, "process": { "type": [ "string", "null" ], "description": "UBL profile: `P1` for a sale, `P9` for a correction. Set on e-invoices.", "examples": [ "P1" ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Self-invoicing type, when the invoice is a self-invoice.", "examples": [ "DOMESTIC" ] }, "reversed_at": { "type": [ "string", "null" ], "description": "When the invoice was canceled, `YYYY-MM-DD HH:MM:SS`, or `null`.", "examples": [ "2026-09-14 08:05:00" ] }, "reversed_by": { "type": [ "integer", "null" ], "description": "Id of the invoice this invoice cancels, or `null`.", "examples": [ 40311 ] }, "pdf_url": { "type": "string", "description": "URL to download the invoice PDF.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/print\/40323" ] }, "reverse_charge": { "type": "boolean", "description": "Reverse charge: the buyer declares the VAT.", "examples": [ false ] }, "periodic_invoice": { "type": "boolean", "description": "An invoice belonging to a recurring billing cycle.", "examples": [ false ] }, "payment_methods": { "type": "array", "description": "One element per payment method, with the amount settled by each. An invoice paid with a single method holds one element with the full amount.", "items": { "$ref": "#\/components\/schemas\/InvoicePaymentMethod" } }, "lines": { "type": "array", "description": "Invoice lines; loaded only when a single invoice is read.", "items": { "$ref": "#\/components\/schemas\/InvoiceLine" } } }, "required": [ "id", "number", "type", "issue_date", "due_date", "delivery_date", "created_at", "supply_start_date", "supply_end_date", "client", "amount", "payment", "bank_account", "notes", "iic", "fic", "eic", "doc_type", "process", "self_issue_type", "reversed_at", "reversed_by", "pdf_url", "reverse_charge", "periodic_invoice", "payment_methods", "lines" ], "title": "InvoiceDetail" }, "InvoiceIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "The invoice's id in fature.al. Store it next to your `internalId`.", "examples": [ 40323 ] }, "number": { "type": [ "string", "null" ], "description": "Invoice number, such as `12\/2026`.", "examples": [ "12\/2026" ] }, "iic": { "type": [ "string", "null" ], "description": "Invoice identification code, IIC (NSLF).", "examples": [ "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returns when it registers the invoice, FIC (NIVF). Null while the invoice is waiting for deferred fiscalization.", "examples": [ "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91" ] }, "tcrCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device that issued it; null on invoices not issued from a TCR.", "examples": [ "xb131xb131" ] }, "businessCode": { "type": [ "string", "null" ], "description": "Code of the business unit under which the invoice was issued.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "Code of the operator who issued the invoice.", "examples": [ "aa123aa123" ] }, "fiscalizedAt": { "type": "string", "description": "Invoice creation date and time, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:15:00" ] }, "verifyURL": { "type": [ "string", "null" ], "description": "The tax administration verification URL, the one the QR code opens.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/verify?iic=3C7E9A1F52B84D0E6A2C4F8B1D9E7A35&tin=L81306019C&crtd=2026-09-13T10:15:00+02:00&prc=53190.00" ] }, "pdf": { "type": "string", "description": "URL to download the document. On an e-invoice that already has an EIC, it points to the official PDF\nof the e-invoicing platform instead of the fature.al one.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/print\/40323" ] }, "eic": { "type": [ "string", "null" ], "description": "The e-invoice code on the e-invoicing platform, EIC. The key is present only on an\ne-invoice that already has one; on any other invoice it is missing entirely, it does not come back as null.", "examples": [ "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65" ] }, "payment_methods": { "type": "array", "description": "One element per payment method, with the amount settled by each. The same list that `GET \/invoice\/{id}\/details` returns.", "items": { "$ref": "#\/components\/schemas\/InvoicePaymentMethod" } } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic", "payment_methods" ], "title": "InvoiceIssueResult" }, "InvoiceLine": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the product or service.", "examples": [ "Or\u00eb pune mir\u00ebmbajtje" ] }, "product_code": { "type": [ "string", "null" ], "description": "Product code in fature.al, when the line belongs to a catalog product.", "examples": [ "SRV-MNT" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure.", "examples": [ "Or\u00eb" ] }, "unit_code": { "type": [ "string", "null" ], "description": "Unit of measure code, e.g. `C62`.", "examples": [ "HUR" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 2 ] }, "unitPrice": { "type": "number", "description": "Unit price including VAT, after the line discount is taken off.", "examples": [ 270 ] }, "vat_rate": { "type": [ "number", "null" ], "description": "VAT rate as a percentage.", "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Type of VAT exemption, when the line is exempt.", "examples": [ "TYPE_1" ] }, "margin_cost": { "type": [ "number", "null" ], "description": "The purchase cost of the whole line under the margin scheme; null on other lines.", "examples": [ 80 ] }, "discount_rate": { "type": [ "number", "null" ], "description": "Line discount as a percentage, as sent in `lines[].discount`; null when the line has no discount.", "examples": [ 10 ] }, "discount": { "type": [ "number", "null" ], "description": "Line discount amount, excluding VAT.", "examples": [ 50 ] }, "amount_net": { "type": "number", "description": "Line value excluding VAT.", "examples": [ 450 ] }, "amount_vat": { "type": "number", "description": "Line VAT.", "examples": [ 90 ] }, "total": { "type": "number", "description": "Line total including VAT.", "examples": [ 540 ] }, "vouchers_sold": { "anyOf": [ { "description": "The single-purpose vouchers the line sells; `null` for an ordinary line.", "$ref": "#\/components\/schemas\/InvoiceLineVouchersSold" }, { "type": "null" } ] } }, "required": [ "name", "product_code", "unit", "unit_code", "quantity", "unitPrice", "vat_rate", "vat_exempt_type", "margin_cost", "discount_rate", "discount", "amount_net", "amount_vat", "total", "vouchers_sold" ], "title": "InvoiceLine" }, "InvoiceLineVouchersSold": { "type": "object", "properties": { "purpose": { "type": "string", "description": "Which goods or services the voucher is for.", "examples": [ "veshje dhe k\u00ebpuc\u00eb" ] }, "expires_at": { "type": "string", "description": "The vouchers' expiry date, `YYYY-MM-DD`.", "examples": [ "2027-12-31" ] }, "nominal_value": { "type": "number", "description": "The nominal value of one voucher, in the invoice currency.", "examples": [ 1000 ] }, "numbers": { "type": "array", "description": "The serial numbers of the vouchers sold, in the form number-year-NIPT.", "examples": [ [ "12-2026-K51501011M", "13-2026-K51501011M" ] ], "items": {} } }, "required": [ "purpose", "expires_at", "nominal_value", "numbers" ], "title": "InvoiceLineVouchersSold" }, "InvoiceListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "The invoice's id in fature.al.", "examples": [ 40323 ] }, "number": { "type": [ "string", "null" ], "description": "Invoice number, such as `12\/2026`.", "examples": [ "12\/2026" ] }, "type": { "type": "string", "description": "Invoice type: `CASH`, `NONCASH` or `EINVOICE`.", "examples": [ "EINVOICE" ] }, "issue_date": { "type": "string", "description": "Issue date, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "due_date": { "type": "string", "description": "Payment due date, `YYYY-MM-DD`.", "examples": [ "2026-09-27" ] }, "delivery_date": { "type": "string", "description": "Delivery date, or the end of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "created_at": { "type": [ "string", "null" ], "description": "Creation date and time, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:15:00" ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "Start of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "client": { "description": "The invoice's buyer.", "$ref": "#\/components\/schemas\/InvoiceParty" }, "amount": { "description": "Invoice amounts, in its currency and in lek.", "$ref": "#\/components\/schemas\/InvoiceAmount" }, "payment": { "description": "How much of the invoice has been paid.", "$ref": "#\/components\/schemas\/InvoicePayment" }, "bank_account": { "anyOf": [ { "description": "The bank account printed on the invoice, or `null`.", "$ref": "#\/components\/schemas\/InvoiceBankAccount" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the invoice.", "examples": [ "Pagesa brenda 14 dit\u00ebve." ] }, "iic": { "type": [ "string", "null" ], "description": "Invoice identification code (IIC, NSLF in the law).", "examples": [ "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returned when it registered the invoice (FIC, NIVF in the law). `null` while the invoice is waiting for fiscalization.", "examples": [ "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91" ] }, "eic": { "type": [ "string", "null" ], "description": "Invoice code on the e-invoicing platform. Only on e-invoices.", "examples": [ "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65" ] }, "doc_type": { "type": [ "string", "null" ], "description": "Document type in UBL: `380` invoice, `381` credit note, `383` debit note. `null` on a regular fiscal invoice.", "examples": [ "380" ] }, "process": { "type": [ "string", "null" ], "description": "UBL profile: `P1` for a sale, `P9` for a correction. Set on e-invoices.", "examples": [ "P1" ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Self-invoicing type, when the invoice is a self-invoice.", "examples": [ "DOMESTIC" ] }, "reversed_at": { "type": [ "string", "null" ], "description": "When the invoice was canceled, `YYYY-MM-DD HH:MM:SS`, or `null`.", "examples": [ "2026-09-14 08:05:00" ] }, "reversed_by": { "type": [ "integer", "null" ], "description": "Id of the invoice this invoice cancels, or `null`.", "examples": [ 40311 ] }, "pdf_url": { "type": "string", "description": "URL to download the invoice PDF.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/print\/40323" ] }, "reverse_charge": { "type": "boolean", "description": "Reverse charge: the buyer declares the VAT.", "examples": [ false ] }, "periodic_invoice": { "type": "boolean", "description": "An invoice belonging to a recurring billing cycle.", "examples": [ false ] }, "payment_methods": { "type": "array", "description": "One element per payment method, with the amount settled by each. An invoice paid with a single method holds one element with the full amount.", "items": { "$ref": "#\/components\/schemas\/InvoicePaymentMethod" } } }, "required": [ "id", "number", "type", "issue_date", "due_date", "delivery_date", "created_at", "supply_start_date", "supply_end_date", "client", "amount", "payment", "bank_account", "notes", "iic", "fic", "eic", "doc_type", "process", "self_issue_type", "reversed_at", "reversed_by", "pdf_url", "reverse_charge", "periodic_invoice", "payment_methods" ], "title": "InvoiceListItem" }, "InvoiceListPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many invoices `items` holds on this page.", "examples": [ 10 ] }, "limit": { "type": "integer", "description": "The request's `limit` parameter, after rounding up to at least 1.", "examples": [ 10 ] }, "offset": { "type": "integer", "description": "The request's `offset` parameter, after rounding up to at least 0.", "examples": [ 0 ] }, "type": { "type": [ "string", "null" ], "description": "The `type` filter as sent, `null` when not sent.", "examples": [ "CASH,NONCASH" ] }, "query": { "type": [ "string", "null" ], "description": "The `query` filter as sent, `null` when not sent.", "examples": [ "K12345AB" ] } }, "required": [ "records", "limit", "offset", "type", "query" ], "title": "InvoiceListPagination" }, "InvoiceLocalAmount": { "type": "object", "properties": { "exchange_rate": { "type": "number", "description": "The exchange rate the amounts were converted with.", "examples": [ 98.5 ] }, "gross": { "type": "number", "description": "Total including VAT in lek.", "examples": [ 53190 ] }, "net": { "type": "number", "description": "Total excluding VAT in lek.", "examples": [ 44325 ] }, "vat": { "type": "number", "description": "VAT in lek.", "examples": [ 8865 ] }, "discount": { "type": "number", "description": "Invoice discount in lek, as an amount excluding VAT.", "examples": [ 0 ] } }, "required": [ "exchange_rate", "gross", "net", "vat", "discount" ], "title": "InvoiceLocalAmount" }, "InvoiceParty": { "type": "object", "properties": { "name": { "type": "string", "description": "The person's full name or the company name.", "examples": [ "Alba Trade shpk" ] }, "id": { "description": "The buyer's fiscal identifier.", "$ref": "#\/components\/schemas\/InvoicePartyId" }, "address": { "description": "The buyer's address.", "$ref": "#\/components\/schemas\/InvoiceAddress" } }, "required": [ "name", "id", "address" ], "title": "InvoiceParty" }, "InvoicePartyId": { "type": "object", "properties": { "type": { "type": [ "string", "null" ], "description": "Identifier type: `NUIS`, `VAT` or `TAX` for a business; `ID`, `PASS` or `SOC` for a person.", "examples": [ "NUIS" ] }, "id": { "type": [ "string", "null" ], "description": "Identifier value, e.g. the NIPT.", "examples": [ "K91807012A" ] } }, "required": [ "type", "id" ], "title": "InvoicePartyId" }, "InvoicePayment": { "type": "object", "properties": { "state": { "type": "string", "description": "`PAID`, `PARTIALLY_PAID` or `UNPAID`.", "examples": [ "PARTIALLY_PAID" ] }, "amount_paid": { "type": "number", "description": "Amount collected so far, in the invoice currency.", "examples": [ 300 ] }, "amount_left": { "type": "number", "description": "Total including VAT minus the amount collected, in the invoice currency.", "examples": [ 240 ] } }, "required": [ "state", "amount_paid", "amount_left" ], "title": "InvoicePayment" }, "InvoicePaymentMethod": { "type": "object", "properties": { "type": { "type": "string", "description": "Payment method, e.g. `BANKNOTE` or `CARD`.", "examples": [ "ACCOUNT" ] }, "amount": { "type": "number", "description": "Amount settled with this method, including VAT, in the invoice currency.", "examples": [ 540 ] }, "company_card": { "type": [ "string", "null" ], "description": "The company card number; filled in only when `type` is `COMPANY`, otherwise null.", "examples": [ null ] }, "vouchers": { "type": "array", "description": "Voucher serial numbers; filled in only when `type` is `SVOUCHER`, otherwise an empty list.", "examples": [ [] ], "items": { "type": "string" } } }, "required": [ "type", "amount", "company_card", "vouchers" ], "title": "InvoicePaymentMethod" }, "InvoicePrintAmounts": { "type": "object", "properties": { "net": { "type": "number", "description": "Total excluding VAT.", "examples": [ 450 ] }, "gross": { "type": "number", "description": "Total including VAT.", "examples": [ 540 ] }, "vat": { "type": "number", "description": "Total VAT.", "examples": [ 90 ] }, "discount": { "type": "number", "description": "Invoice discount, as an amount excluding VAT.", "examples": [ 0 ] }, "net_all": { "type": "number", "description": "Total excluding VAT in lek.", "examples": [ 44325 ] }, "gross_all": { "type": "number", "description": "Total including VAT in lek.", "examples": [ 53190 ] }, "vat_all": { "type": "number", "description": "VAT in lek.", "examples": [ 8865 ] }, "discount_all": { "type": "number", "description": "Invoice discount in lek.", "examples": [ 0 ] } }, "required": [ "net", "gross", "vat", "discount", "net_all", "gross_all", "vat_all", "discount_all" ], "title": "InvoicePrintAmounts" }, "InvoicePrintClient": { "type": "object", "properties": { "name": { "type": "string", "description": "The buyer's name.", "examples": [ "Alba Trade shpk" ] }, "id": { "description": "The buyer's fiscal identifier.", "$ref": "#\/components\/schemas\/InvoicePartyId" }, "addres": { "type": [ "string", "null" ], "description": "The buyer's street. The key really is spelled `addres`, with one s. It is a typo we cannot fix without\nbreaking every integration that already reads it.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "city": { "type": [ "string", "null" ], "description": "The buyer's city.", "examples": [ "Tiran\u00eb" ] }, "country": { "type": "string", "description": "Country code, ISO 3166-1 alpha-3; `ALB` when the buyer has none recorded.", "examples": [ "ALB" ] } }, "required": [ "name", "id", "addres", "city", "country" ], "title": "InvoicePrintClient" }, "InvoicePrintCompany": { "type": "object", "properties": { "name": { "type": "string", "description": "Company name as printed.", "examples": [ "Alfa Solutions shpk" ] }, "nuis": { "type": [ "string", "null" ], "description": "The seller's NIPT.", "examples": [ "L81306019C" ] }, "address": { "type": [ "string", "null" ], "description": "Address of the business unit that issued the invoice.", "examples": [ "Rruga Myslym Shyri 47, Tiran\u00eb" ] } }, "required": [ "name", "nuis", "address" ], "title": "InvoicePrintCompany" }, "InvoicePrintDocument": { "type": "object", "properties": { "logo": { "type": [ "string", "null" ], "description": "Company logo in base64; null when none is set.", "examples": [ "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" ] }, "title": { "type": "string", "description": "Document title in the account's language, e.g. \"Fatur\u00eb Tatimore\" (\"Tax Invoice\").", "examples": [ "Fatur\u00eb Tatimore" ] }, "company": { "description": "The seller.", "$ref": "#\/components\/schemas\/InvoicePrintCompany" }, "client": { "description": "The buyer.", "$ref": "#\/components\/schemas\/InvoicePrintClient" }, "transporter": { "description": "The carrier; every field of it is null when the invoice has no carrier.", "$ref": "#\/components\/schemas\/InvoicePrintTransporter" }, "invoice": { "description": "The invoice itself: lines, totals and fiscal codes.", "$ref": "#\/components\/schemas\/InvoicePrintInvoice" } }, "required": [ "logo", "title", "company", "client", "transporter", "invoice" ], "title": "InvoicePrintDocument" }, "InvoicePrintInvoice": { "type": "object", "properties": { "type": { "type": "string", "description": "Invoice type: `CASH`, `NONCASH` or `EINVOICE`.", "examples": [ "EINVOICE" ] }, "payment_method": { "type": [ "string", "null" ], "description": "Payment method, as a code.", "examples": [ "ACCOUNT" ] }, "payment_method_label": { "type": [ "string", "null" ], "description": "Payment method written out in the account's language, ready for printing.", "examples": [ "Transaksion nga llogaria - ACCOUNT" ] }, "bank_account": { "anyOf": [ { "description": "The bank account printed as a payment instruction, or `null`.", "$ref": "#\/components\/schemas\/InvoiceBankAccount" }, { "type": "null" } ] }, "issueDate": { "type": [ "string", "null" ], "description": "Issue date and time, `YYYY-MM-DD HH:MM:SS`.", "examples": [ "2026-09-13 10:15:00" ] }, "businessCode": { "type": [ "string", "null" ], "description": "Code of the business unit that issued the invoice.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "Code of the operator who issued the invoice.", "examples": [ "aa123aa123" ] }, "operatorName": { "type": [ "string", "null" ], "description": "The operator's shortened name, such as `Ana H.`, when known.", "examples": [ "Ana H." ] }, "deviceCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device.", "examples": [ "xb131xb131" ] }, "currency": { "type": [ "string", "null" ], "description": "Invoice currency; `null` when it is in lek.", "examples": [ "EUR" ] }, "exchangeRate": { "type": [ "number", "null" ], "description": "How many lek one unit of the currency is worth; `null` when the invoice is in lek.", "examples": [ 98.5 ] }, "number": { "type": [ "string", "null" ], "description": "Invoice number, such as `12\/2026`.", "examples": [ "12\/2026" ] }, "lines": { "type": "array", "description": "Invoice lines, in the order they are printed.", "items": { "$ref": "#\/components\/schemas\/InvoicePrintLine" } }, "amounts": { "description": "Invoice amounts, ready for printing.", "$ref": "#\/components\/schemas\/InvoicePrintAmounts" }, "iic": { "type": [ "string", "null" ], "description": "Invoice identification code (IIC, NSLF in the law).", "examples": [ "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returned (FIC, NIVF in the law); `null` while the invoice is waiting for fiscalization.", "examples": [ "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91" ] }, "eic": { "type": [ "string", "null" ], "description": "Invoice code on the e-invoicing platform. Only on e-invoices.", "examples": [ "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65" ] }, "process": { "type": [ "string", "null" ], "description": "UBL profile of the document, on e-invoices.", "examples": [ "P1" ] }, "doc_type": { "type": [ "string", "null" ], "description": "UBL document type, on e-invoices.", "examples": [ "380" ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the invoice.", "examples": [ "Pagesa brenda 14 dit\u00ebve." ] }, "verifyUrl": { "type": [ "string", "null" ], "description": "The tax administration verification URL, the one encoded as the QR code.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/verify?iic=3C7E9A1F52B84D0E6A2C4F8B1D9E7A35&tin=L81306019C&crtd=2026-09-13T10:15:00+02:00&prc=53190.00" ] }, "footer": { "type": "array", "description": "Lines printed below the total, already sorted.", "examples": [ [ "Faleminderit p\u00ebr besimin!", "fiskalizoi: fature.al", "---" ] ], "items": { "type": "string" } } }, "required": [ "type", "payment_method", "payment_method_label", "bank_account", "issueDate", "businessCode", "operatorCode", "operatorName", "deviceCode", "currency", "exchangeRate", "number", "lines", "amounts", "iic", "fic", "eic", "process", "doc_type", "notes", "verifyUrl", "footer" ], "title": "InvoicePrintInvoice" }, "InvoicePrintLine": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the product or service.", "examples": [ "Or\u00eb pune mir\u00ebmbajtje" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure.", "examples": [ "Or\u00eb" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 2 ] }, "unitPrice": { "type": "number", "description": "Unit price including VAT, after the line discount is taken off.", "examples": [ 270 ] }, "total": { "type": "number", "description": "Line total including VAT.", "examples": [ 540 ] } }, "required": [ "name", "unit", "quantity", "unitPrice", "total" ], "title": "InvoicePrintLine" }, "InvoicePrintTransporter": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Carrier name.", "examples": [ "Trans Alba shpk" ] }, "plate": { "type": [ "string", "null" ], "description": "Vehicle license plate.", "examples": [ "AA 123 BB" ] }, "address": { "type": [ "string", "null" ], "description": "Carrier address.", "examples": [ "Rruga e Durr\u00ebsit 5" ] }, "city": { "type": [ "string", "null" ], "description": "Carrier city.", "examples": [ "Durr\u00ebs" ] } }, "required": [ "name", "plate", "address", "city" ], "title": "InvoicePrintTransporter" }, "NonCashInvoiceRequest": { "type": "object", "description": "Non-cash invoice, in the v2 shape.\n\nEvery other field is exactly the same as in v1, and a test keeps it that way.\nOnly the payment changes: here it is always sent as a `payment_methods` list,\neven when the invoice is settled with a single method, so a new integration\nlearns one shape instead of two.\n\nNone of this invoice's payment methods carries a card or vouchers, so a list element holds only `type` and `amount`.\n\nThe rules are written out in full and not inherited from the v1 class, because\nthe documentation generator reads `rules()` as text and cannot get any field\nfrom a `parent::rules()` call. See V2RequestRulesParityTest.", "properties": { "internalId": { "type": "string", "description": "The invoice identifier in your system, unique within the company for the year; also serves as the\nidempotency key. Required.", "examples": [ "NONCASH-2026-000412" ] }, "client": { "type": "object", "description": "The buyer. Without it the invoice is issued to the walk-in customer. With `client.internal_id` a client saved in fature.al is used; otherwise `client.name` is required.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Id of a client saved in fature.al. When you send it, the buyer is taken from it and the other `client` fields are not read." }, "name": { "type": "string", "description": "The buyer's name. Required when you do not send `client.internal_id`.", "examples": [ "Alpha SHPK" ] }, "id": { "type": [ "object", "null" ], "description": "The buyer's identification document, as an object with `type` and `id`.", "properties": { "type": { "type": [ "string", "null" ], "description": "Document type: `NUIS` for an Albanian business, `VAT` or `TAX` for a foreign business,\n`ID`, `PASS` or `SOC` for a person. Defaults to `NUIS`.", "enum": [ "NUIS", "VAT", "TAX", "ID", "PASS", "SOC", null ], "examples": [ "NUIS" ] }, "id": { "type": [ "string", "null" ], "description": "Identification document number, e.g. the NIPT when `type` is `NUIS`.", "examples": [ "L62221018T" ] } } }, "address": { "type": [ "string", "null" ], "description": "The buyer's address; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "city": { "type": [ "string", "null" ], "description": "The buyer's city; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "country": { "type": "string", "description": "The buyer's country, ISO 3166-1 alpha-3 code, e.g. `ALB`, `RKS`, `ITA`. Defaults to `ALB`." } } }, "lines": { "type": "array", "description": "Invoice lines, at least one.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Name of the product or service.", "examples": [ "Kafe" ] }, "product_code": { "type": "string", "description": "Product code in your catalog.", "examples": [ "KAF-001" ] }, "unit": { "type": "string", "description": "Unit of measure, as human-readable text.", "examples": [ "cope" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 2 ] }, "price": { "type": "number", "description": "Unit price, including VAT.", "examples": [ 150 ] }, "total": { "type": "number", "description": "Line total, including VAT.", "examples": [ 300 ] }, "discount": { "type": [ "number", "null" ], "description": "Line discount, as a percentage of the unit price, from 0 to 100. Optional: without it,\nor with an empty value, the line goes through as you send it. `price` stays the full unit price, while `total` is sent already reduced: `price` times\n`quantity`, with the discount taken off. A `total` that does not match that figure rejects the\nrequest with `400`, and `errors` says which line and which value was expected.", "examples": [ 10 ], "minimum": 0, "maximum": 100 }, "vat": { "type": [ "integer", "null" ], "description": "VAT rate as a percentage: `0`, `6`, `10` or `20`. Validation allows it to be missing, but\nsend it on every line: without it the line has no VAT rate. When your business is not in the VAT scheme, the line is recorded with VAT `0` and\nexemption `TAX_FREE`, however you send this field; the request is not rejected.", "enum": [ "0", "6", "10", "20", null ], "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Type of VAT exemption, when the line is exempt: `TYPE_1`, `TYPE_2`,\n`EXPORT_OF_GOODS`, `TAX_FREE` or `MARGIN_SCHEME`. `MARGIN_SCHEME` is the margin scheme, for travel agencies: the line is sold at its full price with\nno VAT, and VAT is charged only on the margin. It is accepted only when the business has switched it\non in Settings and is VAT-registered; otherwise the request is refused. It requires `margin_cost`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", "MARGIN_SCHEME", null ], "examples": [ "EXPORT_OF_GOODS" ] }, "margin_cost": { "type": [ "number", "null" ], "description": "The purchase cost of the whole line (not per unit), in the invoice currency, for a line under the\nmargin scheme. Required when `vat_exempt_type` is `MARGIN_SCHEME`, not read on other lines. The\nmargin is `total` minus this cost and never goes below zero. The buyer never sees it: it is on\nneither the printed invoice nor the e-invoice.", "examples": [ 80 ], "minimum": 0 }, "vouchers_sold": { "type": [ "object", "null" ], "description": "The single-purpose vouchers this line sells, when the goods sold are the vouchers themselves: the\npurpose, the expiry date, the nominal value and the serial numbers. Sent to CIS as the line's `VS`\nelement. Optional: without it the line is an ordinary sale. It is not a voucher payment. An invoice paid with vouchers sends the numbers in\n`payment_methods[].vouchers`, inside the `SVOUCHER` entry.", "examples": [ { "purpose": "veshje dhe k\u00ebpuc\u00eb", "expires_at": "2027-12-31", "nominal_value": 1000, "numbers": [ "12-2026-K51501011M", "13-2026-K51501011M" ] } ], "properties": { "purpose": { "type": "string", "description": "Which goods or services the voucher is for. Required when the line carries `vouchers_sold`, up\nto 255 characters. Not sent to CIS: it builds the description required by Instruction 16\/2020\n(article 8, point 4), which appears under the item name on the printed invoice and in the\ne-invoice.", "examples": [ "veshje dhe k\u00ebpuc\u00eb" ], "maxLength": 255 }, "expires_at": { "type": "string", "format": "date", "description": "The vouchers' expiry date, `YYYY-MM-DD`. Required when the line carries `vouchers_sold`.", "examples": [ "2027-12-31" ] }, "nominal_value": { "type": "number", "description": "The nominal value of one voucher, in the invoice currency. Not negative. Required when the line\ncarries `vouchers_sold`.", "examples": [ 1000 ], "minimum": 0 }, "numbers": { "type": "array", "description": "The serial numbers of the vouchers sold, in the form number-year-NIPT, from 1 to 1000. A\nnumber is not repeated anywhere on the invoice.", "examples": [ [ "12-2026-K51501011M", "13-2026-K51501011M" ] ], "items": { "type": "string", "description": "One voucher sold, in the form number-year-NIPT.", "pattern": "^[1-9][0-9]{0,7}-[0-9]{4}-[a-zA-Z][0-9]{8}[a-zA-Z]$" }, "minItems": 1, "maxItems": 1000, "uniqueItems": true } } } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total" ] }, "minItems": 1 }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "How `invoice_discount_value` is read: `percent` as a percentage, `amount` as a fixed value including\nVAT. The discount applies to the whole invoice: lines are saved as you send them and only the\ntotal is reduced. Works only paired with `invoice_discount_value`. One without the other is silently ignored and\nthe invoice comes out with no discount.", "enum": [ "percent", "amount", null ], "examples": [ "percent" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "Discount value, read according to `invoice_discount_type`: a percentage up to 100 when the type\nis `percent`; a value including VAT in the invoice currency, up to the invoice total, when the type\nis `amount`. Zero leaves the invoice without a discount. The discount is spread over the VAT groups by each one's weight in the total, and the VAT\nis recomputed on the reduced value. The discount base is the sum of the lines; the `fee` stays\noutside it.", "examples": [ 10 ], "minimum": 0 }, "bank_account": { "type": [ "integer", "null" ], "description": "Id of a bank account saved in fature.al.", "examples": [ 42 ] }, "bank_account_iban": { "type": [ "string", "null" ], "description": "IBAN of an account saved in fature.al; the account is looked up by IBAN, instead of\n`bank_account`.", "examples": [ "AL35202111090000000001234567" ] }, "bankAccount": { "type": "object", "description": "The full bank account, when you do not have it in fature.al yet: `name`, `iban`, `currency`, `swift`, `holder`. Saved as an account of your company; an IBAN that already exists is reused.", "properties": { "name": { "type": [ "string", "null" ], "description": "Bank name.", "examples": [ "BKT" ] }, "iban": { "type": [ "string", "null" ], "description": "Account IBAN.", "examples": [ "AL35202111090000000001234567" ] }, "currency": { "type": [ "string", "null" ], "description": "Account currency, ISO 4217 code.", "examples": [ "ALL" ] }, "swift": { "type": [ "string", "null" ], "description": "The bank's SWIFT\/BIC code.", "examples": [ "NCBAALTX" ] }, "notes": { "type": [ "string", "null" ], "description": "Notes that accompany the account on the invoice." }, "holder": { "type": [ "string", "null" ], "description": "Account holder.", "examples": [ "Ei3 Software Solution shpk" ] } } }, "fee": { "type": "object", "description": "The fee, as an object with `fee_type` and `fee_amount`. Added on top of the lines and kept outside the discount.", "properties": { "fee_type": { "type": [ "string", "null" ], "description": "Fee type: `OTHER`, `COMMISSION`, `PACK` or `BOTTLE`.", "examples": [ "PACK" ] }, "fee_amount": { "type": [ "number", "null" ], "description": "Fee amount, in the invoice currency.", "examples": [ 50 ] } } }, "currency": { "type": [ "string", "null" ], "description": "Invoice currency, ISO 4217 code; defaults to `ALL`.", "examples": [ "ALL" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "How many lek one unit of the invoice currency is worth. Without it, or with a non-positive value, 1 is used. For\ncurrencies worth less than one lek, such as JPY or HUF, send a value below 1.", "examples": [ 100.5 ] }, "due_date": { "type": [ "string", "null" ], "description": "Payment due date, `YYYY-MM-DD`.", "examples": [ "2026-10-04" ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "Start of the supply period, `YYYY-MM-DD`, for invoices covering an interval.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-30" ] }, "reverse_charge": { "type": [ "boolean", "null" ], "description": "Reverse charge: VAT is declared by the buyer, not by the seller.", "examples": [ false ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the invoice.", "examples": [ "Faleminderit per blerjen" ] }, "periodic_invoice": { "type": [ "boolean", "null" ], "description": "Marks an invoice belonging to a recurring billing cycle.", "examples": [ false ] }, "self_issue_type": { "type": [ "string", "null" ], "description": "Self-invoicing: `DOMESTIC`, `ABROAD` or `OTHER`. When you send it, `client` is the seller and\nneeds its identification (`client.id`) together with the country. Without it the invoice is a regular one.", "enum": [ "DOMESTIC", "ABROAD", "OTHER", null ], "examples": [ "DOMESTIC" ] }, "doc_type": { "type": [ "string", "null" ], "description": "Document type: `380` sales invoice, `381` credit note, `383` debit note. Without it, or\nwith `380`, the invoice is a regular one. A note requires `original_invoice_iic`; the lines you\nsend are the correction lines, with positive values, and `doc_type` sets\nthe direction.", "examples": [ "381" ] }, "original_invoice_iic": { "type": [ "string", "null" ], "description": "The `iic` of the invoice this document corrects, the one the original invoice returned to you.\nRequired when `doc_type` is `381` or `383` and rejected with any other document\ntype. The original must be of the same type, fiscalized, not canceled and still\ncorrectable; to reverse a whole invoice use cancellation, not a credit note.", "examples": [ "8FE72E2ACD1C500A83F8C89B4E2E3E1D" ] }, "payment_method": { "type": "string", "description": "Not accepted in v2: the payment method is sent as an element of `payment_methods`." }, "payment_methods": { "type": "array", "description": "Payment methods, one element for each. Required even when the invoice is paid with a single method; the list then has one element. Up to 10 elements, the same method is not repeated, and the `amount` values must add up to the invoice total, with the discount already applied; otherwise the request is rejected with `400`. None of these methods carries a card or vouchers, so an element has only `type` and `amount`.", "examples": [ [ { "type": "TRANSFER", "amount": 1500 }, { "type": "COMPENSATION", "amount": 500 } ] ], "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The payment method of this element: `ACCOUNT`, `COMPENSATION`, `FACTORING`, `KIND`, `OTHER`, `TRANSFER` or `WAIVER`. Required.", "enum": [ "ACCOUNT", "COMPENSATION", "FACTORING", "KIND", "OTHER", "TRANSFER", "WAIVER" ], "examples": [ "TRANSFER" ] }, "amount": { "type": "number", "description": "The amount paid with this method, including VAT, in the invoice currency. Required. Accepts any value\nthe CIS accepts: including 0, for an invoice worth 0, and negative.", "examples": [ 1500 ] } }, "required": [ "type", "amount" ] }, "minItems": 1, "maxItems": 10, "uniqueItems": true } }, "required": [ "internalId", "lines", "payment_methods" ], "title": "NonCashInvoiceRequest" }, "OrderInvoice": { "type": "object", "properties": { "internalId": { "type": "string", "description": "The invoice identifier in your system; also serves as the idempotency key. Required.", "examples": [ "ORD-001" ] }, "client": { "type": "object", "description": "The buyer. Optional, as on the cash invoice: without it the order is issued to the walk-in customer.\nWith `client.internal_id` a client saved in fature.al is used; otherwise `client.name`\nbecomes required as soon as you send any other `client` field.", "properties": { "internal_id": { "type": [ "integer", "null" ], "description": "Id of a client saved in fature.al. When you send it, the buyer is taken from it and the other `client` fields are not read." }, "name": { "type": [ "string", "null" ], "description": "The buyer's name.", "examples": [ "Klient i rastit" ] }, "id": { "type": [ "object", "null" ], "description": "The buyer's identification document, as an object with `type` and `id`.", "properties": { "type": { "type": [ "string", "null" ], "description": "Document type: `NUIS` for an Albanian business, `VAT` or `TAX` for a foreign business, `ID`, `PASS` or `SOC` for a person. Defaults to `NUIS`." }, "id": { "type": [ "string", "null" ], "description": "Identification document number, e.g. the NIPT when `type` is `NUIS`.", "examples": [ "L62221018T" ] } } }, "address": { "type": [ "string", "null" ], "description": "The buyer's address; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "city": { "type": [ "string", "null" ], "description": "The buyer's city; sent to the CIS. A named client requires it, either in this request or saved earlier on the client in fature.al." }, "country": { "type": [ "string", "null" ], "description": "The buyer's country, ISO 3166-1 alpha-3 code, e.g. `ALB`, `RKS`, `ITA`. Defaults to `ALB`." } } }, "lines": { "type": "array", "description": "The order lines, at least one, with the same fields as on the cash invoice.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "Name of the product or service.", "examples": [ "Kafe" ] }, "product_code": { "type": "string", "description": "Product code in your catalog.", "examples": [ "KAF-001" ] }, "unit": { "type": "string", "description": "Unit of measure, as human-readable text.", "examples": [ "cope" ] }, "quantity": { "type": "number", "description": "Quantity." }, "price": { "type": "number", "description": "Unit price, including VAT." }, "total": { "type": "number", "description": "Line total, including VAT." }, "discount": { "type": [ "number", "null" ], "description": "The line discount, as a percentage of the unit price, from 0 to 100. Optional:\nwithout it, or with an empty value, the line goes through as you send it. `price` stays the full unit price, while `total` is sent already reduced: `price`\ntimes `quantity`, with the discount removed. A `total` that does not match that figure\nrejects the request with `400`, and `errors` says which line and which value was expected.", "examples": [ 10 ], "minimum": 0, "maximum": 100 }, "vat": { "type": "integer", "description": "The VAT rate as a percentage, as on the cash invoice: `0`, `6`, `10` or `20`. Required. When your business is not in the VAT scheme, the line is recorded with VAT `0` and\nexemption `TAX_FREE`, however you send this field; the request is not rejected.", "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "Type of VAT exemption, when the line is exempt: `TYPE_1`, `TYPE_2`, `EXPORT_OF_GOODS` or `TAX_FREE`." } }, "required": [ "product_name", "product_code", "unit", "quantity", "price", "total", "vat" ] }, "minItems": 1 }, "currency": { "type": [ "string", "null" ], "description": "The order currency, an ISO 4217 code; defaults to ALL.", "examples": [ "ALL" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "How many lek one unit of the order currency is worth. Defaults to 1.", "examples": [ 100.5 ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "The start of the supply period, `YYYY-MM-DD`, for orders that cover an interval.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-30" ] }, "notes": { "type": [ "string", "null" ], "description": "Notes shown on the order, e.g. the table.", "examples": [ "Tavolina 4" ] } }, "required": [ "internalId", "lines" ], "title": "OrderInvoice" }, "OrderInvoiceIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "The invoice's id in fature.al. Store it next to your `internalId`.", "examples": [ 40323 ] }, "number": { "type": [ "string", "null" ], "description": "Invoice number, such as `12\/2026`.", "examples": [ "12\/2026" ] }, "iic": { "type": [ "string", "null" ], "description": "Invoice identification code, IIC (NSLF).", "examples": [ "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returns when it registers the invoice, FIC (NIVF). Null while the invoice is waiting for deferred fiscalization.", "examples": [ "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91" ] }, "tcrCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device that issued it; null on invoices not issued from a TCR.", "examples": [ "xb131xb131" ] }, "businessCode": { "type": [ "string", "null" ], "description": "Code of the business unit under which the invoice was issued.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "Code of the operator who issued the invoice.", "examples": [ "aa123aa123" ] }, "fiscalizedAt": { "type": "string", "description": "Invoice creation date and time, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:15:00" ] }, "verifyURL": { "type": [ "string", "null" ], "description": "The tax administration verification URL, the one the QR code opens.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/verify?iic=3C7E9A1F52B84D0E6A2C4F8B1D9E7A35&tin=L81306019C&crtd=2026-09-13T10:15:00+02:00&prc=53190.00" ] }, "pdf": { "type": "string", "description": "URL to download the document. On an e-invoice that already has an EIC, it points to the official PDF\nof the e-invoicing platform instead of the fature.al one.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/print\/40323" ] }, "eic": { "type": [ "string", "null" ], "description": "The e-invoice code on the e-invoicing platform, EIC. The key is present only on an\ne-invoice that already has one; on any other invoice it is missing entirely, it does not come back as null.", "examples": [ "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65" ] }, "payment_methods": { "type": "array", "description": "One element per payment method, with the amount settled by each. The same list that `GET \/invoice\/{id}\/details` returns.", "items": { "$ref": "#\/components\/schemas\/InvoicePaymentMethod" } }, "isOrderInvoice": { "type": "boolean", "description": "Always true; the key marks the invoice as an order.", "examples": [ true ] }, "summaryInvoiceId": { "type": [ "integer", "null" ], "description": "The id of the summary invoice that closed this order. The key appears only after the order\nhas been closed, so a newly issued order does not carry it.", "examples": [ 40330 ] } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic", "payment_methods", "isOrderInvoice", "summaryInvoiceId" ], "title": "OrderInvoiceIssueResult" }, "PurchaseInvoiceCurrency": { "type": "object", "properties": { "code": { "type": "string", "description": "The ISO 4217 code of the invoice currency.", "examples": [ "EUR" ] }, "exchangeRate": { "type": "number", "description": "How many lek one unit of the currency is worth. Invoice amounts come in lek; divided by this rate\nthey give the amount in the invoice currency.", "examples": [ 100.5 ] } }, "required": [ "code", "exchangeRate" ], "title": "PurchaseInvoiceCurrency" }, "PurchaseInvoiceItem": { "type": "object", "properties": { "iic": { "type": "string", "description": "The invoice identification code, IIC (NSLF), 32 hex digits. The invoice can be found again with it.", "examples": [ "0F1E2D3C4B5A69788796A5B4C3D2E1F0" ] }, "fic": { "type": "string", "description": "The code the CIS returned when it registered the invoice, FIC (NIVF). Also serves as the list's `fic`\nfilter.", "examples": [ "8a941d47-7d47-4b7e-8f3a-1c2d3e4f5a6b" ] }, "invoiceNumber": { "type": "string", "description": "The invoice number as the supplier issued it: the sequence number and year on a non-cash invoice, such as\n`152\/2026`; with the TCR code at the end on a cash invoice, such as `152\/2026\/cc123cc123`.", "examples": [ "152\/2026" ] }, "invoiceOrderNumber": { "type": "integer", "description": "The invoice sequence number in the supplier's series.", "examples": [ 152 ] }, "dateTimeCreated": { "type": "string", "description": "The invoice issue date and time, as the CIS returns it: an ISO 8601 date-time with the time zone.", "examples": [ "2026-07-01T10:15:23+02:00" ] }, "payDeadline": { "type": [ "string", "null" ], "description": "The payment due date, as the CIS returns it; `null` when the invoice has no due date.", "examples": [ "2026-07-31T00:00:00+02:00" ] }, "invoiceType": { "type": "string", "description": "The invoice type: `CASH` or `NONCASH`.", "examples": [ "NONCASH" ] }, "issuerTaxNumber": { "type": "string", "description": "The issuer's NIPT, the same as `seller.idNum`.", "examples": [ "K71828301A" ] }, "seller": { "description": "The supplier that issued the invoice.", "$ref": "#\/components\/schemas\/PurchaseInvoiceParty" }, "buyer": { "description": "The buyer, that is, your company.", "$ref": "#\/components\/schemas\/PurchaseInvoiceParty" }, "items": { "type": "array", "description": "The invoice lines.", "items": { "$ref": "#\/components\/schemas\/PurchaseInvoiceLine" } }, "paymentMethod": { "type": "array", "description": "The payment methods: one element on an invoice paid with a single method, one for each\npart of a split payment.", "items": { "$ref": "#\/components\/schemas\/PurchaseInvoicePaymentMethod" } }, "currency": { "anyOf": [ { "description": "The invoice currency and rate; `null` when the invoice is in lek.", "$ref": "#\/components\/schemas\/PurchaseInvoiceCurrency" }, { "type": "null" } ] }, "totalPrice": { "type": "number", "description": "The invoice total including VAT, in lek.", "examples": [ 12000 ] }, "totalPriceWithoutVAT": { "type": "number", "description": "The invoice total excluding VAT, in lek.", "examples": [ 10000 ] }, "reverseCharge": { "type": "boolean", "description": "Reverse charge: the buyer declares the VAT.", "examples": [ false ] }, "businessUnit": { "type": [ "string", "null" ], "description": "The code of the supplier's business unit the invoice was issued from.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "The code of the supplier's operator who issued the invoice.", "examples": [ "oo123oo123" ] }, "tcrCode": { "type": [ "string", "null" ], "description": "The TCR code of the supplier's fiscal device; `null` on invoices not issued from a TCR.", "examples": [ "cc123cc123" ] }, "softwareCode": { "type": [ "string", "null" ], "description": "The code of the software the supplier issued the invoice with.", "examples": [ "ss123ss123" ] }, "iicSignature": { "type": [ "string", "null" ], "description": "The IIC signature with the supplier's certificate, in hex.", "examples": [ "3a5f9c1e7b2d4680a1c3e5f7092b4d6e8f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f6" ] } }, "required": [ "iic", "fic", "invoiceNumber", "invoiceOrderNumber", "dateTimeCreated", "payDeadline", "invoiceType", "issuerTaxNumber", "seller", "buyer", "items", "paymentMethod", "currency", "totalPrice", "totalPriceWithoutVAT", "reverseCharge", "businessUnit", "operatorCode", "tcrCode", "softwareCode", "iicSignature" ], "title": "PurchaseInvoiceItem" }, "PurchaseInvoiceLine": { "type": "object", "properties": { "name": { "type": "string", "description": "The product or service name, as the supplier wrote it.", "examples": [ "Kafe e pjekur 1kg" ] }, "code": { "type": [ "string", "null" ], "description": "The product code at the supplier; `null` when they sent no code.", "examples": [ "K1" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure; `null` when missing.", "examples": [ "kg" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 100 ] }, "unitPriceAfterVat": { "type": "number", "description": "The unit price including VAT, in lek.", "examples": [ 120 ] }, "priceAfterVat": { "type": "number", "description": "The line value including VAT, in lek.", "examples": [ 12000 ] }, "vatAmount": { "type": "number", "description": "The line VAT, in lek.", "examples": [ 2000 ] }, "vatRate": { "type": [ "number", "null" ], "description": "The VAT rate as a percentage; `null` when the line carries no rate, a case fature.al reads as\n0.", "examples": [ 20 ] }, "exemptFromVat": { "type": [ "string", "null" ], "description": "The VAT exemption type: `TYPE_1` (article 51 of the VAT law), `TYPE_2` (articles 53\nand 54), `EXPORT_OF_GOODS` export of goods, `TAX_FREE` zero rate. `null` when the line has\nVAT.", "examples": [ "TYPE_1" ] } }, "required": [ "name", "code", "unit", "quantity", "unitPriceAfterVat", "priceAfterVat", "vatAmount", "vatRate", "exemptFromVat" ], "title": "PurchaseInvoiceLine" }, "PurchaseInvoicePagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "The number of invoices the CIS finds for the whole period and filters, the same on every page. It\nis not the number of `items` on this page.", "examples": [ 12 ] }, "page": { "type": "integer", "description": "The request's `page` parameter, after rounding up to at least 1.", "examples": [ 1 ] }, "hasMore": { "type": "boolean", "description": "`true` when this page held invoices and the CIS has more for the period: request `page + 1`.\n`false` means the list is finished. The CIS does not report its page size, so the last page\nmay say `true` and the one after it come back empty with `false`.", "examples": [ true ] } }, "required": [ "records", "page", "hasMore" ], "title": "PurchaseInvoicePagination" }, "PurchaseInvoiceParty": { "type": "object", "properties": { "idType": { "type": "string", "description": "The identifier type: `NUIS`, `VAT` or `TAX` for a business; `ID`, `PASS` or `SOC` for a\nperson.", "examples": [ "NUIS" ] }, "idNum": { "type": "string", "description": "Identifier value, e.g. the NIPT.", "examples": [ "K71828301A" ] }, "name": { "type": "string", "description": "The name of the business or person.", "examples": [ "Furnizimi Alba SHPK" ] }, "address": { "type": [ "string", "null" ], "description": "The address, as the CIS holds it; `null` when missing.", "examples": [ "Rruga e Durr\u00ebsit 5" ] }, "town": { "type": [ "string", "null" ], "description": "The city; `null` when missing.", "examples": [ "Tiran\u00eb" ] }, "country": { "type": [ "string", "null" ], "description": "The three-letter country code, such as `ALB`; `null` when missing.", "examples": [ "ALB" ] } }, "required": [ "idType", "idNum", "name", "address", "town", "country" ], "title": "PurchaseInvoiceParty" }, "PurchaseInvoicePaymentMethod": { "type": "object", "properties": { "typeCode": { "type": "string", "description": "The payment method: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` or `ORDER` on a\ncash invoice; `ACCOUNT`, `TRANSFER`, `COMPENSATION`, `FACTORING`, `KIND`, `WAIVER` or\n`OTHER` on a non-cash invoice.", "examples": [ "ACCOUNT" ] }, "compCard": { "type": [ "string", "null" ], "description": "The company card number when `typeCode` is `COMPANY`. On bank payments, invoicing software,\nfature.al included, puts the account IBAN here. `null` when missing.", "examples": [ "AL47212110090000000235698741" ] } }, "required": [ "typeCode", "compCard" ], "title": "PurchaseInvoicePaymentMethod" }, "SettledOrderInvoice": { "type": "object", "properties": { "id": { "type": "integer", "description": "The order id in fature.al.", "examples": [ 40298 ] }, "number": { "type": [ "string", "null" ], "description": "The order invoice number.", "examples": [ "9\/2026" ] }, "date": { "type": "string", "description": "When the order was issued, `YYYY-MM-DD HH:MM:SS`.", "examples": [ "2026-09-12 18:20:00" ] }, "amountGross": { "type": "number", "description": "The order total including VAT, in its currency.", "examples": [ 540 ] }, "currency": { "type": [ "string", "null" ], "description": "The order currency, ISO 4217.", "examples": [ "EUR" ] } }, "required": [ "id", "number", "date", "amountGross", "currency" ], "title": "SettledOrderInvoice" }, "SummaryInvoice": { "type": "object", "description": "Summary invoice, in the v2 shape.\n\nEvery other field is exactly the same as in v1, and a test keeps it that way.\nOnly the payment changes: here it is always sent as a `payment_methods` list,\neven when the invoice is settled with a single method, so a new integration\nlearns one shape instead of two.\n\nOnly `BANKNOTE` and `CARD` are allowed, as in v1.\n\nThe rules are written out in full and not inherited from the v1 class, because\nthe documentation generator reads `rules()` as text and cannot get any field\nfrom a `parent::rules()` call. See V2RequestRulesParityTest.", "properties": { "internalId": { "type": "string", "description": "The invoice identifier in your system; also serves as the idempotency key. Required.", "examples": [ "SUMMARY-2026-000021" ] }, "order_invoices": { "type": "array", "description": "The IICs of the order invoices being closed, at least one. The summary invoice's lines\nare taken from these orders, so they are not sent in the request.", "examples": [ [ "8FE72E2ACD1C500A83F8C89B4E2E3E1D" ] ], "items": { "type": "string", "description": "The IIC of an order invoice being closed.", "examples": [ "8FE72E2ACD1C500A83F8C89B4E2E3E1D" ] }, "minItems": 1 }, "currency": { "type": [ "string", "null" ], "description": "The invoice currency, an ISO 4217 code; defaults to ALL.", "examples": [ "ALL" ] }, "exchange_rate": { "type": [ "number", "null" ], "description": "How many lek one unit of the invoice currency is worth. Defaults to 1.", "examples": [ 100.5 ] }, "supply_start_date": { "type": [ "string", "null" ], "description": "Start of the supply period, `YYYY-MM-DD`, for invoices covering an interval.", "examples": [ "2026-09-01" ] }, "supply_end_date": { "type": [ "string", "null" ], "description": "End of the supply period, `YYYY-MM-DD`.", "examples": [ "2026-09-30" ] }, "invoice_discount_type": { "type": [ "string", "null" ], "description": "How `invoice_discount_value` is read: `percent` as a percentage, `amount` as a fixed value\nincluding VAT. The discount on the whole invoice is applied to the summary invoice, not to the orders, which\ndo not accept it; line discounts come along with the lines copied from\nthe orders. Works only paired with `invoice_discount_value`. Either one without the other is silently ignored\nand the invoice comes out without a discount.", "enum": [ "percent", "amount", null ], "examples": [ "percent" ] }, "invoice_discount_value": { "type": [ "number", "null" ], "description": "The discount value, read according to `invoice_discount_type`: a percentage up to 100 when\nthe type is `percent`; a value including VAT in the invoice currency, up to the total of the\nsummary invoice, when the type is `amount`. Zero leaves the invoice without a discount.", "examples": [ 10 ], "minimum": 0 }, "payment_method": { "type": "string", "description": "Payment method in the v1 shape. Not accepted in v2: send it as an element of `payment_methods`." }, "payment_methods": { "type": "array", "description": "List with one element per payment method, up to 10. A summary invoice paid with a single method sends a one-element list. The amounts must add up exactly to the summary invoice total, with the discount already applied, and the same method is not repeated.", "examples": [ [ { "type": "BANKNOTE", "amount": 1200 }, { "type": "CARD", "amount": 800 } ] ], "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The payment method of this element: `BANKNOTE` or `CARD`.", "enum": [ "BANKNOTE", "CARD" ], "examples": [ "BANKNOTE" ] }, "amount": { "type": "number", "description": "How much is paid with this method, including VAT, in the invoice currency. Accepts any value the CIS accepts: 0 too, for a summary invoice worth 0, and negative values.", "examples": [ 1200 ] } }, "required": [ "type", "amount" ] }, "minItems": 1, "maxItems": 10, "uniqueItems": true } }, "required": [ "internalId", "order_invoices", "payment_methods" ], "title": "SummaryInvoice" }, "SummaryInvoiceIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "The invoice's id in fature.al. Store it next to your `internalId`.", "examples": [ 40323 ] }, "number": { "type": [ "string", "null" ], "description": "Invoice number, such as `12\/2026`.", "examples": [ "12\/2026" ] }, "iic": { "type": [ "string", "null" ], "description": "Invoice identification code, IIC (NSLF).", "examples": [ "3C7E9A1F52B84D0E6A2C4F8B1D9E7A35" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returns when it registers the invoice, FIC (NIVF). Null while the invoice is waiting for deferred fiscalization.", "examples": [ "2f6c1e8a-9b3d-4c7e-a5f1-0d8b6e4c2a91" ] }, "tcrCode": { "type": [ "string", "null" ], "description": "TCR code of the fiscal device that issued it; null on invoices not issued from a TCR.", "examples": [ "xb131xb131" ] }, "businessCode": { "type": [ "string", "null" ], "description": "Code of the business unit under which the invoice was issued.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "Code of the operator who issued the invoice.", "examples": [ "aa123aa123" ] }, "fiscalizedAt": { "type": "string", "description": "Invoice creation date and time, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:15:00" ] }, "verifyURL": { "type": [ "string", "null" ], "description": "The tax administration verification URL, the one the QR code opens.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/verify?iic=3C7E9A1F52B84D0E6A2C4F8B1D9E7A35&tin=L81306019C&crtd=2026-09-13T10:15:00+02:00&prc=53190.00" ] }, "pdf": { "type": "string", "description": "URL to download the document. On an e-invoice that already has an EIC, it points to the official PDF\nof the e-invoicing platform instead of the fature.al one.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/print\/40323" ] }, "eic": { "type": [ "string", "null" ], "description": "The e-invoice code on the e-invoicing platform, EIC. The key is present only on an\ne-invoice that already has one; on any other invoice it is missing entirely, it does not come back as null.", "examples": [ "9b4e2d1c-6f7a-4b3c-8d2e-1f0a9c8b7d65" ] }, "payment_methods": { "type": "array", "description": "One element per payment method, with the amount settled by each. The same list that `GET \/invoice\/{id}\/details` returns.", "items": { "$ref": "#\/components\/schemas\/InvoicePaymentMethod" } }, "isSummaryInvoice": { "type": "boolean", "description": "Always true; the key marks the invoice as a summary invoice.", "examples": [ true ] }, "settledOrderInvoices": { "type": "array", "description": "The orders that were closed with this invoice.", "items": { "$ref": "#\/components\/schemas\/SettledOrderInvoice" } } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic", "payment_methods", "isSummaryInvoice", "settledOrderInvoices" ], "title": "SummaryInvoiceIssueResult" }, "WtnCarrier": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The carrier's name; the name of the token's user when not sent.", "examples": [ "Transport Alba SHPK" ] }, "id_type": { "type": [ "string", "null" ], "description": "The carrier's identifier type: `NUIS` for a business, `ID` for a person. `NUIS`\nwhen not sent.", "examples": [ "NUIS" ] }, "id_num": { "type": [ "string", "null" ], "description": "The carrier's NIPT or document number, according to `id_type`; the company's NIPT when not\nsent.", "examples": [ "L01234567A" ] }, "town": { "type": [ "string", "null" ], "description": "The carrier's city; the company's city when not sent.", "examples": [ "Tiran\u00eb" ] }, "address": { "type": [ "string", "null" ], "description": "The carrier's address; the business unit address when not sent.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "vehicle_ownership": { "type": [ "string", "null" ], "description": "The vehicle ownership: `OWNER` a company vehicle, `THIRDPARTY` a third-party\nvehicle.", "examples": [ "OWNER" ] }, "vehicle_plates": { "type": [ "string", "null" ], "description": "The vehicle plate number, in uppercase.", "examples": [ "AA123BB" ] } }, "required": [ "name", "id_type", "id_num", "town", "address", "vehicle_ownership", "vehicle_plates" ], "title": "WtnCarrier" }, "WtnFiscal": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "description": "`FISCALIZED` when the CIS has registered the note, `UNFISCALIZED` while it awaits\nfiscalization. An unfiscalized note is fiscalized again by fature.al.", "examples": [ "FISCALIZED" ] }, "iic": { "type": [ "string", "null" ], "description": "The note identification code (WTNIC, playing the role of the invoices' IIC), 32 hex digits.\nIt is computed by fature.al with the company's certificate before sending to the CIS, so it is\npresent even when the note awaits fiscalization.", "examples": [ "A1B2C3D4E5F60718293A4B5C6D7E8F90" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returned when it registered the note (FWTNIC, playing the role of the FIC); `null` while\nthe note awaits fiscalization.", "examples": [ "7f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f" ] }, "tcr_code": { "type": [ "string", "null" ], "description": "The TCR code of the token user's fiscal device at the moment of issue.", "examples": [ "cc123cc123" ] }, "business_code": { "type": [ "string", "null" ], "description": "The code of the business unit the note was issued under.", "examples": [ "bb123bb123" ] }, "operator_code": { "type": [ "string", "null" ], "description": "The code of the operator who issued the note.", "examples": [ "oo123oo123" ] }, "fiscalized_at": { "type": [ "string", "null" ], "description": "The date and time of fiscalization, `YYYY-MM-DD HH:MM:SS`, local time. `null` while the note awaits\nfiscalization. Notes fiscalized before September 28, 2026 carry `00:00:00`, because the column\nstored only the date.", "examples": [ "2026-09-13 10:30:00" ] }, "verify_url": { "type": [ "string", "null" ], "description": "The note's verification URL at the tax administration, the one the QR code opens; `null` when\nthe note has no `iic`.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/wtn?wtnic=A1B2C3D4E5F60718293A4B5C6D7E8F90&tin=L01234567A&crtd=2026-09-13T10:30:00+02:00&ord=3&bu=bb123bb123&sw=ss123ss123" ] } }, "required": [ "status", "iic", "fic", "tcr_code", "business_code", "operator_code", "fiscalized_at", "verify_url" ], "title": "WtnFiscal" }, "WtnInvoiceItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "The note id in fature.al; use it to read the details and the print data.", "examples": [ 403 ] }, "internalId": { "type": "string", "description": "The note's identifier in your system, the one you sent in `internalId` when it was issued.", "examples": [ "WTN-2026-000412" ] }, "number": { "type": [ "string", "null" ], "description": "The note number, such as `3\/2026`: the note's sequence number within the day for the business unit, and\nthe year.", "examples": [ "3\/2026" ] }, "type": { "type": [ "string", "null" ], "description": "The note type: `WTN` for goods moving without a sale, `SALE` for goods accompanying a sale.", "examples": [ "WTN" ] }, "transaction": { "type": [ "string", "null" ], "description": "The transaction type: `TRANSFER` goods transfer, `EXAMINATION` sent for examination or\ntrial, `SALES` sale, `DOOR` door-to-door sale.", "examples": [ "TRANSFER" ] }, "issue_date": { "type": [ "string", "null" ], "description": "The date and time of issue, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:30:00" ] }, "start_date": { "type": [ "string", "null" ], "description": "The date and time the goods departed, `YYYY-MM-DD HH:MM:SS`, local time; the moment of issue when not\nsent.", "examples": [ "2026-09-13 10:30:00" ] }, "destination_date": { "type": [ "string", "null" ], "description": "The date and time the goods arrived, `YYYY-MM-DD HH:MM:SS`, local time; the moment of issue when\nnot sent.", "examples": [ "2026-09-13 14:30:00" ] }, "origin": { "description": "The goods' starting point.", "$ref": "#\/components\/schemas\/WtnPoint" }, "destination": { "description": "The goods' destination point.", "$ref": "#\/components\/schemas\/WtnPoint" }, "carrier": { "description": "The carrier and the vehicle.", "$ref": "#\/components\/schemas\/WtnCarrier" }, "value_of_goods": { "type": "number", "description": "The value of the goods in transit, in lek, as sent in `valueOfGoods`.", "examples": [ 10000 ] }, "items_num": { "type": "integer", "description": "Sasia e mallit: shuma e `quantity` t\u00eb rreshtave, e rrumbullakosur lart n\u00eb num\u00ebr t\u00eb plot\u00eb (0,3 kg jep 1).", "examples": [ 5 ] }, "fiscal": { "description": "The note's fiscalization status and codes.", "$ref": "#\/components\/schemas\/WtnFiscal" }, "lines": { "type": "array", "description": "The goods lines, as sent in `invoice_lines`.", "items": { "$ref": "#\/components\/schemas\/WtnLine" } }, "print": { "type": "string", "description": "The URL of `GET \/invoice\/wtn\/print\/{id}`, this note's print data. It comes under the\nsame version that returned the note.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/wtn\/print\/403" ] } }, "required": [ "id", "internalId", "number", "type", "transaction", "issue_date", "start_date", "destination_date", "origin", "destination", "carrier", "value_of_goods", "items_num", "fiscal", "lines", "print" ], "title": "WtnInvoiceItem" }, "WtnInvoiceRequest": { "type": "object", "description": "Warehouse transfer note in the v2 shape.\n\nEvery other field is word for word the v1 one, and a test keeps it that way. Only `internalId` changes: here it is required, as on every other document issued through v2. With it, a retried request does not issue a second note, and the note is read by the integrator's number without keeping our id.\n\nThe rules are written out in full and not taken from the v1 class, because the documentation generator reads `rules()` as text: it cannot extract a single field from a `parent::rules()` call. See V2RequestRulesParityTest.", "properties": { "vehPlates": { "type": "string", "description": "The vehicle plate number. Required.", "examples": [ "AA123BB" ] }, "valueOfGoods": { "type": "number", "description": "The value of the goods in transit, in ALL. Required.", "examples": [ 10000 ] }, "invoice_lines": { "type": "array", "description": "The goods lines, at least one.", "items": { "type": "object", "properties": { "product_name": { "type": "string", "description": "The name or description of the goods.", "examples": [ "Kafe" ], "maxLength": 255 }, "product_code": { "type": "string", "description": "The goods code.", "examples": [ "K1" ], "maxLength": 50 }, "unit": { "type": "string", "description": "Unit of measure.", "examples": [ "cope" ], "maxLength": 50 }, "quantity": { "type": "number", "description": "The quantity, always greater than 0.", "examples": [ 5 ] } }, "required": [ "product_name", "product_code", "unit", "quantity" ] }, "minItems": 1 }, "internalId": { "type": "string", "description": "The note's identifier in your system, unique within the company for the year; also serves as the idempotency key. Required.", "examples": [ "WTN-2026-000412" ], "maxLength": 255 }, "type": { "type": [ "string", "null" ], "description": "The note type: `WTN` for goods moving without a sale, `SALE` for goods accompanying a\nsale. Defaults to `WTN`.", "enum": [ "WTN", "SALE", null ], "examples": [ "WTN" ] }, "transaction": { "type": [ "string", "null" ], "description": "The transaction type: `TRANSFER` goods transfer, `EXAMINATION` sent for\nexamination or trial, `SALES` sale, `DOOR` door-to-door sale. Defaults to\n`TRANSFER`.", "enum": [ "TRANSFER", "EXAMINATION", "SALES", "DOOR", null ], "examples": [ "TRANSFER" ] }, "vehOwnership": { "type": [ "string", "null" ], "description": "The vehicle ownership: `OWNER` a company vehicle, `THIRDPARTY` a third-party\nvehicle. Defaults to `OWNER`.", "enum": [ "OWNER", "THIRDPARTY", null ], "examples": [ "OWNER" ] }, "startPoint": { "type": [ "string", "null" ], "description": "The starting point, as a location type: `WAREHOUSE` warehouse, `STORE` store, `SALE` point\nof sale, `EXHIBITION` fair, `CUSTOMS` customs, `ANOTHER` another person's\nwarehouse, `OTHER` other. Defaults to `WAREHOUSE`.", "enum": [ "ANOTHER", "CUSTOMS", "EXHIBITION", "OTHER", "SALE", "STORE", "WAREHOUSE", null ], "examples": [ "WAREHOUSE" ] }, "destinPoint": { "type": [ "string", "null" ], "description": "The destination point, as a location type, with the same values as `startPoint`. Defaults to\n`STORE`.", "enum": [ "ANOTHER", "CUSTOMS", "EXHIBITION", "OTHER", "SALE", "STORE", "WAREHOUSE", null ], "examples": [ "STORE" ] }, "carrier_id_type": { "type": [ "string", "null" ], "description": "The carrier's identifier type: `NUIS` for a business, `ID` for a person.\nDefaults to `NUIS`.", "enum": [ "NUIS", "ID", null ], "examples": [ "NUIS" ] }, "startCity": { "type": [ "string", "null" ], "description": "The departure city. Defaults to the company's city.", "examples": [ "Tirane" ] }, "startAddr": { "type": [ "string", "null" ], "description": "The departure address. Defaults to the business unit address.", "examples": [ "Rruga X" ] }, "destinCity": { "type": [ "string", "null" ], "description": "The destination city. Defaults to the company's city.", "examples": [ "Durres" ] }, "destinAddr": { "type": [ "string", "null" ], "description": "The destination address. Defaults to the business unit address.", "examples": [ "Rruga Y" ] }, "carrier_id_num": { "type": [ "string", "null" ], "description": "The carrier's NIPT or document number, according to `carrier_id_type`. Defaults to\nthe company's NIPT.", "examples": [ "L01234567A" ] }, "carrier_name": { "type": [ "string", "null" ], "description": "The carrier's name. Defaults to the name of the token's user.", "examples": [ "Transport SHPK" ] }, "carrier_town": { "type": [ "string", "null" ], "description": "The carrier's city. Defaults to the company's city.", "examples": [ "Tirane" ] }, "carrier_address": { "type": [ "string", "null" ], "description": "The carrier's address. Defaults to the business unit address.", "examples": [ "Rruga Z" ] }, "startDateTime": { "type": [ "string", "null" ], "description": "The departure date and time, `YYYY-MM-DD HH:MM`. Defaults to the moment of issue.", "examples": [ "2025-01-15 10:30" ] }, "destinDateTime": { "type": [ "string", "null" ], "description": "The arrival date and time, `YYYY-MM-DD HH:MM`. Defaults to the moment of issue.", "examples": [ "2025-01-15 14:30" ] } }, "required": [ "vehPlates", "valueOfGoods", "invoice_lines", "internalId" ], "title": "WtnInvoiceRequest" }, "WtnIssueResult": { "type": "object", "properties": { "id": { "type": "integer", "description": "The note id in fature.al. Store it: use it to read the details and the print data.", "examples": [ 403 ] }, "internalId": { "type": "string", "description": "The note's identifier in your system, the one you sent in `internalId`.", "examples": [ "WTN-2026-000412" ] }, "number": { "type": [ "string", "null" ], "description": "The note number, such as `3\/2026`: the note's sequence number within the day for the business unit, and\nthe year.", "examples": [ "3\/2026" ] }, "iic": { "type": [ "string", "null" ], "description": "The note identification code (WTNIC, playing the role of the invoices' IIC), 32 hex digits.\nIt is computed by fature.al before sending to the CIS, so it is returned even when the note awaits fiscalization.", "examples": [ "A1B2C3D4E5F60718293A4B5C6D7E8F90" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returned when it registered the note (FWTNIC, playing the role of the FIC); `null` while\nthe note awaits fiscalization.", "examples": [ "7f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f" ] }, "tcrCode": { "type": [ "string", "null" ], "description": "The TCR code of the token user's fiscal device at the moment of issue.", "examples": [ "cc123cc123" ] }, "businessCode": { "type": [ "string", "null" ], "description": "The code of the business unit the note was issued under.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "The code of the operator who issued the note.", "examples": [ "oo123oo123" ] }, "fiscalStatus": { "type": [ "string", "null" ], "description": "`FISCALIZED` when the CIS registered the note, `UNFISCALIZED` when it was saved without being\nfiscalized.", "examples": [ "FISCALIZED" ] }, "fiscalizedAt": { "type": [ "string", "null" ], "description": "The date and time of fiscalization, `YYYY-MM-DD HH:MM:SS`, local time. `null` while the note awaits\nfiscalization. Notes fiscalized before September 28, 2026 carry `00:00:00`, because the column\nstored only the date.", "examples": [ "2026-09-13 10:30:00" ] }, "verifyURL": { "type": [ "string", "null" ], "description": "The note's verification URL at the tax administration, the one the QR code opens; `null` when\nthe note has no `iic`.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/wtn?wtnic=A1B2C3D4E5F60718293A4B5C6D7E8F90&tin=L01234567A&crtd=2026-09-13T10:30:00+02:00&ord=3&bu=bb123bb123&sw=ss123ss123" ] }, "print": { "type": "string", "description": "The URL of `GET \/invoice\/wtn\/print\/{id}`, the note's print data. It comes under the same\nversion that issued the note.", "examples": [ "https:\/\/fature.al\/api\/v1\/invoice\/wtn\/print\/403" ] } }, "required": [ "id", "internalId", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalStatus", "fiscalizedAt", "verifyURL", "print" ], "title": "WtnIssueResult" }, "WtnLine": { "type": "object", "properties": { "product_name": { "type": [ "string", "null" ], "description": "The name or description of the goods.", "examples": [ "Kafe e pjekur 1kg" ] }, "product_code": { "type": [ "string", "null" ], "description": "The goods code, as sent.", "examples": [ "K1" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure, as sent.", "examples": [ "cope" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 5 ] } }, "required": [ "product_name", "product_code", "unit", "quantity" ], "title": "WtnLine" }, "WtnListPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many notes `items` holds on this page.", "examples": [ 20 ] }, "limit": { "type": "integer", "description": "The request's `limit` parameter, after rounding up to at least 1.", "examples": [ 20 ] }, "offset": { "type": "integer", "description": "The request's `offset` parameter, after rounding up to at least 0.", "examples": [ 0 ] } }, "required": [ "records", "limit", "offset" ], "title": "WtnListPagination" }, "WtnPoint": { "type": "object", "properties": { "point": { "type": [ "string", "null" ], "description": "The location type: `WAREHOUSE` warehouse, `STORE` store, `SALE` point of sale, `EXHIBITION`\nfair, `CUSTOMS` customs, `ANOTHER` another person's warehouse, `OTHER` other. When nothing\nwas sent, the starting point carries `WAREHOUSE` and the destination `STORE`.", "examples": [ "WAREHOUSE" ] }, "city": { "type": [ "string", "null" ], "description": "The city; the company's city when not sent.", "examples": [ "Tiran\u00eb" ] }, "address": { "type": [ "string", "null" ], "description": "The address; the business unit address when not sent.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] } }, "required": [ "point", "city", "address" ], "title": "WtnPoint" }, "WtnPrintAmounts": { "type": "object", "properties": { "valueOfGoods": { "type": "number", "description": "The value of the goods in transit, in lek.", "examples": [ 10000 ] }, "currency": { "type": "string", "description": "The currency of the value; always `ALL`.", "examples": [ "ALL" ] }, "itemsNum": { "type": "integer", "description": "Sasia e mallit: shuma e `quantity` t\u00eb rreshtave, e rrumbullakosur lart n\u00eb num\u00ebr t\u00eb plot\u00eb (0,3 kg jep 1).", "examples": [ 5 ] } }, "required": [ "valueOfGoods", "currency", "itemsNum" ], "title": "WtnPrintAmounts" }, "WtnPrintCarrier": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Carrier name.", "examples": [ "Transport Alba SHPK" ] }, "idType": { "type": [ "string", "null" ], "description": "The carrier's identifier type: `NUIS` for a business, `ID` for a person.", "examples": [ "NUIS" ] }, "idNum": { "type": [ "string", "null" ], "description": "The carrier's NIPT or document number, according to `idType`.", "examples": [ "L01234567A" ] }, "town": { "type": [ "string", "null" ], "description": "Carrier city.", "examples": [ "Tiran\u00eb" ] }, "address": { "type": [ "string", "null" ], "description": "Carrier address.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "vehicleOwnership": { "type": [ "string", "null" ], "description": "The vehicle ownership: `OWNER` a company vehicle, `THIRDPARTY` a third-party\nvehicle.", "examples": [ "OWNER" ] }, "vehiclePlates": { "type": [ "string", "null" ], "description": "The vehicle plate number, in uppercase.", "examples": [ "AA123BB" ] } }, "required": [ "name", "idType", "idNum", "town", "address", "vehicleOwnership", "vehiclePlates" ], "title": "WtnPrintCarrier" }, "WtnPrintCompany": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name as printed: the company, or the unit that issued the note when the company has chosen this\nin its settings.", "examples": [ "Alba Trade SHPK" ] }, "nuis": { "type": [ "string", "null" ], "description": "The company's NIPT.", "examples": [ "L01234567A" ] }, "address": { "type": [ "string", "null" ], "description": "The address of the unit that issued the note; the company's address when the unit has none of its own.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] } }, "required": [ "name", "nuis", "address" ], "title": "WtnPrintCompany" }, "WtnPrintDocument": { "type": "object", "properties": { "logo": { "type": [ "string", "null" ], "description": "The company logo as the file content in base64, without the `data:` prefix; `null` when none\nhas been set.", "examples": [ "iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAYAAABw4pVUAAAA" ] }, "title": { "type": "string", "description": "The document title; always `Fatur\u00eb Shoq\u00ebruese` (\"warehouse transfer note\").", "examples": [ "Fatur\u00eb Shoq\u00ebruese" ] }, "company": { "description": "The issuer of the note.", "$ref": "#\/components\/schemas\/WtnPrintCompany" }, "carrier": { "description": "The carrier and the vehicle.", "$ref": "#\/components\/schemas\/WtnPrintCarrier" }, "origin": { "description": "The goods' starting point, with the date and time.", "$ref": "#\/components\/schemas\/WtnPrintPoint" }, "destination": { "description": "The goods' destination point, with the date and time.", "$ref": "#\/components\/schemas\/WtnPrintPoint" }, "invoice": { "description": "The note itself: the number, the fiscal codes, the lines and the value of the goods.", "$ref": "#\/components\/schemas\/WtnPrintInvoice" } }, "required": [ "logo", "title", "company", "carrier", "origin", "destination", "invoice" ], "title": "WtnPrintDocument" }, "WtnPrintInvoice": { "type": "object", "properties": { "issueDate": { "type": [ "string", "null" ], "description": "The date and time of issue, `YYYY-MM-DD HH:MM:SS`, local time.", "examples": [ "2026-09-13 10:30:00" ] }, "businessCode": { "type": [ "string", "null" ], "description": "The code of the business unit the note was issued under.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "The code of the operator who issued the note.", "examples": [ "oo123oo123" ] }, "deviceCode": { "type": [ "string", "null" ], "description": "The TCR code of the fiscal device of the user who issued the note.", "examples": [ "cc123cc123" ] }, "number": { "type": [ "string", "null" ], "description": "The note number, such as `3\/2026`: the note's sequence number within the day for the business unit, and\nthe year.", "examples": [ "3\/2026" ] }, "type": { "type": [ "string", "null" ], "description": "The note type: `WTN` for goods moving without a sale, `SALE` for goods accompanying a sale.", "examples": [ "WTN" ] }, "transaction": { "type": [ "string", "null" ], "description": "The transaction type: `TRANSFER` goods transfer, `EXAMINATION` sent for examination or\ntrial, `SALES` sale, `DOOR` door-to-door sale.", "examples": [ "TRANSFER" ] }, "lines": { "type": "array", "description": "The goods lines.", "items": { "$ref": "#\/components\/schemas\/WtnPrintLine" } }, "amounts": { "description": "The value and quantity of the goods, ready for printing.", "$ref": "#\/components\/schemas\/WtnPrintAmounts" }, "iic": { "type": [ "string", "null" ], "description": "The note identification code (WTNIC, playing the role of the invoices' IIC), 32 hex digits.", "examples": [ "A1B2C3D4E5F60718293A4B5C6D7E8F90" ] }, "fic": { "type": [ "string", "null" ], "description": "The code the CIS returned when it registered the note (FWTNIC, playing the role of the FIC); `null` while\nthe note awaits fiscalization.", "examples": [ "7f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f" ] }, "fiscalStatus": { "type": [ "string", "null" ], "description": "`FISCALIZED` when the CIS has registered the note, `UNFISCALIZED` while it awaits\nfiscalization.", "examples": [ "FISCALIZED" ] }, "verifyUrl": { "type": [ "string", "null" ], "description": "The note's verification URL at the tax administration, the one encoded as the QR; `null` when\nthe note has no `iic`.", "examples": [ "https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/wtn?wtnic=A1B2C3D4E5F60718293A4B5C6D7E8F90&tin=L01234567A&crtd=2026-09-13T10:30:00+02:00&ord=3&bu=bb123bb123&sw=ss123ss123" ] }, "footer": { "type": "array", "description": "The lines printed at the bottom of the document, already in order: the company's default invoice\nnote when one exists, then `fiskalizoi: fature.al` and `---`.", "examples": [ [ "fiskalizoi: fature.al", "---" ] ], "items": { "type": "string" } } }, "required": [ "issueDate", "businessCode", "operatorCode", "deviceCode", "number", "type", "transaction", "lines", "amounts", "iic", "fic", "fiscalStatus", "verifyUrl", "footer" ], "title": "WtnPrintInvoice" }, "WtnPrintLine": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The name or description of the goods.", "examples": [ "Kafe e pjekur 1kg" ] }, "code": { "type": [ "string", "null" ], "description": "The goods code.", "examples": [ "K1" ] }, "unit": { "type": [ "string", "null" ], "description": "Unit of measure.", "examples": [ "cope" ] }, "quantity": { "type": [ "number", "null" ], "description": "The quantity, as stored; `null` only on a line stored without a quantity.", "examples": [ 5 ] } }, "required": [ "name", "code", "unit", "quantity" ], "title": "WtnPrintLine" }, "WtnPrintPoint": { "type": "object", "properties": { "point": { "type": [ "string", "null" ], "description": "The location type: `WAREHOUSE` warehouse, `STORE` store, `SALE` point of sale, `EXHIBITION`\nfair, `CUSTOMS` customs, `ANOTHER` another person's warehouse, `OTHER` other. When nothing\nwas sent, the starting point carries `WAREHOUSE` and the destination `STORE`.", "examples": [ "WAREHOUSE" ] }, "city": { "type": [ "string", "null" ], "description": "The city; the company's city when not sent.", "examples": [ "Tiran\u00eb" ] }, "address": { "type": [ "string", "null" ], "description": "The address; the business unit address when not sent.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "dateTime": { "type": [ "string", "null" ], "description": "The departure or arrival date and time, `YYYY-MM-DD HH:MM:SS`, local time; the moment of issue\nwhen not sent.", "examples": [ "2026-09-13 10:30:00" ] } }, "required": [ "point", "city", "address", "dateTime" ], "title": "WtnPrintPoint" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }