{ "openapi": "3.1.0", "info": { "title": "fature.al API v2", "version": "2.0", "description": "# fature.al API v2\n\nVersion 2 covers three groups: **invoices**, **clients** and **warehouse transfer notes**. Only these\nchange shape from v1, so only these have a second address. Everything else (purchase invoices,\nproducts, cash register, reports and registration) stays on `v1` and is called from there even by\nan integration 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." }, "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\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": "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`." } ], "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": "A request with this `internalId` is still in progress. Wait a moment and retry, or read the state with `POST \/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": "A request with this `internalId` is still in progress. Wait a moment and retry, or read the state with `POST \/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\"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| 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`.", "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": "A request with this `internalId` is still in progress. Wait a moment and retry, or read the state with `POST \/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": "A request with this `internalId` is still in progress. Wait a moment and retry, or read the state with `POST \/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": "A request with this `internalId` is still in progress. Wait a moment and retry, or read the state with `POST \/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.", "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": { "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\/pdf": { "schema": { "type": "string", "format": "binary" } }, "application\/json": { "schema": { "$ref": "#\/components\/schemas\/InvoicePrintDocument" } }, "text\/html": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "The invoice was not found, or does not belong to your company.", "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\nCheck `Content-Type` before saving it as a PDF: an EIC that is not found returns the text\n`Document not found.` with status `200` and `text\/html`, not a PDF.", "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": { "200": { "description": "The e-invoice PDF. Check `Content-Type` before saving it: an EIC that is not found is still returned with status 200, but as `text\/html`.", "content": { "application\/pdf": { "schema": { "type": "string", "format": "binary" } }, "text\/html": { "schema": { "type": "string" } } }, "headers": { "Content-Disposition": { "schema": { "type": "string" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/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`.", "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}": { "post": { "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`.", "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 with `limit` and `offset`. `limit` is capped at `100`; a larger value is lowered without\n an error. `pagination` returns `total`, so continue with `offset += limit` until `offset`\n reaches `total`.\n- `query` searches by partial match on the company name, first name, last name, NIPT,\n document number, email, phone and client number.\n- A second request from the same token, while the first has not finished, is rejected immediately with\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": "Search in the company name, first name, last name, NIPT, document number, email, phone or client number.", "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" } } } } } } }, "\/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" } } } } } } } }, "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" }, "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\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`, `EXPORT_OF_GOODS` or `TAX_FREE`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", null ] } }, "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" }, "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` or `TAX_FREE`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", null ], "examples": [ "EXPORT_OF_GOODS" ] } }, "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" ] }, "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" ] }, "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 ] } }, "required": [ "name", "product_code", "unit", "unit_code", "quantity", "unitPrice", "vat_rate", "vat_exempt_type", "discount_rate", "discount", "amount_net", "amount_vat", "total" ], "title": "InvoiceLine" }, "InvoiceListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "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` or `TAX_FREE`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", null ], "examples": [ "EXPORT_OF_GOODS" ] } }, "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" }, "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": "The quantity of goods: the sum of the lines' `quantity`, as an integer.", "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": "The quantity of goods: the sum of the lines' `quantity`, as an integer.", "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" ] } } } } } } }