01 · API overview
Fiscalization, sales and purchases in one API
Integrate Albania fiscalization and electronic invoicing with easyPos. Create invoices, manage cash balances, and access your business’s sales and purchases through one REST API.
- 01
Get credentials
Request an access token registered for the environment, business and device you will use.
- 02
Create a docId
Generate and persist one stable identifier before the first request.
- 03
Register and verify
Send the invoice, then evaluate completion identifiers—not HTTP 200 alone.
Minimal normal invoice
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHOP-2026-000123",
"articles": [
{
"articleId": "ART-1",
"name": "Kafe",
"vatCode": "B",
"price": 120,
"units": 2,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "CASH",
"amount": 240
}
]
}'Completed response
{
"orderId": "SHOP-2026-000123",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "12/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 240
}02 · Access
Authentication and request headers
Every endpoint requires a bearer token. Replace the example integration-app value with the stable identifier assigned to your integration, then keep that value unchanged across requests.
| Header | Requirement | Purpose |
|---|---|---|
Authorization | Required | Bearer access token for the selected environment. |
Content-Type | Required | Use application/json for every request. |
integration-app | Recommended | Replace your-client-name or erp-x with the stable identifier assigned to your integration. |
03 · Recovery protocol
docId is your duplicate-prevention key
Choose docId in your system before sending a document. Reusing it continues the same fiscal operation and returns the same result; it must not create a second invoice.
- Generate once
- 5–200 characters, unique for each business document.
- Persist before POST
- Store docId, the immutable request body and your local document ID atomically.
- Reuse on recovery
- Timeouts, connection loss, 502/503 and incomplete electronic responses keep the same docId.
- Single flight
- Never run register and status concurrently for one docId.
Safe recovery sequence
same docId · same body- 01
POST register
- 02
Ambiguous or incomplete
- 03
Wait + jitter
- 04
POST status
- 05
Complete?
- 06
Replay same body
- 1Check completion: normal invoices require fic; electronic invoices require both fic and eic.
- 2For a timeout, network error, 502/503 or incomplete result, wait with exponential backoff and jitter, capped at 30 seconds.
- 3Call /invoice/status with the same docId. If the API says it does not exist, replay /invoice/register with the exact same body and docId.
- 4Do not retry validation errors or cisError.faultEnv=env:CLIENT until the request is corrected.
Cancellation is a new fiscal document: create a new cancellation docId. Every retry of that cancellation reuses its cancellation docId.
Client-side decision outline
const docId = await persistOperation(payload)
const result = await register({ ...payload, docId })
if (result.fic && (!payload.isEinvoice || result.eic)) return complete(result)
await backoffWithJitter()
const recovered = await status({ docId })
if (recovered.notFound) {
return register({ ...payload, docId }) // exact same body
}
return evaluate(recovered)04 · Document model
Invoice request explorer
Open any document type to inspect a complete request, response and the exact completion identifiers your client must check.
POST NORMALArticles, split payments and optional buyer. documentType may be omitted. fic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHOP-2026-000123",
"articles": [
{
"articleId": "ART-COFFEE",
"name": "Kafe ekspres",
"vatCode": "B",
"price": 120,
"units": 2,
"soldIn": "XPP"
},
{
"articleId": "ART-WATER",
"name": "Ujë natyral",
"vatCode": "B",
"price": 100,
"units": 1,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "CASH",
"amount": 200
},
{
"type": "CARD",
"amount": 140
}
]
}'Example response
{
"orderId": "SHOP-2026-000123",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "12/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 340
}Request fields
| Field | Type |
|---|---|
docId | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
POST ORDERArticles only; payment is omitted and generated as ORDER. fic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "ORDER-2026-000124",
"documentType": "ORDER",
"articles": [
{
"articleId": "ORD-1",
"name": "Drekë biznesi",
"vatCode": "B",
"price": 1200,
"units": 1,
"soldIn": "XPP"
}
]
}'Example response
{
"orderId": "ORDER-2026-000124",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "13/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 1200
}Request fields
| Field | Type |
|---|---|
docId | string |
documentType | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
POST SUMMARYConsumes unused ORDER iic values; articles are omitted. fic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SUMMARY-2026-000125",
"documentType": "SUMMARY",
"summaryInvoices": [
"D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"A11EBF3F7B7C502D6AAF2321A7CE2CE9"
],
"total": 1800,
"payment": [
{
"type": "CASH",
"amount": 1800
}
]
}'Example response
{
"orderId": "SUMMARY-2026-000125",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "14/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 1800
}Request fields
| Field | Type |
|---|---|
docId | string |
documentType | string |
summaryInvoices | string[] |
total | number |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
POST SELFISSUERequires selfIssueType; supplier data in buyer becomes the seller, and the business becomes the buyer. fic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SELFISSUE-2026-000126",
"documentType": "SELFISSUE",
"selfIssueType": "DOMESTIC",
"reverseCharge": true,
"buyer": {
"buyerIDType": "NUIS",
"buyerIDNum": "{{supplierNipt}}",
"buyerName": "Furnitor SHPK",
"buyerAddress": "Tiranë",
"buyerTown": "Tiranë",
"buyerCountry": "ALB"
},
"articles": [
{
"articleId": "SVC-1",
"name": "Shërbim profesional",
"vatCode": "B",
"price": 10000,
"units": 1,
"soldIn": "HUR"
}
],
"payment": [
{
"type": "CASH",
"amount": 10000
}
]
}'Example response
{
"orderId": "SELFISSUE-2026-000126",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "15/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 10000
}Request fields
| Field | Type |
|---|---|
docId | string |
documentType | string |
selfIssueType | string |
reverseCharge | boolean |
buyer | object |
buyer.buyerIDType | string |
buyer.buyerIDNum | string |
buyer.buyerName | string |
buyer.buyerAddress | string |
buyer.buyerTown | string |
buyer.buyerCountry | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
POST EXPORTForeign buyer required; use the export VAT code configured for the business. fic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "EXPORT-2026-000127",
"documentType": "EXPORT",
"supplyPeriod": {
"start": "2026-08-01",
"end": "2026-08-28"
},
"buyer": {
"buyerIDType": "VAT",
"buyerIDNum": "IT12345678901",
"buyerName": "Acquirente Demo SRL",
"buyerAddress": "Via Roma 1",
"buyerTown": "Bari",
"buyerCountry": "ITA",
"buyerCountryCode": "IT"
},
"articles": [
{
"articleId": "EXP-1",
"name": "Mall për eksport",
"vatCode": "J",
"price": 25000,
"units": 4,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "TRANSFER",
"amount": 100000
}
]
}'Example response
{
"orderId": "EXPORT-2026-000127",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "16/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 100000
}Request fields
| Field | Type |
|---|---|
docId | string |
documentType | string |
supplyPeriod | object |
supplyPeriod.start | string |
supplyPeriod.end | string |
buyer | object |
buyer.buyerIDType | string |
buyer.buyerIDNum | string |
buyer.buyerName | string |
buyer.buyerAddress | string |
buyer.buyerTown | string |
buyer.buyerCountry | string |
buyer.buyerCountryCode | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
POST ELECTRONIC · P1Standard electronic invoice with NUIS buyer and non-cash payment. fic + eic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "EINVOICE-P1-2026-000128",
"isEinvoice": true,
"selectedProcess": "P1",
"payDeadline": "2026-09-30",
"buyer": {
"buyerIDType": "NUIS",
"buyerIDNum": "{{buyerNipt}}",
"buyerName": "Blerës SHPK",
"buyerAddress": "Tiranë",
"buyerTown": "Tiranë",
"buyerCountry": "ALB",
"buyerCountryCode": "AL"
},
"articles": [
{
"articleId": "SVC-CLOUD",
"name": "Shërbim cloud",
"vatCode": "B",
"price": 10000,
"units": 1,
"soldIn": "HUR"
}
],
"payment": [
{
"type": "ACCOUNT",
"amount": 10000,
"details": [
{
"idNumber": "{{sellerIban}}",
"name": "Shitësi SHPK",
"bankName": "Banka",
"swift_code": "ABCDEFGH",
"country": "Shqipëri",
"countryCode": "AL",
"currency": "ALL"
}
]
}
]
}'Example response
{
"orderId": "EINVOICE-P1-2026-000128",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "17/2026/xx123xx123",
"invoiceType": "NONCASH",
"totalPrice": 10000,
"eic": "2a8d91cf-8fea-4d86-b79d-4bcb0b153e78"
}Request fields
| Field | Type |
|---|---|
docId | string |
isEinvoice | boolean |
selectedProcess | string |
payDeadline | string |
buyer | object |
buyer.buyerIDType | string |
buyer.buyerIDNum | string |
buyer.buyerName | string |
buyer.buyerAddress | string |
buyer.buyerTown | string |
buyer.buyerCountry | string |
buyer.buyerCountryCode | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
payment[].details | object[] |
payment[].details[].idNumber | string |
payment[].details[].name | string |
payment[].details[].bankName | string |
payment[].details[].swift_code | string |
payment[].details[].country | string |
payment[].details[].countryCode | string |
payment[].details[].currency | string |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
eic | string |
POST ELECTRONIC · P4Prepayment invoice; prepaidAmount must be within the total. fic + eic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "EINVOICE-P4-2026-000129",
"isEinvoice": true,
"selectedProcess": "P4",
"prepaidAmount": 5000,
"buyer": {
"buyerIDType": "NUIS",
"buyerIDNum": "{{buyerNipt}}",
"buyerName": "Blerës SHPK",
"buyerAddress": "Tiranë",
"buyerTown": "Tiranë",
"buyerCountry": "ALB"
},
"articles": [
{
"articleId": "ADV-1",
"name": "Parapagim shërbimi",
"vatCode": "B",
"price": 10000,
"units": 1,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "TRANSFER",
"amount": 10000
}
]
}'Example response
{
"orderId": "EINVOICE-P4-2026-000129",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "18/2026/xx123xx123",
"invoiceType": "NONCASH",
"totalPrice": 10000,
"eic": "0543e84b-6108-48b2-a2af-5db66bb80616"
}Request fields
| Field | Type |
|---|---|
docId | string |
isEinvoice | boolean |
selectedProcess | string |
prepaidAmount | number |
buyer | object |
buyer.buyerIDType | string |
buyer.buyerIDNum | string |
buyer.buyerName | string |
buyer.buyerAddress | string |
buyer.buyerTown | string |
buyer.buyerCountry | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
eic | string |
POST ELECTRONIC · P9/P10Credit or corrective invoice referencing an electronic iic. fic + eic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "EINVOICE-P9-2026-000130",
"isEinvoice": true,
"selectedProcess": "P9",
"correctiveInvoice": {
"iicRef": "{{electronicIic}}"
},
"buyer": {
"buyerIDType": "NUIS",
"buyerIDNum": "{{buyerNipt}}",
"buyerName": "Blerës SHPK",
"buyerAddress": "Tiranë",
"buyerTown": "Tiranë",
"buyerCountry": "ALB"
},
"articles": [
{
"articleId": "CORR-1",
"name": "Korrigjim shërbimi",
"vatCode": "B",
"price": 1000,
"units": -1,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "TRANSFER",
"amount": -1000
}
]
}'Example response
{
"orderId": "EINVOICE-P9-2026-000130",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "19/2026/xx123xx123",
"invoiceType": "NONCASH",
"totalPrice": -1000,
"eic": "6df80aec-f690-43ce-a2f2-45ee0cb948ce"
}Request fields
| Field | Type |
|---|---|
docId | string |
isEinvoice | boolean |
selectedProcess | string |
correctiveInvoice | object |
correctiveInvoice.iicRef | string |
buyer | object |
buyer.buyerIDType | string |
buyer.buyerIDNum | string |
buyer.buyerName | string |
buyer.buyerAddress | string |
buyer.buyerTown | string |
buyer.buyerCountry | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
eic | string |
POST ELECTRONIC · P11Partial electronic invoicing flow. fic + eic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "EINVOICE-P11-2026-000131",
"isEinvoice": true,
"selectedProcess": "P11",
"buyer": {
"buyerIDType": "NUIS",
"buyerIDNum": "{{buyerNipt}}",
"buyerName": "Blerës SHPK",
"buyerAddress": "Tiranë",
"buyerTown": "Tiranë",
"buyerCountry": "ALB"
},
"articles": [
{
"articleId": "PART-1",
"name": "Faturim i pjesshëm",
"vatCode": "B",
"price": 25000,
"units": 1,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "TRANSFER",
"amount": 25000
}
]
}'Example response
{
"orderId": "EINVOICE-P11-2026-000131",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "20/2026/xx123xx123",
"invoiceType": "NONCASH",
"totalPrice": 25000,
"eic": "55df7eaf-126f-41b7-8270-6fa57080703e"
}Request fields
| Field | Type |
|---|---|
docId | string |
isEinvoice | boolean |
selectedProcess | string |
buyer | object |
buyer.buyerIDType | string |
buyer.buyerIDNum | string |
buyer.buyerName | string |
buyer.buyerAddress | string |
buyer.buyerTown | string |
buyer.buyerCountry | string |
articles | object[] |
articles[].articleId | string |
articles[].name | string |
articles[].vatCode | string |
articles[].price | number |
articles[].units | number |
articles[].soldIn | string |
payment | object[] |
payment[].type | string |
payment[].amount | number |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
eic | string |
POST CANCELLATION · NORMALNew cancellation docId referencing the original invoice iic. fic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "CANCEL-2026-000132",
"correctiveInvoice": {
"iicRef": "D21EBF3F7B7C502D6AAF2321A7CE2CE8"
},
"invoiceNotes": "Anulim me kërkesë të klientit"
}'Example response
{
"orderId": "CANCEL-2026-000132",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "21/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": -340
}Request fields
| Field | Type |
|---|---|
docId | string |
correctiveInvoice | object |
correctiveInvoice.iicRef | string |
invoiceNotes | string |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
POST CANCELLATION · ELECTRONICP10 corrective cancellation of an invoice that already has eic. fic + eic
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "CANCEL-EINVOICE-2026-000133",
"isEinvoice": true,
"selectedProcess": "P10",
"correctiveInvoice": {
"iicRef": "{{electronicIic}}"
},
"invoiceNotes": "Anulim i faturës elektronike"
}'Example response
{
"orderId": "CANCEL-EINVOICE-2026-000133",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "22/2026",
"invoiceType": "NONCASH",
"totalPrice": -10000,
"eic": "d59ef857-47df-4a80-a7d8-22ce70577df3"
}Request fields
| Field | Type |
|---|---|
docId | string |
isEinvoice | boolean |
selectedProcess | string |
correctiveInvoice | object |
correctiveInvoice.iicRef | string |
invoiceNotes | string |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string |
iic | string |
invoiceNumber | string |
invoiceType | string |
totalPrice | number |
eic | string |
Electronic invoice process map
Electronic invoices may take longer because fiscalization and eInvoice delivery are separate stages. Treat them as complete only when both identifiers are present.
| Process | Default invoice type | Extra rule |
|---|---|---|
P1 | 380 | Deliveries against purchase orders under a contract. |
P2 | 380 | Deliveries of goods or services under a contract. |
P3 | 380 | Delivery against an occasional purchase order. |
P4 | 386 | Prepayment; prepaidAmount must be greater than 0 and no greater than total. |
P5 | 380 | Payment on the spot. |
P6 | 380 | Payment before delivery. |
P7 | 380 | Invoice referencing a despatch advice. |
P8 | 380 | Invoice referencing both despatch and receipt advice. |
P9 | 384 | Credit note or negative invoice; correctiveInvoice.iicRef must reference an invoice with eic. |
P10 | 384 | Corrective invoice or cancellation; correctiveInvoice.iicRef must reference an invoice with eic. |
P11 | 326 | Partial and final invoicing. |
Direct UNTDID invoice type codes
Use selectedInvoiceType only when you need a specific document classification. If omitted, selectedProcess chooses the default shown above.
| Code | Meaning |
|---|---|
82 | Metered-services invoice |
84 | Debit note for financial adjustments |
325 | Pro forma invoice |
326 | Partial invoice |
380 | Commercial invoice |
383 | Debit note |
386 | Prepayment invoice |
393 | Factored invoice |
394 | Lease invoice |
395 | Consignment invoice |
575 | Insurer invoice |
623 | Forwarder invoice |
780 | Freight invoice |
Codes 80, 381, 384, 385 and 389 are reserved for process-assigned document types and cannot be selected directly.
05 · HTTP reference
Endpoints
All endpoints use POST with JSON and the same authentication headers.
POST/invoice/registerRegister invoice · Create a new fiscal document or continue the document identified by docId.
Invoices#register-invoice
- Required
- docId · articles[]* · payment[]*
- Rules
- NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT | eInvoice
Request fields
| Field | Type |
|---|---|
docId | string |
operatorCode | string? |
currency | Currency? |
articles | Article[] (conditional) |
payment | Payment[] (conditional) |
invoiceRebate | Rebate? |
buyer | Buyer (conditional) |
correctiveInvoice | CorrectiveInvoiceRef (conditional) |
invoiceNotes | string? |
documentType | NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT? |
selfIssueType | AGREEMENT | DOMESTIC | ABROAD | SELF | OTHER (conditional) |
reverseCharge | boolean? |
summaryInvoices | string[] (conditional) |
total | number (conditional) |
supplyPeriod | SupplyPeriod? · start <= end · same calendar month |
isEinvoice | boolean? |
selectedProcess | P1 | P2 | P3 | P4 | P5 | P6 | P7 | P8 | P9 | P10 | P11? |
selectedInvoiceType | UNTDID code? |
payDeadline | string(date)? |
prepaidAmount | number (conditional) |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string? |
eic | string? |
iic | string? |
link | string(uri)? |
error | FiscalError? |
invoiceNumber | string? |
invoiceOrderNumber | integer? |
invoiceType | CASH | NONCASH? |
totalPrice | number? |
totalPriceWithoutVat | number? |
totalVatAmount | number? |
taxFreeAmount | number? |
goodsExport | number? |
markUpAmount | number? |
operatorCode | string? |
businessUnitCode | string? |
tcrCode | string? |
sellerName | string? |
sellerNuis | string? |
sellerAddress | string? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/register' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHOP-2026-000123",
"articles": [
{
"articleId": "ART-1",
"name": "Kafe",
"vatCode": "B",
"price": 120,
"units": 2,
"soldIn": "XPP"
}
],
"payment": [
{
"type": "CASH",
"amount": 240
}
]
}'Example response
{
"orderId": "SHOP-2026-000123",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "12/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 240
}POST/invoice/cancelCancel invoice · Create a corrective cancellation for an existing invoice iic.
Invoices#cancel-invoice
- Required
- new docId · correctiveInvoice.iicRef
- Rules
- no articles · no payment
Request fields
| Field | Type |
|---|---|
docId | string |
operatorCode | string? |
correctiveInvoice | CorrectiveInvoiceRef |
invoiceNotes | string? |
isEinvoice | boolean? |
selectedProcess | P1–P11? |
selectedInvoiceType | UNTDID code? |
payDeadline | string(date)? |
prepaidAmount | number? |
supplyPeriod | SupplyPeriod? (inherits from original when omitted) |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string? |
eic | string? |
iic | string? |
link | string(uri)? |
error | FiscalError? |
invoiceNumber | string? |
invoiceOrderNumber | integer? |
invoiceType | CASH | NONCASH? |
totalPrice | number? |
totalPriceWithoutVat | number? |
totalVatAmount | number? |
taxFreeAmount | number? |
goodsExport | number? |
markUpAmount | number? |
operatorCode | string? |
businessUnitCode | string? |
tcrCode | string? |
sellerName | string? |
sellerNuis | string? |
sellerAddress | string? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/cancel' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHOP-2026-000123-CANCEL",
"correctiveInvoice": {
"iicRef": "D21EBF3F7B7C502D6AAF2321A7CE2CE8"
},
"invoiceNotes": "Customer cancellation"
}'Example response
{
"orderId": "SHOP-2026-000123-CANCEL",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "13/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": -240
}POST/invoice/statusInvoice status · Read status by docId and continue an incomplete operation.
Invoices#invoice-status
- Required
- docId
- Rules
- same docId · may continue processing
Request fields
| Field | Type |
|---|---|
docId | string |
Response fields
| Field | Type |
|---|---|
orderId | string |
fic | string? |
eic | string? |
iic | string? |
link | string(uri)? |
error | FiscalError? |
invoiceNumber | string? |
invoiceOrderNumber | integer? |
invoiceType | CASH | NONCASH? |
totalPrice | number? |
totalPriceWithoutVat | number? |
totalVatAmount | number? |
taxFreeAmount | number? |
goodsExport | number? |
markUpAmount | number? |
operatorCode | string? |
businessUnitCode | string? |
tcrCode | string? |
sellerName | string? |
sellerNuis | string? |
sellerAddress | string? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/status' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHOP-2026-000123"
}'Example response
{
"orderId": "SHOP-2026-000123",
"fic": "52ca073b-536e-48e9-8678-cc0bf2202046",
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"invoiceNumber": "12/2026/xx123xx123",
"invoiceType": "CASH",
"totalPrice": 240
}POST/invoice/pdfInvoice PDF · Generate an A4 PDF, receipt PNG or official electronic invoice PDF as base64.
Invoices#invoice-pdf
- Required
- iic
- Rules
- A4 | receipt | eInvoice
Request fields
| Field | Type |
|---|---|
iic | string |
pdfType | 'A4' | 'receipt' | 'eInvoice' |
paperWidth | 58 | 80 | 110? |
lang | 'sq' | 'en'? |
Response fields
| Field | Type |
|---|---|
base64 | string |
lang | string? |
eic | string? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/invoice/pdf' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"iic": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"pdfType": "A4",
"lang": "sq"
}'Example response
{
"base64": "JVBERi0xLjQKJcfsj6IK...",
"lang": "sq"
}POST/balance/initiateInitiate balance · Report the opening cash balance in ALL.
Cash balance#initiate-balance
- Required
- docId · amount
- Rules
- once per business day and fiscal device · before the first cash invoice · amount in ALL
Request fields
| Field | Type |
|---|---|
docId | string |
amount | number |
notes | string? |
operatorCode | string? |
Response fields
| Field | Type |
|---|---|
orderId | string |
fcdc | string? |
error | FiscalError? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/initiate' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHIFT-2026-08-28-OPEN",
"amount": 10000
}'Example response
{
"orderId": "SHIFT-2026-08-28-OPEN",
"fcdc": "b5c3e1a2-9f44-4c3a-9c1e-2f0d7a5b8e10"
}POST/balance/depositDeposit cash · Report cash added to the till in ALL.
Cash balance#deposit-balance
- Required
- docId · amount
- Rules
- amount in ALL
Request fields
| Field | Type |
|---|---|
docId | string |
amount | number |
notes | string? |
operatorCode | string? |
Response fields
| Field | Type |
|---|---|
orderId | string |
fcdc | string? |
error | FiscalError? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/deposit' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHIFT-2026-08-28-IN-1",
"amount": 5000,
"notes": "Cash added to till"
}'Example response
{
"orderId": "SHIFT-2026-08-28-IN-1",
"fcdc": "d6a4e2b3-8e55-4d2b-8b2f-3a1e6b4c9f21"
}POST/balance/withdrawWithdraw cash · Report cash removed from the till in ALL.
Cash balance#withdraw-balance
- Required
- docId · amount
- Rules
- amount in ALL
Request fields
| Field | Type |
|---|---|
docId | string |
amount | number |
notes | string? |
operatorCode | string? |
Response fields
| Field | Type |
|---|---|
orderId | string |
fcdc | string? |
error | FiscalError? |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/balance/withdraw' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"docId": "SHIFT-2026-08-28-OUT-1",
"amount": 2500,
"notes": "Bank deposit"
}'Example response
{
"orderId": "SHIFT-2026-08-28-OUT-1",
"fcdc": "e7b5f3c4-7d66-5e3c-9a3e-4b2f7c5d0a32"
}POST/utilities/get-taxpayersSearch taxpayers · Search Albanian taxpayers by NIPT or business name.
Utilities#get-taxpayers
- Required
- searchTerm (3–200)
- Rules
- NIPT or business name · searchTerm minimum 3 characters · no activity-status field
Request fields
| Field | Type |
|---|---|
searchTerm | string (3–200) |
Response fields
| Field | Type |
|---|---|
[] | Taxpayer[] |
[].Tin | string |
[].Name | string |
[].Address | string |
[].Town | string |
[].Country | string (ISO 3166-1 alpha-3) |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/get-taxpayers' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"searchTerm": "Vodafone"
}'Example response
[
{
"Address": "Rruga Pavaresia, kodi postal 1050, Kashar 61",
"Country": "ALB",
"Name": "FONDACIONI VODAFONE ALBANIA",
"Tin": "K72118452F",
"Town": "Tirane"
},
{
"Address": "Autostrada Tirane-Durres, Rruga Pavaresia, Nr.61, Kashar",
"Country": "ALB",
"Name": "VODAFONE ALBANIA",
"Tin": "K11715005L",
"Town": "Kashar"
}
]POST/utilities/get-operatorsList operators · Return operators available to the authenticated business and device.
Utilities#get-operators
- Required
- none
- Rules
- authenticated business + device
Request fields
| Field | Type |
|---|---|
body | {} |
Response fields
| Field | Type |
|---|---|
[] | Operator[] |
[].name | string |
[].opCode | string |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/get-operators' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{}'Example response
[
{
"name": "test3",
"opCode": "gh537ez280"
},
{
"name": "User A",
"opCode": "aa111aa222"
}
]POST/utilities/cis-invoices/salesCIS sales · Retrieve the business’s sales registered in CIS. Dates cover full days; ToDate must not precede FromDate. Omit dates for the current month, or use FIC for the full invoice with items.
Utilities#cis-sales
- Required
- none · body optional
- Rules
- current month by default · up to 1000/page · FIC returns Items · CIS scalar values are strings
Request fields
| Field | Type |
|---|---|
FromDate | string(date)? · YYYY-MM-DD · default: first day of current month |
ToDate | string(date)? · YYYY-MM-DD · default: last day of current month |
Page | integer? · minimum: 1 · default: 1 |
FIC | string(uuid)? · ignores FromDate, ToDate and Page |
Response fields
| Field | Type |
|---|---|
[] | CisInvoice[] · empty when no invoice is found |
[].TypeOfInv | CASH | NONCASH? |
[].IsSimplifiedInv | 'true' | 'false'? |
[].IsBadDeb | 'true' | 'false'? |
[].TypeOfSelfIss | string? |
[].IssueDateTime | string? |
[].SendDateTime | string? |
[].InvNum | string? |
[].InvOrdNum | string? |
[].TCRCode | string? |
[].IsIssuerInVAT | 'true' | 'false'? |
[].TaxFreeAmt | string? |
[].MarkUpAmt | string? |
[].GoodsExAmt | string? |
[].TotPriceWoVAT | string? |
[].TotVATAmt | string? |
[].TotPrice | string? |
[].OperatorCode | string? |
[].BusinUnitCode | string? |
[].SoftCode | string? |
[].IIC | string? |
[].IICSignature | string? |
[].FIC | string(uuid)? |
[].IsReverseCharge | 'true' | 'false'? |
[].PayDeadline | string(date)? |
[].PayMethods | { Type?: string; Amt?: string; CompCard?: string; Vouchers?: object[] }[]? |
[].Seller | CisParty? |
[].Buyer | CisParty? |
[].Currency | { Code?: string; ExRate?: string; IsBuying?: string }? |
[].SupplyDateOrPeriod | { Start?: string(date); End?: string(date) }? |
[].CorrectiveInv | { IICRef?: string; IssueDateTime?: string; Type?: string }? |
[].BadDebtInv | { IICRef?: string; IssueDateTime?: string }? |
[].IsEinvoice | 'true' | 'false'? |
[].EIC | string(uuid)? |
[].SameTaxes | object[]? · numeric values are strings |
[].Fees | { Type?: string; Amt?: string }[]? |
[].SumInvIICRefs | { IIC?: string; IssueDateTime?: string }[]? |
[].Items | CisInvoiceItem[]? · returned only for FIC lookup |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/cis-invoices/sales' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"FromDate": "2026-09-01",
"ToDate": "2026-09-30",
"Page": 1
}'Example response
[
{
"TypeOfInv": "NONCASH",
"IssueDateTime": "2026-09-15T12:41:32+02:00",
"InvNum": "12/2026/xx123xx123",
"InvOrdNum": "12",
"TotPriceWoVAT": "100.00",
"TotVATAmt": "20.00",
"TotPrice": "120.00",
"IIC": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"FIC": "2ed48eff-f3d0-4315-a2a5-16618c63ad0b",
"IsIssuerInVAT": "true",
"IsEinvoice": "false",
"Seller": {
"IDType": "NUIS",
"IDNum": "BUSINESS_NIPT",
"Name": "Business Demo SHPK"
},
"Buyer": {
"IDType": "NUIS",
"IDNum": "BUYER_NIPT",
"Name": "Buyer Demo SHPK"
},
"PayMethods": [
{
"Type": "ACCOUNT",
"Amt": "120.00"
}
],
"SameTaxes": [
{
"NumOfItems": "1",
"PriceBefVAT": "100.00",
"VATRate": "20.00",
"VATAmt": "20.00"
}
]
}
]POST/utilities/cis-invoices/purchasesCIS purchases · Retrieve supplier invoices registered in CIS where this business is the buyer. Up to 1,000 invoices per page; no match returns an empty array. FIC ignores dates and Page.
Utilities#cis-purchases
- Required
- none · body optional
- Rules
- current month by default · up to 1000/page · FIC returns Items · CIS scalar values are strings
Request fields
| Field | Type |
|---|---|
FromDate | string(date)? · YYYY-MM-DD · default: first day of current month |
ToDate | string(date)? · YYYY-MM-DD · default: last day of current month |
Page | integer? · minimum: 1 · default: 1 |
FIC | string(uuid)? · ignores FromDate, ToDate and Page |
Response fields
| Field | Type |
|---|---|
[] | CisInvoice[] · empty when no invoice is found |
[].TypeOfInv | CASH | NONCASH? |
[].IsSimplifiedInv | 'true' | 'false'? |
[].IsBadDeb | 'true' | 'false'? |
[].TypeOfSelfIss | string? |
[].IssueDateTime | string? |
[].SendDateTime | string? |
[].InvNum | string? |
[].InvOrdNum | string? |
[].TCRCode | string? |
[].IsIssuerInVAT | 'true' | 'false'? |
[].TaxFreeAmt | string? |
[].MarkUpAmt | string? |
[].GoodsExAmt | string? |
[].TotPriceWoVAT | string? |
[].TotVATAmt | string? |
[].TotPrice | string? |
[].OperatorCode | string? |
[].BusinUnitCode | string? |
[].SoftCode | string? |
[].IIC | string? |
[].IICSignature | string? |
[].FIC | string(uuid)? |
[].IsReverseCharge | 'true' | 'false'? |
[].PayDeadline | string(date)? |
[].PayMethods | { Type?: string; Amt?: string; CompCard?: string; Vouchers?: object[] }[]? |
[].Seller | CisParty? |
[].Buyer | CisParty? |
[].Currency | { Code?: string; ExRate?: string; IsBuying?: string }? |
[].SupplyDateOrPeriod | { Start?: string(date); End?: string(date) }? |
[].CorrectiveInv | { IICRef?: string; IssueDateTime?: string; Type?: string }? |
[].BadDebtInv | { IICRef?: string; IssueDateTime?: string }? |
[].IsEinvoice | 'true' | 'false'? |
[].EIC | string(uuid)? |
[].SameTaxes | object[]? · numeric values are strings |
[].Fees | { Type?: string; Amt?: string }[]? |
[].SumInvIICRefs | { IIC?: string; IssueDateTime?: string }[]? |
[].Items | CisInvoiceItem[]? · returned only for FIC lookup |
Request body
curl --request POST \
--url 'https://api.dev.easypos.al/fiscalisation-service/v1/utilities/cis-invoices/purchases' \
--header 'Authorization: Bearer {{accessToken}}' \
--header 'Content-Type: application/json' \
--header 'integration-app: your-client-name' \
--data '{
"FromDate": "2026-09-01",
"ToDate": "2026-09-30",
"Page": 1
}'Example response
[
{
"TypeOfInv": "NONCASH",
"IssueDateTime": "2026-09-15T12:41:32+02:00",
"InvNum": "12/2026/xx123xx123",
"InvOrdNum": "12",
"TotPriceWoVAT": "100.00",
"TotVATAmt": "20.00",
"TotPrice": "120.00",
"IIC": "D21EBF3F7B7C502D6AAF2321A7CE2CE8",
"FIC": "2ed48eff-f3d0-4315-a2a5-16618c63ad0b",
"IsIssuerInVAT": "true",
"IsEinvoice": "false",
"Seller": {
"IDType": "NUIS",
"IDNum": "SUPPLIER_NIPT",
"Name": "Supplier Demo SHPK"
},
"Buyer": {
"IDType": "NUIS",
"IDNum": "BUSINESS_NIPT",
"Name": "Business Demo SHPK"
},
"PayMethods": [
{
"Type": "ACCOUNT",
"Amt": "120.00"
}
],
"SameTaxes": [
{
"NumOfItems": "1",
"PriceBefVAT": "100.00",
"VATRate": "20.00",
"VATAmt": "20.00"
}
]
}
]06 · Field reference
API schema catalog
Expand a schema to inspect every field, exact data type, requirement level and validation constraint.
RegisterInvoiceRequest22
| Field | Type | Requirement | Rules |
|---|---|---|---|
docId | string | Required | 5–200 chars · unique per business document |
operatorCode | string | Optional | ^[a-z]{2}\d{3}[a-z]{2}\d{3}$ |
currency | Currency | Optional | default: ALL / 1 |
articles | Article[] | Conditional | required except SUMMARY · minItems: 1 |
payment | Payment[] | Conditional | required except ORDER · minItems: 1 |
invoiceRebate | Rebate | Optional | percentage or value, never both |
buyer | Buyer | Conditional | required for eInvoice and EXPORT |
correctiveInvoice | CorrectiveInvoiceRef | Conditional | required for P9 / P10 |
invoiceNotes | string | Optional | maxLength: 500 |
documentType | enum | Optional | NORMAL | ORDER | SUMMARY | SELFISSUE | EXPORT |
selfIssueType | enum | Conditional | AGREEMENT | DOMESTIC | ABROAD | SELF | OTHER |
reverseCharge | boolean | Optional | true only for SELFISSUE |
summaryInvoices | string[] | Conditional | SUMMARY only · minItems: 1 · each iic is 32 hex chars |
total | number | Conditional | SUMMARY only · exact referenced ORDER total |
supplyPeriod | SupplyPeriod | Optional | start <= end; dates in one calendar month |
supplyPeriod.start | string(date) | Conditional | YYYY-MM-DD |
supplyPeriod.end | string(date) | Conditional | YYYY-MM-DD |
isEinvoice | boolean | Optional | default: false |
selectedProcess | enum | Optional | P1–P11 · default: P1 |
selectedInvoiceType | string(enum) | Optional | 82 | 84 | 325 | 326 | 380 | 383 | 386 | 393 | 394 | 395 | 575 | 623 | 780 |
payDeadline | string(date) | Optional | YYYY-MM-DD · current year · not in the past |
prepaidAmount | number | Conditional | required for P4 · > 0 for P4 · <= invoice total · max 2 decimals |
Article8
| Field | Type | Requirement | Rules |
|---|---|---|---|
articleId | string | Required | maxLength: 100 |
name | string | Required | maxLength: 100 |
vatCode | string(enum) | Required | A | B | C | D | E | F | G | H | I | J | K | L · must match the business fiscal configuration |
price | number | Required | non-negative unit price including VAT; credit notes use negative units |
units | number | Required | quantity; negative for corrective invoices |
soldIn | string | Required | UN/CEFACT unit code, e.g. XPP | KGM | LTR | HUR |
totalPrice | number | Optional | default: price × units |
rebate | Rebate | Optional | line-level discount |
Rebate2
| Field | Type | Requirement | Rules |
|---|---|---|---|
inPercentage | number | Conditional | mutually exclusive with inValue |
inValue | number | Conditional | mutually exclusive with inPercentage |
Payment3
| Field | Type | Requirement | Rules |
|---|---|---|---|
type | string(enum) | Required | CASH | BANKNOTE | CARD | CHECK | SVOUCHER | COMPANY | ORDER | ACCOUNT | FACTORING | COMPENSATION | TRANSFER | WAIVER | KIND | OTHER |
amount | number | Required | payment sum must equal calculated invoice total |
details | PaymentDetail[] | Conditional | required and non-empty for ACCOUNT |
PaymentDetail7
| Field | Type | Requirement | Rules |
|---|---|---|---|
idNumber | string | Required | IBAN or account number |
name | string | Required | account holder |
bankName | string | Required | bank name |
swift_code | string | Required | SWIFT / BIC |
country | string | Required | country name |
countryCode | string | Required | ISO 3166-1 alpha-2 · exactly 2 chars |
currency | string | Required | ISO 4217 · exactly 3 chars |
Buyer7
| Field | Type | Requirement | Rules |
|---|---|---|---|
buyerIDType | string(enum) | Required | NUIS | ID | PASS | VAT | TAX | SOC | POINTS |
buyerIDNum | string | Required | when buyerIDType=NUIS: ^[A-Za-z][0-9]{8}[A-Za-z]$ · normalize to uppercase |
buyerName | string | Required | buyer legal/display name |
buyerAddress | string | Required | buyer address |
buyerTown | string | Required | buyer town |
buyerCountry | string | Required | ISO 3166-1 alpha-3, e.g. ALB |
buyerCountryCode | string | Optional | ISO 3166-1 alpha-2 · default: AL |
Currency2
| Field | Type | Requirement | Rules |
|---|---|---|---|
code | string | Optional | ISO 4217 · default: ALL |
exRate | number | Conditional | required when code != ALL · rate against ALL |
CorrectiveInvoiceRef2
| Field | Type | Requirement | Rules |
|---|---|---|---|
iicRef | string | Required | existing invoice iic · 32 hex chars |
issueDateTime | string(date) | Optional | defaults to original invoice date |
CancelInvoiceRequest10
| Field | Type | Requirement | Rules |
|---|---|---|---|
docId | string | Required | new cancellation id · 5–200 chars |
operatorCode | string | Optional | ^[a-z]{2}\d{3}[a-z]{2}\d{3}$ |
correctiveInvoice | CorrectiveInvoiceRef | Required | iicRef points to original invoice |
invoiceNotes | string | Optional | maxLength: 500 |
isEinvoice | boolean | Optional | inherits from original when omitted |
selectedProcess | enum | Optional | P1–P11 · electronic default: P10 |
selectedInvoiceType | string(enum) | Optional | same values as RegisterInvoiceRequest |
payDeadline | string(date) | Optional | YYYY-MM-DD |
prepaidAmount | number | Optional | >= 0 · max 2 decimals |
supplyPeriod | SupplyPeriod | Optional | inherits from original invoice when omitted |
StatusInvoiceRequest1
| Field | Type | Requirement | Rules |
|---|---|---|---|
docId | string | Required | same invoice docId · 5–200 chars |
InvoicePdfRequest4
| Field | Type | Requirement | Rules |
|---|---|---|---|
iic | string | Required | exactly 32 hexadecimal chars |
pdfType | string(enum) | Optional | A4 | receipt | eInvoice · default: A4 |
paperWidth | integer(enum) | Optional | 58 | 80 | 110 · receipt only · default: 80 |
lang | string(enum) | Optional | sq | en |
BalanceRequest4
| Field | Type | Requirement | Rules |
|---|---|---|---|
docId | string | Required | 5–200 chars · unique per balance operation · no prescribed naming convention |
amount | number | Required | amount in ALL |
notes | string | Optional | operation note |
operatorCode | string | Optional | ^[a-z]{2}\d{3}[a-z]{2}\d{3}$ |
GetTaxpayersRequest1
| Field | Type | Requirement | Rules |
|---|---|---|---|
searchTerm | string | Required | NIPT or business name · 3–200 chars |
InvoiceResponse21
| Field | Type | Requirement | Rules |
|---|---|---|---|
orderId | string | Required | echoes request docId |
fic | string | Conditional | normal completion identifier |
eic | string | Conditional | required with fic for electronic completion |
iic | string | Conditional | invoice identifier · 32 hex chars |
link | string(uri) | Optional | public verification URL |
error | FiscalError | Optional | present when incomplete or failed |
invoiceNumber | string | Optional | fiscal invoice number |
invoiceOrderNumber | integer | Optional | fiscal sequence number |
invoiceType | string(enum) | Optional | CASH | NONCASH |
totalPrice | number | Optional | gross total |
totalPriceWithoutVat | number | Optional | net total |
totalVatAmount | number | Optional | VAT total |
taxFreeAmount | number | Optional | tax-free total |
goodsExport | number | Optional | export amount |
markUpAmount | number | Optional | markup amount |
operatorCode | string | Optional | fiscal operator code |
businessUnitCode | string | Optional | fiscal business-unit code |
tcrCode | string | Optional | empty for electronic invoices |
sellerName | string | Optional | seller name |
sellerNuis | string | Optional | seller NIPT |
sellerAddress | string | Optional | seller address |
InvoiceIncompleteResponse2
| Field | Type | Requirement | Rules |
|---|---|---|---|
orderId | string | Required | echoes request docId |
error | FiscalError | Required | fiscalization or eInvoice delivery has not completed |
Error2
| Field | Type | Requirement | Rules |
|---|---|---|---|
message | string | Required | validation, authorization or domain error message |
field | string | Optional | field that failed validation |
CisError3
| Field | Type | Requirement | Rules |
|---|---|---|---|
faultEnv | string(enum) | Optional | env:CLIENT | env:SERVER |
faultString | string | Optional | message returned by the tax platform |
faultCode | string | Optional | tax-platform error code |
FiscalError2
| Field | Type | Requirement | Rules |
|---|---|---|---|
cisError | CisError | Optional | tax platform error |
otherError | string | Optional | temporary processing error |
PdfResponse2
| Field | Type | Requirement | Rules |
|---|---|---|---|
base64 | string | Required | base64 PDF or PNG |
lang | string | Optional | document language |
EinvoicePdfResponse2
| Field | Type | Requirement | Rules |
|---|---|---|---|
base64 | string | Required | official eInvoice PDF encoded as base64 |
eic | string | Required | electronic invoice identifier |
BalanceResponse3
| Field | Type | Requirement | Rules |
|---|---|---|---|
orderId | string | Required | echoes request docId |
fcdc | string | Conditional | balance-operation completion identifier |
error | FiscalError | Optional | processing error |
Taxpayer5
| Field | Type | Requirement | Rules |
|---|---|---|---|
Tin | string | Required | taxpayer NIPT |
Name | string | Required | registered name |
Address | string | Required | registered address |
Town | string | Required | registered town |
Country | string | Required | ISO 3166-1 alpha-3 |
Operator2
| Field | Type | Requirement | Rules |
|---|---|---|---|
name | string | Required | operator display name |
opCode | string | Required | use as operatorCode in fiscal requests |
SupplyPeriod2
| Field | Type | Requirement | Rules |
|---|---|---|---|
start | string(date) | Required | YYYY-MM-DD; must not follow end; both dates must be in the same calendar month |
end | string(date) | Required | YYYY-MM-DD; must not precede start; both dates must be in the same calendar month |
GetCisInvoicesRequest4
| Field | Type | Requirement | Rules |
|---|---|---|---|
FromDate | string(date) | Optional | YYYY-MM-DD at 00:00:00; defaults to first day of current month; ignored with FIC |
ToDate | string(date) | Optional | YYYY-MM-DD through 23:59:59; defaults to last day of current month; must not precede FromDate; ignored with FIC |
Page | integer | Optional | minimum 1; default 1; up to 1000 invoices per page; ignored with FIC |
FIC | string(uuid) | Optional | UUID; returns full invoice with Items; other fields are ignored and not validated |
CisInvoice61
| Field | Type | Requirement | Rules |
|---|---|---|---|
TypeOfInv | string(enum) | Optional | CASH | NONCASH |
IsSimplifiedInv | string(enum) | Optional | true | false |
IsBadDeb | string(enum) | Optional | true | false |
TypeOfSelfIss | string | Optional | Self-issue type |
IssueDateTime | string | Optional | Invoice issue date and time |
SendDateTime | string | Optional | CIS scalar value; numeric and boolean values remain strings |
InvNum | string | Optional | CIS scalar value; numeric and boolean values remain strings |
InvOrdNum | string | Optional | CIS scalar value; numeric and boolean values remain strings |
TCRCode | string | Optional | CIS scalar value; numeric and boolean values remain strings |
IsIssuerInVAT | string(enum) | Optional | true | false |
TaxFreeAmt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
MarkUpAmt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
GoodsExAmt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
TotPriceWoVAT | string | Optional | CIS scalar value; numeric and boolean values remain strings |
TotVATAmt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
TotPrice | string | Optional | CIS scalar value; numeric and boolean values remain strings |
OperatorCode | string | Optional | CIS scalar value; numeric and boolean values remain strings |
BusinUnitCode | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SoftCode | string | Optional | CIS scalar value; numeric and boolean values remain strings |
IIC | string | Optional | CIS scalar value; numeric and boolean values remain strings |
IICSignature | string | Optional | CIS scalar value; numeric and boolean values remain strings |
FIC | string(uuid) | Optional | CIS scalar value; numeric and boolean values remain strings |
IsReverseCharge | string(enum) | Optional | true | false |
PayDeadline | string(date) | Optional | CIS scalar value; numeric and boolean values remain strings |
IsEinvoice | string(enum) | Optional | true | false |
EIC | string(uuid) | Optional | CIS scalar value; numeric and boolean values remain strings |
Seller | CisParty | Optional | |
Buyer | CisParty | Optional | |
Currency | object | Optional | |
Currency.Code | string | Optional | CIS scalar value; numeric and boolean values remain strings |
Currency.ExRate | string | Optional | CIS scalar value; numeric and boolean values remain strings |
Currency.IsBuying | string(enum) | Optional | true | false |
SupplyDateOrPeriod | object | Optional | |
SupplyDateOrPeriod.Start | string(date) | Optional | CIS scalar value; numeric and boolean values remain strings |
SupplyDateOrPeriod.End | string(date) | Optional | CIS scalar value; numeric and boolean values remain strings |
CorrectiveInv | object | Optional | |
CorrectiveInv.IICRef | string | Optional | CIS scalar value; numeric and boolean values remain strings |
CorrectiveInv.IssueDateTime | string | Optional | CIS scalar value; numeric and boolean values remain strings |
CorrectiveInv.Type | string(enum) | Optional | CORRECTIVE | DEBIT | CREDIT |
BadDebtInv | object | Optional | |
BadDebtInv.IICRef | string | Optional | CIS scalar value; numeric and boolean values remain strings |
BadDebtInv.IssueDateTime | string | Optional | CIS scalar value; numeric and boolean values remain strings |
PayMethods | object[] | Optional | |
PayMethods[].Type | string | Optional | CIS scalar value; numeric and boolean values remain strings |
PayMethods[].Amt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
PayMethods[].CompCard | string | Optional | CIS scalar value; numeric and boolean values remain strings |
PayMethods[].Vouchers | object[] | Optional | |
PayMethods[].Vouchers[].Num | string | Optional | CIS scalar value; numeric and boolean values remain strings |
Fees | object[] | Optional | |
Fees[].Type | string | Optional | CIS scalar value; numeric and boolean values remain strings |
Fees[].Amt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SameTaxes | object[] | Optional | |
SameTaxes[].NumOfItems | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].PriceBefVAT | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].VATRate | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].ExemptFromVAT | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SameTaxes[].VATAmt | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SumInvIICRefs | object[] | Optional | |
SumInvIICRefs[].IIC | string | Optional | CIS scalar value; numeric and boolean values remain strings |
SumInvIICRefs[].IssueDateTime | string | Optional | CIS scalar value; numeric and boolean values remain strings |
Items | CisInvoiceItem[] | Optional | Returned only for FIC lookup; omitted from date-range lists |
CisParty6
| Field | Type | Requirement | Rules |
|---|---|---|---|
IDType | string | Optional | Party identifier type |
IDNum | string | Optional | Party identifier |
Name | string | Optional | Party name |
Address | string | Optional | Party address |
Town | string | Optional | Party town |
Country | string | Optional | Country code as returned by CIS |
CisInvoiceItem15
| Field | Type | Requirement | Rules |
|---|---|---|---|
N | string | Optional | Item name |
C | string | Optional | Item code |
U | string | Optional | Unit of measure as returned by CIS |
Q | string | Optional | Quantity as a string |
UPB | string | Optional | Unit price excluding VAT as a string |
UPA | string | Optional | Unit price including VAT as a string |
R | string | Optional | Discount percentage as a string |
RR | string(enum) | Optional | Whether the discount reduces the base price; true | false |
PB | string | Optional | Line total excluding VAT as a string |
VR | string | Optional | VAT rate (%) as a string |
VA | string | Optional | Line VAT amount as a string |
PA | string | Optional | Line total including VAT as a string |
EX | string | Optional | VAT exemption reason |
IN | string(enum) | Optional | Investment item flag; true | false |
VS | object | Optional | Sold vouchers; CIS may return additional fields |
VAT code map
vatCode depends on the business VAT status and fiscal configuration, not only on the article. For a VAT-registered business, the standard 20% category is B; A is the 0% category for a business that is not subject to VAT.
| Code | Rate | Fiscal treatment |
|---|---|---|
A | 0% | Business not subject to VAT |
B | 20% | Standard rate |
C | 0% | Exempt supply |
D | 10% | Reduced rate |
E | 6% | Reduced rate |
J | 0% | Export of goods |
The API does not currently return this mapping. Store it in your integration configuration. Do not use other A–L codes without a confirmed fiscal configuration.
Complete ACCOUNT payment
details must be a non-empty array. Every entry describes one seller bank account and requires all seven fields shown here.
Payment fragment
{
"payment": [
{
"type": "ACCOUNT",
"amount": 10000,
"details": [
{
"idNumber": "ALXXXXXXXXXXXXXXXXXXXXXXXXXX",
"name": "Shitësi SHPK",
"bankName": "Banka XYZ",
"swift_code": "ABCDEFGH",
"country": "Shqipëri",
"countryCode": "AL",
"currency": "ALL"
}
]
}
]
}Operational clarifications
| Field | Rules |
|---|---|
Credit notes | Keep price non-negative and use negative units with correctiveInvoice. Negative unit prices are rejected by fiscal validation. |
Noncash buyers | Use the identifier type belonging to the buyer. A business NIPT cannot be sent as ID. Noncash sales to NUIS buyers require electronic invoicing. |
Currency totals | Request prices and payments use the invoice currency. Response totalPrice and tax totals are returned in ALL after applying exRate. |
Demo self-issuance | On 2026-10-10, SELF was rejected by the fiscal schema. AGREEMENT requires eInvoice upstream, while this API disallows isEinvoice with SELFISSUE. DOMESTIC requires an eligible domestic supplier. |
buyerIDNum · NUIS | Accepted shape: one letter, eight digits, one letter (^[A-Za-z][0-9]{8}[A-Za-z]$). Normalize to uppercase. No alternative legacy NIPT shape is part of this contract. |
get-taxpayers | Country uses ISO 3166-1 alpha-3 (ALB for Albania). The response has no active, inactive or deregistered status field; use this endpoint to search and populate buyer data, not as final verification of tax status. |
Rate limiting | No numeric quota is currently published. Debounce searches and do not send a request for every keystroke. |
balance/initiate | Send one successful opening balance per business day and authenticated fiscal device/TCR, before its first cash invoice. An application shift is not the fiscal boundary, and there is no balance-close endpoint. |
balance docId | The SHIFT-… values are examples only. Use any stable unique identifier of 5–200 characters and reuse it only to recover the same balance operation. |
Canonical enums
- soldIn
- XPP · KGM · LTR · HUR · other UN/CEFACT unit codes
- vatCode
- A · B · C · D · E · F · G · H · I · J · K · L
- payment.type
- CASH · BANKNOTE · CARD · CHECK · SVOUCHER · COMPANY · ORDER · ACCOUNT · FACTORING · COMPENSATION · TRANSFER · WAIVER · KIND · OTHER
- buyerIDType
- NUIS · ID · PASS · VAT · TAX · SOC · POINTS
- selectedProcess
- P1 · P2 · P3 · P4 · P5 · P6 · P7 · P8 · P9 · P10 · P11
- selectedInvoiceType
- 82 · 84 · 325 · 326 · 380 · 383 · 386 · 393 · 394 · 395 · 575 · 623 · 780
- selfIssueType
- AGREEMENT · DOMESTIC · ABROAD · SELF · OTHER
- pdfType
- A4 · receipt · eInvoice
07 · Completion contract
Read identifiers before declaring success
A successful HTTP response can still describe an unfinished external fiscalization operation. Persist the body and decide from the identifiers.
| Operation | Complete when | If incomplete |
|---|---|---|
| Normal invoice / cancellation | fic is present | Recover with the same docId. |
| Electronic invoice / cancellation | fic and eic are both present | Poll status with the same docId. |
| Balance transaction | fcdc is present | Retry the same operation and docId. |
base64 is present | Retry after the source invoice is complete. |
Error decision table
| Error | Retryable | Action |
|---|---|---|
400 validation / field | No | Fix the request; unknown top-level fields are rejected. |
401 Unauthorized | After credentials | Renew the correct environment token, then preserve docId. |
cisError env:CLIENT | No | Correct the fiscal or request data first. |
cisError env:SERVER / otherError | Yes | Back off and recover with the same docId. |
Timeout / connection / 502 / 503 | Yes | Status first; replay the immutable request only if not found. |
Another request is processing | Yes, later | Stop parallel work, wait, then query status. |
08 · Source files
Use the same contract in your tools
The page is the readable reference. These files are direct downloads for generators, API clients and coding agents.
OpenAPI 3.1.2 JSONJSON
The same contract as YAML, generated automatically for API clients and AI agents.
DownloadOpenAPI 3.1.2 YAMLYAML
Complete paths, schemas, enums, examples and development/production servers.
DownloadPostman collection JSONJSON
Importable requests for all endpoints and invoice families. Download only; no external documenter.
DownloadAI reference textTXT
Compact operational rules, endpoint map and retry semantics for coding agents.
DownloadMeasurement unit codesXLSX
Download the supported measurement-unit list and use its code value as soldIn, for example XPP, KGM, LTR or HUR.
DownloadGet credentials