{ "openapi": "3.1.0", "info": { "title": "fature.al API", "version": "1.0", "description": "# fature.al API\n\nfature.al is the invoicing and fiscalization platform for businesses in Albania. With this API your system\nissues fiscalized invoices without dealing with certificates, XML signing, or SOAP yourself: send the\ninvoice as JSON and get back the document registered with the tax administration, with its fiscal\ncodes, the verification URL, and the PDF.\n\n## Who it is for\n\n- **Accounting and ERP software**, which issues the invoice where the sale happens.\n- **Online stores**, which turn a paid order into an invoice at the same moment.\n- **Point-of-sale, bar, and restaurant software**, with orders that are opened and closed with a single payment.\n- **Software providers**, who install the same software at many businesses, each with its own\n fiscal identity.\n\n## What you need before the first call\n\n| You need | Where to get it |\n| --- | --- |\n| A fature.al account, with a subscription that includes the modules you will use | `fature.al`, or `demo.fature.al` for sandbox |\n| An **API token** | In the fature.al dashboard, under **Settings > API tokens**. The token belongs to a user, not to the company |\n| The app's **client id** and **client secret**, if you are a software provider | From fature.al, when your integration is registered. See \"Identify your application\" |\n| The business's electronic certificate, uploaded to fature.al | The business gets it from e-Albania and uploads it once in the dashboard |\n| For cash invoices: a fiscal device (TCR) linked to the token's user | Configured by the business in the dashboard, or by you with the registration endpoints |\n\nThe first useful call is `GET \/account`: it tells you which business, business unit, and fiscal\ndevice you are working with.\n\n## Core concepts\n\n### Fiscalization in a few lines\n\nIn Albania every invoice is reported in real time to the tax administration, in the central\nfiscalization system (**CIS**). The system registers the invoice and returns its codes, which appear on\nthe document the buyer receives, together with a QR code that opens the verification page. When the CIS cannot be reached,\nthe invoice is issued anyway, stored, and fiscalized automatically as soon as the service is back. Invoices to\nbusinesses can also go to the central e-invoicing platform, which delivers the electronic\ndocument to the buyer.\n\nfature.al does all of this: it signs with the business's certificate, communicates with the CIS and with\nthe e-invoicing platform, keeps the numbering, stores the document, and retries fiscalization when the service does not\nrespond.\n\n### Who issues the invoice\n\n| Entity | What it is | Where it appears in the API |\n| --- | --- | --- |\n| **Company** | The business issuing the invoices, identified by its **NIPT** (the same code is also called **NUIS**) | The token belongs to one of its users |\n| **Business unit** | The place where the activity is carried out: the store, the office, the warehouse. It has a code issued by the tax administration, `businessUnitCode` | `businessCode` in the response |\n| **Operator** | The person issuing the invoice, with the operator code issued by the tax administration | `operatorCode` in the response |\n| **Fiscal device (TCR)** | The cash register registered with the tax administration, with its TCR code. Only cash invoices are issued from a TCR | `tcrCode` in the response |\n| **Certificate** | The business's electronic certificate, used to sign every request to the tax administration | Uploaded once; not sent in requests |\n\nThe user's token carries all of them: the company, business unit, operator, and TCR are selected from it.\nYou do not send them in any invoicing request.\n\n### Document types\n\n| Document | Endpoint | When to use it |\n| --- | --- | --- |\n| **Cash invoice** | `POST \/invoice\/cash` | Payment is made on the spot, at the till: cash, card, company card, vouchers |\n| **Non-cash invoice** | `POST \/invoice\/noncash` | Payment comes later, by transfer or on account |\n| **E-invoice** | `POST \/invoice\/e-invoice` | The buyer is a business and the invoice is delivered through the e-invoicing platform |\n| **Order invoice** | `POST \/invoice\/order` | Consumption has started, payment has not: a restaurant table |\n| **Summary invoice** | `POST \/invoice\/summary` | Closes one or more orders with a single payment |\n| **Bulk non-cash** | `POST \/invoice\/bulk-noncash` | Many non-cash invoices in one request, for periodic invoicing |\n| **Warehouse transfer note (WTN)** | `POST \/invoice\/wtn` | Goods moving without being sold; required by law |\n\nThe request body differs from one type to another more than it seems: the same invoice sent to\ntwo endpoints is rejected by one of them. Each endpoint states its own rules.\n\n### Corrections, advance payments and non-fiscal documents\n\n| Document | How it is issued |\n| --- | --- |\n| **Credit note** | `doc_type` `381` with `original_invoice_iic`, on `POST \/invoice\/noncash` or `POST \/invoice\/e-invoice` |\n| **Debit note** | `doc_type` `383` with `original_invoice_iic`, on the same endpoints |\n| **Corrective invoice** | `POST \/invoice\/cancel\/{id}`: a full cancellation for any invoice, a partial one for cash invoices only |\n| **Advance payment**, including a reservation or group deposit | A cash or non-cash invoice for the amount received, or an e-invoice with `doc_type` `386` and `process` `P4` |\n| **Proforma, information bill** | Not issued by the API: they are not fiscal documents and are not registered with the CIS |\n\nAn advance payment has no type of its own at the CIS, and the API does not link it to the final\ninvoice: no field deducts it from the invoice issued when the service is completed.\n\nCash, non-cash and e-invoices, and every document in this table, have a ready-to-send example in\nthe Postman collection [document-examples.json](\/docs\/api\/postman\/document-examples.json).\n\n### What you get back and what to store\n\nEvery issuance returns the same identifiers:\n\n| Field | What it is | Store it? |\n| --- | --- | --- |\n| `id` | The invoice id in fature.al | Yes, or work with your own `internalId` |\n| `number` | The invoice number, such as `12\/2026` | Yes; it is shown to the buyer |\n| `iic` | The invoice identification code, computed from the signature. By law it is called **NSLF** | Yes; it is the key for correction notes and summary invoices |\n| `fic` | The code the CIS returns when it registers the invoice. By law it is called **NIVF**. `null` while the invoice awaits fiscalization | Yes |\n| `eic` | The invoice code on the e-invoicing platform. E-invoices only | Yes, for e-invoices |\n| `verifyURL` | The verification page at the tax administration, the one the QR code opens | Yes, if you print yourself |\n| `pdf` | The URL of the finished document | As needed |\n\n`internalId` is the invoice number in your system. You send it with every issuance, and with it you can\nfind and cancel the invoice without keeping our `id`.\n\n### Glossary\n\n| Term | Meaning |\n| --- | --- |\n| **NIPT \/ NUIS** | Taxpayer identification number, such as `L62221018T`. Two names for the same code |\n| **CIS** | The tax administration's central fiscalization system, where every invoice is registered |\n| **IIC \/ NSLF** | The invoice identification code, 32 hexadecimal characters. The same code with two names |\n| **FIC \/ NIVF** | The code the CIS returns when it registers the invoice, a UUID. The same code with two names |\n| **EIC** | The e-invoice code on the central e-invoicing platform |\n| **TCR** | The fiscal device (cash register) registered with the tax administration, and its code |\n| **Business unit** | The place where the activity is carried out; it has the code `businessUnitCode` |\n| **Operator code** | The code of the person issuing the invoice, issued by the tax administration |\n| **Self-care** | The tax administration's portal where the business gets the business unit code and the operator code |\n| **e-Albania** | The government portal from which the business gets its electronic certificate |\n| **Cash register** | The working day on a TCR: opening balance, cash in and cash out, closing |\n| **Walk-in customer** | The anonymous buyer in a retail sale. A cash invoice without `client` is issued to them |\n| **Self-invoicing** | An invoice the buyer issues on behalf of the seller (`self_issue_type`) |\n| **Credit note, debit note** | A document that corrects an issued invoice by lowering or raising its value (`doc_type` `381` or `383`) |\n| **Warehouse transfer note (WTN)** | The document that accompanies goods in transit when there is no sale |\n| **UBL** | The e-invoice XML format; `process` and `doc_type` are fields of it |\n\n## Quick start\n\nThree calls take you from the token to your first fiscalized invoice. Work in sandbox,\n`https:\/\/demo.fature.al\/api\/v1`, where invoices have no fiscal value.\n\n**1. Test the token.** `GET \/ping` touches nothing:\n\n```bash\ncurl https:\/\/demo.fature.al\/api\/v1\/ping \\\n -H 'Authorization: Bearer YOUR_TOKEN'\n```\n\n```json\n{\"status\": true, \"data\": {\"pong\": 1788547330, \"ip\": [\"81.2.3.4\"]}}\n```\n\nA `401` means the token is not getting through: check that the header is named `Authorization` and that\nthe word `Bearer` comes before the token.\n\n**2. See who you are working as.** `GET \/account` returns the user, the company, the business unit, and\nthe fiscal device code, confirming that the token belongs to the right business.\n\n**3. Issue your first invoice.** A non-cash invoice is the simplest place to start, because it does not require\na fiscal device:\n\n```bash\ncurl -X POST https:\/\/demo.fature.al\/api\/v1\/invoice\/noncash \\\n -H 'Authorization: Bearer YOUR_TOKEN' \\\n -H 'Content-Type: application\/json' \\\n -d '{\n \"internalId\": \"TEST-0001\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\"name\": \"Klient Prov\u00eb\", \"address\": \"Rruga e Kavaj\u00ebs 12\", \"city\": \"Tiran\u00eb\"},\n \"lines\": [\n {\"product_name\": \"Sh\u00ebrbim\", \"product_code\": \"SRV-01\", \"unit\": \"cop\u00eb\", \"unit_code\": \"C62\",\n \"quantity\": 1, \"price\": 1000, \"total\": 1000, \"vat\": 20}\n ]\n }'\n```\n\n```json\n{\n \"status\": true,\n \"data\": {\n \"invoice\": {\n \"id\": 40312,\n \"number\": \"1\/2026\",\n \"iic\": \"8FE72E2ACD1C500A83F8C89B4E2E3E1D\",\n \"fic\": \"b3f1c0a2-4d5e-4f60-9a71-2c3d4e5f6071\",\n \"tcrCode\": null,\n \"businessCode\": \"bb123bb123\",\n \"operatorCode\": \"aa123aa123\",\n \"fiscalizedAt\": \"2026-09-13 10:42:07\",\n \"verifyURL\": \"https:\/\/efiskalizimi-app.tatime.gov.al\/invoice-check\/#\/verify?iic=...\",\n \"pdf\": \"https:\/\/demo.fature.al\/api\/v1\/invoice\/print\/40312\"\n }\n }\n}\n```\n\nThe invoice also appears immediately in the fature.al dashboard. Store `id`, `number`, `iic`, and `fic` alongside\nyour sale.\n\n## Authentication\n\nEvery request has two levels of identification: **who** makes it (the user, with a bearer token) and **which\nsoftware** makes it (your application, with a client id and client secret).\n\n```\nAuthorization: Bearer {api_token}\nX-Client-Id: ft_id_...\nX-Client-Secret: ft_sk_...\n```\n\nYou generate the token from **Settings > API tokens** in the fature.al dashboard, or get it from the\nresponse of `POST \/register`. It belongs to the business using your software and differs from one\nbusiness to the next.\n\nThe client id and client secret belong to **your application**, not to the business: they are the same for\nall businesses using your software. An integration written for a single business works\nwith the token alone. See \"Identify your application\" below.\n\nThe token grants full access to the account. Keep it on the server, not in browser code or in\npublic apps, do not commit it to version control, and regenerate it immediately if you\nsuspect it has leaked.\n\n## Servers and versions\n\nEvery path in this document is relative to the addresses below: `\/invoice\/cash` means\n`https:\/\/fature.al\/api\/v1\/invoice\/cash`.\n\n| Environment | URL |\n| --- | --- |\n| **Live** | `https:\/\/fature.al\/api\/v1` |\n| **Sandbox** | `https:\/\/demo.fature.al\/api\/v1` |\n\nAlways build against sandbox and switch to live by changing only the base address.\nRequests and responses are the same in both environments.\n\nThe version is part of the path. `v1` holds the entire API and is the version to build on.\n`v2` exists only for invoices and clients, with payment as a list and the client as separate objects,\nand is used alongside `v1`, not instead of it. No version is being retired. Within a version,\nchanges are additive only: an existing field does not change meaning and is not removed.\n\n| Document | What it covers | Address |\n| --- | --- | --- |\n| **v1** (this document) | The entire invoicing and registration API | [`\/docs\/api`](\/docs\/api) |\n| **v2** | Invoices with split payment and clients in the new format | [`\/docs\/api\/v2`](\/docs\/api\/v2) |\n| **Partner** | Wolt orders for a single business unit | [`\/docs\/api\/partner`](\/docs\/api\/partner) |\n\nEach document is also published as OpenAPI JSON (`\/docs\/api.json`) and as Markdown for AI assistants\n(`\/docs\/api.md`).\n\n## How to read a response\n\nEvery response is JSON. Read it in this order:\n\n1. **The HTTP code.**\n2. **On `200`, the `status` field.** `true`: the result is in `data`. `false`: the action was rejected,\n the reason is in `message` and, when there are details, in `errors`.\n3. **On `422`, the `success` field.** This is the validation response and the only one that uses `success`\n instead of `status`. There `errors` is an object keyed by field, with the full field name, such as\n `lines.0.quantity` or `client.id.type`.\n4. **On any other code**, `status: false` with `message` and `errors` (a list). The exceptions are `429`\n from the global limit and from cancellations, which return only `message`.\n\n```json\n{\"status\": true, \"data\": {\"...\": \"...\"}}\n```\n\n```json\n{\"status\": false, \"message\": \"P\u00ebrshkrimi i gabimit\", \"errors\": [\"Mesazhi p\u00ebr p\u00ebrdoruesin\"]}\n```\n\n```json\n{\"success\": false, \"message\": \"Te dhenat jo te sakta.\", \"errors\": {\"lines.0.quantity\": [\"...\"]}}\n```\n\n### HTTP codes\n\n| Code | Meaning | What to do |\n| --- | --- | --- |\n| `200` with `status: false` | The request was understood, but the action was rejected: user without a fiscal device, cash register without funds, NIPT already registered, rejection by the CIS | Read `message`. Do not retry without changing something |\n| `400` | Incomplete data for fiscalization, usually the buyer's address or city, or a `total` that does not match | `errors` says exactly what is missing. The invoice was not saved; retry with the same `internalId` |\n| `401` with `{\"message\": \"Unauthenticated.\"}` | The token is missing, wrong, or revoked | Check the `Authorization` header |\n| `401` with `status: false` | The module is not in the business's subscription: invoices, cash register, warehouse transfer notes, or purchase invoices | Regenerating the token does not help; the subscription must be extended |\n| `403` | The subscription has expired, or the action is not allowed for this account | |\n| `404` | The resource does not exist, or does not belong to your company | |\n| `409` | A request with this `internalId` is still in progress | Wait a moment; read it with `POST \/invoice\/details\/{internalId}` |\n| `422` | Validation failed | Fix the data. Do not retry the same request |\n| `429` | The rate limit was reached | Wait as long as `Retry-After` says, or one second when it is missing |\n| `500` | Unexpected error | Retry later with the same `internalId` |\n| `502` | The fiscalization service responded with an error (purchase invoices) | Retry later |\n| `503` | The fiscalization service could not be reached and the invoice **was not saved** | Retry with the same `internalId` |\n\n## internalId and idempotency\n\n`internalId` (string, required on every issuance) is the invoice identifier in your system:\nyour invoice number or a UUID. It must be unique within your company for the calendar year.\n\n- **It does not create duplicates.** When you send an `internalId` that already exists for this year, the server does not\n issue a second invoice: it returns the existing invoice with `200`, and if that invoice was awaiting fiscalization,\n it tries to complete it before returning it.\n- **That is why retrying is safe.** A timeout or interruption during issuance does not mean the\n invoice failed; it may have been saved. Retry with the **same** `internalId`, never with a new one.\n- **`409` means \"still in progress\".** If you retry while the first request has not finished (up\n to about 5 minutes), you get `409`. Wait a moment and retry, or read the state with\n `POST \/invoice\/details\/{internalId}`.\n- fature.al does not return `internalId` in the issuance response; keep the mapping between it and `id`,\n `number`, and `iic` yourself.\n\n## The buyer on the invoice\n\nThe `client` object has three flows:\n\n| Case | What you send | Result |\n| --- | --- | --- |\n| **Walk-in customer** | `client` is missing, or is `null` | The invoice is issued to the company's walk-in customer. Cash invoices only: a non-cash invoice without `client` is rejected with `422` |\n| **Client stored in fature.al** | Only `client.internal_id` | The client is taken as stored; other fields are not read |\n| **Client from your system** | `client.name` and the other details | The client is looked up by name and identifier. If it does not exist, it is created |\n\nIn the third flow:\n\n- `client.name` becomes required as soon as you send any other client detail.\n- `client.address` and `client.city` are needed for every named client, because they go to the CIS, which\n does not accept an invoice without them. It is enough for them to be stored on the client in fature.al; they do not need to\n be sent with every invoice. If you send only `client.address`, the stored city is not erased.\n- `client.country` is an ISO 3166-1 alpha-3 code, such as `ALB`, `RKS`, or `ITA`. Without it, `ALB` is used.\n- `client.id` identifies the buyer: `{\"type\": \"NUIS\", \"id\": \"L62221018T\"}` for Albanian businesses,\n `VAT` or `TAX` for foreign businesses, `ID`, `PASS`, or `SOC` for individuals. The NIPT is not verified\n with the tax administration during issuance; to verify it beforehand, use `GET \/client\/search`.\n\nWhen a required detail is missing, the request is rejected with `400` and `errors` says exactly what must be\nfilled in, e.g. `Klientit \"Kompani Prov\u00eb SHPK\" i mungon qyteti.` (\"the client is missing a city\"). Neither the invoice nor the client is saved;\nretry with the same `internalId` after filling them in.\n\n## Fiscalization when the tax administration does not respond\n\nWhen the CIS cannot be reached, the invoice is saved and issued anyway: the response comes back with `200`, `status: true`,\nand `fic: null`. fature.al retries fiscalization on its own every 15 minutes and fills in `fic` as soon as the CIS\nis back. Do not treat it as an error and do not issue it again; read it later with\n`POST \/invoice\/details\/{internalId}`.\n\nA `503` is the other case: the invoice **was not saved**. Retry with the same `internalId`.\n\n## Rate limits\n\nLimits are counted per token. When you exceed a limit, the response is `429 Too Many Requests`.\n\n### Limits that return 429 today\n\n| Limit | Value | Response body |\n| --- | --- | --- |\n| Global, every endpoint | 300 requests per minute per token; 120 per minute per IP without a token | `{\"message\": \"Too Many Attempts.\"}` with the `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` headers |\n| Cancellations, `POST \/invoice\/cancel\/*` | 30 per minute and 600 per hour | The same |\n| One request in progress at a time (see below) | For invoice issuance, a wait of up to 1 second; for clients, products, bank accounts, and warehouse transfer notes, immediate rejection | `{\"status\": false, \"errors\": [\"...\"]}`, without `Retry-After` |\n| The same queue, but with `200` | `GET \/products`, `GET \/product\/categories` | `200` with `status: false`. Read `status`, not just the code |\n\n### Budget per endpoint group\n\nThese are the values the API is sized for. Today some of them are only logged when\nexceeded, without rejection; build within them and handle `429`, because they will be enforced without notice.\n\n| Group | Budget | Endpoints |\n| --- | --- | --- |\n| Standard | 240 per minute | Every endpoint outside the groups below |\n| Fiscal | 30 per minute, 600 per hour | `POST \/invoice\/cash`, `\/invoice\/noncash`, `\/invoice\/e-invoice`, `\/invoice\/order`, `\/invoice\/summary`, `\/invoice\/wtn`, `\/invoice\/cancel\/*`, `GET \/purchase-invoices` |\n| Bulk | 3 per minute, 30 per hour | `POST \/invoice\/bulk-noncash` |\n| Printing | 30 per minute | `GET \/invoice\/print\/{id}`, `\/invoice\/print-eic\/{eic}`, `\/invoice\/wtn\/print\/{id}` |\n| Reports | 30 per minute | `GET \/reports\/*`, `GET \/dashboard\/summary` |\n| Search | 90 per minute | `GET \/client\/search` |\n| Registration | 30 per minute, 600 per hour | `POST \/register`, `POST \/on-boarding\/*` |\n\n### One request in progress at a time\n\nInvoice issuance is serialized, because the sequence number is MAX+1 per business and year, and for cash also\nper TCR. A second request to the same endpoint waits up to 1 second for the first one to finish;\nif it does not, it is rejected with `429`.\n\nClients, products, bank accounts, and warehouse transfer notes follow the same rule without waiting:\nas long as a request from your token to that endpoint has not finished, the second one is rejected\nimmediately. Sequential calls have no limit other than the budget.\n\n| Endpoints | Queue |\n| --- | --- |\n| `POST \/invoice\/cash`, `\/invoice\/order`, `\/invoice\/summary` | Per business and TCR, with waiting |\n| `POST \/invoice\/noncash`, `\/invoice\/e-invoice`, `\/invoice\/bulk-noncash` | Per business, with waiting |\n| `POST \/invoice\/cancel\/*` | The queue of the type of invoice being canceled, with waiting |\n| `GET \/invoice`, `GET \/invoice\/{id}\/details` | Per token, with waiting |\n| `GET`, `POST`, `PUT` on `\/clients`; `GET \/bank-accounts`; `GET`, `POST`, `PUT` on `\/products`; `GET \/product\/categories`; `GET` and `POST` on `\/invoice\/wtn` | Per token and endpoint, without waiting |\n\nThis is the limit multi-threaded integrations hit most often. The fix is not immediate\nretrying, but queuing requests per business: parallelism does not produce more invoices, only more\nwaiting.\n\n### Best practices\n\n- Wait as long as `Retry-After` says. When it is missing, wait one second and retry with progressive backoff:\n 1 s, 2 s, 4 s.\n- For many non-cash invoices, use `POST \/invoice\/bulk-noncash`: the budget counts requests, not invoices.\n- Cache the catalog, categories, and currencies, and do not read them in parallel from the same\n token.\n\n## Pagination\n\nNot all lists use the same pagination.\n\n| Endpoint | Parameters | `total` | `limit` cap |\n| --- | --- | --- | --- |\n| `GET \/invoice`, `GET \/invoice\/wtn`, `GET \/cash-register\/actions` | `limit`, `offset` | No | No cap |\n| `GET \/clients`, `GET \/bank-accounts` | `limit`, `offset` | Yes | 100 |\n| `GET \/products` | `limit`, `offset` | Yes | 500. Without `limit`, the entire catalog is returned |\n| `GET \/purchase-invoices` | `page`, from 1 | No | |\n\nWithout `limit`, `20` is used, and without `offset`, `0` is used, except for products. The counters come in the\n`pagination` object: `records` (how many came on this page), `total` (how many exist, where it is computed),\n`limit`, and `offset`. When there is no `total`, stop when a page comes back shorter than `limit`. For\npurchase invoices, repeat with `page + 1` until `items` comes back empty.\n\nLists are returned newest first. When reading a closed period, bound it with\n`fromDate` and `toDate` so that new invoices do not shift the pages.\n\nThe product list keeps `pagination` **alongside** `data`, not inside it, and `data` remains a plain\nlist: `data[0]` is a product, whereas in the other lists the items are in `data.items`.\n\n## Data formats\n\n| Data | Format |\n| --- | --- |\n| Dates | `YYYY-MM-DD` |\n| Date and time | `YYYY-MM-DD HH:MM:SS`, Albanian local time (CET\/CEST), without a time zone |\n| Amounts | JSON numbers, not strings, in the invoice currency. `*_all` fields are in lek |\n| Currency | ISO 4217 code. Without `currency`, `ALL` is used. `exchange_rate` is how many lek one unit of the currency is worth |\n| VAT rates | `0`, `6`, `10`, or `20`, as numbers |\n| Booleans | `true` or `false` in JSON |\n| NIPT | One letter, eight digits, one letter: `L62221018T` |\n| Country | ISO 3166-1 alpha-3: `ALB`, `RKS`, `ITA` |\n| Fiscal identifiers | `iic` 32 hexadecimal characters; `fic` and `eic` UUID |\n| Encoding | UTF-8. Send `Content-Type: application\/json` |\n\n### Unit of measure codes\n\n`unit_code`, on products and on e-invoice lines, accepts only the codes below (UN\/ECE Rec. 20,\nper the tax administration's list). The code is what is written on the fiscal document; the unit\ntext is derived from it and is not sent.\n\n| Group | Codes |\n| --- | --- |\n| Count | `C62` unit, `XPP` piece, `PR` pair, `DZN` dozen, `SET` set, `IE` person, `E55` use, `E54` trip, `QB` page, `D68` word, `H93` percent |\n| Weight | `KGM` kg, `58` net kg, `E4` gross kg, `GRM` g, `DTN` quintal, `TNE` tonne, `DT` dry ton |\n| Volume | `LTR` liter, `MLT` milliliter, `MTQ` m\u00b3 |\n| Length and area | `MTR` meter, `CMT` cm, `MMT` mm, `LM` linear meter, `KMT` km, `MTK` m\u00b2 |\n| Time | `SEC` second, `MIN` minute, `HUR` hour, `DAY` day, `MON` month, `ANN` year, `E49` working day, `OT` overtime hour |\n| Other | `KWH` kWh, `MSK` m\/s\u00b2, `M4` monetary value |\n| Packaging | `XBX` box, `XPK` pack, `XPX` pallet, `XRO` roll, `XBG` bag, `XBO` bottle, `XCT` carton, `XCR` crate, `XSA` sack, `XCA` can, `XBA` barrel |\n\n## Identify your application\n\nIf your software is used by more than one business, your application is identified by a pair of\ncredentials that you send with every request, alongside the user's token:\n\n```\nX-Client-Id: ft_id_a1b2c3d4e5f6g7h8i9j0k1l2\nX-Client-Secret: ft_sk_...\n```\n\n- The **client id** starts with `ft_id_` and is public. The **client secret** starts with `ft_sk_` and is\n secret: treat it like a password.\n- Both belong to your application, not to the business. They are not generated per business and must not\n end up in code that is distributed and can be read by others.\n- You get your first credentials from fature.al when your integration is registered. After that, you view and\n regenerate them yourself under **Settings > Developer** in your fature.al account, where you can also see how many\n users and how many businesses have worked through your application in the last 24 hours.\n\nThe secret is shown **only once**, at the moment it is generated, and cannot be read afterward.\nStore it immediately.\n\nIf you lose it or suspect it has leaked, regenerate it from the same screen. **Regeneration is\nimmediate, with no overlap period:** the old secret stops working on the first request that\narrives after it. So prepare your installations to pick up the new secret, and regenerate it only\nwhen you are ready to roll it out immediately. The client id does not change, so you only have to replace\na single value.\n\n### Keep sending the User-Agent header too\n\nIn addition to the credentials, send the `User-Agent` header with every request in the format\n`\/`:\n\n```\nUser-Agent: YourAppName\/2.4.1\n```\n\n- The **application name** must always be the same: on every request, for every business, and in\n every version of the application. This name is your integration's identifier, so do not change it\n and do not vary it by company, device, or environment. Use letters, digits, or the characters\n `_ . + -`, start with a letter, and do not include spaces.\n- The **build version** changes with every release of your application, e.g. `2.4.1` or\n `2026.07.13`. No spaces and no `\/`.\n\nThe credentials tell us which application is talking, while the User-Agent tells us which version of it is\nin use, which helps us react faster when you report a problem. If the credentials are\nmissing, the User-Agent remains the only way to identify your integration.\n\n### Transition to enforcement\n\nIf the headers are **not sent at all**, the request proceeds normally and the integration is identified only by\nthe User-Agent. Each software provider is notified in advance of the date from which credentials become\nrequired for its application; only after that date are requests without credentials rejected with\n`401 Unauthorized`.\n\nIf the headers **are sent but fail verification**, the request is rejected immediately with `401 Unauthorized`,\nregardless of any date. If you do not have credentials yet, do not send the headers empty or with placeholder\nvalues.\n\n| Cause | Rejected | `message` |\n| --- | --- | --- |\n| Headers missing | Only after the enforcement date | Kjo kerkese duhet te dergoje header-at X-Client-Id dhe X-Client-Secret. |\n| Client id not recognized | Always | Client ID nuk njihet. |\n| Client secret wrong or missing | Always | Client secret nuk eshte i sakte. |\n| App suspended | Always | Ky aplikacion integrimi eshte pezulluar. |\n\nStart sending the pair now: requests with valid credentials work exactly as before.\n\n## Company registration by partners\n\nSoftware providers can open their clients' accounts themselves with the **Company registration**\ngroup. The group is closed by default and opened on request. The order of steps:\n\n1. `POST \/register`: creates the company and returns the first user's token and the unit id.\n2. `POST \/on-boarding\/certificate`: uploads the electronic certificate, without which nothing can be\n signed.\n3. `POST \/on-boarding\/branch\/{id}`: sets the `businessUnitCode` on the unit.\n4. `POST \/on-boarding\/fiscal-device`: registers the TCR with the tax administration and returns its code. Only for\n cash invoices.\n5. `POST \/on-boarding\/user\/{id}`: sets the `operatorCode` and `fiscalTcrCode` on the user.\n6. `POST \/on-boarding\/bank-account`: the bank account for non-cash invoices and e-invoices.\n\nIn sandbox, the NIPT `L62221018T` on `POST \/register` goes through a test flow that does not create a new\ncompany. Details are in the group.\n\n## Postman and other tools\n\nWe do not ship a Postman collection, because it would go stale every time the API changes. Import the\nOpenAPI document directly; it is generated on every request and is always up to date:\n\n**Postman** > *Import* > *Link* > `https:\/\/fature.al\/docs\/api.json`\n\nThe same URL works for Insomnia, Bruno, Swagger UI or any client generator. For v2 and for the\npartner API, use `\/docs\/api\/v2.json` and `\/docs\/api\/partner.json`. After importing, set\n`Authorization: Bearer `, `X-Client-Id` and `X-Client-Secret` as collection variables\nand select the Sandbox server until the integration is ready.\n\n## Changelog\n\nEvery addition to the API, newest first, with the date it landed in the code. No existing field\nhas changed meaning and no endpoint has been removed; see also *Servers and versions*.\n\n| Date | Change |\n| --- | --- |\n| 2026-09-28 | The warehouse transfer note returns the fiscalization time, not just the date |\n| 2026-09-24 | v2: warehouse transfer notes, with a required `internalId` |\n| 2026-09-14 | v2: `payment_methods[].amount` accepts any number, including 0 and negatives, like the CIS |\n| 2026-09-12 | v2: invoice payment as a `payment_methods` list, in issue, cancel, list, details, bulk and PDF |\n| 2026-09-07 | Cancellations get their own rate limit: 30 per minute and 600 per hour per token |\n| 2026-08-26 | `POST \/on-boarding\/branch`: partners create business units |\n| 2026-08-04 | App credentials: the `X-Client-Id` and `X-Client-Secret` headers |\n| 2026-07-22 | Wolt Partner API, with its own document |\n| 2026-07-15 | `GET \/purchase-invoices` |\n| 2026-07-07 | `GET \/reports\/cash-register\/closing` |\n| 2026-06-09 | v2: clients in the new format, `\/api\/v2\/clients` |\n| 2026-05-19 | `PUT \/clients\/{id}` and `PUT \/products\/{id}`; `GET \/currencies` and `GET \/exchange-rates` |\n| 2026-04-24 | `GET \/products\/{id}\/details` |\n| 2026-04-22 | `GET \/bank-accounts`; `GET \/dashboard\/summary` |\n| 2026-04-21 | Reports under `\/reports`; `GET \/cash-register\/balance` |\n| 2026-04-20 | Cash register: `deposit`, `withdraw` and the `actions` list |\n| 2026-04-19 | Clients (list, details, create); `POST \/products`; warehouse transfer notes (WTN) |\n| 2026-02-26 | Order and summary invoices |\n| 2026-02-19 | `GET \/invoice\/{id}\/details` |\n| 2025-02-04 | `GET \/invoice` |\n| 2023-12-11 | `POST \/invoice\/details\/{internalId}` |\n| 2023-10-31 | `POST \/invoice\/cancel-by-internal-id\/{internalId}` |\n| 2023-10-17 | Cash register: opening and closing the day; `GET \/register` |\n| 2023-09-28 | Company registration by partners and onboarding: certificate, unit, user, fiscal device, bank account |\n| 2023-09-23 | `GET \/client\/search` |\n| 2023-01-30 | `POST \/invoice\/bulk-noncash` |\n| 2022-12-02 | First version: issuing cash, non-cash and e-invoices |\n\n## Support\n\nIntegration questions: [info@fature.al](mailto:info@fature.al). If you are a software house and want\nto bring your clients onto fature.al, write to us: we will give you app credentials and a\ntest environment." }, "servers": [ { "url": "https:\/\/fature.al\/api\/v1", "description": "Live" }, { "url": "https:\/\/demo.fature.al\/api\/v1", "description": "Sandbox" } ], "tags": [ { "name": "Ping", "description": "A call that touches nothing, for testing the connection and the token. The first step of every integration and the simplest check when something is not responding." }, { "name": "Account", "description": "The user who holds the token and the context invoices will be issued in: the company with its NIPT, the business unit, the fiscal device (TCR), the rights and the subscription modules.\n\nCall it at the start of the integration, and whenever you want to confirm which business, unit and device the token works with, before issuing the first invoice." }, { "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\nEach invoice type has its own endpoint and its own body: the same invoice sent to two endpoints is rejected by one of them. The \"Document types\" table in the introduction says which endpoint issues which document, and the shared rules (`internalId`, the buyer, fiscalization when the CIS does not respond) are there too." }, { "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": "Products", "description": "The company's catalog of products and services, with their categories: list, details, create and update.\n\nYou need it when you build a till or a catalog on top of fature.al data, or when you keep the catalog in your own system and want to sync it with fature.al." }, { "name": "Cash register", "description": "The working day on the fiscal device (TCR) of the token's user: opening the day, cash in and cash out, closing the day, the balance at any moment and the history of actions. Amounts are always in ALL.\n\nYou need it when you issue cash invoices: every cash movement that is not a sale is recorded here and reported to the CIS. Without a TCR linked to the user, opening, closing, cash in, cash out and the balance are rejected with HTTP 200 and `status: false`." }, { "name": "Bank accounts", "description": "The company's bank accounts, the ones that appear as payment information on non-cash invoices and e-invoices.\n\nRead only. You need it to get the `id` or the IBAN you send as `bank_account` or `bank_account_iban` when issuing a non-cash invoice. A new account is added from the web app, with the `bankAccount` object when issuing the invoice, or through `POST \/on-boarding\/bank-account` for partners." }, { "name": "Currencies", "description": "The currencies configured for the company and the day's exchange rate from kursi.al. You need them when you issue invoices or save products in a currency other than ALL: `currency` takes the code from the list, and the invoice's `exchange_rate` takes the rate." }, { "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 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`.\n\nThe same group also exists in [v2](\/docs\/api\/v2), where the note is issued with `internalId`, the note's number in your system: with it, a retried request does not issue a second note, and the note can be read without storing our `id`. Here that field is not recognized." }, { "name": "Purchase invoices", "description": "The invoices suppliers have issued to the company, as the CIS recorded them. Read only: these documents are not issued here, and they do not come from the supplier but from the central fiscalisation system." }, { "name": "Reports", "description": "Aggregated figures over a period: sales, VAT, the daily trend, top clients and products, sales by operator and by fiscal device, the cash register and warehouse transfer notes.\n\nThe calculation runs in the database over the whole period, so a report answers the question faster and more accurately than fetching invoices one by one. Amounts are in ALL.\n\nPeriod reports require `from` and `to`, both `YYYY-MM-DD`; when `from` is after `to`, they are swapped. The period is returned, confirmed, in `period`. The two cash register reports take a single `date`, today by default, and return `200` with `status: false` when the cash register is not available." }, { "name": "Dashboard", "description": "The day's summary in a single call: the open shift and the cash register balance, today's sales hour by hour, and the last week against the one before.\n\nThe response is cached for a few seconds, so it is for display, not for reconciliation." }, { "name": "Company registration", "description": "For software providers that open fature.al accounts for their own clients. The group is closed by default and opened on request.\n\nThe steps, in the order the code requires:\n\n1. `POST \/register` creates the company and returns the first user's token and the business unit id. The calls that follow are made with this token.\n2. `POST \/on-boarding\/certificate` uploads the electronic certificate; without it nothing can be signed.\n3. `POST \/on-boarding\/branch\/{id}` sets the `businessUnitCode` on the business unit.\n4. `POST \/on-boarding\/fiscal-device` registers the fiscal device (TCR) with the CIS and returns its code. Requires the certificate and the unit code to be set first. Only for cash invoices.\n5. `POST \/on-boarding\/user\/{id}` sets the `operatorCode` and, for cash invoices, the `fiscalTcrCode` on the user.\n6. `POST \/on-boarding\/bank-account` saves the bank account printed on non-cash invoices and e-invoices.\n\nEvery other user is created with `POST \/on-boarding\/user` and gets its own token. Each one needs a unique email, an operator code and, for cash invoices, a fiscal device.\n\n## Sandbox\n\nIn sandbox, the NIPT `L62221018T` on `POST \/register` goes through a test flow: no new company is created, the user and the unit are created under the test company, and a unique suffix is added to the email, so the same request can be repeated. `POST \/on-boarding\/certificate` accepts any certificate and any password and returns `expiresAt` one year from today. The other steps run normally against the test company. In live, the NIPT `L62221018T` is treated like any other NIPT." } ], "security": [ { "bearerAuth": [], "clientId": [], "clientSecret": [] }, { "bearerAuth": [] } ], "paths": { "\/ping": { "get": { "operationId": "v1.ping", "description": "Returns the server time and the IP addresses the request arrived from. Reads and changes\nnothing in the account.\n\nUse it to test the base URL and the token before the first real call, and to\nsee which IP you arrive from when you configure an IP allowlist. To see which\nbusiness the token works with, call `GET \/account`.\n\n- `pong` is a Unix timestamp in seconds.\n- `ip` is the list of the request's IP addresses, as the server sees them.\n\nA `401` means the token is not getting through: check the `Authorization` header.", "summary": "Test the connection", "tags": [ "Ping" ], "responses": { "200": { "description": "The server time in `pong` and the request's IP addresses in `ip`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/PingResult" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/account": { "get": { "operationId": "v1.account", "description": "Returns the token's user and the fiscal context every invoice issued with it gets:\nthe company, the business unit, the fiscal device, the rights and the subscription modules.\n\nUse it after `GET \/ping` to confirm which business you are working with, and before the first cash\ninvoice to see whether the user has a fiscal device. None of these values are sent in\ninvoicing requests; they are resolved from the token.\n\n| Field | What it is |\n| --- | --- |\n| `name`, `email` | The user who holds the token |\n| `company`, `nipt` | The name and NIPT of the company issuing the invoices |\n| `fiscalCode` | The TCR code of the user's fiscal device. Empty string when there is none; cash invoices and cash register actions are then rejected |\n| `branch` | The user's business unit: `name`, `address` and `city` |\n| `companyBranches` | All of the company's units, as an object with the address as key and the name as value |\n| `setupFinished` | `true` when the company has completed the setup steps and can issue invoices |\n| `permissions` | `createArticles` and `createClients`: whether the user can create products and clients. Without them, `POST \/products` and `POST \/clients` are rejected with `403` |\n| `configs.openDayAlways0` | `true` when the company always opens the day on the cash register with a balance of `0` |\n| `vatConfigs` | `issuerInVat` says whether the company is in the VAT scheme. `vat_rates` are the rates accepted on invoice lines: `20`, `10`, `6` and `0` in the scheme, only `0` outside it. `vat_exempts` are the accepted exemption types, with `code` and `label` |\n| `subscription` | `cash`, `noncash`, `einvoice` and `wtn`: which modules the subscription includes. The endpoint of a missing module responds `401` with `status: false` |\n\nStore `nipt` and `fiscalCode` alongside the integration's configuration, so a token swapped\nby mistake is caught before it issues invoices on behalf of another business.", "summary": "Get the account details", "tags": [ "Account" ], "responses": { "200": { "description": "The token's user and their fiscal context: the company, the business unit, the fiscal device, the rights and the subscription modules.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/AccountInfo" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice": { "get": { "operationId": "v1.invoice.list", "description": "Returns the company's invoices, newest first, filtered by type, date and a\nsearch text. Each invoice comes with the buyer, the amounts and the payment, but without the lines; for the lines,\ncall `GET \/invoice\/{id}\/details`.\n\n- Pagination with `limit` and `offset`. `pagination` does not return a `total`, so stop when a page\n comes back shorter than `limit`.\n- When you read a closed period, bound it with `fromDate` and `toDate`, so new invoices do not\n shift the pages.\n- A second request from the same token, while the first has not finished, waits up to one second\n and is then rejected with `429`.", "summary": "List invoices", "tags": [ "Invoices" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many invoices to return per page.", "schema": { "type": "integer", "default": 20 }, "example": 10 }, { "name": "offset", "in": "query", "description": "Which invoice to start from, counting from 0.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "type", "in": "query", "description": "Filter by type: `CASH`, `NONCASH` or `EINVOICE`, several types separated by commas. Any other value is ignored without an error; if none remains valid, the filter is not applied at all.", "schema": { "type": "string" }, "example": "CASH,NONCASH" }, { "name": "fromDate", "in": "query", "description": "Start date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2025-01-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2025-12-31" }, { "name": "query", "in": "query", "description": "Search by invoice number, buyer name or NIPT.", "schema": { "type": "string" }, "example": "K12345AB" } ], "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" }, "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\/{id}\/details": { "get": { "operationId": "v1.invoice.details", "description": "Returns the full invoice by its `id` in fature.al: the buyer, the amounts, the payment, the fiscal\ncodes and the lines.\n\nWhen the invoice is not found, or does not belong to your company, `data.invoice` is `null` with\nstatus `200`. To find it by your own number, use `POST \/invoice\/details\/{internalId}`.", "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" }, "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\/details\/{internalId}": { "post": { "operationId": "v1.invoice.details-by-internal-id", "description": "Returns the issue result of the invoice you sent with this `internalId`: `id`, `number`,\n`iic`, `fic`, the fiscal codes and `pdf`. Use it to read the state after a timeout or\nafter a `409`, and to see whether `fic` was filled in after a deferred fiscalization.\n\nFor the buyer, the amounts and the lines, use `GET \/invoice\/{id}\/details`.", "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 issue result of the invoice with this `internalId`, the same one the issue call returned.", "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" }, "404": { "description": "No invoice with this `internalId` in your company.", "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" } } } } } } }, "\/invoice\/e-invoice": { "post": { "operationId": "v1.invoice.e-invoice", "description": "Issues an electronic invoice to a business: it is fiscalized with the CIS and sent to the\ncentral e-invoicing platform, which delivers it to the buyer as a UBL document.\n\nUse it when the buyer is a business with a NIPT and the invoice must reach them electronically. For\na sale with deferred payment that does not go to the e-invoicing platform, use\n`POST \/invoice\/noncash`.\n\n## The buyer\n\n`client` is required: `client.id` of type `NUIS` (or `VAT` and `TAX` for a foreign\nbusiness), `client.name`, and `client.address` with `client.city`, either in the request or saved\nearlier on the client in fature.al. When a value is missing, the request is rejected with `400` and\n`errors` says exactly what needs to be filled in. Every line requires `unit_code`.\n\n## Document type\n\n`doc_type` is the document type and `process` its UBL profile. Both are\nrequired; for a regular invoice, send `380` and `P1`. Validation also accepts the other document types\nand profiles of the UBL standard, listed in the request fields:\n\n| Document | `doc_type` | `process` | Requires `original_invoice_iic` |\n| --- | --- | --- | --- |\n| Sales invoice | `380` | `P1` | No |\n| Credit note | `381` | `P9` | **Yes** |\n| Debit note | `383` | `P9` | **Yes** |\n\nThe credit note and the debit note correct another invoice: `original_invoice_iic` is\nthe `iic` that invoice returned to you. It goes as BillingReference in the UBL document and as the correction\nreference to the CIS, and without it the request is rejected with `422`. To reverse a full invoice,\nuse cancellation, not a credit note: it marks the original as reversed.\n\n## Discount\n\nA discount on the whole invoice is sent with `invoice_discount_type` and `invoice_discount_value`\ntogether; a line discount with `lines[].discount`, as a percentage of the unit price, with\nthe full `price` and the `total` already reduced. Both can be on the same invoice, and the\nfull rules are in the request fields. In the UBL document the discount appears as\nAllowanceCharge, with one entry per VAT rate.\n\n## Examples\n\n### Advance payment from a business\n\n`doc_type` `386` is the prepayment invoice and `process` `P4` the advance-payment profile. Invoice the amount received, at the VAT rate of the service being prepaid.\n\n```json\n{\n \"internalId\": \"DEP-2026-0032\",\n \"doc_type\": \"386\",\n \"process\": \"P4\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"nuis\": \"L62221018T\",\n \"name\": \"Ei3 Software Solution shpk\",\n \"address\": \"Rruga e Kavaj\u00ebs 12\",\n \"city\": \"Tiran\u00eb\",\n \"country\": \"ALB\"\n },\n \"lines\": [\n {\n \"product_name\": \"Advance, reservation R-88214\",\n \"product_code\": \"DEP-REZ\",\n \"unit\": \"piece\",\n \"unit_code\": \"C62\",\n \"quantity\": 1,\n \"price\": 30000,\n \"total\": 30000,\n \"vat\": 6\n }\n ]\n}\n```\n\n### Credit note\n\nThe lines are only the difference, with positive values.\n\n```json\n{\n \"internalId\": \"NK-2026-0038\",\n \"doc_type\": \"381\",\n \"process\": \"P9\",\n \"original_invoice_iic\": \"8FE72E2ACD1C500A83F8C89B4E2E3E1D\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"nuis\": \"L62221018T\",\n \"name\": \"Ei3 Software Solution shpk\",\n \"address\": \"Rruga e Kavaj\u00ebs 12\",\n \"city\": \"Tiran\u00eb\",\n \"country\": \"ALB\"\n },\n \"lines\": [\n {\n \"product_name\": \"Discount for service interruption\",\n \"product_code\": \"SLL-01\",\n \"unit\": \"day\",\n \"unit_code\": \"DAY\",\n \"quantity\": 1,\n \"price\": 2000,\n \"total\": 2000,\n \"vat\": 20\n }\n ]\n}\n```\n\n## After issuing\n\nThe response carries `iic`, `fic`, `eic` and `pdf`. When the CIS cannot be reached, the invoice is saved and `fic`\nis `null` until fiscalization completes on its own. When the e-invoicing platform cannot be reached\nbut the invoice was fiscalized, `eic` is missing until the submission is retried.", "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": "v1.invoice.noncash", "description": "Issues an invoice with deferred payment: bank transfer, check, offset, or any payment\nnot made at the cash register. It is fiscalized with the CIS but does not go to the e-invoicing platform; when\nthe buyer must receive it electronically, use `POST \/invoice\/e-invoice`.\n\n## The buyer\n\n`client` is required: either `client.internal_id` of a client saved in fature.al,\nor `client.name` with the other details; without either, the request is rejected with `422`. `client.address`\nand `client.city` go to the CIS, so they are needed either in the request or saved earlier on the\nclient; when one is missing, the request is rejected with `400` and `errors` says exactly what needs to be\nfilled in.\n\n## Bank account\n\nThe account where payment is expected is printed on the invoice in one of three ways:\n\n| Field | Meaning |\n| --- | --- |\n| `bank_account` | The id of an account saved in fature.al |\n| `bank_account_iban` | The account is looked up by IBAN |\n| `bankAccount` | The full account is sent and saved as a company account; an existing IBAN is reused |\n\n## Credit note and debit note\n\nA non-cash invoice is corrected by another non-cash invoice. Send `doc_type` together with\n`original_invoice_iic`, the `iic` the original invoice returned to you:\n\n| `doc_type` | Document | Effect |\n| --- | --- | --- |\n| Missing, or `380` | Regular invoice | None |\n| `381` | Credit note | Lowers the amount the buyer owes you |\n| `383` | Debit note | Raises the amount the buyer owes you |\n\nThe original must be a fiscalized non-cash invoice, not canceled, and still correctable.\nThe lines you send are the correction lines, with positive values: the direction is set by\n`doc_type`, not by the sign of the numbers. When the corrections cover the whole invoice, the original\nis marked as reversed. To reverse a full invoice, use cancellation, not a credit\nnote.\n\n## Discount and fee\n\nA discount on the whole invoice is sent with `invoice_discount_type` and `invoice_discount_value`\ntogether; a line discount with `lines[].discount`, as a percentage of the unit price, with\nthe full `price` and the `total` already reduced. The full rules are in the request fields.\nThe `fee` stays outside the discount: the discount applies to the line total, and the fee is added to the reduced\ntotal.\n\n## Examples\n\n### Credit note\n\nThe lines are only the difference, with positive values.\n\n```json\n{\n \"internalId\": \"NK-2026-0037\",\n \"doc_type\": \"381\",\n \"original_invoice_iic\": \"8FE72E2ACD1C500A83F8C89B4E2E3E1D\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"name\": \"Alpha SHPK\"\n },\n \"lines\": [\n {\n \"product_name\": \"Discount, one unused night\",\n \"product_code\": \"DHM-2\",\n \"unit\": \"night\",\n \"quantity\": 1,\n \"price\": 9000,\n \"total\": 9000,\n \"vat\": 6\n }\n ]\n}\n```\n\n### Debit note\n\n```json\n{\n \"internalId\": \"ND-2026-0012\",\n \"doc_type\": \"383\",\n \"original_invoice_iic\": \"8FE72E2ACD1C500A83F8C89B4E2E3E1D\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"name\": \"Alpha SHPK\"\n },\n \"lines\": [\n {\n \"product_name\": \"Minibar, not invoiced\",\n \"product_code\": \"MNB-01\",\n \"unit\": \"piece\",\n \"quantity\": 4,\n \"price\": 500,\n \"total\": 2000,\n \"vat\": 20\n }\n ]\n}\n```\n\n### Advance payment by transfer\n\nAn advance payment has no type of its own at the CIS: it is invoiced as a sale, for the amount received. The API does not link it to the final invoice and does not deduct it from it.\n\n```json\n{\n \"internalId\": \"DEP-2026-0033\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"name\": \"Arben Hoxha\"\n },\n \"notes\": \"Advance for reservation R-88215\",\n \"lines\": [\n {\n \"product_name\": \"Advance, reservation R-88215\",\n \"product_code\": \"DEP-REZ\",\n \"unit\": \"piece\",\n \"quantity\": 1,\n \"price\": 20000,\n \"total\": 20000,\n \"vat\": 6\n }\n ]\n}\n```\n\n## After issuing\n\nThe response carries `iic`, `fic` and `pdf`. When the CIS cannot be reached, the invoice is saved and `fic` is\n`null` until fiscalization completes on its own.", "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": "v1.invoice.cash", "description": "Issues an invoice paid on the spot from the fiscal device (TCR) linked to the token's\nuser: cash, card, check, company card or vouchers. If the day has not been opened on the cash register\nyet, it opens automatically with a balance of `0`.\n\nThe token's user must have a TCR; without one, the request is rejected with `200` and\n`status: false`.\n\n## The buyer is optional\n\nWithout `client`, the invoice is issued to the walk-in customer, which is the normal case at a till. As soon as\nyou send even one client detail, `client.name`, `client.address` and\n`client.city` are required, because the address and city go to the CIS. The address and city can also\ncome from a client saved earlier in fature.al, so you do not need to send them on every\ninvoice. When one is missing, the request is rejected with `400` and `errors` says exactly what needs to be\nfilled in.\n\n## Fields that depend on the payment method\n\nTwo fields are required for only one payment method, and rejected for any other:\n\n| `payment_method` | Required field | Limit |\n| --- | --- | --- |\n| `COMPANY` | `company_card` | Up to 50 characters |\n| `SVOUCHER` | `vouchers` | Up to 20, in the form number-year-NIPT, no duplicates |\n\n`company_card` with `BANKNOTE`, or `vouchers` with `CARD`, are rejected: they have no place in the\nfiscal document, so they are not silently accepted.\n\n## Discount\n\nA discount on the whole invoice is sent with `invoice_discount_type` and `invoice_discount_value`\ntogether; a line discount with `lines[].discount`, as a percentage of the unit price, with\nthe full `price` and the `total` already reduced. Both can be on the same invoice, and the\nfull rules are in the request fields.\n\n## Self-invoicing is paid from the cash register\n\nWith `self_issue_type`, the seller is paid for the invoice in cash from the cash register, so the cash register must hold at\nleast the invoice total, in the invoice currency. When it does not, the invoice is not saved and not\nfiscalized: the response comes back with HTTP 200, `status: false` and a `message` with the cash register balance\nand the invoice amount. Record a cash in and send the invoice again with the same\n`internalId`.\n\n## Example: advance payment at the front desk\n\nAn advance paid in cash or by card is invoiced as a cash sale, for the amount received.\n\n```json\n{\n \"internalId\": \"DEP-2026-0031\",\n \"payment_method\": \"CARD\",\n \"notes\": \"Advance for reservation R-88213, 12 to 15 October\",\n \"lines\": [\n {\n \"product_name\": \"Advance, reservation R-88213\",\n \"product_code\": \"DEP-REZ\",\n \"unit\": \"piece\",\n \"quantity\": 1,\n \"price\": 10000,\n \"total\": 10000,\n \"vat\": 6\n }\n ]\n}\n```\n\n## After issuing\n\nThe response carries `iic`, `fic`, `tcrCode` and `pdf`. When the CIS cannot be reached, the invoice is saved and\n`fic` is `null` until fiscalization completes on its own.", "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": "v1.invoice.order", "description": "Records consumption that has started without settling payment, like a restaurant table. It works\nin tandem with the summary invoice: the order opens the table, the summary pays it. It is issued from the\nuser's TCR, like a cash invoice.\n\n- Do not send `payment_method`: `ORDER` is set automatically.\n- Keep the `iic` you get back: the order is closed with it in `POST \/invoice\/summary`.\n- A table can have several open orders at once.\n- A discount on the whole invoice is not accepted here; it goes on the summary invoice, which\n copies the lines from the orders. A line discount, `lines[].discount`, is stored on the order\n line and carries over to the summary invoice, so the table pays exactly what the order showed.", "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 order 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": "v1.invoice.summary", "description": "Settles payment for one or more order invoices with a single document, issued from the\nuser's TCR.\n\n- `order_invoices` holds the `iic` values of the orders being closed, at least one. They must be order\n invoices of this company, not yet closed; otherwise the request is rejected with `400` and\n `errors` says which one.\n- Lines are not sent: they are taken from the orders themselves, with their discounts.\n- `payment_method` accepts only `BANKNOTE` or `CARD`.\n- The table discount is set here, with `invoice_discount_type` and `invoice_discount_value`.\n\nThe response lists the closed orders in `settledOrderInvoices`.", "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": "v1.invoice.cancel", "description": "Cancels the invoice by issuing a corrective document to the CIS, which gets a new sequence number.\nThe original is marked canceled only when the cancellations cover all of it.\n\n## Full or partial\n\n| Body | What happens |\n| --- | --- |\n| Empty | The whole invoice is canceled, whatever its type |\n| With `lines` | Only the part sent is canceled. **Cash invoices only** |\n\n## Partial cancellation rules\n\n- Every line must exist on the original invoice with the same `product_code` and\n `product_name`.\n- The quantity can only decrease or stay the same; products you do not send remain sold.\n- When the same product was invoiced on two lines at different prices, add `price` to\n pick the line.\n- An invoice with a discount on the whole invoice can only be canceled in full: the discount is spread\n across all VAT rates, and a subset of the lines cannot carry its own share without getting\n the VAT wrong.\n\n## Example: partial cancellation\n\nOne breakfast is returned from a cash invoice; the rest of the invoice stays sold.\n\n```json\n{\n \"lines\": [\n {\n \"product_name\": \"Breakfast\",\n \"product_code\": \"MNG-01\",\n \"quantity\": 1\n }\n ]\n}\n```\n\nThe response is the corrective document, with its own `iic` and `fic`. When the CIS cannot be reached,\nthe cancellation is saved with `fic: null` and is fiscalized automatically later. Cancellations have their own\nrate 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": "v1.invoice.cancel-by-internal-id", "description": "Cancels the invoice by looking it up with the `internalId` you sent when you issued it, so you do not\nneed to keep the fature.al `id` next to your sale. Behaves the same as cancellation by id:\n\n- with no body, the whole invoice is canceled;\n- with `lines`, only part is canceled, possible **only for cash invoices**;\n- lines must match on `product_code` and `product_name`, and the quantity can only decrease;\n- an invoice with a discount on the whole invoice can only be canceled in full.\n\nThe response is the corrective document, with its own `iic` and `fic`. When the CIS cannot be reached,\nthe cancellation is saved with `fic: null` and is fiscalized automatically later.", "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": "v1.invoice.bulk-noncash", "description": "Issues many non-cash invoices in a single request, for periodic invoicing. Each element of\n`invoices` has the same fields as the `POST \/invoice\/noncash` request body, `internalId` included, and\nis issued under the same rules.\n\nThe response is an object with one entry per `internalId`, and the HTTP status stays `200`\neven when some invoice fails:\n\n- check `status` inside each entry separately, not the HTTP code;\n- retry only the `internalId`s that failed, not the whole bulk;\n- invoices are issued one by one, in order, so a large bulk takes as long as the sum of the issuances.\n\n## Example: group advance payment\n\nOne invoice for each member who pays their own share.\n\n```json\n{\n \"invoices\": [\n {\n \"internalId\": \"DEP-GRP-0007-01\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"name\": \"Arben Hoxha\"\n },\n \"lines\": [\n {\n \"product_name\": \"Advance, group G-0007\",\n \"product_code\": \"DEP-GRP\",\n \"unit\": \"piece\",\n \"quantity\": 1,\n \"price\": 15000,\n \"total\": 15000,\n \"vat\": 6\n }\n ]\n },\n {\n \"internalId\": \"DEP-GRP-0007-02\",\n \"payment_method\": \"TRANSFER\",\n \"client\": {\n \"name\": \"Elira Kola\"\n },\n \"lines\": [\n {\n \"product_name\": \"Advance, group G-0007\",\n \"product_code\": \"DEP-GRP\",\n \"unit\": \"piece\",\n \"quantity\": 1,\n \"price\": 15000,\n \"total\": 15000,\n \"vat\": 6\n }\n ]\n }\n ]\n}\n```", "summary": "Issue bulk non-cash invoices", "tags": [ "Invoices" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "invoices": { "type": "array", "description": "The invoices to issue, each with the same fields as the `POST \/invoice\/noncash` request body, `internalId` included. There is no limit on their number, but the endpoint allows only 3 requests per minute, so send a few large bulks instead of many small ones.", "items": {} } }, "required": [ "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" } } } }, "\/invoice\/print\/{id}": { "get": { "operationId": "v1.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": "v1.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" } } } }, "\/clients": { "get": { "operationId": "v1.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": "v1.clients.create", "description": "Creates a new client for the company, a company or a person, and returns its `id`.\n\nUse it when you keep your client records in fature.al. When you need the client for only one\ninvoice, send it in the invoice's `client` object; this endpoint is not needed.\n\n`client_type` determines which fields are required:\n\n| `client_type` | Required fields |\n| --- | --- |\n| `COMPANY` | `company_name`, `nipt`, `address`, `city` |\n| `PERSON` | `name`, `surname`, `document_type`, `document_number` |\n\n- For an Albanian business, call `GET \/client\/search` first: the name, address and city come\n prefilled from the registry.\n- The NIPT is unique within the company; a second client with the same NIPT is rejected with `409`.\n- A second request from the same token, while the first has not finished, is rejected immediately with\n `429`.\n\nStore the returned `id`: you use it to read and update the client later.", "summary": "Create a client", "tags": [ "Clients" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientRequest" } } } }, "responses": { "200": { "description": "The newly created client in `client`, with its `id`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/ClientV1" } }, "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 this NIPT 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}\/details": { "get": { "operationId": "v1.clients.details", "description": "Returns a single client with all fields, a company or a person.\n\nUse it when you have stored the `id` from the list or from creation and need the\nup-to-date data. `company_type` is returned `null` for a person, and `first_name` and `surname` for\na company; `name` always holds the full name.", "summary": "Get a client by id", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The client's id in fature.al.", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "The requested client in `client`, with all fields.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/ClientV1" } }, "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" } } } } } } }, "\/clients\/{id}": { "put": { "operationId": "v1.clients.update", "description": "Updates an existing client and returns its data after the change.\n\nThe request body has the same format and the same required fields per `client_type`\nas `POST \/clients`.\n\n- The new NIPT cannot match another client's; it is rejected with `409`.\n- A 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's id in fature.al.", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ClientRequest" } } } }, "responses": { "200": { "description": "The client after the change, in `client`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/ClientV1" } }, "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" } } } }, "404": { "description": "The client was not found, or does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Another client with this NIPT 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" } } } } } } }, "\/client\/search": { "get": { "operationId": "v1.client.search", "description": "Looks up a business in the fiscal registry by NIPT and returns its name, address, city and\ncountry.\n\nUse it to fill in a new client's details from a single field, or to\ncatch a wrong NIPT before it ends up on an invoice. For clients you have already saved in\nfature.al, use `GET \/clients` with `query`.\n\n`verified` says whether the registry confirmed the business. The two rejection responses are not the\nsame thing:\n\n- `404`: the NIPT is not in the registry.\n- `503`: the registry could not be reached and the NIPT was left unchecked. Retry later.", "summary": "Look up a business by NIPT", "tags": [ "Clients" ], "parameters": [ { "name": "nuis", "in": "query", "required": true, "description": "The NIPT to look up in the fiscal registry: one letter, eight digits, one letter.\nLowercase letters are accepted. Required.", "schema": { "type": "string", "pattern": "^[A-Z]\\d{8}[A-Z]$" }, "example": "L91806031A" } ], "responses": { "200": { "description": "The business found, in `client`, with `verified: true`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "client": { "$ref": "#\/components\/schemas\/BusinessLookupResult" } }, "required": [ "client" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The NIPT is missing or not in the X00000000X format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "404": { "description": "The NIPT is not in the fiscal registry.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscal registry could not be reached and the NIPT was left unchecked. Retry later.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/product\/categories": { "get": { "operationId": "v1.products.categories", "description": "Returns all of the company's product categories in a single response, without pagination,\neach with `id`, `name` and `color`.\n\nUse it to get the `id` you send as `id_category` when you filter `GET \/products` or\nwhen you create a product. The list rarely changes, so cache it.\n\nThis endpoint returns neither `429` nor `500`. A second request from the same token, while the first\nhas not finished, as well as any unexpected error, are returned with HTTP 200 and `status: false`; the reason\nis in `message`. Read `status`, not just the HTTP code.", "summary": "List product categories", "tags": [ "Products" ], "responses": { "200": { "description": "The company's categories in `data`, empty when there are none; or `status: false` with the reason in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ProductCategoryRef" } } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/products": { "get": { "operationId": "v1.products.list", "description": "Returns the company's products and services that are for sale, by ascending `id`, filtered\nby text, category and kind. Deleted products and those not for sale are left out.\n\nUse it to build a till or a catalog, or to find a product's `id`.\nEach product comes with its code, name, unit, prices, VAT rate and `id_category`; for\nthe category object and for `service`, call `GET \/products\/{id}\/details`.\n\n- `query` searches by partial match on name, code and description.\n- `id_category` keeps only the products of one category; `service` `true` only services,\n `false` only inventory items.\n- Pagination with `limit` and `offset`. `limit` is capped at `500`; a larger value is lowered without\n an error. Without `limit` the whole catalog is returned, `pagination.limit` is `null` and `offset`\n is ignored.\n- `pagination` returns `total`, so continue with `offset += limit` until `offset` reaches\n `total`.\n\nUnlike the other lists, `data` is the product list itself and `pagination` sits\nnext to it, not inside it.\n\nThis endpoint returns neither `429` nor `500`. A second request from the same token, while the first\nhas not finished, as well as any unexpected error, are returned with HTTP 200 and `status: false`; the reason\nis in `message`. Read `status`, not just the HTTP code.", "summary": "List products", "tags": [ "Products" ], "parameters": [ { "name": "query", "in": "query", "description": "Search in the product's name, code or description.", "schema": { "type": "string" }, "example": "kafe" }, { "name": "id_category", "in": "query", "description": "Only the products of this category, by `id` from `GET \/product\/categories`.", "schema": { "type": "integer" }, "example": 3 }, { "name": "limit", "in": "query", "description": "How many products to return per page, up to 500. Without it the whole catalog is returned.", "schema": { "type": "integer" }, "example": 50 }, { "name": "offset", "in": "query", "description": "Which product to start from, counting from 0. Applies only together with `limit`.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "service", "in": "query", "description": "`true` returns only services, `false` only inventory items. Without it, both are returned.", "schema": { "type": "boolean" }, "example": false } ], "responses": { "200": { "description": "The page's products in `data`, with `pagination` next to it; or `status: false` with the reason in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ProductListItem" } }, "pagination": { "$ref": "#\/components\/schemas\/ProductListPagination" } }, "required": [ "status", "data", "pagination" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.products.create", "description": "Creates a new product or service in the company's catalog and returns its `id`.\n\nUse it when you keep the catalog in your own system and want the product to appear in fature.al as well.\n\n- `name` is unique within the company; a second product with the same name is rejected with\n `409`.\n- `code` is generated automatically when you do not send it; store the one returned to you.\n- `unit` is not sent: the unit is derived from `unit_code`, the code the fiscal document carries.\n- `vat_rate` accepts `0`, `6`, `10` or `20`; for an exempt product also send\n `vat_exempt_type`.\n- A second request from the same token, while the first has not finished, is rejected immediately with\n `429`.\n\nThe product appears immediately in `GET \/products`. Store the returned `id` for details and\nupdates.", "summary": "Create a product", "tags": [ "Products" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ProductRequest" } } } }, "responses": { "200": { "description": "The newly created product in `product`, with its `id` and code.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "product": { "$ref": "#\/components\/schemas\/ProductDetail" } }, "required": [ "product" ] } }, "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 product with this name 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" } } } } } } }, "\/products\/{id}\/details": { "get": { "operationId": "v1.products.details", "description": "Returns a single product with all fields: code, name, unit with its fiscal code,\nprices, VAT rate with the exemption type, `service` and the category as an object.\n\nUse it when you have the `id` from the list or from creation and need the fields the list does not\ncarry.", "summary": "Get a product by id", "tags": [ "Products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The product's id in fature.al.", "schema": { "type": "integer" }, "example": 42 } ], "responses": { "200": { "description": "The requested product in `product`, with all fields.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "product": { "$ref": "#\/components\/schemas\/ProductDetail" } }, "required": [ "product" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "404": { "description": "The product 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" } } } } } } }, "\/products\/{id}": { "put": { "operationId": "v1.products.update", "description": "Updates an existing product and returns its data after the change.\n\nThe request body has the same format and the same required fields as `POST \/products`,\nwith the same rules for `unit_code` and `vat_rate`.\n\n- The new name or code cannot match another product's; it is rejected with `409`.\n- A price change does not affect issued invoices: they keep the price they were sold at.\n- A second request from the same token, while the first has not finished, is rejected immediately with\n `429`.", "summary": "Update a product", "tags": [ "Products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The product's id in fature.al.", "schema": { "type": "integer" }, "example": 42 } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ProductRequest" } } } }, "responses": { "200": { "description": "The product after the change, in `product`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "product": { "$ref": "#\/components\/schemas\/ProductDetail" } }, "required": [ "product" ] } }, "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" } } } }, "404": { "description": "The product was not found, or does not belong to your company.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "409": { "description": "Another product with this name or this code already exists.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "429": { "description": "Rate limit reached. From the global limit, the response carries only `message` and the `Retry-After` header; from the endpoint's limit, it has the standard error format.", "content": { "application\/json": { "schema": { "anyOf": [ { "$ref": "#\/components\/schemas\/ApiError" }, { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } ] } } }, "headers": { "Retry-After": { "description": "How many seconds until you can retry. Sent only by a time-window limit, such as the global one or the cancellation one; rejecting a request still in progress does not carry it.", "schema": { "type": "integer" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/open-balance": { "post": { "operationId": "v1.cash-register.open", "description": "Opens the working day on the fiscal device (TCR) of the token's user with the opening\n`balance`, in ALL, and records it as an `OPEN_DAY` action.\n\nCall it at the start of the shift, before the first cash invoice. It is not required: the first\ncash invoice, a cash in, a cash out or closing the day open the day automatically with `0`. Use it when the day\nstarts with money in the cash register and you want the balance to be accurate.\n\n- `balance` is optional; without it, `0` is used. A negative value is rejected.\n- The user must have a TCR.\n\nThe response returns `balance` as it was accepted. When the CIS cannot be reached, the opening is saved and\nis fiscalized automatically later; the response is the same.", "summary": "Open the day on the cash register", "tags": [ "Cash register" ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "balance": { "type": "number", "description": "The balance the day starts with, in lek. Without it, `0` is used. A negative value is rejected.", "examples": [ 5000 ] } } } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when `balance` is negative, or when saving fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashRegisterOpenBalance" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/close-balance": { "post": { "operationId": "v1.cash-register.close", "description": "Closes the working day on the fiscal device (TCR) of the token's user: takes the whole\nbalance out of the cash register and returns the amount that went out.\n\nCall it at the end of the shift, without first checking whether the day is open: when it is not,\nit is opened automatically with `0` and closed immediately. The request has no body.\n\n- The user must have a TCR.\n\n`balance` is the amount in ALL that went out of the cash register; `0` when the cash register was empty. The cash out appears in\n`GET \/cash-register\/actions` as a `MONEY_OUT` action with the description \"Mbyllje turni\/xhiro ditore\" (shift\/daily close); when the cash register was empty, no cash out is recorded. When the CIS cannot be reached, the closing\nis saved and is fiscalized automatically later; the response is the same.", "summary": "Close the day on the cash register", "tags": [ "Cash register" ], "responses": { "200": { "description": "When the user has no fiscal device or when closing fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashRegisterCloseBalance" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/cash-register\/deposit": { "post": { "operationId": "v1.cash-register.deposit", "description": "Records money that enters the cash register without being a sale, such as a collection from a client or an opening\nfloat, as a `MONEY_IN` action on the fiscal device (TCR) of the token's user.\n\nFor a sale, issue a cash invoice, not a cash in. If the day has not been opened yet, it is opened automatically with\n`0`.\n\n- `amount` is in ALL and must be greater than `0`.\n- `id_client`, when sent, must be the `id` of a client of your company.\n- The user must have a TCR.\n\nThe response carries the action's `id`, its numbers (`transaction_no`, `cash_action_no`) and\nfiscal state (`fiscal_status`, `fiscal_uuid`, `fiscal_fic`). When the CIS cannot be reached,\nthe action is saved and is fiscalized automatically later: the response comes with `status: true`,\n`fiscal_status: UNFISCALISED` and no `id`; read it afterwards in `GET \/cash-register\/actions`.", "summary": "Record a cash in", "tags": [ "Cash register" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashActionRequest" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when `id_client` does not belong to your company, or when saving fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashAction" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/cash-register\/withdraw": { "post": { "operationId": "v1.cash-register.withdraw", "description": "Records money that leaves the cash register, such as a supplier payment or a withdrawal during the day, as a\n`MONEY_OUT` action on the fiscal device (TCR) of the token's user.\n\nTo withdraw the whole balance at the end of the shift, use `POST \/cash-register\/close-balance`.\nIf the day has not been opened yet, it is opened automatically with `0`.\n\n- `amount` is in ALL and must be greater than `0`; the sign comes from the endpoint, not\n from the number.\n- The cash register must hold at least `amount`; when it does not, the cash out is rejected.\n- `id_client`, when sent, must be the `id` of a client of your company.\n- The user must have a TCR.\n\nThe response has the same format as the cash in. When the CIS cannot be reached, the action is saved and\nis fiscalized automatically later: the response comes with `status: true`, `fiscal_status: UNFISCALISED`\nand no `id`; read it afterwards in `GET \/cash-register\/actions`.", "summary": "Record a cash out", "tags": [ "Cash register" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CashActionRequest" } } } }, "responses": { "200": { "description": "When the user has no fiscal device, when the cash register does not hold as much money as `amount`, when `id_client` does not belong to your company, or when saving fails, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashAction" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/cash-register\/actions": { "get": { "operationId": "v1.cash-register.list", "description": "Returns the cash register history, newest first, filtered by type and date:\ncash ins, cash outs, and day openings and closings.\n\nUse it to reconcile the shift and to read the fiscal state of an action that was\nsaved while the CIS could not be reached.\n\n| `type` | Action |\n| --- | --- |\n| `MONEY_IN` | Cash in |\n| `MONEY_OUT` | Cash out |\n| `OPEN_DAY` | Opening the day |\n| `CLOSE_DAY` | Closing the day |\n\n- Several types are separated by commas: `type=MONEY_IN,MONEY_OUT` returns only money movements.\n- The closing from `POST \/cash-register\/close-balance` appears as `MONEY_OUT` with the description\n \"Mbyllje turni\/xhiro ditore\" (shift\/daily close), not as `CLOSE_DAY`.\n- `fromDate` and `toDate` limit by action date, both inclusive.\n- Pagination with `limit` and `offset`. `pagination` does not return `total`, so stop when a page\n comes back shorter than `limit`.\n\n`amount` is always positive, in ALL; `action_type` gives the direction. `fiscal_status` and\n`fiscal_fic` say whether the action has been fiscalized.", "summary": "List cash register actions", "tags": [ "Cash register" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many actions to return per page.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Which action to start from, counting from 0.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "type", "in": "query", "description": "Filter by type: `MONEY_IN`, `MONEY_OUT`, `OPEN_DAY` or `CLOSE_DAY`, several types separated by commas.", "schema": { "type": "string" }, "example": "MONEY_IN" }, { "name": "fromDate", "in": "query", "description": "Start date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2026-01-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2026-12-31" } ], "responses": { "200": { "description": "The period's actions, newest first, with `pagination`; `items` is empty when there are no actions.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CashActionListItem" } }, "pagination": { "$ref": "#\/components\/schemas\/CashActionPagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/cash-register\/balance": { "get": { "operationId": "v1.cash-register.balance", "description": "Returns the balance of the fiscal device (TCR) of the token's user, in ALL, together with its\n`fiscal_tcr_code`.\n\nWithout `toDate`, the current balance is returned. With `toDate`, the balance at the end of that day is returned, for\nreconciliation with a past day. The balance is cached for 5 seconds, so a just-recorded\naction may show up a moment later.\n\n- The user must have a TCR.", "summary": "Get the cash register balance", "tags": [ "Cash register" ], "parameters": [ { "name": "toDate", "in": "query", "description": "The date, `YYYY-MM-DD`, up to which the cash register balance is calculated. Without it, the latest balance\nis returned.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "When the user has no fiscal device, the response is returned with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/CashRegisterBalance" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/bank-accounts": { "get": { "operationId": "v1.bank-accounts.list", "description": "Returns the company's active bank accounts, with the default account first and then\nnewest to oldest, with text search.\n\nUse it to choose the account that goes on a non-cash invoice or an e-invoice: store\nthe `id` for `bank_account`, or the `iban` for `bank_account_iban`. The list rarely changes, so\ncache it.\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 bank name, IBAN, SWIFT, holder and\n notes.\n- A second request from the same token, while the first has not finished, is rejected immediately with\n `429`.\n\nEach account comes with `bank_name`, `iban`, `swift`, `holder`, `currency_code` (ISO 4217),\n`is_default`, `notes`, `valid_from` and `valid_to` when the account has a validity period, and\n`created_at` (ISO 8601).", "summary": "List bank accounts", "tags": [ "Bank accounts" ], "parameters": [ { "name": "limit", "in": "query", "description": "How many accounts to return per page, up to 100.", "schema": { "type": "integer", "default": 20 }, "example": 20 }, { "name": "offset", "in": "query", "description": "Which account to start from, counting from 0.", "schema": { "type": "integer", "default": 0 }, "example": 0 }, { "name": "query", "in": "query", "description": "Search in the bank name, IBAN, SWIFT, holder or notes.", "schema": { "type": "string" }, "example": "Raiffeisen" } ], "responses": { "200": { "description": "The company's active bank accounts, with the default first, and `pagination` with `total`; `items` is empty when the company has no accounts.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/BankAccountListItem" } }, "pagination": { "$ref": "#\/components\/schemas\/BankAccountPagination" } }, "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" } } } } } } }, "\/currencies": { "get": { "operationId": "v1.currencies.list", "description": "Returns the currencies configured for the company, with `ALL` always first and the rest by\ncode.\n\nUse it to fill the currency picker in your system: `code` is the ISO 4217 code you\nsend as `currency` on invoices and products. Without `currency`, `ALL` is used. For the day's\nrate, call `GET \/exchange-rates`.\n\n- `id` is the currency's id in fature.al; `name` holds the same value as `code`.\n- The list changes only when the business adds a currency from the dashboard, so cache it.", "summary": "List currencies", "tags": [ "Currencies" ], "responses": { "200": { "description": "The currencies configured for the company, with `ALL` first and the rest by code.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "currencies": { "type": "array", "items": { "$ref": "#\/components\/schemas\/CurrencyListItem" } } }, "required": [ "currencies" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/exchange-rates": { "get": { "operationId": "v1.exchange-rates", "description": "Returns the day's selling rate for each currency, in lek per unit of the currency, from the\nselected source. The data comes from kursi.al and is cached on the server for one hour.\n\nUse it to suggest `exchange_rate` when you issue an invoice in a foreign currency. The rate that\ngoes on the invoice is the one you send, not this one.\n\n| `source` | Source |\n| --- | --- |\n| `BOA` | Bank of Albania, official rate |\n| `BKT` | Banka Komb\u00ebtare Tregtare |\n| `Iliria98` | Iliria '98 currency exchange |\n| `ADON` | Adon currency exchange |\n\n- `source` is case-sensitive: `bkt` is not recognized. An unrecognized source does not return an error;\n `BOA` is used, and `source` in the response says which source was used.\n- `rates` is an object with the currency code as key and the rate as value, always with `ALL: 1`.\n `EUR: 98.5` means one euro is worth 98.5 lek.\n- `fetchedAt` is the response time, ISO 8601.\n\nWhen kursi.al cannot be reached, `rates` holds only `ALL: 1`, with no error, for up to one hour. Do not\ntreat it as a rate: keep the last complete snapshot and use that.", "summary": "Get the day's exchange rates", "tags": [ "Currencies" ], "parameters": [ { "name": "source", "in": "query", "description": "The rate source: `BOA`, `BKT`, `Iliria98` or `ADON`, with the letters exactly as shown. Any other value falls back to `BOA`.", "schema": { "type": "string", "default": "BOA" }, "example": "BOA" } ], "responses": { "200": { "description": "The day's selling rate for each currency from the `source`, always with `ALL: 1`; when kursi.al cannot be reached, `rates` holds only `ALL: 1`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ExchangeRateSnapshot" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/invoice\/wtn": { "get": { "operationId": "v1.invoice.wtn.list", "description": "Returns the company's warehouse transfer notes, newest first, filtered by creation\ndate. Each note comes complete, with `origin`, `destination`, `carrier`, `fiscal` and `lines`,\nso the lines do not need a second call.\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.\n\n`fiscal.status` is `FISCALIZED` or `UNFISCALIZED`, and `print` is the address of the note's\nprint data.", "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": "2025-01-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`.", "schema": { "type": "string" }, "example": "2025-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" } } } } } }, "post": { "operationId": "v1.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- `vehPlates`, the vehicle's license plate;\n- `valueOfGoods`, the value of the goods in transit;\n- `invoice_lines`, at least one line.\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`, `number`, `iic`, `fic`, `fiscalStatus`, `verifyURL` and `print`. Store\nthe `id` and the `iic`. When the CIS cannot be reached, the note is saved unfiscalized, with\n`fic: null` and `fiscalStatus: UNFISCALIZED`; fiscalization is done later from the fature.al\ndashboard, and you read the state in `fiscal.status` with `GET \/invoice\/wtn\/{id}\/details`. When\nthe CIS rejects the note, 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. 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" } } } } } } }, "\/invoice\/wtn\/{id}\/details": { "get": { "operationId": "v1.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 it 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" } } } } } } }, "\/invoice\/wtn\/print\/{id}": { "get": { "operationId": "v1.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" } } } } } } }, "\/purchase-invoices": { "get": { "operationId": "v1.purchase-invoices.list", "description": "Returns the invoices that suppliers have issued to your company, read from the CIS. The supplier\ndoes not send you anything: the documents are fetched from the central fiscalization system, each with the\nfull data, the seller, the buyer, the items, VAT and payment methods.\n\nUse it to reconcile purchases and deductible VAT without any manual step.\n\n- Pagination uses `page`, starting at `1`, not `limit` and `offset`, because the list comes from\n the CIS and not from fature.al. Repeat with `page + 1` until `items` comes back empty.\n- Without `fromDate` and `toDate` only today is read, not the whole history.\n- `fic` narrows the list to a single invoice.\n- `pagination.records` is the CIS count for the page. A document whose details cannot be\n reached is dropped from `items` without an error, so `items` can be shorter than `records`.\n- The details of each invoice are cached for one hour.\n\nStore `iic` and `fic`: they let you find the invoice again, and `fic` also serves as a filter here.", "summary": "List purchase invoices", "tags": [ "Purchase invoices" ], "parameters": [ { "name": "page", "in": "query", "description": "The page of the list from the CIS, starting at 1. Repeat with `page + 1` until `items` comes back empty.", "schema": { "type": "integer", "default": 1 }, "example": 1 }, { "name": "fromDate", "in": "query", "description": "Start date, `YYYY-MM-DD`. Defaults to today.", "schema": { "type": "string" }, "example": "2026-07-01" }, { "name": "toDate", "in": "query", "description": "End date, `YYYY-MM-DD`. Defaults to today.", "schema": { "type": "string" }, "example": "2026-07-15" }, { "name": "fic", "in": "query", "description": "Return only the invoice with this FIC.", "schema": { "type": "string" }, "example": "8a941d47-7d47-4b7e-8f3a-1c2d3e4f5a6b" } ], "responses": { "200": { "description": "The page's purchase invoices in `items`, each one complete, with `pagination`; `items` is empty when the page has no invoices.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#\/components\/schemas\/PurchaseInvoiceItem" } }, "pagination": { "$ref": "#\/components\/schemas\/PurchaseInvoicePagination" } }, "required": [ "items", "pagination" ] } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The dates are not in `YYYY-MM-DD` format.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "500": { "description": "Unexpected server error.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "502": { "description": "The CIS responded with an error; the reason is in `message`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "503": { "description": "The fiscalization service could not be reached. Try again later.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/reports\/sales-summary": { "get": { "operationId": "v1.reports.sales-summary", "description": "Sales totals for a period: the number of invoices, gross, net, VAT and the average invoice\nvalue, broken down at once by payment method, invoice type, VAT rate\nand day.\n\nUse it for periodic reconciliation or for a sales dashboard. For a single cash register day\nuse `GET \/reports\/cash-register`.\n\nThe totals include only invoices that are not canceled. `cancelled` holds the count and value of the invoices\ncanceled in the period, so you do not need a second call to check them.", "summary": "Get the sales summary", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "The period's sales summary in `data`: `totals`, the breakdowns by payment method, invoice type, VAT rate and day, and `cancelled`; the breakdowns are empty when the period has no sales.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportSalesSummary" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing, or is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/top-products": { "get": { "operationId": "v1.reports.top-products", "description": "The period's products ranked by revenue or by quantity sold, with `quantity`\nand `revenue` for each.\n\n| Parameter | Values | Default |\n| --- | --- | --- |\n| `sort` | `revenue`, `quantity` | `revenue` |\n| `limit` | `1` to `200` | `20` |\n\n`sort` and `limit` are echoed back together with `period`.", "summary": "List the best-selling products", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "limit", "in": "query", "description": "How many products to return, from 1 to 200.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 200 }, "example": 20 }, { "name": "sort", "in": "query", "description": "The ordering: `revenue` by revenue, `quantity` by quantity. Defaults to `revenue`.", "schema": { "type": [ "string", "null" ], "enum": [ "quantity", "revenue", null ] }, "example": "revenue" } ], "responses": { "200": { "description": "The period's products in `items`, best-selling first according to `sort`, up to `limit`; `items` is empty when the period has no sales.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportTopProducts" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing or is not in the `YYYY-MM-DD` format, or `limit` and `sort` are outside the allowed values. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/top-clients": { "get": { "operationId": "v1.reports.top-clients", "description": "The period's clients ranked by invoiced value, with the number of invoices and the gross amount for\neach.\n\n- `limit` accepts `1` to `500`, with `20` as the default.\n- The walk-in customer, that is invoices without a named buyer, is not included in the ranking.", "summary": "List the top clients", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "limit", "in": "query", "description": "How many rows to return, from 1 to 500.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "example": 20 } ], "responses": { "200": { "description": "The period's clients in `items`, highest gross value first, up to `limit`; `items` is empty when the period has no sales.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportTopClients" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing or is not in the `YYYY-MM-DD` format, or `limit` is outside `1` to `500`. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/vat": { "get": { "operationId": "v1.reports.vat", "description": "The VAT collected on sales against the VAT paid on purchases for the period, with the resulting\ndifference in `summary.vat_due`.\n\nThe rows are split into two groups, both for sales and for purchases in `purchases`:\n\n- `taxable`, by rate: `0`, `6`, `10`, `20`;\n- `exempt`, by exemption type.\n\nPurchases come from the purchase invoices registered by the CIS, so the report covers both\nsides without asking you to import anything.", "summary": "Get the VAT report", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "The VAT report in `data`: sales in `totals`, `taxable` and `exempt`, purchases in `purchases`, and the difference in `summary.vat_due`.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportVat" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing, or is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/daily-trend": { "get": { "operationId": "v1.reports.daily-trend", "description": "One point for each day of the period, ready for a chart.\n\n| `metric` | What the point measures |\n| --- | --- |\n| `gross` | Gross sales value, the default |\n| `count` | Number of invoices |\n\nDays without sales are returned with the value `0` and are not dropped from the series, so the chart is not\ndistorted. Each point carries `date`, `count` and `gross`, and `metric` is echoed back.", "summary": "Get the daily trend", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "metric", "in": "query", "description": "What the series measures: `gross` the gross value, `count` the number of invoices. Defaults to `gross`.", "schema": { "type": [ "string", "null" ], "enum": [ "gross", "count", null ] }, "example": "gross" } ], "responses": { "200": { "description": "One point for each day of the period in `series`, in chronological order, with `0` for days without sales; `metric` is echoed back.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportDailyTrend" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing or is not in the `YYYY-MM-DD` format, or `metric` is neither `gross` nor `count`. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/by-operator": { "get": { "operationId": "v1.reports.by-operator", "description": "How many invoices each operator issued and how much value they generated in the period, with `operator_code` next to the\nname.\n\nUse it to compare shifts or for sales-based bonuses.", "summary": "Get sales by operator", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "The period's operators in `items`, highest gross value first; `items` is empty when the period has no sales.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportByOperator" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing, or is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/by-tcr": { "get": { "operationId": "v1.reports.by-tcr", "description": "How many invoices each fiscal device (TCR) issued and how much value it generated in the period.\n\nA business with several units uses it to split sales by point of sale, because each TCR\nbelongs to a single unit.", "summary": "Get sales by fiscal device", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "The period's fiscal devices in `items`, highest gross value first; `items` is empty when the period has no cash invoices.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportByTcr" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing, or is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/reversals": { "get": { "operationId": "v1.reports.reversals", "description": "The invoices canceled in the period, each with `original_invoice_id`, the original invoice it\ncorrects, and `reversed_at`. `totals` holds their count and value.\n\n- `limit` accepts `1` to `500`, with `100` as the default.\n- Use it to see how much and why invoices are canceled: a high number of cancellations is usually\n a sign of a problem in the sales process.", "summary": "List canceled invoices", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" }, { "name": "limit", "in": "query", "description": "How many rows to return, from 1 to 500.", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 }, "example": 20 } ], "responses": { "200": { "description": "The period's canceled invoices in `items`, most recent cancellation first, up to `limit`, with `totals` over all cancellations; `items` is empty when there are no cancellations.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportReversals" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing or is not in the `YYYY-MM-DD` format, or `limit` is outside `1` to `500`. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/wtn": { "get": { "operationId": "v1.reports.wtn", "description": "The period's warehouse transfer notes (WTN), grouped by fiscal status in `by_status`, together\nwith the destinations used and the value of the goods moved.\n\nAn unfiscalized note here needs attention: the goods moved without the document the law\nrequires.", "summary": "Get the warehouse transfer notes report", "tags": [ "Reports" ], "parameters": [ { "name": "from", "in": "query", "required": true, "description": "Start date, `YYYY-MM-DD`, inclusive. Required.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-01" }, { "name": "to", "in": "query", "required": true, "description": "End date, `YYYY-MM-DD`, inclusive. Required. When it is before `from`,\nthe two are swapped.", "schema": { "type": "string", "format": "date" }, "example": "2026-01-31" } ], "responses": { "200": { "description": "The period's warehouse transfer notes in `data`: `totals`, the breakdown by fiscal status in `by_status` and the destination cities in `destinations`; `by_status` and `destinations` are empty when the period has no notes.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportWtn" } }, "required": [ "status", "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`from` or `to` is missing, or is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/cash-register": { "get": { "operationId": "v1.reports.cash-register", "description": "The balance of the user's cash register for a single day: the opening, the closing and the expected\nclosing, together with sales by payment method and money movements.\n\nThe expected closing, `expected_closing`, is what the register should hold if everything was\nrecorded. The difference from the actual closing is exactly what reconciliation looks for.\n\n- Without `date`, today is used. The format is `YYYY-MM-DD`.\n- The report belongs to the fiscal device of the token's user. Without a fiscal device, or when\n the ALL currency is not configured, the cash register is not available and the response comes back with\n `200` and `status: false`.", "summary": "Get the cash register balance for a day", "tags": [ "Reports" ], "parameters": [ { "name": "date", "in": "query", "description": "The report day, `YYYY-MM-DD`. Defaults to today.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "The day's cash register balance in `data`, with `sales_by_method` and `movements`; without a fiscal device, or when the ALL currency is not configured, the response comes back with HTTP 200 and `status: false`, with the reason in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportCashRegister" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`date` is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/reports\/cash-register\/closing": { "get": { "operationId": "v1.reports.cash-register.closing", "description": "The end-of-day report, the one printed when the shift closes: sales totals, products\nsold and money movements, with the shift's `opened_at` and `closed_at`.\n\nThe difference from the cash register balance is the focus: this report belongs to the shift that closed, not to the day as a\nperiod.\n\n- Without `date`, today is used. The format is `YYYY-MM-DD`.\n- The report belongs to the fiscal device of the token's user. Without a fiscal device, or when\n the ALL currency is not configured, the cash register is not available and the response comes back with\n `200` and `status: false`.", "summary": "Get the cash register closing report", "tags": [ "Reports" ], "parameters": [ { "name": "date", "in": "query", "description": "The report day, `YYYY-MM-DD`. Defaults to today.", "schema": { "type": [ "string", "null" ], "format": "date" }, "example": "2026-04-21" } ], "responses": { "200": { "description": "The shift closing report in `data`, with `sales`, `sales_by_method`, `products_sold` and `movements`; without a fiscal device, or when the ALL currency is not configured, the response comes back with HTTP 200 and `status: false`, with the reason in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/ReportCashRegisterClosing" } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "`date` is not in the `YYYY-MM-DD` format. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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" } } } } } } }, "\/dashboard\/summary": { "get": { "operationId": "v1.dashboard.summary", "description": "Returns a quick view of today for the home screen, in three objects:\n\n| Object | Contents |\n| --- | --- |\n| `shift` | `is_open`, `opened_at`, `cash_in_drawer` and `currency` for the user's fiscal device. Without a device, `is_open` is `false` and `cash_in_drawer` is `0`. |\n| `today` | `invoice_count`, `gross_total` and `hourly_series`, one point for every two hours with `hour` and `gross`. |\n| `week` | `series`, one point for each of the last 7 days with `date` and `gross`, and `wow_delta_percent`, the percentage change against the previous 7 days, `null` when those have no sales. |\n\nSales count cash invoices, non-cash invoices and e-invoices, excluding order invoices and\ncanceled invoices. Amounts are in ALL.\n\nThe response is cached for 5 seconds per user, so it is not a source for reconciliation:\nfor exact figures over a period use the reports.", "summary": "Get the daily summary", "tags": [ "Dashboard" ], "responses": { "200": { "description": "The daily summary in `data`, in three objects: `shift`, `today` and `week`; the figures can be up to 5 seconds old from the cache.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "$ref": "#\/components\/schemas\/DashboardSummary" } }, "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" } } } } } } }, "\/register": { "get": { "operationId": "v1.pong", "description": "Returns `pong` when the token's account is allowed to register companies. Call it before the\nfirst step, to know whether the group is open to you.\n\nThe group is closed by default and is opened on request, either for the token of a single\noperator or for all operators of your company.", "summary": "Check registration access", "tags": [ "Company registration" ], "responses": { "200": { "description": "When your account is not authorized for registration, the response comes back with HTTP 200 and `status: false`; the reason is in `message`.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } }, "post": { "operationId": "v1.register", "description": "Creates a new company in fature.al, with the first user, the first business unit,\nthe walk-in customer, the currencies and an active subscription. It is the first step of registration; the other\nsteps are called with the token it returns.\n\nUse it only for businesses that are not yet on fature.al. For an existing company\nuse the `POST \/on-boarding\/*` endpoints directly with its token.\n\n- The token's account must be authorized for registration; otherwise the request is rejected\n with `200` and `status: false`.\n- `nuis` must be a NIPT not yet registered on fature.al and known to the tax\n administration. Lowercase letters are accepted and converted to uppercase.\n- `email` becomes the email and username of the first user, so it must be unused on\n fature.al.\n- `lastNonCashEInvoiceNumber` sets the number from which the numbering of non-cash invoices\n and e-invoices continues for the current year.\n\nThe response carries `user.token`, the API token of the first user, and `branch.id`, the id of the\nbusiness unit. Store both: the token is shown only here and is used for all the other\nsteps, while the business unit id is needed for `POST \/on-boarding\/branch\/{id}`,\n`POST \/on-boarding\/user` and `POST \/on-boarding\/fiscal-device`.\n\n## Sandbox\n\nIn sandbox, the NIPT `L62221018T` goes through a test flow: no new company is created, only\na user and a business unit under the sandbox company, and `user.token` is a real token\nfor the other steps. The suffix `+sandbox-XXXXXXXX` is added to the email, so you can send the\nsame email as many times as you like. In live this NIPT is treated like any other NIPT.", "summary": "Register a company", "tags": [ "Company registration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/RegisterCompanyRequest" } } } }, "responses": { "200": { "description": "When the account is not authorized for registration, when the NIPT is already registered or is not found at the tax administration, or when the email is in use, 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": { "user": { "$ref": "#\/components\/schemas\/OnboardingRegisteredUser" }, "branch": { "$ref": "#\/components\/schemas\/OnboardingRegisteredBranch" } }, "required": [ "user", "branch" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/on-boarding\/certificate": { "post": { "operationId": "v1.on-boarding.certificate", "description": "Uploads the company's electronic certificate (`.p12` or `.pfx`) together with its password.\nEvery document sent to the CIS is signed with it, so it is the first step after registration.\n\n- `certificate_file` is the certificate file and `password` is its password.\n- The password must open the certificate.\n- The NIPT inside the certificate must match the company's NIPT.\n\nThe response returns `expiresAt`, the certificate's expiry date. Store it: after that date\nfiscalization stops until a new certificate is uploaded.\n\nIn sandbox any certificate and any password is accepted, and `expiresAt` is one year from today.", "summary": "Upload the electronic certificate", "tags": [ "Company registration" ], "requestBody": { "content": { "multipart\/form-data": { "schema": { "$ref": "#\/components\/schemas\/CertificateRequest" } } } }, "responses": { "200": { "description": "When the password is wrong, when the certificate's NIPT does not match the company, or when saving fails, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "cert": { "$ref": "#\/components\/schemas\/OnboardingCertificate" } }, "required": [ "cert" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } }, "\/on-boarding\/branch": { "post": { "operationId": "v1.on-boarding.branch-create", "description": "Creates a new business unit for the company. Used when the company has more than one point of\nsale: the first unit is created by `POST \/register` itself, and for that one you only set the code with\n`POST \/on-boarding\/branch\/{id}`.\n\n- `name`, `type`, `administrator` and `address` are required.\n- `type` is `main` for the headquarters or `secondary` for a secondary unit. The company has\n a single headquarters, so `main` is rejected with `409` when one already exists.\n- The number of units depends on the subscription; when the limit is reached, the request is rejected with `403`.\n- `businessUnitCode` can be sent now or later with `POST \/on-boarding\/branch\/{id}`, but\n without it the unit cannot issue invoices.\n\nStore the returned `id`: the unit's users and fiscal devices are linked to it.", "summary": "Create a business unit", "tags": [ "Company registration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/CreateBranchRequest" } } } }, "responses": { "200": { "description": "When saving fails for another reason, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "branch": { "$ref": "#\/components\/schemas\/OnboardingBranchCreated" } }, "required": [ "branch" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "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": "The company already has a headquarters.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/on-boarding\/branch\/{id}": { "post": { "operationId": "v1.on-boarding.branch", "description": "Sets or changes the name, address, administrator and code of a business unit. The\nusual step is `businessUnitCode`, the business unit code obtained from self-care: without it the unit cannot\nissue invoices.\n\n- `name`, `businessUnitCode`, `administrator` and `address` are all optional; a field\n that is not sent stays as it is.\n- The body is not validated separately, so there is no `422` response.\n\nA unit that is not found, or does not belong to your company, comes back with `200` and\n`status: false`.", "summary": "Update a business unit", "tags": [ "Company registration" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the business unit.", "schema": { "type": "integer" }, "example": 12 } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the business unit. If omitted, the existing one is kept.", "examples": [ "Dyqani Qend\u00ebr" ] }, "address": { "type": "string", "description": "The address of the unit. If omitted, the existing one is kept.", "examples": [ "Rruga e Kavaj\u00ebs 12, Tiran\u00eb" ] }, "administrator": { "type": "string", "description": "The administrator of the unit. If omitted, the existing one is kept.", "examples": [ "Arben Hoxha" ] }, "businessUnitCode": { "type": "string", "description": "The business unit code, obtained from self-care. Required for issuing invoices from this unit.", "examples": [ "bb123bb123" ] } } } } } }, "responses": { "200": { "description": "When the unit is not found, does not belong to your company, or saving fails, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "branch": { "$ref": "#\/components\/schemas\/OnboardingBranchUpdated" } }, "required": [ "branch" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/on-boarding\/user": { "post": { "operationId": "v1.on-boarding.user", "description": "Creates an operator user for the company and returns its token. Every person who issues\ninvoices has their own user, because the operator code and the fiscal device belong to the user.\n\n- `email` is required and unique across all of fature.al, not only within the company.\n- `branchId` must be a unit of your company.\n- `operatorCode` is obtained from self-care. For cash invoices also send `fiscalTcrCode`, the code\n returned by `POST \/on-boarding\/fiscal-device`; a code that is not found leaves the user without a device,\n without an error.\n- `name` and `phone` are optional.\n- The body is not validated separately, so every rejection comes with `200` and `status: false`.\n\nStore the `token`: it is returned only once and it is the one this user calls the API with.", "summary": "Create a user", "tags": [ "Company registration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The user's name.", "examples": [ "Ana Hoxha" ] }, "email": { "type": "string", "description": "The user's email, unique on fature.al. Used for identification; the token is returned in the response.", "examples": [ "ana@shembull.al" ] }, "phone": { "type": "string", "description": "The phone number.", "examples": [ "0691234567" ] }, "branchId": { "type": "integer", "description": "The id of the business unit where the user works.", "examples": [ 12 ] }, "operatorCode": { "type": "string", "description": "The operator code, obtained from self-care. Required for issuing invoices.", "examples": [ "aa123aa123" ] }, "fiscalTcrCode": { "type": "string", "description": "The TCR code of the fiscal device the user will use. Only for cash invoices.", "examples": [ "ab123ab123" ] } }, "required": [ "name", "email", "branchId" ] } } } }, "responses": { "200": { "description": "When `email` is missing or in use, when the unit is not found, or when saving fails, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "$ref": "#\/components\/schemas\/OnboardingUserCreated" } }, "required": [ "user" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/on-boarding\/user\/{id}": { "post": { "operationId": "v1.on-boarding.user-update", "description": "Sets the name, unit, operator code and fiscal device of a user. This is where the\nfirst user, the one created by `POST \/register`, is linked to `operatorCode` and, for cash invoices, to\n`fiscalTcrCode`.\n\n- `operatorCode` is the operator code obtained from self-care; without it the user cannot issue\n invoices.\n- `fiscalTcrCode` is the code returned by `POST \/on-boarding\/fiscal-device` and must be sent on\n every call: without it, or with a code not found among the company's devices, the user\n is left without a fiscal device, without an error.\n- `branchId` must be a unit of your company; otherwise the request is rejected with `200` and\n `status: false`.\n- `name`, `branchId` and `operatorCode` that are not sent stay as they are.\n- The body is not validated separately, so there is no `422` response.", "summary": "Update a user", "tags": [ "Company registration" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id of the user.", "schema": { "type": "integer" }, "example": 7 } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The user's name. If omitted, the existing one is kept.", "examples": [ "Ana Hoxha" ] }, "operatorCode": { "type": "string", "description": "The operator code, obtained from self-care. Required for issuing invoices.", "examples": [ "aa123aa123" ] }, "fiscalTcrCode": { "type": "string", "description": "The TCR code of the fiscal device the user will use, from `POST \/on-boarding\/fiscal-device`. Only for cash invoices.", "examples": [ "ab123ab123" ] }, "branchId": { "type": "integer", "description": "The id of the business unit where the user works. If omitted, the existing one is kept.", "examples": [ 12 ] } } } } } }, "responses": { "200": { "description": "When the user or the unit is not found, or saving fails, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "user": { "$ref": "#\/components\/schemas\/OnboardingUserUpdated" } }, "required": [ "user" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/on-boarding\/fiscal-device": { "post": { "operationId": "v1.on-boarding.fiscal-device", "description": "Registers a fiscal device (TCR) with the CIS for a business unit and returns its code.\nNeeded only for cash invoices; non-cash invoices and e-invoices have no TCR.\n\n- Done after the certificate has been uploaded and the unit has a `businessUnitCode`; without them the CIS\n rejects the registration.\n- `branchId`, `name` and `fromDate` (`YYYY-MM-DD`) are required. `toDate` closes\n the device on that date; without it the device stays active indefinitely.\n- When the unit has reached the number of active devices it is allowed, the request is rejected with `403`.\n\nStore `fiscalTcrCode` and set it on the user who will issue cash invoices, with\n`POST \/on-boarding\/user\/{id}`.\n\nWhen the CIS rejects the registration, the device is not saved and the response comes back with `200` and\n`status: false`. When the CIS cannot be reached, the device is also not saved, but the response comes back\nwith `status: true` and `fiscalTcrCode: null`: check the value, not only `status`, and\ntry again later.", "summary": "Register a fiscal device", "tags": [ "Company registration" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/FiscalDeviceRequest" } } } }, "responses": { "200": { "description": "When the CIS rejects the registration, or when saving fails, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`. When the CIS cannot be reached, `status` is `true` and `fiscalTcrCode` is `null`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "device": { "$ref": "#\/components\/schemas\/OnboardingFiscalDevice" } }, "required": [ "device" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } }, "403": { "description": "The subscription has expired, or the action is not allowed for this account.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiError" } } } } } } }, "\/on-boarding\/bank-account": { "post": { "operationId": "v1.on-boarding.bank-account", "description": "Saves a bank account of the company. The account is printed on non-cash invoices and on e-invoices\nas the place where payment is expected, so it is needed before the first non-cash invoice.\n\n- `iban` and `currency` (the currency code, e.g. `ALL`) are what define the account;\n `name`, `holder`, `swift` and `notes` are descriptive.\n- Spaces in `iban` are removed and letters are uppercased before saving.\n- An IBAN the company already has does not create a second account: the existing one is returned.\n- An unknown currency is rejected with `200` and `status: false`.\n\nStore the returned `id`: with it, or with the IBAN, the account is selected on non-cash invoices and on\ne-invoices.", "summary": "Create a bank account", "tags": [ "Company registration" ], "requestBody": { "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/BankAccountRequest" } } } }, "responses": { "200": { "description": "When the currency is not recognized, or when saving fails, the response comes back with HTTP 200 and `status: false`; the reason is in `message` or in `errors`.", "content": { "application\/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "boolean" }, "data": { "type": "object", "properties": { "bankAccount": { "$ref": "#\/components\/schemas\/OnboardingBankAccount" } }, "required": [ "bankAccount" ] } }, "required": [ "status", "data" ] }, { "$ref": "#\/components\/schemas\/ApiError" } ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "description": "The data failed validation. This response uses the `success` field, not `status`, and `errors` is an object keyed by field.", "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/ApiValidationError" } } } } } } } }, "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": { "AccountBranch": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the business unit.", "examples": [ "Dyqani Qend\u00ebr" ] }, "address": { "type": "string", "description": "The address of the unit.", "examples": [ "Rruga e Kavaj\u00ebs 12, Tiran\u00eb" ] }, "city": { "type": "string", "description": "The city. Currently taken from the company's data, not from the unit.", "examples": [ "Tiran\u00eb" ] } }, "required": [ "name", "address", "city" ], "title": "AccountBranch" }, "AccountConfigs": { "type": "object", "properties": { "openDayAlways0": { "type": "boolean", "description": "true when the company always opens the day at the cash register with a balance of `0`, without asking the operator for\nthe opening balance.", "examples": [ false ] } }, "required": [ "openDayAlways0" ], "title": "AccountConfigs" }, "AccountInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "The full name of the user who holds the token.", "examples": [ "Ana Hoxha" ] }, "email": { "type": "string", "description": "The user's email.", "examples": [ "ana@alpha.al" ] }, "fiscalCode": { "type": "string", "description": "The TCR code of the user's fiscal device. Empty string when the user has no device; in that case\ncash invoices and cash register operations are rejected.", "examples": [ "ab123ab123" ] }, "company": { "type": "string", "description": "The name of the company that issues the invoices.", "examples": [ "Alpha SHPK" ] }, "nipt": { "type": "string", "description": "The company's NIPT.", "examples": [ "L91806031A" ] }, "setupFinished": { "type": "boolean", "description": "true when the company has completed its initial setup and can issue invoices. Becomes true\nwhen the electronic certificate is uploaded.", "examples": [ true ] }, "branch": { "description": "The business unit where the user works.", "$ref": "#\/components\/schemas\/AccountBranch" }, "companyBranches": { "type": "object", "description": "All of the company's business units, as an object with the unit's address as the key and its name\nas the value.", "examples": [ { "Rruga e Kavaj\u00ebs 12, Tiran\u00eb": "Dyqani Qend\u00ebr" } ], "additionalProperties": { "type": "string" } }, "permissions": { "description": "The user's rights that affect the API.", "$ref": "#\/components\/schemas\/AccountPermissions" }, "configs": { "description": "The company's choices for the cash register.", "$ref": "#\/components\/schemas\/AccountConfigs" }, "vatConfigs": { "description": "The VAT scheme and the values accepted on invoice lines.", "$ref": "#\/components\/schemas\/AccountVatConfigs" }, "subscription": { "description": "The invoicing modules the subscription enables for this user.", "$ref": "#\/components\/schemas\/AccountSubscription" } }, "required": [ "name", "email", "fiscalCode", "company", "nipt", "setupFinished", "branch", "companyBranches", "permissions", "configs", "vatConfigs", "subscription" ], "title": "AccountInfo" }, "AccountPermissions": { "type": "object", "properties": { "createArticles": { "type": "boolean", "description": "true when the user has the right to manage products. Without it `POST \/products` is rejected\nwith `403`.", "examples": [ true ] }, "createClients": { "type": "boolean", "description": "true when the user has the right to create clients. Without it `POST \/clients` is rejected with\n`403`.", "examples": [ true ] } }, "required": [ "createArticles", "createClients" ], "title": "AccountPermissions" }, "AccountSubscription": { "type": "object", "properties": { "cash": { "type": "boolean", "description": "true when the user can issue cash invoices and perform cash register operations.", "examples": [ true ] }, "noncash": { "type": "boolean", "description": "true when the user can issue non-cash invoices.", "examples": [ true ] }, "einvoice": { "type": "boolean", "description": "true when the user can issue e-invoices.", "examples": [ true ] }, "wtn": { "type": "boolean", "description": "true when the user can issue warehouse transfer notes (WTN).", "examples": [ false ] } }, "required": [ "cash", "noncash", "einvoice", "wtn" ], "title": "AccountSubscription" }, "AccountVatConfigs": { "type": "object", "properties": { "issuerInVat": { "type": "boolean", "description": "true when the company is in the VAT scheme.", "examples": [ true ] }, "vat_rates": { "type": "array", "description": "The VAT rates, in percent, accepted as `vat_rate` on invoice lines: `20`, `10`, `6`\nand `0` in the VAT scheme; only `0` outside it.", "examples": [ [ 20, 10, 6, 0 ] ], "items": { "type": "integer" } }, "vat_exempts": { "type": "array", "description": "The VAT exemption types accepted as `vat_exempt_type` on invoice lines: in\nthe VAT scheme `TAX_FREE`, `TYPE_1`, `TYPE_2` and `EXPORT_OF_GOODS`; outside it `TAX_FREE`\nand `EXPORT_OF_GOODS`.", "items": { "$ref": "#\/components\/schemas\/AccountVatExempt" } } }, "required": [ "issuerInVat", "vat_rates", "vat_exempts" ], "title": "AccountVatConfigs" }, "AccountVatExempt": { "type": "object", "properties": { "code": { "type": "string", "description": "The exemption code, the one sent as `vat_exempt_type`: `TAX_FREE`, `TYPE_1`, `TYPE_2` or\n`EXPORT_OF_GOODS`.", "examples": [ "TYPE_1" ] }, "label": { "type": "string", "description": "The exemption description, in the account's language.", "examples": [ "P\u00ebrjashtim i llojit 1. (P\u00ebrjashtim n\u00eb baz\u00eb t\u00eb nenit 51 t\u00eb Ligjit p\u00ebr TVSH-n\u00eb.)" ] } }, "required": [ "code", "label" ], "title": "AccountVatExempt" }, "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" }, "BankAccountListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "The account's id in fature.al; the value for `bank_account` when you issue a non-cash invoice or\nan e-invoice.", "examples": [ 17 ] }, "bank_name": { "type": [ "string", "null" ], "description": "The bank's name; `null` when not filled in.", "examples": [ "Raiffeisen Bank Albania" ] }, "iban": { "type": [ "string", "null" ], "description": "The account's IBAN; the value for `bank_account_iban` when you issue a non-cash invoice or an\ne-invoice. `null` when not filled in.", "examples": [ "AL47212110090000000235698741" ] }, "swift": { "type": [ "string", "null" ], "description": "The bank's SWIFT (BIC) code; when it was not filled in for the account, it is taken from the fature.al bank\ncatalog. `null` when unknown.", "examples": [ "SGSBALTX" ] }, "holder": { "type": [ "string", "null" ], "description": "The account holder, the name shown in the payment information on the e-invoice; when missing,\nthe e-invoice carries the bank's name. `null` when not filled in.", "examples": [ "Drini Trade shpk" ] }, "currency_code": { "type": [ "string", "null" ], "description": "The ISO 4217 code of the account's currency; `null` when the account has no currency.", "examples": [ "ALL" ] }, "is_default": { "type": "boolean", "description": "`true` on the company's default account, the one listed first.", "examples": [ true ] }, "notes": { "type": [ "string", "null" ], "description": "Free-form notes about the account; `null` when there are none.", "examples": [ "Llogaria kryesore" ] }, "valid_from": { "type": [ "string", "null" ], "description": "The start of the account's validity period, `YYYY-MM-DD`, as set in the dashboard;\n`null` when not set.", "examples": [ "2024-01-01" ] }, "valid_to": { "type": [ "string", "null" ], "description": "The end of the validity period, `YYYY-MM-DD`; `null` when not set. The list does not\nfilter by it: an account with a past `valid_to` is returned all the same.", "examples": [ "2026-12-31" ] }, "created_at": { "type": [ "string", "null" ], "description": "The date and time the account was created, ISO 8601 with the time zone; `null` for accounts created\nbefore fature.al stored the creation date.", "examples": [ "2024-01-05T09:15:00+01:00" ] } }, "required": [ "id", "bank_name", "iban", "swift", "holder", "currency_code", "is_default", "notes", "valid_from", "valid_to", "created_at" ], "title": "BankAccountListItem" }, "BankAccountPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many accounts `items` holds on this page.", "examples": [ 3 ] }, "total": { "type": "integer", "description": "How many accounts match the request in total, across all pages.", "examples": [ 3 ] }, "limit": { "type": "integer", "description": "The request's `limit` parameter, after clamping between 1 and 100.", "examples": [ 20 ] }, "offset": { "type": "integer", "description": "The request's `offset` parameter, after rounding up to at least 0.", "examples": [ 0 ] } }, "required": [ "records", "total", "limit", "offset" ], "title": "BankAccountPagination" }, "BankAccountRequest": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "The bank's name, the one shown on the invoice next to the IBAN.", "examples": [ "BKT" ] }, "holder": { "type": [ "string", "null" ], "description": "The account holder, usually the company's name.", "examples": [ "Ei3 Software Solution shpk" ] }, "iban": { "type": [ "string", "null" ], "description": "The account's IBAN, the one shown on the invoice so the buyer can pay.", "examples": [ "AL35202111090000000001234567" ] }, "swift": { "type": [ "string", "null" ], "description": "The bank's SWIFT\/BIC code, needed for payments from abroad.", "examples": [ "NCBAALTX" ] }, "currency": { "type": [ "string", "null" ], "description": "The account's currency, an ISO 4217 code. An account holds a single currency.", "examples": [ "ALL" ] }, "notes": { "type": [ "string", "null" ], "description": "Notes that accompany the account on the invoice." } }, "title": "BankAccountRequest" }, "BusinessLookupResult": { "type": "object", "properties": { "nuis": { "type": "string", "description": "The business's NIPT, as it appears in the register.", "examples": [ "L91806031A" ] }, "name": { "type": "string", "description": "The business's name.", "examples": [ "Alpha SHPK" ] }, "address": { "type": "string", "description": "The business's address.", "examples": [ "Rruga e Kavaj\u00ebs 12" ] }, "city": { "type": "string", "description": "The business's city.", "examples": [ "Tiran\u00eb" ] }, "country": { "type": "integer", "description": "The country's id in fature.al, the same one returned as `nationality_id` on clients.", "examples": [ 3 ] }, "country_code": { "type": "string", "description": "The country's ISO 3166-1 alpha-3 code; `ALB` for a business that comes from the fiscal register.", "examples": [ "ALB" ] }, "verified": { "type": "boolean", "description": "true: the business was confirmed, by the fiscal register or by a client previously verified on\nfature.al. A NIPT that is not confirmed is not returned with 200, but with `404`.", "examples": [ true ] } }, "required": [ "nuis", "name", "address", "city", "country", "country_code", "verified" ], "title": "BusinessLookupResult" }, "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" }, "CashAction": { "type": "object", "properties": { "id": { "type": "integer", "description": "The action's id in fature.al. Missing when the CIS could not be reached at the time of the call;\nread it later from `GET \/cash-register\/actions`.", "examples": [ 5120 ] }, "action_type": { "type": "string", "description": "Action type: `MONEY_IN` cash in, from `POST \/cash-register\/deposit`; `MONEY_OUT`\ncash out, from `POST \/cash-register\/withdraw`.", "examples": [ "MONEY_IN" ] }, "amount": { "type": "number", "description": "Action amount, always positive, in lek; `action_type` gives the direction.", "examples": [ 1500 ] }, "currency": { "type": "string", "description": "ISO 4217 code of the action's currency. Through the API, actions are recorded only in lek, so\nthis is always `ALL`.", "examples": [ "ALL" ] }, "transaction_date": { "type": "string", "description": "Action date, `YYYY-MM-DD`: the day it was recorded.", "examples": [ "2026-09-14" ] }, "transaction_no": { "type": "integer", "description": "Sequence number of the action within the company: counts all of the company's cash register actions,\nof every type and every fiscal device (TCR). Missing when the CIS could not be reached.", "examples": [ 812 ] }, "cash_action_no": { "type": "string", "description": "Action number, `n\/year\/TCR code`: `n` starts at 1 every year, separately for each action type and\neach fiscal device (TCR). Missing when the CIS could not be reached.", "examples": [ "12\/2026\/pp556gh743" ] }, "fiscal_status": { "type": [ "string", "null" ], "description": "Fiscal status: `FISCALIZED` when the CIS has registered the action, `UNFISCALIZED` while it\nis waiting for fiscalization, which fature.al retries on its own. When the CIS could not be reached at the time of\nthe call, this response returns it as `UNFISCALISED`.", "examples": [ "FISCALIZED" ] }, "fiscal_uuid": { "type": [ "string", "null" ], "description": "The UUID fature.al assigns to the action when sending it to the CIS, the same one sent as the UUID of the\n`RegisterCashDeposit` request. `null` when the action has not been sent to the CIS yet.", "examples": [ "3f2c9a4e-6b1d-4c8e-9a7f-2d5e8b1c4a60" ] }, "fiscal_fic": { "type": [ "string", "null" ], "description": "The FCDC code the CIS returns when it registers the action. `null` while the action is waiting for fiscalization;\nit also stays `null` when the CIS answered with one of the errors 56, 63 or 920, which fature.al\ncloses as `FISCALIZED` without a code.", "examples": [ "b6e1f2a3-9c4d-4e5f-8a7b-1c2d3e4f5a6b" ] }, "description": { "type": [ "string", "null" ], "description": "Action description, as sent in `description`; `null` when not sent. When\nthe CIS could not be reached at the time of the call, it comes back as an empty string instead of `null`.", "examples": [ "Arketim nga klienti" ] } }, "required": [ "id", "action_type", "amount", "currency", "transaction_date", "transaction_no", "cash_action_no", "fiscal_status", "fiscal_uuid", "fiscal_fic", "description" ], "title": "CashAction" }, "CashActionListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "The action's id in fature.al.", "examples": [ 5120 ] }, "action_type": { "type": "string", "description": "Action type: `MONEY_IN` cash in, `MONEY_OUT` cash out, `OPEN_DAY` opening the\nday, `CLOSE_DAY` closing the day. Without the `type` filter the list returns every cash register action, including\ntypes recorded only from the dashboard, such as `INITIAL_OPEN_BALANCE` (the first opening of the cash register) and\n`MONEY_IN_TRANSFER` (money moved in from another cash register).", "examples": [ "MONEY_IN" ] }, "amount": { "type": "number", "description": "Action amount, always positive, in the `currency` currency; `action_type` gives the direction.", "examples": [ 1500 ] }, "currency": { "type": "string", "description": "ISO 4217 code of the action's currency; `ALL` on every action recorded through the API.", "examples": [ "ALL" ] }, "transaction_date": { "type": "string", "description": "Action date, `YYYY-MM-DD`: the day it was recorded.", "examples": [ "2026-09-14" ] }, "transaction_no": { "type": "integer", "description": "Sequence number of the action within the company: counts all of the company's cash register actions,\nof every type and every fiscal device (TCR).", "examples": [ 812 ] }, "cash_action_no": { "type": "string", "description": "Action number, `n\/year\/TCR code`: `n` starts at 1 every year, separately for each action type and\neach fiscal device (TCR).", "examples": [ "12\/2026\/pp556gh743" ] }, "fiscal_status": { "type": [ "string", "null" ], "description": "Fiscal status: `FISCALIZED` when the CIS has registered the action, `UNFISCALIZED` while it\nis waiting for fiscalization, which fature.al retries on its own.", "examples": [ "FISCALIZED" ] }, "fiscal_uuid": { "type": [ "string", "null" ], "description": "The UUID fature.al assigns to the action when sending it to the CIS, the same one sent as the UUID of the\n`RegisterCashDeposit` request. `null` when the action has not been sent to the CIS yet.", "examples": [ "3f2c9a4e-6b1d-4c8e-9a7f-2d5e8b1c4a60" ] }, "fiscal_fic": { "type": [ "string", "null" ], "description": "The FCDC code the CIS returns when it registers the action. `null` while the action is waiting for fiscalization;\nit also stays `null` when the CIS answered with one of the errors 56, 63 or 920, which fature.al\ncloses as `FISCALIZED` without a code.", "examples": [ "b6e1f2a3-9c4d-4e5f-8a7b-1c2d3e4f5a6b" ] }, "fiscal_tcr_code": { "type": [ "string", "null" ], "description": "Code of the fiscal device (TCR) where the action was recorded. For an administrator the list covers\nall of the company's cash registers, so this field tells which one the action belongs to. `null` on an action\nsaved without a fiscal device.", "examples": [ "pp556gh743" ] }, "description": { "type": [ "string", "null" ], "description": "Action description: the one sent in `description`, or the one fature.al sets itself on\nits own actions, such as \"Mbyllje turni\/xhiro ditore\" on closing the day and \"Hapje e gjendjes fillestare\" on opening with a balance. `null` when there is none.", "examples": [ "Arketim nga klienti" ] }, "third_party": { "type": [ "string", "null" ], "description": "The action's third party, as sent in `third_party`; when the action was linked to a\nclient (`id_client`), it is replaced by the client's name. `null` when there is none.", "examples": [ "Alba Market shpk" ] }, "id_client": { "type": [ "integer", "null" ], "description": "Id of the client linked to the action, as sent in `id_client`; `null` when the action has\nno client.", "examples": [ 42 ] }, "created_at": { "type": "string", "description": "Date and time of recording, `YYYY-MM-DD HH:MM:SS`, local time. The balance from\n`GET \/cash-register\/balance` with `toDate` is computed on this time, not on `transaction_date`.", "examples": [ "2026-09-14 10:15:00" ] } }, "required": [ "id", "action_type", "amount", "currency", "transaction_date", "transaction_no", "cash_action_no", "fiscal_status", "fiscal_uuid", "fiscal_fic", "fiscal_tcr_code", "description", "third_party", "id_client", "created_at" ], "title": "CashActionListItem" }, "CashActionPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many actions `items` holds on this page.", "examples": [ 20 ] }, "limit": { "type": "integer", "description": "The request's `limit` parameter, after rounding up to at least 1.", "examples": [ 20 ] }, "offset": { "type": "integer", "description": "The request's `offset` parameter, after rounding up to at least 0.", "examples": [ 0 ] }, "type": { "type": [ "string", "null" ], "description": "The `type` filter as sent, `null` when not sent.", "examples": [ "MONEY_IN,MONEY_OUT" ] } }, "required": [ "records", "limit", "offset", "type" ], "title": "CashActionPagination" }, "CashActionRequest": { "type": "object", "properties": { "amount": { "type": "number", "description": "The amount, always positive, in ALL. Whether it is cash in or cash out is decided by the endpoint you call,\nnot by the sign of the number.", "examples": [ 1500 ] }, "description": { "type": [ "string", "null" ], "description": "Action description.", "examples": [ "Arketim nga klienti" ], "maxLength": 255 }, "third_party": { "type": [ "string", "null" ], "description": "The action's third party: who brought or who took the money.", "examples": [ "Klienti XYZ" ], "maxLength": 255 }, "id_client": { "type": [ "integer", "null" ], "description": "Client: the id of one of your clients in fature.al, to link the action to it.\nReturned later in the list of actions. An id that does not belong to your company is rejected.", "examples": [ 42 ] } }, "required": [ "amount" ], "title": "CashActionRequest" }, "CashInvoice": { "type": "object", "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" ] }, "payment_method": { "type": "string", "description": "Payment method: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` or `ORDER`.\nRequired.", "enum": [ "BANKNOTE", "CARD", "CHECK", "SVOUCHER", "COMPANY", "ORDER" ], "examples": [ "BANKNOTE" ] }, "company_card": { "type": [ "string", "null" ], "description": "Company card. Required only with `COMPANY` and rejected with any other payment\nmethod. Up to 50 characters.", "examples": [ "4111-2233" ], "maxLength": 50 }, "vouchers": { "type": [ "array", "null" ], "description": "Voucher serial numbers, in the form number-year-NIPT, no repeats, up to 20.\nRequired only with `SVOUCHER` and rejected with any other payment method.", "examples": [ [ "12-2026-K51501011M" ] ], "items": { "type": "string", "description": "A voucher, in the form number-year-NIPT. Must not repeat within the invoice.", "pattern": "^[1-9][0-9]{0,7}-[0-9]{4}-[a-zA-Z][0-9]{8}[a-zA-Z]$" }, "maxItems": 20, "uniqueItems": true }, "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" ] } }, "required": [ "internalId", "payment_method", "lines" ], "title": "CashInvoice" }, "CashRegisterBalance": { "type": "object", "properties": { "fiscal_tcr_code": { "type": "string", "description": "Code of the fiscal device (TCR) of the token's user, the one the balance was computed\nfor.", "examples": [ "pp556gh743" ] }, "currency": { "type": "string", "description": "ISO 4217 code of the balance currency; always `ALL`.", "examples": [ "ALL" ] }, "to_date": { "type": [ "string", "null" ], "description": "The request's `toDate` parameter as sent, `YYYY-MM-DD`: the balance is the one at the end\nof that day, with every action and invoice recorded up to 23:59:59. `null` when it was not\nsent and the balance is the current one.", "examples": [ "2026-09-14" ] }, "balance": { "type": "number", "description": "The balance, in lek, with two decimal places: cash in minus cash out recorded on this TCR\nplus the cash invoices issued from it, where self-invoices are subtracted and order invoices are not\nincluded.", "examples": [ 23450.5 ] } }, "required": [ "fiscal_tcr_code", "currency", "to_date", "balance" ], "title": "CashRegisterBalance" }, "CashRegisterCloseBalance": { "type": "object", "properties": { "balance": { "type": "number", "description": "The amount taken out of the cash register, in lek: the balance of the fiscal device (TCR) at the moment of closing,\nrecorded as a `MONEY_OUT` cash out. `0` when the cash register was empty; then no\ncash out is recorded.", "examples": [ 23450.5 ] } }, "required": [ "balance" ], "title": "CashRegisterCloseBalance" }, "CashRegisterOpenBalance": { "type": "object", "properties": { "balance": { "type": "number", "description": "The day's opening balance, in lek, as accepted from the request's `balance`; `0` when\n`balance` was not sent.", "examples": [ 5000 ] } }, "required": [ "balance" ], "title": "CashRegisterOpenBalance" }, "CertificateRequest": { "type": "object", "properties": { "certificate_file": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application\/octet-stream", "description": "The business's electronic certificate as a file (.p12 or .pfx). It signs every\ninvoice sent for fiscalization; without a valid certificate no invoice can be issued." }, "password": { "type": [ "string", "null" ], "description": "The certificate password. Without it the file cannot be opened and signing fails." } }, "title": "CertificateRequest" }, "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" }, "ClientRequest": { "type": "object", "properties": { "client_type": { "type": "string", "description": "Client type: `COMPANY` or `PERSON`. Required; decides which of the fields below\nare required.", "enum": [ "PERSON", "COMPANY" ], "examples": [ "COMPANY" ] }, "company_name": { "type": [ "string", "null" ], "description": "Company name. Required for `COMPANY`.", "examples": [ "Alpha SHPK" ], "maxLength": 255 }, "nipt": { "type": [ "string", "null" ], "description": "The company's NIPT, or the VAT\/TAX number of a foreign business. Required for\n`COMPANY`.", "examples": [ "L91806031A" ], "maxLength": 20 }, "address": { "type": [ "string", "null" ], "description": "Company address. Required for `COMPANY`.", "examples": [ "Rruga X" ], "maxLength": 255 }, "city": { "type": [ "string", "null" ], "description": "Company city. Required for `COMPANY`.", "examples": [ "Tirane" ], "maxLength": 50 }, "company_type": { "type": [ "string", "null" ], "description": "Company category: `BUSINESS`, `BANK` or `EXCHANGE`.", "enum": [ "BUSINESS", "BANK", "EXCHANGE", null ], "examples": [ "BUSINESS" ] }, "name": { "type": [ "string", "null" ], "description": "The person's first name. Required for `PERSON`.", "examples": [ "Agon" ], "maxLength": 255 }, "surname": { "type": [ "string", "null" ], "description": "The person's last name. Required for `PERSON`.", "examples": [ "Hoxha" ], "maxLength": 255 }, "document_type": { "type": [ "string", "null" ], "description": "Identification document type: `NUIS`, `ID`, `PASS`, `VAT`, `TAX` or `SOC`.\nRequired for `PERSON`.", "enum": [ "NUIS", "ID", "PASS", "VAT", "TAX", "SOC", null ], "examples": [ "ID" ] }, "document_number": { "type": [ "string", "null" ], "description": "Identification document number. Required for `PERSON`.", "examples": [ "I12345678A" ], "maxLength": 255 }, "nationality_code": { "type": [ "string", "null" ], "description": "The client's country, ISO 3166-1 alpha-3 code. Defaults to `ALB`.", "examples": [ "ALB" ], "minLength": 3, "maxLength": 3 }, "nationality_id": { "type": [ "integer", "null" ], "description": "Country id in fature.al. Filled in automatically from `nationality_code`; you do not need to send it." }, "telephone": { "type": [ "string", "null" ], "description": "Phone number.", "examples": [ "+355691234567" ], "maxLength": 255 }, "email": { "type": [ "string", "null" ], "format": "email", "description": "Email.", "examples": [ "klient@example.com" ], "maxLength": 255 }, "customer_number": { "type": [ "string", "null" ], "description": "Client number in your system.", "examples": [ "CLI-001" ], "maxLength": 30 }, "gender": { "type": [ "string", "null" ], "description": "Gender, only for `PERSON`.", "examples": [ "M" ], "maxLength": 10 }, "birthday": { "type": [ "string", "null" ], "format": "date-time", "description": "Date of birth, `YYYY-MM-DD`, only for `PERSON`.", "examples": [ "1990-01-15" ] } }, "required": [ "client_type" ], "title": "ClientRequest" }, "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" }, "CreateBranchRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the business unit, the one shown on the invoice. Required.", "examples": [ "Dega Tirane" ], "maxLength": 255 }, "type": { "type": "string", "description": "Unit type: `main` for the head office, `secondary` for a secondary office.\nRequired. A company has only one `main`.", "enum": [ "main", "secondary" ], "examples": [ "main" ] }, "administrator": { "type": "string", "description": "The administrator: the person responsible for the unit. Required.", "examples": [ "Festim Peposhi" ], "maxLength": 255 }, "address": { "type": "string", "description": "Address of the unit; sent to the CIS. Required.", "examples": [ "Rruga e Kavajes 12, Tirane" ], "maxLength": 255 }, "businessUnitCode": { "type": [ "string", "null" ], "description": "Business unit code, obtained from the tax administration. You can also send it later with\n`POST \/on-boarding\/branch\/{id}`, but without it the unit cannot issue invoices.", "examples": [ "bb123bb123" ], "maxLength": 50 } }, "required": [ "name", "type", "administrator", "address" ], "title": "CreateBranchRequest" }, "CurrencyListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "Currency id in fature.al.", "examples": [ 2 ] }, "code": { "type": "string", "description": "ISO 4217 code of the currency; the value for `currency` on invoices and products.", "examples": [ "EUR" ] }, "name": { "type": "string", "description": "Same value as `code`; fature.al keeps no other name for the currency.", "examples": [ "EUR" ] } }, "required": [ "id", "code", "name" ], "title": "CurrencyListItem" }, "DashboardDayPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Date, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "gross": { "type": "number", "description": "Gross value of the day's invoices, in lek; `0` when there are none.", "examples": [ 48900 ] } }, "required": [ "date", "gross" ], "title": "DashboardDayPoint" }, "DashboardHourPoint": { "type": "object", "properties": { "hour": { "type": "integer", "description": "Start hour of the interval: `0`, `2`, `4` and so on up to `22`. The point covers invoices from\nthis hour until before hour `hour + 2`.", "examples": [ 10 ] }, "gross": { "type": "number", "description": "Gross value of the interval's invoices, in lek; `0` when there are none.", "examples": [ 6300 ] } }, "required": [ "hour", "gross" ], "title": "DashboardHourPoint" }, "DashboardShift": { "type": "object", "properties": { "is_open": { "type": "boolean", "description": "`true` when the device's cash register was opened today and has not been closed yet.", "examples": [ true ] }, "opened_at": { "type": [ "string", "null" ], "description": "Date and time of today's opening of the cash register, ISO 8601 with the time zone; when it was not opened today, the latest\nopening from previous days. `null` when the cash register has never been opened.", "examples": [ "2026-09-13T08:02:11+02:00" ] }, "cash_in_drawer": { "type": "number", "description": "The current cash register balance, in lek, per the fature.al ledger: the cash register actions and the TCR's cash\ninvoices, with every payment method. `0` when the shift is not open.", "examples": [ 23450 ] }, "currency": { "type": "string", "description": "Currency of `cash_in_drawer`, always `ALL`.", "examples": [ "ALL" ] } }, "required": [ "is_open", "opened_at", "cash_in_drawer", "currency" ], "title": "DashboardShift" }, "DashboardSummary": { "type": "object", "properties": { "shift": { "description": "The shift and the cash register of the user's fiscal device.", "$ref": "#\/components\/schemas\/DashboardShift" }, "today": { "description": "Today's sales.", "$ref": "#\/components\/schemas\/DashboardToday" }, "week": { "description": "The last seven days against the seven before them.", "$ref": "#\/components\/schemas\/DashboardWeek" } }, "required": [ "shift", "today", "week" ], "title": "DashboardSummary" }, "DashboardToday": { "type": "object", "properties": { "invoice_count": { "type": "integer", "description": "Number of today's invoices.", "examples": [ 57 ] }, "gross_total": { "type": "number", "description": "Their gross value, in lek.", "examples": [ 48900 ] }, "hourly_series": { "type": "array", "description": "Twelve points, one for every two hours of the day, from hour `0` to hour `22`.", "items": { "$ref": "#\/components\/schemas\/DashboardHourPoint" } } }, "required": [ "invoice_count", "gross_total", "hourly_series" ], "title": "DashboardToday" }, "DashboardWeek": { "type": "object", "properties": { "series": { "type": "array", "description": "Seven points, one for each of the last 7 days up to today, in chronological order.", "items": { "$ref": "#\/components\/schemas\/DashboardDayPoint" } }, "wow_delta_percent": { "type": [ "number", "null" ], "description": "Percentage change in gross sales of the last 7 days against the 7 days before them, with two\ndecimal places: `12.5` means 12.5% more, negative when less. `null` when the previous 7\ndays have no sales.", "examples": [ 12.5 ] } }, "required": [ "series", "wow_delta_percent" ], "title": "DashboardWeek" }, "EInvoiceRequest": { "type": "object", "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" ] }, "payment_method": { "type": [ "string", "null" ], "description": "Payment method: `ACCOUNT`, `COMPENSATION`, `FACTORING`, `KIND`, `OTHER`, `TRANSFER` or\n`WAIVER`.", "enum": [ "ACCOUNT", "COMPENSATION", "FACTORING", "KIND", "OTHER", "TRANSFER", "WAIVER", null ], "examples": [ "TRANSFER" ] }, "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" ] } }, "required": [ "internalId", "client", "lines", "doc_type", "process" ], "title": "EInvoiceRequest" }, "ExchangeRateSnapshot": { "type": "object", "properties": { "rates": { "type": "object", "description": "Selling rate for each currency, with the ISO 4217 code as key and lek per unit of the\ncurrency as value; always includes `ALL: 1`. When kursi.al cannot be reached, it holds only `ALL: 1`.", "examples": [ { "ALL": 1, "EUR": 98.5, "USD": 91.2, "GBP": 116.3 } ], "additionalProperties": { "type": "number" } }, "source": { "type": "string", "description": "The rate source that was used: `BOA`, `BKT`, `Iliria98` or `ADON`. When the request's `source`\nis not recognized, `BOA` is returned.", "examples": [ "BOA" ] }, "fetchedAt": { "type": "string", "description": "When the response was built, ISO 8601 with the time zone. kursi.al data is cached\non the server for one hour, so it may be up to one hour older than this time.", "examples": [ "2026-09-14T10:15:00+02:00" ] } }, "required": [ "rates", "source", "fetchedAt" ], "title": "ExchangeRateSnapshot" }, "FiscalDeviceRequest": { "type": "object", "properties": { "branchId": { "type": "integer", "description": "Id of the business unit where the device is located, the one\n`POST \/on-boarding\/branch` returned to you. Each TCR belongs to a single unit. Required.", "examples": [ 12 ] }, "name": { "type": "string", "description": "Name of the fiscal device, the one that tells it apart from the others in the same unit. Required.", "examples": [ "Arka 1" ], "maxLength": 255 }, "fromDate": { "type": "string", "description": "Start date, `YYYY-MM-DD`: from this date the device issues invoices. Required.", "examples": [ "2026-01-01" ] }, "toDate": { "type": [ "string", "null" ], "description": "End date, `YYYY-MM-DD`: until when the device is active. Without it, the device stays\nactive indefinitely.", "examples": [ "2026-12-31" ] } }, "required": [ "branchId", "name", "fromDate" ], "title": "FiscalDeviceRequest" }, "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_method": { "type": [ "string", "null" ], "description": "The payment method the invoice was paid with; for a split payment, the one with the largest share.", "examples": [ "ACCOUNT" ] }, "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_method", "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" ] } }, "required": [ "id", "number", "iic", "fic", "tcrCode", "businessCode", "operatorCode", "fiscalizedAt", "verifyURL", "pdf", "eic" ], "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_method": { "type": [ "string", "null" ], "description": "The payment method the invoice was paid with; for a split payment, the one with the largest share.", "examples": [ "ACCOUNT" ] } }, "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_method" ], "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" }, "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", "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" ] }, "payment_method": { "type": [ "string", "null" ], "description": "Payment method: `ACCOUNT`, `COMPENSATION`, `FACTORING`, `KIND`, `OTHER`, `TRANSFER` or\n`WAIVER`.", "enum": [ "ACCOUNT", "COMPENSATION", "FACTORING", "KIND", "OTHER", "TRANSFER", "WAIVER", null ], "examples": [ "TRANSFER" ] }, "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" ] } }, "required": [ "internalId", "lines" ], "title": "NonCashInvoiceRequest" }, "OnboardingBankAccount": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id of the bank account; with it, or with the IBAN, the account is selected on non-cash invoices and on\ne-invoices.", "examples": [ 5 ] }, "iban": { "type": "string", "description": "The IBAN as saved: without spaces and in uppercase.", "examples": [ "AL35202111090000000001234567" ] } }, "required": [ "id", "iban" ], "title": "OnboardingBankAccount" }, "OnboardingBranchCreated": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id of the business unit; the unit's users and fiscal devices are linked through it.", "examples": [ 13 ] }, "name": { "type": "string", "description": "Unit name.", "examples": [ "Dyqani Qend\u00ebr" ] }, "type": { "type": "string", "description": "`main` for the head office, `secondary` for a secondary unit, as sent.", "examples": [ "secondary" ] }, "administrator": { "type": "string", "description": "The unit's administrator.", "examples": [ "Arben Hoxha" ] }, "address": { "type": "string", "description": "The address of the unit.", "examples": [ "Rruga e Kavaj\u00ebs 12, Tiran\u00eb" ] }, "businessUnitCode": { "type": "string", "description": "Business unit code; an empty string when not sent, in which case it is expected with\n`POST \/on-boarding\/branch\/{id}`.", "examples": [ "bb123bb123" ] } }, "required": [ "id", "name", "type", "administrator", "address", "businessUnitCode" ], "title": "OnboardingBranchCreated" }, "OnboardingBranchUpdated": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the business unit.", "examples": [ 12 ] }, "name": { "type": "string", "description": "Unit name after saving.", "examples": [ "Dyqani Qend\u00ebr" ] }, "businessUnitCode": { "type": "string", "description": "Business unit code after saving.", "examples": [ "bb123bb123" ] } }, "required": [ "id", "name", "businessUnitCode" ], "title": "OnboardingBranchUpdated" }, "OnboardingCertificate": { "type": "object", "properties": { "expiresAt": { "type": "string", "description": "Certificate expiry date, `YYYY-MM-DD`. After it, fiscalization stops until a new certificate\nis uploaded. In sandbox it is one year from today.", "examples": [ "2027-09-13" ] } }, "required": [ "expiresAt" ], "title": "OnboardingCertificate" }, "OnboardingFiscalDevice": { "type": "object", "properties": { "fiscalTcrCode": { "type": [ "string", "null" ], "description": "The TCR code the CIS assigned to the device; set it on the user with `POST \/on-boarding\/user\/{id}`.\nnull when the CIS could not be reached: the device was not saved, try again later.", "examples": [ "ab123ab123" ] } }, "required": [ "fiscalTcrCode" ], "title": "OnboardingFiscalDevice" }, "OnboardingRegisteredBranch": { "type": "object", "properties": { "id": { "type": "integer", "description": "Id of the business unit; needed for `POST \/on-boarding\/branch\/{id}`, `POST \/on-boarding\/user`\nand `POST \/on-boarding\/fiscal-device`.", "examples": [ 12 ] }, "name": { "type": "string", "description": "Unit name, formed from the company name and `Selia Qendrore`.", "examples": [ "Alpha SHPK - Selia Qendrore" ] } }, "required": [ "id", "name" ], "title": "OnboardingRegisteredBranch" }, "OnboardingRegisteredUser": { "type": "object", "properties": { "token": { "type": "string", "description": "API token of the first user, 96 letters and digits. Shown only here; all the other registration\nsteps are done with it.", "examples": [ "k7Qm2ZpX9vL4rT1nB8wJ3cH6yF0sD5aG2eV7uN4iK9oP1lM8qR3tW6xY0zA5bC2dE7fH4gJ1hK9jL6mN3pQ8rS5tU2vW7xZ0" ] }, "id": { "type": "integer", "description": "The user's id in fature.al; needed for `POST \/on-boarding\/user\/{id}`.", "examples": [ 7 ] } }, "required": [ "token", "id" ], "title": "OnboardingRegisteredUser" }, "OnboardingUserCreated": { "type": "object", "properties": { "id": { "type": "integer", "description": "The user's id in fature.al.", "examples": [ 8 ] }, "name": { "type": "string", "description": "The user's name.", "examples": [ "Ana Hoxha" ] }, "operatorCode": { "type": "string", "description": "Operator code, as sent.", "examples": [ "aa123aa123" ] }, "token": { "type": "string", "description": "The user's API token, 96 letters and digits. Returned only once; this user\ncalls the API with it.", "examples": [ "E7fH4gJ1hK9jL6mN3pQ8rS5tU2vW7xZ0k7Qm2ZpX9vL4rT1nB8wJ3cH6yF0sD5aG2eV7uN4iK9oP1lM8qR3tW6xY0zA5bC2d" ] } }, "required": [ "id", "name", "operatorCode", "token" ], "title": "OnboardingUserCreated" }, "OnboardingUserUpdated": { "type": "object", "properties": { "id": { "type": "integer", "description": "The user's id in fature.al.", "examples": [ 7 ] }, "name": { "type": "string", "description": "The user's name after saving.", "examples": [ "Ana Hoxha" ] }, "operatorCode": { "type": "string", "description": "The operator code after saving.", "examples": [ "aa123aa123" ] } }, "required": [ "id", "name", "operatorCode" ], "title": "OnboardingUserUpdated" }, "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" ] }, "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", "isOrderInvoice", "summaryInvoiceId" ], "title": "OrderInvoiceIssueResult" }, "PingResult": { "type": "object", "properties": { "pong": { "type": "integer", "description": "The server time at the moment of the response, a Unix timestamp in seconds.", "examples": [ 1789380900 ] }, "ip": { "type": "array", "description": "The request's IP addresses as the server sees them. Usually a single one; more than one when the request\npassed through a trusted proxy, in which case every address along the route is in the list.", "examples": [ [ "203.0.113.10" ] ], "items": { "type": "string" } } }, "required": [ "pong", "ip" ], "title": "PingResult" }, "ProductCategoryRef": { "type": "object", "properties": { "id": { "type": "integer", "description": "The category id.", "examples": [ 12 ] }, "name": { "type": "string", "description": "The category name.", "examples": [ "Sh\u00ebrbime" ] }, "color": { "type": [ "string", "null" ], "description": "The hex color the POS product grid uses.", "examples": [ "dd9f52" ] } }, "required": [ "id", "name", "color" ], "title": "ProductCategoryRef" }, "ProductDetail": { "type": "object", "properties": { "id": { "type": "integer", "description": "The product's id in fature.al.", "examples": [ 314 ] }, "code": { "type": [ "string", "null" ], "description": "The unique product code.", "examples": [ "SRV-MNT" ] }, "name": { "type": "string", "description": "The product name.", "examples": [ "Or\u00eb pune mir\u00ebmbajtje" ] }, "description": { "type": [ "string", "null" ], "description": "The product description.", "examples": [ "Mir\u00ebmbajtje e sistemit, faturohet p\u00ebr or\u00eb" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure, derived from `unit_code`.", "examples": [ "Or\u00eb" ] }, "unit_code": { "type": [ "string", "null" ], "description": "The unit of measure code, e.g. `C62`, `XPP`, `LTR`.", "examples": [ "HUR" ] }, "last_price": { "type": "number", "description": "The sale price.", "examples": [ 300 ] }, "cost_price": { "type": [ "number", "null" ], "description": "The purchase price, when recorded.", "examples": [ 150 ] }, "vat_rate": { "type": "number", "description": "The VAT rate as a percentage: 0, 6, 10 or 20.", "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "The VAT exemption type, when the product is exempt.", "examples": [ "TYPE_1" ] }, "vat_exempt_description": { "type": [ "string", "null" ], "description": "The exemption written in the account's language.", "examples": [ "P\u00ebrjashtim i llojit 1. (P\u00ebrjashtim n\u00eb baz\u00eb t\u00eb nenit 51 t\u00eb Ligjit p\u00ebr TVSH-n\u00eb.)" ] }, "currency": { "type": [ "string", "null" ], "description": "The price currency.", "examples": [ "EUR" ] }, "id_category": { "type": [ "integer", "null" ], "description": "The category id, or null when the product has none.", "examples": [ 12 ] }, "service": { "type": "boolean", "description": "true for a service, false for an item tracked in the warehouse.", "examples": [ true ] }, "category": { "anyOf": [ { "description": "The product category, or null when there is none.", "$ref": "#\/components\/schemas\/ProductCategoryRef" }, { "type": "null" } ] }, "created_at": { "type": [ "string", "null" ], "description": "Creation date and time, ISO 8601.", "examples": [ "2026-01-15T09:00:00+01:00" ] } }, "required": [ "id", "code", "name", "description", "unit", "unit_code", "last_price", "cost_price", "vat_rate", "vat_exempt_type", "vat_exempt_description", "currency", "id_category", "service", "category", "created_at" ], "title": "ProductDetail" }, "ProductListItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "The product's id in fature.al.", "examples": [ 314 ] }, "code": { "type": [ "string", "null" ], "description": "The unique product code.", "examples": [ "SRV-MNT" ] }, "name": { "type": "string", "description": "The product name.", "examples": [ "Or\u00eb pune mir\u00ebmbajtje" ] }, "description": { "type": [ "string", "null" ], "description": "The product description.", "examples": [ "Mir\u00ebmbajtje e sistemit, faturohet p\u00ebr or\u00eb" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure, derived from `unit_code`.", "examples": [ "Or\u00eb" ] }, "unit_code": { "type": [ "string", "null" ], "description": "The unit of measure code, e.g. `C62`, `XPP`, `LTR`.", "examples": [ "HUR" ] }, "last_price": { "type": "number", "description": "The sale price.", "examples": [ 300 ] }, "cost_price": { "type": [ "number", "null" ], "description": "The purchase price, when recorded.", "examples": [ 150 ] }, "vat_rate": { "type": "number", "description": "The VAT rate as a percentage: 0, 6, 10 or 20.", "examples": [ 20 ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "The VAT exemption type, when the product is exempt.", "examples": [ "TYPE_1" ] }, "vat_exempt_description": { "type": [ "string", "null" ], "description": "The exemption written in the account's language.", "examples": [ "P\u00ebrjashtim i llojit 1. (P\u00ebrjashtim n\u00eb baz\u00eb t\u00eb nenit 51 t\u00eb Ligjit p\u00ebr TVSH-n\u00eb.)" ] }, "currency": { "type": [ "string", "null" ], "description": "The price currency.", "examples": [ "EUR" ] }, "id_category": { "type": [ "integer", "null" ], "description": "The category id, or null when the product has none.", "examples": [ 12 ] } }, "required": [ "id", "code", "name", "description", "unit", "unit_code", "last_price", "cost_price", "vat_rate", "vat_exempt_type", "vat_exempt_description", "currency", "id_category" ], "title": "ProductListItem" }, "ProductListPagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "How many products `data` holds in this response.", "examples": [ 50 ] }, "total": { "type": "integer", "description": "How many products match the filters in total, across all pages.", "examples": [ 312 ] }, "limit": { "type": [ "integer", "null" ], "description": "The limit that was applied: the one you sent, lowered to `500` when it was larger. null when you did not send\n`limit` and the whole catalog was returned.", "examples": [ 50 ] }, "offset": { "type": "integer", "description": "Which product this page started from, counting from 0. Always `0` when there is no `limit`.", "examples": [ 0 ] } }, "required": [ "records", "total", "limit", "offset" ], "title": "ProductListPagination" }, "ProductRequest": { "type": "object", "properties": { "code": { "type": [ "string", "null" ], "description": "The product code, unique within the company. Generated automatically when omitted.", "examples": [ "P001" ], "maxLength": 255 }, "name": { "type": "string", "description": "The product name. Required.", "examples": [ "Kafe Espresso" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "description": "The description. Defaults to the name.", "examples": [ "Kafe espresso e peshuar 18g" ], "maxLength": 255 }, "unit_code": { "type": "string", "description": "The unit of measure code carried by the fiscal document, e.g. `XPP` piece, `KGM` kg, `LTR` liter,\n`HUR` hour, `MTK` m\u00b2. Required; the unit as text is derived from it and is not sent.\nThe meaning of 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": [ "XPP" ] }, "last_price": { "type": "number", "description": "The sale price per unit. Required.", "examples": [ 150 ], "minimum": 0 }, "cost_price": { "type": [ "number", "null" ], "description": "The purchase price per unit.", "examples": [ 80 ], "minimum": 0 }, "vat_rate": { "type": "string", "description": "The VAT rate as a percentage: `0`, `6`, `10` or `20`. Required.", "enum": [ "0", "6", "10", "20" ], "examples": [ "20" ] }, "vat_exempt_type": { "type": [ "string", "null" ], "description": "The VAT exemption type, for an exempt product: `TYPE_1`, `TYPE_2`,\n`EXPORT_OF_GOODS` or `TAX_FREE`.", "enum": [ "TYPE_1", "TYPE_2", "EXPORT_OF_GOODS", "TAX_FREE", null ], "examples": [ "TAX_FREE" ] }, "currency": { "type": [ "string", "null" ], "description": "The price currency, an ISO 4217 code; defaults to ALL.", "examples": [ "ALL" ], "maxLength": 10 }, "service": { "type": "boolean", "description": "`true` for a service, `false` for an item kept in inventory. Defaults to\n`true`.", "examples": [ true ] }, "id_category": { "type": [ "integer", "null" ], "description": "The category id, from `GET \/product\/categories`.", "examples": [ 3 ] } }, "required": [ "name", "unit_code", "last_price", "vat_rate" ], "title": "ProductRequest" }, "PurchaseInvoiceCurrency": { "type": "object", "properties": { "code": { "type": "string", "description": "The ISO 4217 code of the invoice currency.", "examples": [ "EUR" ] }, "exchangeRate": { "type": "number", "description": "How many lek one unit of the currency is worth. Invoice amounts come in lek; divided by this rate\nthey give the amount in the invoice currency.", "examples": [ 100.5 ] } }, "required": [ "code", "exchangeRate" ], "title": "PurchaseInvoiceCurrency" }, "PurchaseInvoiceItem": { "type": "object", "properties": { "iic": { "type": "string", "description": "The invoice identification code, IIC (NSLF), 32 hex digits. The invoice can be found again with it.", "examples": [ "0F1E2D3C4B5A69788796A5B4C3D2E1F0" ] }, "fic": { "type": "string", "description": "The code the CIS returned when it registered the invoice, FIC (NIVF). Also serves as the list's `fic`\nfilter.", "examples": [ "8a941d47-7d47-4b7e-8f3a-1c2d3e4f5a6b" ] }, "invoiceNumber": { "type": "string", "description": "The invoice number as the supplier issued it: the sequence number and year on a non-cash invoice, such as\n`152\/2026`; with the TCR code at the end on a cash invoice, such as `152\/2026\/cc123cc123`.", "examples": [ "152\/2026" ] }, "invoiceOrderNumber": { "type": "integer", "description": "The invoice sequence number in the supplier's series.", "examples": [ 152 ] }, "dateTimeCreated": { "type": "string", "description": "The invoice issue date and time, as the CIS returns it: an ISO 8601 date-time with the time zone.", "examples": [ "2026-07-01T10:15:23+02:00" ] }, "payDeadline": { "type": [ "string", "null" ], "description": "The payment due date, as the CIS returns it; `null` when the invoice has no due date.", "examples": [ "2026-07-31T00:00:00+02:00" ] }, "invoiceType": { "type": "string", "description": "The invoice type: `CASH` or `NONCASH`.", "examples": [ "NONCASH" ] }, "issuerTaxNumber": { "type": "string", "description": "The issuer's NIPT, the same as `seller.idNum`.", "examples": [ "K71828301A" ] }, "seller": { "description": "The supplier that issued the invoice.", "$ref": "#\/components\/schemas\/PurchaseInvoiceParty" }, "buyer": { "description": "The buyer, that is, your company.", "$ref": "#\/components\/schemas\/PurchaseInvoiceParty" }, "items": { "type": "array", "description": "The invoice lines.", "items": { "$ref": "#\/components\/schemas\/PurchaseInvoiceLine" } }, "paymentMethod": { "type": "array", "description": "The payment methods: one element on an invoice paid with a single method, one for each\npart of a split payment.", "items": { "$ref": "#\/components\/schemas\/PurchaseInvoicePaymentMethod" } }, "currency": { "anyOf": [ { "description": "The invoice currency and rate; `null` when the invoice is in lek.", "$ref": "#\/components\/schemas\/PurchaseInvoiceCurrency" }, { "type": "null" } ] }, "totalPrice": { "type": "number", "description": "The invoice total including VAT, in lek.", "examples": [ 12000 ] }, "totalPriceWithoutVAT": { "type": "number", "description": "The invoice total excluding VAT, in lek.", "examples": [ 10000 ] }, "reverseCharge": { "type": "boolean", "description": "Reverse charge: the buyer declares the VAT.", "examples": [ false ] }, "businessUnit": { "type": [ "string", "null" ], "description": "The code of the supplier's business unit the invoice was issued from.", "examples": [ "bb123bb123" ] }, "operatorCode": { "type": [ "string", "null" ], "description": "The code of the supplier's operator who issued the invoice.", "examples": [ "oo123oo123" ] }, "tcrCode": { "type": [ "string", "null" ], "description": "The TCR code of the supplier's fiscal device; `null` on invoices not issued from a TCR.", "examples": [ "cc123cc123" ] }, "softwareCode": { "type": [ "string", "null" ], "description": "The code of the software the supplier issued the invoice with.", "examples": [ "ss123ss123" ] }, "iicSignature": { "type": [ "string", "null" ], "description": "The IIC signature with the supplier's certificate, in hex.", "examples": [ "3a5f9c1e7b2d4680a1c3e5f7092b4d6e8f0a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5061728394a5b6c7d8e9f0a1b2c3d4e5f6" ] } }, "required": [ "iic", "fic", "invoiceNumber", "invoiceOrderNumber", "dateTimeCreated", "payDeadline", "invoiceType", "issuerTaxNumber", "seller", "buyer", "items", "paymentMethod", "currency", "totalPrice", "totalPriceWithoutVAT", "reverseCharge", "businessUnit", "operatorCode", "tcrCode", "softwareCode", "iicSignature" ], "title": "PurchaseInvoiceItem" }, "PurchaseInvoiceLine": { "type": "object", "properties": { "name": { "type": "string", "description": "The product or service name, as the supplier wrote it.", "examples": [ "Kafe e pjekur 1kg" ] }, "code": { "type": [ "string", "null" ], "description": "The product code at the supplier; `null` when they sent no code.", "examples": [ "K1" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure; `null` when missing.", "examples": [ "kg" ] }, "quantity": { "type": "number", "description": "Quantity.", "examples": [ 100 ] }, "unitPriceAfterVat": { "type": "number", "description": "The unit price including VAT, in lek.", "examples": [ 120 ] }, "priceAfterVat": { "type": "number", "description": "The line value including VAT, in lek.", "examples": [ 12000 ] }, "vatAmount": { "type": "number", "description": "The line VAT, in lek.", "examples": [ 2000 ] }, "vatRate": { "type": [ "number", "null" ], "description": "The VAT rate as a percentage; `null` when the line carries no rate, a case fature.al reads as\n0.", "examples": [ 20 ] }, "exemptFromVat": { "type": [ "string", "null" ], "description": "The VAT exemption type: `TYPE_1` (article 51 of the VAT law), `TYPE_2` (articles 53\nand 54), `EXPORT_OF_GOODS` export of goods, `TAX_FREE` zero rate. `null` when the line has\nVAT.", "examples": [ "TYPE_1" ] } }, "required": [ "name", "code", "unit", "quantity", "unitPriceAfterVat", "priceAfterVat", "vatAmount", "vatRate", "exemptFromVat" ], "title": "PurchaseInvoiceLine" }, "PurchaseInvoicePagination": { "type": "object", "properties": { "records": { "type": "integer", "description": "The CIS pagination for the page. `items` may be shorter, because an invoice whose details cannot\nbe reached is dropped without an error.", "examples": [ 12 ] }, "page": { "type": "integer", "description": "The request's `page` parameter, after rounding up to at least 1.", "examples": [ 1 ] } }, "required": [ "records", "page" ], "title": "PurchaseInvoicePagination" }, "PurchaseInvoiceParty": { "type": "object", "properties": { "idType": { "type": "string", "description": "The identifier type: `NUIS`, `VAT` or `TAX` for a business; `ID`, `PASS` or `SOC` for a\nperson.", "examples": [ "NUIS" ] }, "idNum": { "type": "string", "description": "Identifier value, e.g. the NIPT.", "examples": [ "K71828301A" ] }, "name": { "type": "string", "description": "The name of the business or person.", "examples": [ "Furnizimi Alba SHPK" ] }, "address": { "type": [ "string", "null" ], "description": "The address, as the CIS holds it; `null` when missing.", "examples": [ "Rruga e Durr\u00ebsit 5" ] }, "town": { "type": [ "string", "null" ], "description": "The city; `null` when missing.", "examples": [ "Tiran\u00eb" ] }, "country": { "type": [ "string", "null" ], "description": "The three-letter country code, such as `ALB`; `null` when missing.", "examples": [ "ALB" ] } }, "required": [ "idType", "idNum", "name", "address", "town", "country" ], "title": "PurchaseInvoiceParty" }, "PurchaseInvoicePaymentMethod": { "type": "object", "properties": { "typeCode": { "type": "string", "description": "The payment method: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` or `ORDER` on a\ncash invoice; `ACCOUNT`, `TRANSFER`, `COMPENSATION`, `FACTORING`, `KIND`, `WAIVER` or\n`OTHER` on a non-cash invoice.", "examples": [ "ACCOUNT" ] }, "compCard": { "type": [ "string", "null" ], "description": "The company card number when `typeCode` is `COMPANY`. On bank payments, invoicing software,\nfature.al included, puts the account IBAN here. `null` when missing.", "examples": [ "AL47212110090000000235698741" ] } }, "required": [ "typeCode", "compCard" ], "title": "PurchaseInvoicePaymentMethod" }, "RegisterCompanyRequest": { "type": "object", "properties": { "nuis": { "type": "string", "description": "The NIPT of the company being registered: one letter, eight digits, one letter.\nRequired. It is checked against the fiscal register, and a NIPT already registered\nin fature.al is rejected.", "pattern": "^[A-Z]\\d{8}[A-Z]$", "examples": [ "L62221018T" ] }, "name": { "type": "string", "description": "The company name. Required.", "examples": [ "Ei3 Software Solution shpk" ], "maxLength": 255 }, "address": { "type": "string", "description": "The address of the company's registered office, as registered. Required.", "examples": [ "Rruga e Kavajes 12, Tirane" ], "maxLength": 255 }, "administrator": { "type": "string", "description": "The company administrator. Required.", "examples": [ "Festim Peposhi" ], "maxLength": 255 }, "phone": { "type": "string", "description": "The company's contact phone number. Required.", "examples": [ "+355 69 000 0000" ], "maxLength": 50 }, "email": { "type": "string", "format": "email", "description": "The email of the first user, the one who will administer the account. Required.", "examples": [ "admin@example.com" ], "maxLength": 255 }, "issuerInVat": { "type": [ "boolean", "null" ], "description": "Whether the company is in the VAT scheme. Boolean; defaults to `false`, and invoices\ncome out without VAT.", "examples": [ true ] }, "lastNonCashEInvoiceNumber": { "type": [ "string", "null" ], "description": "The last number of the non-cash invoice or e-invoice issued in the previous system,\nso that numbering continues from it and does not restart from 1.", "examples": [ "412" ], "maxLength": 50 } }, "required": [ "nuis", "name", "address", "administrator", "phone", "email" ], "title": "RegisterCompanyRequest" }, "ReportByOperator": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "items": { "type": "array", "description": "The operators, from the largest gross value.", "items": { "$ref": "#\/components\/schemas\/ReportOperatorRow" } } }, "required": [ "period", "items" ], "title": "ReportByOperator" }, "ReportByTcr": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "items": { "type": "array", "description": "The fiscal devices, from the largest gross value.", "items": { "$ref": "#\/components\/schemas\/ReportTcrRow" } } }, "required": [ "period", "items" ], "title": "ReportByTcr" }, "ReportCashMovementRow": { "type": "object", "properties": { "type": { "type": "string", "description": "`DEPOSIT` cash in, `WITHDRAWAL` cash out.", "examples": [ "DEPOSIT" ] }, "amount": { "type": "number", "description": "The amount, in lek, always positive; `type` gives the direction.", "examples": [ 3000 ] }, "description": { "type": [ "string", "null" ], "description": "The description of the action as it was written; opening and closing the cash register come with their standard\ndescriptions, `Hapje e gjendjes fillestare` and `Mbyllje turni\/xhiro ditore`. `null` when\nthe action carries no description.", "examples": [ "Kusur p\u00ebr turnin" ] }, "time": { "type": [ "string", "null" ], "description": "The date and time of the action, ISO 8601 with the time zone; `null` when the action carries no time.", "examples": [ "2026-09-13T08:05:40+02:00" ] }, "cash_action_no": { "type": [ "string", "null" ], "description": "The action number on the cash register, in the form `number\/year\/TCR`: how many actions of this type the\ndevice has made that year. `null` when the action carries no number.", "examples": [ "3\/2026\/ab123cd456" ] } }, "required": [ "type", "amount", "description", "time", "cash_action_no" ], "title": "ReportCashMovementRow" }, "ReportCashMovements": { "type": "object", "properties": { "deposits_count": { "type": "integer", "description": "How many cash-in actions (`MONEY_IN`) were recorded.", "examples": [ 1 ] }, "deposits_total": { "type": "number", "description": "The total of cash in, in lek.", "examples": [ 3000 ] }, "withdrawals_count": { "type": "integer", "description": "How many cash-out actions (`MONEY_OUT`) were recorded.", "examples": [ 1 ] }, "withdrawals_total": { "type": "number", "description": "The total of cash out, in lek, as a positive value.", "examples": [ 2000 ] } }, "required": [ "deposits_count", "deposits_total", "withdrawals_count", "withdrawals_total" ], "title": "ReportCashMovements" }, "ReportCashRegister": { "type": "object", "properties": { "date": { "type": "string", "description": "The report day, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "currency": { "type": "string", "description": "The currency of the amounts, always `ALL`.", "examples": [ "ALL" ] }, "opening": { "type": "number", "description": "The opening balance declared for the day, in lek: the sum of the day's cash register openings for\nthis TCR. `0` when the cash register was not opened that day.", "examples": [ 5000 ] }, "closing": { "type": "number", "description": "The cash register balance at the end of the day according to the fature.al ledger, in lek: the sum of all\ncash register actions and all cash invoices of this TCR from the start through the\nend of the day, with every payment method, not only cash in hand.", "examples": [ 68450 ] }, "expected_closing": { "type": "number", "description": "How much cash in hand the cash register should hold if everything was recorded, in lek: `opening`\nplus the day's `BANKNOTE` sales plus `movements.deposits_total` minus\n`movements.withdrawals_total`. The difference from `closing` is what reconciliation looks for.", "examples": [ 68450 ] }, "tcr": { "type": [ "string", "null" ], "description": "The TCR code of the user's fiscal device; `null` when the device has no code yet.", "examples": [ "ab123cd456" ] }, "operator": { "type": "string", "description": "The full name of the token's user; empty when the user has no name.", "examples": [ "Arben Hoxha" ] }, "sales_by_method": { "type": "array", "description": "The day's sales by the payment method that settled them, from the largest gross: `BANKNOTE`,\n`CARD`, `CHECK`, `SVOUCHER` or `COMPANY`.", "items": { "$ref": "#\/components\/schemas\/ReportCashRegisterSalesByMethodRow" } }, "movements": { "description": "The day's cash in and cash out on this TCR.", "$ref": "#\/components\/schemas\/ReportCashMovements" } }, "required": [ "date", "currency", "opening", "closing", "expected_closing", "tcr", "operator", "sales_by_method", "movements" ], "title": "ReportCashRegister" }, "ReportCashRegisterClosing": { "type": "object", "properties": { "date": { "type": "string", "description": "The report day, `YYYY-MM-DD`.", "examples": [ "2026-09-13" ] }, "currency": { "type": "string", "description": "The currency of the amounts, always `ALL`.", "examples": [ "ALL" ] }, "opening": { "type": "number", "description": "The cash the shift started with, in lek: the balance declared when opening the day, minus the cash register\nemptying made the same day before the opening, when the business redeclares the balance.", "examples": [ 5000 ] }, "closing": { "type": "number", "description": "The cash register balance at the end of the day according to the fature.al ledger, in lek: the sum of all\ncash register actions and all cash invoices of this TCR from the start through the\nend of the day, with every payment method, not only cash in hand.", "examples": [ 68450 ] }, "closing_total": { "type": [ "number", "null" ], "description": "The cash counted and taken out of the cash register at the shift close, in lek, as a positive value;\n`null` when the shift is not closed yet or the cash register was not opened that day.", "examples": [ 67900 ] }, "expected_closing": { "type": "number", "description": "How much cash in hand the cash register should hold if everything was recorded, in lek: `opening`\nplus the shift's `BANKNOTE` sales plus `movements.deposits_total` minus\n`movements.withdrawals_total`. The difference from `closing_total` is what reconciliation looks for.", "examples": [ 68450 ] }, "opened_at": { "type": [ "string", "null" ], "description": "The date and time the shift opened, ISO 8601 with the time zone; `null` when the cash register was not opened that day.", "examples": [ "2026-09-13T08:02:11+02:00" ] }, "closed_at": { "type": [ "string", "null" ], "description": "The date and time the shift closed, ISO 8601 with the time zone; `null` when the shift is still\nopen or the cash register was not opened that day.", "examples": [ "2026-09-13T21:47:30+02:00" ] }, "tcr": { "type": [ "string", "null" ], "description": "The TCR code of the user's fiscal device; `null` when the device has no code yet.", "examples": [ "ab123cd456" ] }, "operator": { "type": "string", "description": "The full name of the token's user; empty when the user has no name.", "examples": [ "Arben Hoxha" ] }, "sales": { "description": "The shift's sales totals.", "$ref": "#\/components\/schemas\/ReportCashRegisterClosingSales" }, "sales_by_method": { "type": "array", "description": "The shift's sales by the payment method that settled them, from the largest gross: `BANKNOTE`,\n`CARD`, `CHECK`, `SVOUCHER` or `COMPANY`.", "items": { "$ref": "#\/components\/schemas\/ReportSalesByMethodRow" } }, "products_sold": { "type": "array", "description": "The products sold during the shift, from the largest gross value.", "items": { "$ref": "#\/components\/schemas\/ReportCashRegisterProductRow" } }, "movements": { "description": "The shift's cash movements, with the totals and the list of actions.", "$ref": "#\/components\/schemas\/ReportCashRegisterClosingMovements" } }, "required": [ "date", "currency", "opening", "closing", "closing_total", "expected_closing", "opened_at", "closed_at", "tcr", "operator", "sales", "sales_by_method", "products_sold", "movements" ], "title": "ReportCashRegisterClosing" }, "ReportCashRegisterClosingMovements": { "type": "object", "properties": { "deposits_count": { "type": "integer", "description": "How many cash-in actions (`MONEY_IN`) were recorded.", "examples": [ 1 ] }, "deposits_total": { "type": "number", "description": "The total of cash in, in lek.", "examples": [ 3000 ] }, "withdrawals_count": { "type": "integer", "description": "How many cash-out actions (`MONEY_OUT`) were recorded.", "examples": [ 1 ] }, "withdrawals_total": { "type": "number", "description": "The total of cash out, in lek, as a positive value.", "examples": [ 2000 ] }, "items": { "type": "array", "description": "The shift's actions in chronological order.", "items": { "$ref": "#\/components\/schemas\/ReportCashMovementRow" } } }, "required": [ "deposits_count", "deposits_total", "withdrawals_count", "withdrawals_total", "items" ], "title": "ReportCashRegisterClosingMovements" }, "ReportCashRegisterClosingSales": { "type": "object", "properties": { "invoice_count": { "type": "integer", "description": "The number of the shift's invoices, each counted once, regardless of how many methods it was paid with.", "examples": [ 96 ] }, "gross_total": { "type": "number", "description": "Their gross value, in lek: the sum of `sales_by_method[].gross`.", "examples": [ 87300 ] }, "net_total": { "type": "number", "description": "The net value (excluding VAT), in lek.", "examples": [ 72750 ] }, "vat_total": { "type": "number", "description": "The VAT, in lek.", "examples": [ 14550 ] } }, "required": [ "invoice_count", "gross_total", "net_total", "vat_total" ], "title": "ReportCashRegisterClosingSales" }, "ReportCashRegisterProductRow": { "type": "object", "properties": { "product_name": { "type": "string", "description": "The product name as written on the invoice.", "examples": [ "Kafe espresso" ] }, "product_code": { "type": [ "string", "null" ], "description": "The product code on the invoice; `null` when the lines carry no code.", "examples": [ "KF-001" ] }, "quantity": { "type": "number", "description": "The total quantity sold, with up to three decimal places.", "examples": [ 143 ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure on the invoice; `null` when the lines carry no unit.", "examples": [ "cop\u00eb" ] }, "unit_price": { "type": "number", "description": "The unit price including VAT, after the line discount, in lek.", "examples": [ 150 ] }, "gross": { "type": "number", "description": "The gross value (including VAT) sold, in lek.", "examples": [ 21450 ] }, "net": { "type": "number", "description": "The net value (excluding VAT), in lek.", "examples": [ 17875 ] }, "vat": { "type": "number", "description": "The VAT, in lek.", "examples": [ 3575 ] }, "vat_rate": { "type": "integer", "description": "The VAT rate as a percentage, an integer: `20`, `10`, `6` or `0`.", "examples": [ 20 ] } }, "required": [ "product_name", "product_code", "quantity", "unit", "unit_price", "gross", "net", "vat", "vat_rate" ], "title": "ReportCashRegisterProductRow" }, "ReportCashRegisterSalesByMethodRow": { "type": "object", "properties": { "method": { "type": "string", "description": "The payment method code, the CIS one: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` on\ncash invoices; `ACCOUNT`, `TRANSFER`, `COMPENSATION`, `FACTORING`, `KIND`, `WAIVER`, `OTHER` on\nnon-cash invoices and e-invoices. Also `OTHER` when the invoice carries no payment method.", "examples": [ "BANKNOTE" ] }, "count": { "type": "integer", "description": "How many invoices were settled, fully or partly, with this method.", "examples": [ 318 ] }, "gross": { "type": "number", "description": "The gross amount settled with this method, in lek.", "examples": [ 1210400 ] }, "net": { "type": "number", "description": "The net part (excluding VAT), in lek. On split invoices it is apportioned in proportion to the gross.", "examples": [ 1008666.67 ] }, "vat": { "type": "number", "description": "The VAT part, in lek, split the same way.", "examples": [ 201733.33 ] }, "label": { "type": "string", "description": "The display name of the method, in Albanian; when the code has no translation, the code itself is returned.", "examples": [ "Me para n\u00eb dor\u00eb" ] } }, "required": [ "method", "count", "gross", "net", "vat", "label" ], "title": "ReportCashRegisterSalesByMethodRow" }, "ReportDailyPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "Date, `YYYY-MM-DD`.", "examples": [ "2026-09-05" ] }, "count": { "type": "integer", "description": "The number of the day's non-canceled invoices.", "examples": [ 38 ] }, "gross": { "type": "number", "description": "Their gross value, in lek.", "examples": [ 152300 ] } }, "required": [ "date", "count", "gross" ], "title": "ReportDailyPoint" }, "ReportDailyTrend": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "metric": { "type": "string", "description": "The metric you requested for the chart, confirmed: `gross` or `count`. The points carry both\nvalues regardless.", "examples": [ "gross" ] }, "series": { "type": "array", "description": "The days of the period in order, with no gaps: a day without sales comes with `count` and `gross` `0`.", "items": { "$ref": "#\/components\/schemas\/ReportDailyPoint" } } }, "required": [ "period", "metric", "series" ], "title": "ReportDailyTrend" }, "ReportOperatorRow": { "type": "object", "properties": { "id_user": { "type": [ "integer", "null" ], "description": "The id of the fature.al user who issued the invoices; `null` when the invoices carry no user.", "examples": [ 917 ] }, "name": { "type": [ "string", "null" ], "description": "The user's full name; `null` when the user no longer exists or the invoices carry no\nuser.", "examples": [ "Arben Hoxha" ] }, "operator_code": { "type": [ "string", "null" ], "description": "The operator code recorded on the invoices, the CIS one; `null` when the invoices carry no code.", "examples": [ "ef789gh012" ] }, "invoices": { "type": "integer", "description": "The number of non-canceled invoices they issued.", "examples": [ 163 ] }, "gross": { "type": "number", "description": "Their gross value, in lek.", "examples": [ 712450 ] } }, "required": [ "id_user", "name", "operator_code", "invoices", "gross" ], "title": "ReportOperatorRow" }, "ReportPeriod": { "type": "object", "properties": { "from": { "type": "string", "description": "The start date, `YYYY-MM-DD`, inclusive.", "examples": [ "2026-09-01" ] }, "to": { "type": "string", "description": "The end date, `YYYY-MM-DD`, inclusive.", "examples": [ "2026-09-13" ] } }, "required": [ "from", "to" ], "title": "ReportPeriod" }, "ReportReversalRow": { "type": "object", "properties": { "id": { "type": "integer", "description": "The id of the canceled invoice in fature.al.", "examples": [ 51902 ] }, "number": { "type": "string", "description": "The number of the canceled invoice, such as `118\/2026`; empty when the invoice carries no number.", "examples": [ "118\/2026" ] }, "type": { "type": "string", "description": "The invoice type: `CASH`, `NONCASH` or `EINVOICE`.", "examples": [ "CASH" ] }, "reversed_at": { "type": [ "string", "null" ], "description": "The date and time of the cancellation, `YYYY-MM-DD HH:MM:SS`, local time; `null` on old invoices with no\ncancellation date.", "examples": [ "2026-09-08 14:22:05" ] }, "original_invoice_id": { "type": [ "integer", "null" ], "description": "The id of the invoice the canceled invoice derives from: when it was itself a corrective\ninvoice, the invoice it corrected. `null` on an ordinary sale.", "examples": [ 51877 ] }, "gross": { "type": "number", "description": "The gross value of the canceled invoice, in lek.", "examples": [ 4200 ] }, "operator": { "type": [ "string", "null" ], "description": "The full name of the user who had issued it; `null` when the invoice carries no user.", "examples": [ "Arben Hoxha" ] } }, "required": [ "id", "number", "type", "reversed_at", "original_invoice_id", "gross", "operator" ], "title": "ReportReversalRow" }, "ReportReversalTotals": { "type": "object", "properties": { "count": { "type": "integer", "description": "How many invoices were canceled in the period.", "examples": [ 7 ] }, "gross": { "type": "number", "description": "The gross value of the canceled invoices, in lek.", "examples": [ 23150 ] } }, "required": [ "count", "gross" ], "title": "ReportReversalTotals" }, "ReportReversals": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "description": "The number and value of all cancellations in the period, regardless of `limit`.", "$ref": "#\/components\/schemas\/ReportReversalTotals" }, "items": { "type": "array", "description": "The canceled invoices, from the most recent cancellation, up to `limit` (default `100`).", "items": { "$ref": "#\/components\/schemas\/ReportReversalRow" } } }, "required": [ "period", "totals", "items" ], "title": "ReportReversals" }, "ReportSalesByMethodRow": { "type": "object", "properties": { "method": { "type": "string", "description": "The payment method code, the CIS one: `BANKNOTE`, `CARD`, `CHECK`, `SVOUCHER`, `COMPANY` on\ncash invoices; `ACCOUNT`, `TRANSFER`, `COMPENSATION`, `FACTORING`, `KIND`, `WAIVER`, `OTHER` on\nnon-cash invoices and e-invoices. Also `OTHER` when the invoice carries no payment method.", "examples": [ "BANKNOTE" ] }, "count": { "type": "integer", "description": "How many invoices were settled, fully or partly, with this method.", "examples": [ 318 ] }, "gross": { "type": "number", "description": "The gross amount settled with this method, in lek.", "examples": [ 1210400 ] }, "net": { "type": "number", "description": "The net part (excluding VAT), in lek. On split invoices it is apportioned in proportion to the gross.", "examples": [ 1008666.67 ] }, "vat": { "type": "number", "description": "The VAT part, in lek, split the same way.", "examples": [ 201733.33 ] } }, "required": [ "method", "count", "gross", "net", "vat" ], "title": "ReportSalesByMethodRow" }, "ReportSalesByTypeRow": { "type": "object", "properties": { "type": { "type": "string", "description": "The invoice type: `CASH` cash invoice, `NONCASH` non-cash invoice, `EINVOICE` e-invoice.", "examples": [ "CASH" ] }, "count": { "type": "integer", "description": "The number of non-canceled invoices of this type.", "examples": [ 351 ] }, "gross": { "type": "number", "description": "Their gross value, in lek.", "examples": [ 1402100 ] } }, "required": [ "type", "count", "gross" ], "title": "ReportSalesByTypeRow" }, "ReportSalesCancelled": { "type": "object", "properties": { "count": { "type": "integer", "description": "How many cash invoices, non-cash invoices and e-invoices dated within the period have been canceled.", "examples": [ 7 ] }, "gross": { "type": "number", "description": "Their gross value, in lek. There is no need to subtract it from `totals`: those carry only non-canceled\ninvoices.", "examples": [ 23150 ] } }, "required": [ "count", "gross" ], "title": "ReportSalesCancelled" }, "ReportSalesSummary": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "description": "The period totals over the non-canceled invoices.", "$ref": "#\/components\/schemas\/ReportSalesTotals" }, "by_payment_method": { "type": "array", "description": "Sales by the payment method that settled them, from the largest gross. An invoice paid with\nseveral methods counts toward each only with its own part.", "items": { "$ref": "#\/components\/schemas\/ReportSalesByMethodRow" } }, "by_type": { "type": "array", "description": "Sales by invoice type, from the largest gross.", "items": { "$ref": "#\/components\/schemas\/ReportSalesByTypeRow" } }, "by_vat_rate": { "type": "array", "description": "The invoice line amounts by VAT rate, from the highest rate to the\nlowest; exempt lines appear separately, with `exempt_type`.", "items": { "$ref": "#\/components\/schemas\/ReportSalesVatRateRow" } }, "by_day": { "type": "array", "description": "One point for each day with sales, in chronological order; days without sales do not appear. Empty when\n`from` and `to` are the same day.", "items": { "$ref": "#\/components\/schemas\/ReportDailyPoint" } }, "cancelled": { "description": "The period's canceled invoices, which are not included in any of the amounts above.", "$ref": "#\/components\/schemas\/ReportSalesCancelled" } }, "required": [ "period", "totals", "by_payment_method", "by_type", "by_vat_rate", "by_day", "cancelled" ], "title": "ReportSalesSummary" }, "ReportSalesTotals": { "type": "object", "properties": { "invoices": { "type": "integer", "description": "The number of non-canceled invoices in the period.", "examples": [ 412 ] }, "gross": { "type": "number", "description": "The gross value (including VAT) of the invoices, in lek.", "examples": [ 1845250 ] }, "net": { "type": "number", "description": "The net value (excluding VAT), in lek.", "examples": [ 1537708.33 ] }, "vat": { "type": "number", "description": "The total VAT, in lek.", "examples": [ 307541.67 ] }, "avg_invoice": { "type": "number", "description": "The average gross value of an invoice: `gross` divided by `invoices`; `0` when there are no invoices.", "examples": [ 4478.76 ] }, "currency": { "type": "string", "description": "The currency of the amounts, always `ALL`.", "examples": [ "ALL" ] } }, "required": [ "invoices", "gross", "net", "vat", "avg_invoice", "currency" ], "title": "ReportSalesTotals" }, "ReportSalesVatRateRow": { "type": "object", "properties": { "rate": { "type": "number", "description": "The VAT rate as a percentage, as on the invoice line: `20`, `10`, `6` or `0`.", "examples": [ 20 ] }, "net": { "type": "number", "description": "The net value (excluding VAT) of the lines, in lek.", "examples": [ 1250000 ] }, "vat": { "type": "number", "description": "The VAT of the lines, in lek.", "examples": [ 250000 ] }, "gross": { "type": "number", "description": "The gross value (including VAT) of the lines, in lek.", "examples": [ 1500000 ] }, "exempt_type": { "type": [ "string", "null" ], "description": "The VAT exemption type, the CIS code: `TYPE_1`, `TYPE_2`, `TAX_FREE` or\n`EXPORT_OF_GOODS`; on invoices pulled from the CIS, `MARGIN_SCHEME` may also appear. The key\nis present only on exempt lines; on taxable lines it is missing altogether, it does not\ncome as null.", "examples": [ "TAX_FREE" ] } }, "required": [ "rate", "net", "vat", "gross", "exempt_type" ], "title": "ReportSalesVatRateRow" }, "ReportTcrRow": { "type": "object", "properties": { "tcr_code": { "type": "string", "description": "The TCR code of the fiscal device, the one the CIS assigned.", "examples": [ "ab123cd456" ] }, "invoices": { "type": "integer", "description": "The number of non-canceled cash invoices it issued.", "examples": [ 208 ] }, "gross": { "type": "number", "description": "Their gross value, in lek.", "examples": [ 890300 ] } }, "required": [ "tcr_code", "invoices", "gross" ], "title": "ReportTcrRow" }, "ReportTopClientRow": { "type": "object", "properties": { "id_client": { "type": [ "integer", "null" ], "description": "The client id in fature.al, the buyer on the invoices; `null` when the group's invoices carry no\nbuyer. The walk-in customer, when the business has one set, is a catalog client and appears\nas its own row.", "examples": [ 3407 ] }, "name": { "type": "string", "description": "The client's business name, or the person's name when the client is not a business; empty when\nthe client no longer exists.", "examples": [ "Alfa Market shpk" ] }, "nipt": { "type": [ "string", "null" ], "description": "The client's NIPT; `null` when the client has none.", "examples": [ "K91234567A" ] }, "invoices": { "type": "integer", "description": "The number of the client's non-canceled invoices in the period.", "examples": [ 26 ] }, "gross": { "type": "number", "description": "Their gross value, in lek; the list is sorted by this amount.", "examples": [ 412600 ] } }, "required": [ "id_client", "name", "nipt", "invoices", "gross" ], "title": "ReportTopClientRow" }, "ReportTopClients": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "limit": { "type": "integer", "description": "The maximum number of clients returned, confirmed.", "examples": [ 20 ] }, "items": { "type": "array", "description": "The clients, from the largest gross value.", "items": { "$ref": "#\/components\/schemas\/ReportTopClientRow" } } }, "required": [ "period", "limit", "items" ], "title": "ReportTopClients" }, "ReportTopProductRow": { "type": "object", "properties": { "id_product": { "type": [ "integer", "null" ], "description": "The product id in the catalog; `null` for lines typed freely on the invoice, with no catalog\nproduct, which are all grouped into a single row.", "examples": [ 8123 ] }, "name": { "type": "string", "description": "The product name as written on the invoice; when the name differs between invoices, one of\nthem is returned.", "examples": [ "Kafe espresso" ] }, "code": { "type": [ "string", "null" ], "description": "The product code on the invoice; `null` when the lines carry no code.", "examples": [ "KF-001" ] }, "unit": { "type": [ "string", "null" ], "description": "The unit of measure on the invoice; `null` when the lines carry no unit.", "examples": [ "cop\u00eb" ] }, "quantity": { "type": "number", "description": "The total quantity sold, with up to three decimal places.", "examples": [ 1260 ] }, "revenue": { "type": "number", "description": "The gross revenue (including VAT) from the product, in lek.", "examples": [ 189000 ] } }, "required": [ "id_product", "name", "code", "unit", "quantity", "revenue" ], "title": "ReportTopProductRow" }, "ReportTopProducts": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "sort": { "type": "string", "description": "The sort criterion, confirmed: `revenue` by revenue, `quantity` by quantity.", "examples": [ "revenue" ] }, "limit": { "type": "integer", "description": "The maximum number of products returned, confirmed.", "examples": [ 20 ] }, "items": { "type": "array", "description": "The products, from the best selling, according to `sort`.", "items": { "$ref": "#\/components\/schemas\/ReportTopProductRow" } } }, "required": [ "period", "sort", "limit", "items" ], "title": "ReportTopProducts" }, "ReportVat": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "description": "The sales totals: the sum of `taxable` and `exempt`.", "$ref": "#\/components\/schemas\/ReportVatTotals" }, "taxable": { "type": "array", "description": "Taxable sales by VAT rate, from the highest rate.", "items": { "$ref": "#\/components\/schemas\/ReportVatTaxableRow" } }, "exempt": { "type": "array", "description": "VAT-exempt sales by exemption type.", "items": { "$ref": "#\/components\/schemas\/ReportVatExemptRow" } }, "purchases": { "description": "The same breakdown for the period's purchases.", "$ref": "#\/components\/schemas\/ReportVatPurchases" }, "summary": { "description": "The VAT collected against the VAT paid, and the difference.", "$ref": "#\/components\/schemas\/ReportVatSummary" } }, "required": [ "period", "totals", "taxable", "exempt", "purchases", "summary" ], "title": "ReportVat" }, "ReportVatExemptRow": { "type": "object", "properties": { "exempt_type": { "type": "string", "description": "The exemption type, the CIS code: `TYPE_1` (article 51 of the VAT law), `TYPE_2`\n(articles 53 and 54), `TAX_FREE` (no VAT) or `EXPORT_OF_GOODS` (export of goods). On invoices\npulled from the CIS, `MARGIN_SCHEME` may also appear.", "examples": [ "TAX_FREE" ] }, "rate": { "type": "number", "description": "The VAT rate of the lines as a percentage, usually `0`.", "examples": [ 0 ] }, "net": { "type": "number", "description": "The net value of the lines, in lek.", "examples": [ 287708.33 ] }, "vat": { "type": "number", "description": "The VAT of the lines, in lek, usually `0`.", "examples": [ 0 ] }, "gross": { "type": "number", "description": "The gross value of the lines, in lek.", "examples": [ 287708.33 ] } }, "required": [ "exempt_type", "rate", "net", "vat", "gross" ], "title": "ReportVatExemptRow" }, "ReportVatPurchases": { "type": "object", "properties": { "taxable": { "type": "array", "description": "Taxable purchases by VAT rate, from the highest rate.", "items": { "$ref": "#\/components\/schemas\/ReportVatTaxableRow" } }, "exempt": { "type": "array", "description": "VAT-exempt purchases by exemption type.", "items": { "$ref": "#\/components\/schemas\/ReportVatExemptRow" } }, "totals": { "description": "The purchase totals.", "$ref": "#\/components\/schemas\/ReportVatTotals" } }, "required": [ "taxable", "exempt", "totals" ], "title": "ReportVatPurchases" }, "ReportVatSummary": { "type": "object", "properties": { "output_vat": { "type": "number", "description": "The VAT collected on sales, the same as `totals.vat`, in lek.", "examples": [ 250000 ] }, "input_vat": { "type": "number", "description": "The VAT paid on purchases, the same as `purchases.totals.vat`, in lek.", "examples": [ 96000 ] }, "vat_due": { "type": "number", "description": "`output_vat` minus `input_vat`, in lek: the VAT payable; negative when purchases carry\nmore VAT than sales.", "examples": [ 154000 ] }, "currency": { "type": "string", "description": "The currency of the amounts, always `ALL`.", "examples": [ "ALL" ] } }, "required": [ "output_vat", "input_vat", "vat_due", "currency" ], "title": "ReportVatSummary" }, "ReportVatTaxableRow": { "type": "object", "properties": { "rate": { "type": "number", "description": "The VAT rate as a percentage: `20`, `10`, `6` or `0`.", "examples": [ 20 ] }, "net": { "type": "number", "description": "The net value (excluding VAT) of the lines, in lek.", "examples": [ 1250000 ] }, "vat": { "type": "number", "description": "The VAT of the lines, in lek.", "examples": [ 250000 ] }, "gross": { "type": "number", "description": "The gross value (including VAT) of the lines, in lek.", "examples": [ 1500000 ] } }, "required": [ "rate", "net", "vat", "gross" ], "title": "ReportVatTaxableRow" }, "ReportVatTotals": { "type": "object", "properties": { "net": { "type": "number", "description": "The net value (excluding VAT) of the lines, in lek.", "examples": [ 1537708.33 ] }, "vat": { "type": "number", "description": "The VAT of the lines, in lek.", "examples": [ 250000 ] }, "gross": { "type": "number", "description": "The gross value (including VAT) of the lines, in lek.", "examples": [ 1787708.33 ] }, "currency": { "type": "string", "description": "The currency of the amounts, always `ALL`.", "examples": [ "ALL" ] } }, "required": [ "net", "vat", "gross", "currency" ], "title": "ReportVatTotals" }, "ReportWtn": { "type": "object", "properties": { "period": { "description": "The confirmed report period.", "$ref": "#\/components\/schemas\/ReportPeriod" }, "totals": { "description": "The number and value of all notes in the period.", "$ref": "#\/components\/schemas\/ReportWtnTotals" }, "by_status": { "type": "array", "description": "One row for each fiscal status encountered.", "items": { "$ref": "#\/components\/schemas\/ReportWtnStatusRow" } }, "unique_destinations": { "type": "integer", "description": "How many different destination cities the period's notes have; the length of `destinations`.", "examples": [ 3 ] }, "destinations": { "type": "array", "description": "The destination cities, each once, as written on the notes; notes without a city\nare not included.", "examples": [ [ "Tiran\u00eb", "Durr\u00ebs", "Shkod\u00ebr" ] ], "items": { "type": "string" } } }, "required": [ "period", "totals", "by_status", "unique_destinations", "destinations" ], "title": "ReportWtn" }, "ReportWtnStatusRow": { "type": "object", "properties": { "status": { "type": [ "string", "null" ], "description": "The fiscal status of the notes: `FISCALIZED` registered with the CIS, `UNFISCALIZED` not yet\nregistered; `null` on notes with no status recorded.", "examples": [ "FISCALIZED" ] }, "count": { "type": "integer", "description": "How many notes are in this status.", "examples": [ 40 ] }, "value_of_goods": { "type": "number", "description": "The total value of goods declared on them, in lek.", "examples": [ 1498000 ] } }, "required": [ "status", "count", "value_of_goods" ], "title": "ReportWtnStatusRow" }, "ReportWtnTotals": { "type": "object", "properties": { "count": { "type": "integer", "description": "The number of warehouse transfer notes in the period.", "examples": [ 42 ] }, "value_of_goods": { "type": "number", "description": "The total value of goods declared on the notes, in lek.", "examples": [ 1560000 ] } }, "required": [ "count", "value_of_goods" ], "title": "ReportWtnTotals" }, "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", "properties": { "internalId": { "type": "string", "description": "The invoice identifier in your system; also serves as the idempotency key. Required.", "examples": [ "SUMMARY-2026-000021" ] }, "payment_method": { "type": "string", "description": "The payment method: `BANKNOTE` or `CARD`. Required.", "enum": [ "BANKNOTE", "CARD" ], "examples": [ "CARD" ] }, "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 } }, "required": [ "internalId", "payment_method", "order_invoices" ], "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" ] }, "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", "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 ] }, "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", "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", "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 }, "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" ], "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 ] }, "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", "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" ] } } } } } } }